1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 package org.apache.commons.configuration;
19
20 import java.net.URL;
21 import java.io.InputStream;
22 import java.io.Reader;
23 import java.io.OutputStream;
24 import java.io.Writer;
25 import java.io.File;
26
27 import org.apache.commons.configuration.reloading.ReloadingStrategy;
28
29 /***
30 * A persistent configuration loaded and saved to a file.
31 *
32 * @author Emmanuel Bourg
33 * @version $Revision: 492234 $, $Date: 2007-01-03 18:39:39 +0100 (Mi, 03 Jan 2007) $
34 * @since 1.0-rc2
35 */
36 public interface FileConfiguration extends Configuration
37 {
38 /***
39 * Load the configuration from the underlying URL. If the URL is not
40 * specified, it attempts to locate the specified file name.
41 *
42 * @throws ConfigurationException if an error occurs during the load operation
43 */
44 void load() throws ConfigurationException;
45
46 /***
47 * Locate the specified file and load the configuration.
48 *
49 * @param fileName the name of the file loaded
50 *
51 * @throws ConfigurationException if an error occurs during the load operation
52 */
53 void load(String fileName) throws ConfigurationException;
54
55 /***
56 * Load the configuration from the specified file.
57 *
58 * @param file the loaded file
59 *
60 * @throws ConfigurationException if an error occurs during the load operation
61 */
62 void load(File file) throws ConfigurationException;
63
64 /***
65 * Load the configuration from the specified URL.
66 *
67 * @param url the URL of the file loaded
68 *
69 * @throws ConfigurationException if an error occurs during the load operation
70 */
71 void load(URL url) throws ConfigurationException;
72
73 /***
74 * Load the configuration from the specified stream, using the encoding
75 * returned by {@link #getEncoding()}.
76 *
77 * @param in the input stream
78 *
79 * @throws ConfigurationException if an error occurs during the load operation
80 */
81 void load(InputStream in) throws ConfigurationException;
82
83 /***
84 * Load the configuration from the specified stream, using the specified
85 * encoding. If the encoding is null the default encoding is used.
86 *
87 * @param in the input stream
88 * @param encoding the encoding used. <code>null</code> to use the default encoding
89 *
90 * @throws ConfigurationException if an error occurs during the load operation
91 */
92 void load(InputStream in, String encoding) throws ConfigurationException;
93
94 /***
95 * Load the configuration from the specified reader.
96 *
97 * @param in the reader
98 *
99 * @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 if it's a file 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()</code> or <code>setURL()</code> 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</code> the base path
188 * will be <code>file:/temp/</code>). If the base path was explictly set
189 * using <code>setBasePath()</code>, 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()</code> and
199 * <code>setFileName()</code> 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</code>), 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 automatical saving of modified properties to the disk.
238 *
239 * @param autoSave <code>true</code> to enable, <code>false</code> 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</code> if auto-saving is enabled, <code>false</code> 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 }