View Javadoc

1   /*
2    * Copyright 2004-2005 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License")
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
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 }