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: 155408 $, $Date: 2005-02-26 13:56:39 +0100 (Sa, 26 Feb 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
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
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
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
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
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
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
99 */
100 void load(Reader in) throws ConfigurationException;
101
102 /***
103 * Save the configuration.
104 *
105 * @throws ConfigurationException
106 */
107 void save() throws ConfigurationException;
108
109 /***
110 * Save the configuration to the specified file.
111 *
112 * @param fileName
113 *
114 * @throws ConfigurationException
115 */
116 void save(String fileName) throws ConfigurationException;
117
118 /***
119 * Save the configuration to the specified file.
120 *
121 * @param file
122 *
123 * @throws ConfigurationException
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
131 *
132 * @throws ConfigurationException
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
141 *
142 * @throws ConfigurationException
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
151 * @param encoding
152 * @throws ConfigurationException
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
162 */
163 void save(Writer out) throws ConfigurationException;
164
165 /***
166 * Return the name of the file.
167 */
168 String getFileName();
169
170 /***
171 * Set the name of the file.
172 *
173 * @param fileName the name of the file
174 */
175 void setFileName(String fileName);
176
177 /***
178 * Return the base path.
179 */
180 String getBasePath();
181
182 /***
183 * Set the base path. Relative configurations are loaded from this path.
184 *
185 * @param basePath the base path.
186 */
187 void setBasePath(String basePath);
188
189 /***
190 * Return the file where the configuration is stored.
191 */
192 File getFile();
193
194 /***
195 * Set the file where the configuration is stored.
196 *
197 * @param file
198 */
199 void setFile(File file);
200
201 /***
202 * Return the URL where the configuration is stored.
203 */
204 URL getURL();
205
206 /***
207 * The URL where the configuration is stored.
208 *
209 * @param url
210 */
211 void setURL(URL url);
212
213 /***
214 * Enable of disable the automatical saving of modified properties to the disk.
215 *
216 * @param autoSave <code>true</code> to enable, <code>false</code> to disable
217 * @since 1.1
218 */
219 void setAutoSave(boolean autoSave);
220
221 /***
222 * Tells if properties are automatically saved to the disk.
223 *
224 * @return <code>true</code> if auto-saving is enabled, <code>false</code> otherwise
225 * @since 1.1
226 */
227 boolean isAutoSave();
228
229 /***
230 * Return the reloading strategy.
231 *
232 * @since 1.1
233 */
234 ReloadingStrategy getReloadingStrategy();
235
236 /***
237 * Set the reloading strategy.
238 *
239 * @since 1.1
240 */
241 void setReloadingStrategy(ReloadingStrategy strategy);
242
243 /***
244 * Reload the configuration.
245 *
246 * @since 1.1
247 */
248 void reload();
249
250 /***
251 * Return the encoding used to store the configuration file. If the value
252 * is null the default encoding is used.
253 *
254 * @since 1.1
255 */
256 String getEncoding();
257
258 /***
259 * Set the encoding used to store the configuration file. Set the encoding
260 * to null to use the default encoding.
261 *
262 * @since 1.1
263 */
264 void setEncoding(String encoding);
265
266 }