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
34 /** Constant for the default logger. */
35 private static final ConfigurationLogger DEFAULT_LOG = ConfigurationLogger.newDummyLogger();
36
37 /** The Logger. */
38 private volatile ConfigurationLogger log;
39
40 /** FileSystem options provider. */
41 private volatile FileOptionsProvider optionsProvider;
42
43 /**
44 * Constructs a new instance.
45 */
46 public FileSystem() {
47 // empty
48 }
49
50 /**
51 * Gets the base path of the given path, for example a directory for a file.
52 *
53 * @param path the source path.
54 * @return the base path.
55 */
56 public abstract String getBasePath(String path);
57
58 /**
59 * Gets the file name of the given path.
60 *
61 * @param path the source path.
62 * @return the file name.
63 */
64 public abstract String getFileName(String path);
65
66 /**
67 * Gets the FileSystem options provider.
68 *
69 * @return the FileSystem options provider.
70 */
71 public FileOptionsProvider getFileOptionsProvider() {
72 return this.optionsProvider;
73 }
74
75 /**
76 * Gets an input stream for a URL.
77 *
78 * @param url the source URL.
79 * @return an input stream.
80 * @throws ConfigurationException if an problem occurs getting the input stream.
81 */
82 public abstract InputStream getInputStream(URL url) throws ConfigurationException;
83
84 /**
85 * Not abstract for binary compatibility.
86 *
87 * @param url the URL of the file
88 * @param urlConnectionOptions the URLConnection options
89 * @return the input stream for the specified URL
90 * @throws ConfigurationException if an error occurs while opening the file
91 *
92 * @since 2.8.0
93 */
94 public InputStream getInputStream(final URL url, final URLConnectionOptions urlConnectionOptions) throws ConfigurationException {
95 return getInputStream(url);
96 }
97
98 /**
99 * Gets the logger used by this FileSystem.
100 *
101 * @return the logger
102 */
103 public ConfigurationLogger getLogger() {
104 final ConfigurationLogger result = log;
105 return result != null ? result : DEFAULT_LOG;
106 }
107
108 /**
109 * Gets an output stream for a File.
110 *
111 * @param file the source File.
112 * @return an output stream.
113 * @throws ConfigurationException if an problem occurs getting the output stream.
114 */
115 public abstract OutputStream getOutputStream(File file) throws ConfigurationException;
116
117 /**
118 * Gets an output stream for a URL.
119 *
120 * @param url the source URL.
121 * @return an output stream.
122 * @throws ConfigurationException if an problem occurs getting the output stream.
123 */
124 public abstract OutputStream getOutputStream(URL url) throws ConfigurationException;
125
126 /**
127 * Gets a path string for the given input where some values may be null.
128 * <p>
129 * The implementation decides on which argument take precedence.
130 * </p>
131 *
132 * @param file A file.
133 * @param url A URL.
134 * @param basePath A base path string.
135 * @param fileName A file name.
136 * @return A path string.
137 */
138 public abstract String getPath(File file, URL url, String basePath, String fileName);
139
140 /**
141 * Gets a URL for a base path and file name.
142 *
143 * @param basePath The base path.
144 * @param fileName The file name.
145 * @return a URL.
146 * @throws MalformedURLException if a problem occurs creating the URL.
147 */
148 public abstract URL getURL(String basePath, String fileName) throws MalformedURLException;
149
150 /**
151 * Locates a URL for a base path and file name.
152 *
153 * @param basePath The base path.
154 * @param fileName The file name.
155 * @return a URL.
156 */
157 public abstract URL locateFromURL(String basePath, String fileName);
158
159 /**
160 * Sets the FileOptionsProvider
161 *
162 * @param provider The FileOptionsProvider
163 */
164 public void setFileOptionsProvider(final FileOptionsProvider provider) {
165 this.optionsProvider = provider;
166 }
167
168 /**
169 * Sets the logger to be used by this FileSystem. This method makes it possible for clients to exactly control
170 * logging behavior. Per default a logger is set that will ignore all log messages. Derived classes that want to enable
171 * logging should call this method during their initialization with the logger to be used. Passing in a <strong>null</strong>
172 * argument disables logging.
173 *
174 * @param log the new logger
175 */
176 public void setLogger(final ConfigurationLogger log) {
177 this.log = log;
178 }
179 }