Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
FileConfiguration |
|
| 1.0;1 |
1 | /* | |
2 | * Licensed to the Apache Software Foundation (ASF) under one or more | |
3 | * contributor license agreements. See the NOTICE file distributed with | |
4 | * this work for additional information regarding copyright ownership. | |
5 | * The ASF licenses this file to You under the Apache License, Version 2.0 | |
6 | * (the "License"); you may not use this file except in compliance with | |
7 | * the License. You may obtain a copy of the License at | |
8 | * | |
9 | * http://www.apache.org/licenses/LICENSE-2.0 | |
10 | * | |
11 | * Unless required by applicable law or agreed to in writing, software | |
12 | * distributed under the License is distributed on an "AS IS" BASIS, | |
13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
14 | * See the License for the specific language governing permissions and | |
15 | * limitations under the License. | |
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 | } |