View Javadoc

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 }