001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package org.apache.commons.configuration;
019
020 import java.io.File;
021 import java.io.InputStream;
022 import java.io.OutputStream;
023 import java.io.Reader;
024 import java.io.Writer;
025 import java.net.URL;
026
027 import org.apache.commons.configuration.reloading.ReloadingStrategy;
028
029 /**
030 * A persistent configuration loaded and saved to a file.
031 *
032 * @author Emmanuel Bourg
033 * @version $Id: FileConfiguration.java 1209883 2011-12-03 10:56:57Z oheger $
034 * @since 1.0-rc2
035 */
036 public interface FileConfiguration extends Configuration
037 {
038 /**
039 * Load the configuration from the underlying URL. If the URL is not
040 * specified, it attempts to locate the specified file name.
041 *
042 * @throws ConfigurationException if an error occurs during the load operation
043 */
044 void load() throws ConfigurationException;
045
046 /**
047 * Locate the specified file and load the configuration.
048 *
049 * @param fileName the name of the file loaded
050 *
051 * @throws ConfigurationException if an error occurs during the load operation
052 */
053 void load(String fileName) throws ConfigurationException;
054
055 /**
056 * Load the configuration from the specified file.
057 *
058 * @param file the loaded file
059 *
060 * @throws ConfigurationException if an error occurs during the load operation
061 */
062 void load(File file) throws ConfigurationException;
063
064 /**
065 * Load the configuration from the specified URL.
066 *
067 * @param url the URL of the file loaded
068 *
069 * @throws ConfigurationException if an error occurs during the load operation
070 */
071 void load(URL url) throws ConfigurationException;
072
073 /**
074 * Load the configuration from the specified stream, using the encoding
075 * returned by {@link #getEncoding()}.
076 *
077 * @param in the input stream
078 *
079 * @throws ConfigurationException if an error occurs during the load operation
080 */
081 void load(InputStream in) throws ConfigurationException;
082
083 /**
084 * Load the configuration from the specified stream, using the specified
085 * encoding. If the encoding is null the default encoding is used.
086 *
087 * @param in the input stream
088 * @param encoding the encoding used. {@code null} to use the default encoding
089 *
090 * @throws ConfigurationException if an error occurs during the load operation
091 */
092 void load(InputStream in, String encoding) throws ConfigurationException;
093
094 /**
095 * Load the configuration from the specified reader.
096 *
097 * @param in the reader
098 *
099 * @throws ConfigurationException if an error occurs during the load operation
100 */
101 void load(Reader in) throws ConfigurationException;
102
103 /**
104 * Save the configuration.
105 *
106 * @throws ConfigurationException if an error occurs during the save operation
107 */
108 void save() throws ConfigurationException;
109
110 /**
111 * Save the configuration to the specified file.
112 *
113 * @param fileName the name of the file to be saved
114 *
115 * @throws ConfigurationException if an error occurs during the save operation
116 */
117 void save(String fileName) throws ConfigurationException;
118
119 /**
120 * Save the configuration to the specified file.
121 *
122 * @param file specifies the file to be saved
123 *
124 * @throws ConfigurationException if an error occurs during the save operation
125 */
126 void save(File file) throws ConfigurationException;
127
128 /**
129 * Save the configuration to the specified URL.
130 *
131 * @param url the URL
132 *
133 * @throws ConfigurationException if an error occurs during the save operation
134 */
135 void save(URL url) throws ConfigurationException;
136
137 /**
138 * Save the configuration to the specified stream, using the encoding
139 * returned by {@link #getEncoding()}.
140 *
141 * @param out the output stream
142 *
143 * @throws ConfigurationException if an error occurs during the save operation
144 */
145 void save(OutputStream out) throws ConfigurationException;
146
147 /**
148 * Save the configuration to the specified stream, using the specified
149 * encoding. If the encoding is null the default encoding is used.
150 *
151 * @param out the output stream
152 * @param encoding the encoding to be used
153 * @throws ConfigurationException if an error occurs during the save operation
154 */
155 void save(OutputStream out, String encoding) throws ConfigurationException;
156
157 /**
158 * Save the configuration to the specified writer.
159 *
160 * @param out the writer
161 *
162 * @throws ConfigurationException if an error occurs during the save operation
163 */
164 void save(Writer out) throws ConfigurationException;
165
166 /**
167 * Return the name of the file.
168 *
169 * @return the file name
170 */
171 String getFileName();
172
173 /**
174 * Set the name of the file.
175 *
176 * @param fileName the name of the file
177 */
178 void setFileName(String fileName);
179
180 /**
181 * Returns the base path. One way to specify the location of a configuration
182 * source is by setting its base path and its file name. This method returns
183 * this base path. The concrete value returned by this method depends on the
184 * way the location of the configuration file was set. If methods like
185 * {@code setFile()} or {@code setURL()} were used, the base
186 * path typically points to the parent directory of the configuration file
187 * (e.g. for the URL {@code file:/temp/test.properties} the base path
188 * will be {@code file:/temp/}). If the base path was explicitly set
189 * using {@code setBasePath()}, this method will return the exact
190 * value specified here without further modifications.
191 *
192 * @return the base path
193 * @see AbstractFileConfiguration#setBasePath(String)
194 */
195 String getBasePath();
196
197 /**
198 * Sets the base path. The methods {@code setBasePath()} and
199 * {@code setFileName()} can be used together to specify the location
200 * of the configuration file to be loaded. If relative file names are to
201 * be resolved (e.g. for the include files supported by
202 * {@code PropertiesConfiguration}), this base path will be used.
203 *
204 * @param basePath the base path.
205 */
206 void setBasePath(String basePath);
207
208 /**
209 * Return the file where the configuration is stored.
210 *
211 * @return the configuration file
212 */
213 File getFile();
214
215 /**
216 * Set the file where the configuration is stored.
217 *
218 * @param file the file
219 */
220 void setFile(File file);
221
222 /**
223 * Return the URL where the configuration is stored.
224 *
225 * @return the URL of the configuration
226 */
227 URL getURL();
228
229 /**
230 * The URL where the configuration is stored.
231 *
232 * @param url the URL
233 */
234 void setURL(URL url);
235
236 /**
237 * Enable or disable the automatically saving of modified properties to the disk.
238 *
239 * @param autoSave {@code true} to enable, {@code false} to disable
240 * @since 1.1
241 */
242 void setAutoSave(boolean autoSave);
243
244 /**
245 * Tells if properties are automatically saved to the disk.
246 *
247 * @return {@code true} if auto-saving is enabled, {@code false} otherwise
248 * @since 1.1
249 */
250 boolean isAutoSave();
251
252 /**
253 * Return the reloading strategy.
254 *
255 * @return the reloading strategy currently used
256 * @since 1.1
257 */
258 ReloadingStrategy getReloadingStrategy();
259
260 /**
261 * Set the reloading strategy.
262 *
263 * @param strategy the reloading strategy to use
264 * @since 1.1
265 */
266 void setReloadingStrategy(ReloadingStrategy strategy);
267
268 /**
269 * Reload the configuration.
270 *
271 * @since 1.1
272 */
273 void reload();
274
275 /**
276 * Return the encoding used to store the configuration file. If the value
277 * is null the default encoding is used.
278 *
279 * @return the current encoding
280 * @since 1.1
281 */
282 String getEncoding();
283
284 /**
285 * Set the encoding used to store the configuration file. Set the encoding
286 * to null to use the default encoding.
287 *
288 * @param encoding the encoding to use
289 * @since 1.1
290 */
291 void setEncoding(String encoding);
292
293 }