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  /***
27   * A persistent configuration loaded and saved to a file.
28   *
29   * @author Emmanuel Bourg
30   * @version $Revision: 1.1 $, $Date: 2004/09/22 17:17:30 $
31   * @since 1.0-rc2
32   */
33  public interface FileConfiguration extends Configuration
34  {
35      /***
36       * Load the configuration from the underlying URL. If the URL is not
37       * specified, it attempts to locate the specified file name.
38       *
39       * @throws ConfigurationException
40       */
41      void load() throws ConfigurationException;
42  
43      /***
44       * Locate the specified file and load the configuration.
45       *
46       * @param fileName the name of the file loaded
47       *
48       * @throws ConfigurationException
49       */
50      void load(String fileName) throws ConfigurationException;
51  
52      /***
53       * Load the configuration from the specified file.
54       *
55       * @param file the loaded file
56       *
57       * @throws ConfigurationException
58       */
59      void load(File file) throws ConfigurationException;
60  
61      /***
62       * Load the configuration from the specified URL.
63       *
64       * @param url the URL of the file loaded
65       *
66       * @throws ConfigurationException
67       */
68      void load(URL url) throws ConfigurationException;
69  
70      /***
71       * Load the configuration from the specified stream, using the default
72       * platform specific encoding.
73       *
74       * @param in the input stream
75       *
76       * @throws ConfigurationException
77       */
78      void load(InputStream in) throws ConfigurationException;
79  
80      /***
81       * Load the configuration from the specified stream, using the specified
82       * encoding. If the encoding is null the default encoding is used.
83       *
84       * @param in the input stream
85       * @param encoding the encoding used. <code>null</code> to use the default encoding
86       *
87       * @throws ConfigurationException
88       */
89      void load(InputStream in, String encoding) throws ConfigurationException;
90  
91      /***
92       * Load the configuration from the specified reader.
93       *
94       * @param in the reader
95       *
96       * @throws ConfigurationException
97       */
98      void load(Reader in) throws ConfigurationException;
99  
100     /***
101      * Save the configuration.
102      *
103      * @throws ConfigurationException
104      */
105     void save() throws ConfigurationException;
106 
107     /***
108      * Save the configuration to the specified file.
109      *
110      * @param fileName
111      *
112      * @throws ConfigurationException
113      */
114     void save(String fileName) throws ConfigurationException;
115 
116     /***
117      * Save the configuration to the specified file.
118      *
119      * @param file
120      *
121      * @throws ConfigurationException
122      */
123     void save(File file) throws ConfigurationException;
124 
125     /***
126      * Save the configuration to the specified URL if it's a file URL.
127      *
128      * @param url
129      *
130      * @throws ConfigurationException
131      */
132     void save(URL url) throws ConfigurationException;
133 
134     /***
135      * Save the configuration to the specified stream.
136      *
137      * @param out
138      *
139      * @throws ConfigurationException
140      */
141     void save(OutputStream out) throws ConfigurationException;
142 
143     /***
144      * Save the configuration to the specified stream, using the specified
145      * encoding. If the encoding is null the default encoding is used.
146      *
147      * @param out
148      * @param encoding
149      * @throws ConfigurationException
150      */
151     void save(OutputStream out, String encoding) throws ConfigurationException;
152 
153     /***
154      * Save the configuration to the specified writer.
155      *
156      * @param out the writer
157      *
158      * @throws ConfigurationException
159      */
160     void save(Writer out) throws ConfigurationException;
161 
162     /***
163      * Return the name of the file.
164      */
165     String getFileName();
166 
167     /***
168      * Set the name of the file.
169      *
170      * @param fileName the name of the file
171      */
172     void setFileName(String fileName);
173 
174     /***
175      * Return the base path.
176      */
177     String getBasePath();
178 
179     /***
180      * Set the base path. Relative configurations are loaded from this path.
181      *
182      * @param basePath the base path.
183      */
184     void setBasePath(String basePath);
185 
186     /***
187      * Return the file where the configuration is stored.
188      */
189     File getFile();
190 
191     /***
192      * Set the file where the configuration is stored.
193      *
194      * @param file
195      */
196     void setFile(File file);
197 
198     /***
199      * Return the URL where the configuration is stored.
200      */
201     URL getURL();
202 
203     /***
204      * The URL where the configuration is stored.
205      *
206      * @param url
207      */
208     void setURL(URL url);
209 
210 }