View Javadoc

1   /*
2    * Copyright 2004 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: 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 }