1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.configuration2.io;
18
19 import java.io.File;
20 import java.io.InputStream;
21 import java.io.OutputStream;
22 import java.net.MalformedURLException;
23 import java.net.URL;
24
25 import org.apache.commons.configuration2.ex.ConfigurationException;
26
27 /**
28 * Abstract layer to allow various types of file systems.
29 *
30 * @since 1.7
31 */
32 public abstract class FileSystem {
33 /** Constant for the default logger. */
34 private static final ConfigurationLogger DEFAULT_LOG = ConfigurationLogger.newDummyLogger();
35
36 /** The Logger. */
37 private volatile ConfigurationLogger log;
38
39 /** FileSystem options provider. */
40 private volatile FileOptionsProvider optionsProvider;
41
42 /**
43 * Constructs a new instance.
44 */
45 public FileSystem() {
46 // empty
47 }
48
49 /**
50 * Gets the base path of the given path, for example a directory for a file.
51 *
52 * @param path the source path.
53 * @return the base path.
54 */
55 public abstract String getBasePath(String path);
56
57 /**
58 * Gets the file name of the given path.
59 *
60 * @param path the source path.
61 * @return the file name.
62 */
63 public abstract String getFileName(String path);
64
65 /**
66 * Gets the FileSystem options provider.
67 *
68 * @return the FileSystem options provider.
69 */
70 public FileOptionsProvider getFileOptionsProvider() {
71 return this.optionsProvider;
72 }
73
74 /**
75 * Gets an input stream for a URL.
76 *
77 * @param url the source URL.
78 * @return an input stream.
79 * @throws ConfigurationException if an problem occurs getting the input stream.
80 */
81 public abstract InputStream getInputStream(URL url) throws ConfigurationException;
82
83 /**
84 * Not abstract for binary compatibility.
85 *
86 * @param url TODO
87 * @param urlConnectionOptions Ignored.
88 * @return TODO
89 * @throws ConfigurationException TODO
90 * @since 2.8.0
91 */
92 public InputStream getInputStream(final URL url, final URLConnectionOptions urlConnectionOptions) throws ConfigurationException {
93 return getInputStream(url);
94 }
95
96 /**
97 * Gets the logger used by this FileSystem.
98 *
99 * @return the logger
100 */
101 public ConfigurationLogger getLogger() {
102 final ConfigurationLogger result = log;
103 return result != null ? result : DEFAULT_LOG;
104 }
105
106 /**
107 * Gets an output stream for a File.
108 *
109 * @param file the source File.
110 * @return an output stream.
111 * @throws ConfigurationException if an problem occurs getting the output stream.
112 */
113 public abstract OutputStream getOutputStream(File file) throws ConfigurationException;
114
115 /**
116 * Gets an output stream for a URL.
117 *
118 * @param url the source URL.
119 * @return an output stream.
120 * @throws ConfigurationException if an problem occurs getting the output stream.
121 */
122 public abstract OutputStream getOutputStream(URL url) throws ConfigurationException;
123
124 /**
125 * Gets a path string for the given input where some values may be null.
126 * <p>
127 * The implementation decides on which argument take precedence.
128 * </p>
129 *
130 * @param file A file.
131 * @param url A URL.
132 * @param basePath A base path string.
133 * @param fileName A file name.
134 * @return A path string.
135 */
136 public abstract String getPath(File file, URL url, String basePath, String fileName);
137
138 /**
139 * Gets a URL for a base path and file name.
140 *
141 * @param basePath The base path.
142 * @param fileName The file name.
143 * @return a URL.
144 * @throws MalformedURLException if a problem occurs creating the URL.
145 */
146 public abstract URL getURL(String basePath, String fileName) throws MalformedURLException;
147
148 /**
149 * Locates a URL for a base path and file name.
150 *
151 * @param basePath The base path.
152 * @param fileName The file name.
153 * @return a URL.
154 */
155 public abstract URL locateFromURL(String basePath, String fileName);
156
157 /**
158 * Sets the FileOptionsProvider
159 *
160 * @param provider The FileOptionsProvider
161 */
162 public void setFileOptionsProvider(final FileOptionsProvider provider) {
163 this.optionsProvider = provider;
164 }
165
166 /**
167 * Sets the logger to be used by this FileSystem. This method makes it possible for clients to exactly control
168 * logging behavior. Per default a logger is set that will ignore all log messages. Derived classes that want to enable
169 * logging should call this method during their initialization with the logger to be used. Passing in a <strong>null</strong>
170 * argument disables logging.
171 *
172 * @param log the new logger
173 */
174 public void setLogger(final ConfigurationLogger log) {
175 this.log = log;
176 }
177 }