1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.apache.commons.configuration;
18
19 import java.net.URL;
20 import java.io.InputStream;
21 import java.io.Reader;
22 import java.io.OutputStream;
23 import java.io.Writer;
24 import java.io.File;
25
26 import org.apache.commons.configuration.reloading.ReloadingStrategy;
27
28 /***
29 * A persistent configuration loaded and saved to a file.
30 *
31 * @author Emmanuel Bourg
32 * @version $Revision$, $Date: 2005-10-09 20:27:12 +0200 (Sun, 09 Oct 2005) $
33 * @since 1.0-rc2
34 */
35 public interface FileConfiguration extends Configuration
36 {
37 /***
38 * Load the configuration from the underlying URL. If the URL is not
39 * specified, it attempts to locate the specified file name.
40 *
41 * @throws ConfigurationException if an error occurs during the load operation
42 */
43 void load() throws ConfigurationException;
44
45 /***
46 * Locate the specified file and load the configuration.
47 *
48 * @param fileName the name of the file loaded
49 *
50 * @throws ConfigurationException if an error occurs during the load operation
51 */
52 void load(String fileName) throws ConfigurationException;
53
54 /***
55 * Load the configuration from the specified file.
56 *
57 * @param file the loaded file
58 *
59 * @throws ConfigurationException if an error occurs during the load operation
60 */
61 void load(File file) throws ConfigurationException;
62
63 /***
64 * Load the configuration from the specified URL.
65 *
66 * @param url the URL of the file loaded
67 *
68 * @throws ConfigurationException if an error occurs during the load operation
69 */
70 void load(URL url) throws ConfigurationException;
71
72 /***
73 * Load the configuration from the specified stream, using the encoding
74 * returned by {@link #getEncoding()}.
75 *
76 * @param in the input stream
77 *
78 * @throws ConfigurationException if an error occurs during the load operation
79 */
80 void load(InputStream in) throws ConfigurationException;
81
82 /***
83 * Load the configuration from the specified stream, using the specified
84 * encoding. If the encoding is null the default encoding is used.
85 *
86 * @param in the input stream
87 * @param encoding the encoding used. <code>null</code> to use the default encoding
88 *
89 * @throws ConfigurationException if an error occurs during the load operation
90 */
91 void load(InputStream in, String encoding) throws ConfigurationException;
92
93 /***
94 * Load the configuration from the specified reader.
95 *
96 * @param in the reader
97 *
98 * @throws ConfigurationException if an error occurs during the load operation
99 */
100 void load(Reader in) throws ConfigurationException;
101
102 /***
103 * Save the configuration.
104 *
105 * @throws ConfigurationException if an error occurs during the save operation
106 */
107 void save() throws ConfigurationException;
108
109 /***
110 * Save the configuration to the specified file.
111 *
112 * @param fileName the name of the file to be saved
113 *
114 * @throws ConfigurationException if an error occurs during the save operation
115 */
116 void save(String fileName) throws ConfigurationException;
117
118 /***
119 * Save the configuration to the specified file.
120 *
121 * @param file specifies the file to be saved
122 *
123 * @throws ConfigurationException if an error occurs during the save operation
124 */
125 void save(File file) throws ConfigurationException;
126
127 /***
128 * Save the configuration to the specified URL if it's a file URL.
129 *
130 * @param url the URL
131 *
132 * @throws ConfigurationException if an error occurs during the save operation
133 */
134 void save(URL url) throws ConfigurationException;
135
136 /***
137 * Save the configuration to the specified stream, using the encoding
138 * returned by {@link #getEncoding()}.
139 *
140 * @param out the output stream
141 *
142 * @throws ConfigurationException if an error occurs during the save operation
143 */
144 void save(OutputStream out) throws ConfigurationException;
145
146 /***
147 * Save the configuration to the specified stream, using the specified
148 * encoding. If the encoding is null the default encoding is used.
149 *
150 * @param out the output stream
151 * @param encoding the encoding to be used
152 * @throws ConfigurationException if an error occurs during the save operation
153 */
154 void save(OutputStream out, String encoding) throws ConfigurationException;
155
156 /***
157 * Save the configuration to the specified writer.
158 *
159 * @param out the writer
160 *
161 * @throws ConfigurationException if an error occurs during the save operation
162 */
163 void save(Writer out) throws ConfigurationException;
164
165 /***
166 * Return the name of the file.
167 *
168 * @return the file name
169 */
170 String getFileName();
171
172 /***
173 * Set the name of the file.
174 *
175 * @param fileName the name of the file
176 */
177 void setFileName(String fileName);
178
179 /***
180 * Return the base path.
181 *
182 * @return the base path
183 */
184 String getBasePath();
185
186 /***
187 * Set the base path. Relative configurations are loaded from this path.
188 *
189 * @param basePath the base path.
190 */
191 void setBasePath(String basePath);
192
193 /***
194 * Return the file where the configuration is stored.
195 *
196 * @return the configuration file
197 */
198 File getFile();
199
200 /***
201 * Set the file where the configuration is stored.
202 *
203 * @param file the file
204 */
205 void setFile(File file);
206
207 /***
208 * Return the URL where the configuration is stored.
209 *
210 * @return the URL of the configuration
211 */
212 URL getURL();
213
214 /***
215 * The URL where the configuration is stored.
216 *
217 * @param url the URL
218 */
219 void setURL(URL url);
220
221 /***
222 * Enable or disable the automatical saving of modified properties to the disk.
223 *
224 * @param autoSave <code>true</code> to enable, <code>false</code> to disable
225 * @since 1.1
226 */
227 void setAutoSave(boolean autoSave);
228
229 /***
230 * Tells if properties are automatically saved to the disk.
231 *
232 * @return <code>true</code> if auto-saving is enabled, <code>false</code> otherwise
233 * @since 1.1
234 */
235 boolean isAutoSave();
236
237 /***
238 * Return the reloading strategy.
239 *
240 * @return the reloading strategy currently used
241 * @since 1.1
242 */
243 ReloadingStrategy getReloadingStrategy();
244
245 /***
246 * Set the reloading strategy.
247 *
248 * @param strategy the reloading strategy to use
249 * @since 1.1
250 */
251 void setReloadingStrategy(ReloadingStrategy strategy);
252
253 /***
254 * Reload the configuration.
255 *
256 * @since 1.1
257 */
258 void reload();
259
260 /***
261 * Return the encoding used to store the configuration file. If the value
262 * is null the default encoding is used.
263 *
264 * @return the current encoding
265 * @since 1.1
266 */
267 String getEncoding();
268
269 /***
270 * Set the encoding used to store the configuration file. Set the encoding
271 * to null to use the default encoding.
272 *
273 * @param encoding the encoding to use
274 * @since 1.1
275 */
276 void setEncoding(String encoding);
277
278 }