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: 439648 $, $Date: 2006-09-02 22:42:10 +0200 (Sa, 02 Sep 2006) $
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 * Return the base path.
182 *
183 * @return the base path
184 */
185 String getBasePath();
186
187 /***
188 * Set the base path. Relative configurations are loaded from this path.
189 *
190 * @param basePath the base path.
191 */
192 void setBasePath(String basePath);
193
194 /***
195 * Return the file where the configuration is stored.
196 *
197 * @return the configuration file
198 */
199 File getFile();
200
201 /***
202 * Set the file where the configuration is stored.
203 *
204 * @param file the file
205 */
206 void setFile(File file);
207
208 /***
209 * Return the URL where the configuration is stored.
210 *
211 * @return the URL of the configuration
212 */
213 URL getURL();
214
215 /***
216 * The URL where the configuration is stored.
217 *
218 * @param url the URL
219 */
220 void setURL(URL url);
221
222 /***
223 * Enable or disable the automatical saving of modified properties to the disk.
224 *
225 * @param autoSave <code>true</code> to enable, <code>false</code> to disable
226 * @since 1.1
227 */
228 void setAutoSave(boolean autoSave);
229
230 /***
231 * Tells if properties are automatically saved to the disk.
232 *
233 * @return <code>true</code> if auto-saving is enabled, <code>false</code> otherwise
234 * @since 1.1
235 */
236 boolean isAutoSave();
237
238 /***
239 * Return the reloading strategy.
240 *
241 * @return the reloading strategy currently used
242 * @since 1.1
243 */
244 ReloadingStrategy getReloadingStrategy();
245
246 /***
247 * Set the reloading strategy.
248 *
249 * @param strategy the reloading strategy to use
250 * @since 1.1
251 */
252 void setReloadingStrategy(ReloadingStrategy strategy);
253
254 /***
255 * Reload the configuration.
256 *
257 * @since 1.1
258 */
259 void reload();
260
261 /***
262 * Return the encoding used to store the configuration file. If the value
263 * is null the default encoding is used.
264 *
265 * @return the current encoding
266 * @since 1.1
267 */
268 String getEncoding();
269
270 /***
271 * Set the encoding used to store the configuration file. Set the encoding
272 * to null to use the default encoding.
273 *
274 * @param encoding the encoding to use
275 * @since 1.1
276 */
277 void setEncoding(String encoding);
278
279 }