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: 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 | } |