001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package org.apache.commons.configuration;
019:
020: import java.net.URL;
021: import java.io.InputStream;
022: import java.io.Reader;
023: import java.io.OutputStream;
024: import java.io.Writer;
025: import java.io.File;
026:
027: import org.apache.commons.configuration.reloading.ReloadingStrategy;
028:
029: /**
030: * A persistent configuration loaded and saved to a file.
031: *
032: * @author Emmanuel Bourg
033: * @version $Revision: 492234 $, $Date: 2007-01-03 18:39:39 +0100 (Mi, 03 Jan 2007) $
034: * @since 1.0-rc2
035: */
036: public interface FileConfiguration extends Configuration {
037: /**
038: * Load the configuration from the underlying URL. If the URL is not
039: * specified, it attempts to locate the specified file name.
040: *
041: * @throws ConfigurationException if an error occurs during the load operation
042: */
043: void load() throws ConfigurationException;
044:
045: /**
046: * Locate the specified file and load the configuration.
047: *
048: * @param fileName the name of the file loaded
049: *
050: * @throws ConfigurationException if an error occurs during the load operation
051: */
052: void load(String fileName) throws ConfigurationException;
053:
054: /**
055: * Load the configuration from the specified file.
056: *
057: * @param file the loaded file
058: *
059: * @throws ConfigurationException if an error occurs during the load operation
060: */
061: void load(File file) throws ConfigurationException;
062:
063: /**
064: * Load the configuration from the specified URL.
065: *
066: * @param url the URL of the file loaded
067: *
068: * @throws ConfigurationException if an error occurs during the load operation
069: */
070: void load(URL url) throws ConfigurationException;
071:
072: /**
073: * Load the configuration from the specified stream, using the encoding
074: * returned by {@link #getEncoding()}.
075: *
076: * @param in the input stream
077: *
078: * @throws ConfigurationException if an error occurs during the load operation
079: */
080: void load(InputStream in) throws ConfigurationException;
081:
082: /**
083: * Load the configuration from the specified stream, using the specified
084: * encoding. If the encoding is null the default encoding is used.
085: *
086: * @param in the input stream
087: * @param encoding the encoding used. <code>null</code> to use the default encoding
088: *
089: * @throws ConfigurationException if an error occurs during the load operation
090: */
091: void load(InputStream in, String encoding)
092: throws ConfigurationException;
093:
094: /**
095: * Load the configuration from the specified reader.
096: *
097: * @param in the reader
098: *
099: * @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)
156: throws ConfigurationException;
157:
158: /**
159: * Save the configuration to the specified writer.
160: *
161: * @param out the writer
162: *
163: * @throws ConfigurationException if an error occurs during the save operation
164: */
165: void save(Writer out) throws ConfigurationException;
166:
167: /**
168: * Return the name of the file.
169: *
170: * @return the file name
171: */
172: String getFileName();
173:
174: /**
175: * Set the name of the file.
176: *
177: * @param fileName the name of the file
178: */
179: void setFileName(String fileName);
180:
181: /**
182: * Returns the base path. One way to specify the location of a configuration
183: * source is by setting its base path and its file name. This method returns
184: * this base path. The concrete value returned by this method depends on the
185: * way the location of the configuration file was set. If methods like
186: * <code>setFile()</code> or <code>setURL()</code> were used, the base
187: * path typically points to the parent directory of the configuration file
188: * (e.g. for the URL <code>file:/temp/test.properties</code> the base path
189: * will be <code>file:/temp/</code>). If the base path was explictly set
190: * using <code>setBasePath()</code>, this method will return the exact
191: * value specified here without further modifications.
192: *
193: * @return the base path
194: * @see AbstractFileConfiguration#setBasePath(String)
195: */
196: String getBasePath();
197:
198: /**
199: * Sets the base path. The methods <code>setBasePath()</code> and
200: * <code>setFileName()</code> can be used together to specify the location
201: * of the configuration file to be loaded. If relative file names are to
202: * be resolved (e.g. for the include files supported by
203: * <code>PropertiesConfiguration</code>), this base path will be used.
204: *
205: * @param basePath the base path.
206: */
207: void setBasePath(String basePath);
208:
209: /**
210: * Return the file where the configuration is stored.
211: *
212: * @return the configuration file
213: */
214: File getFile();
215:
216: /**
217: * Set the file where the configuration is stored.
218: *
219: * @param file the file
220: */
221: void setFile(File file);
222:
223: /**
224: * Return the URL where the configuration is stored.
225: *
226: * @return the URL of the configuration
227: */
228: URL getURL();
229:
230: /**
231: * The URL where the configuration is stored.
232: *
233: * @param url the URL
234: */
235: void setURL(URL url);
236:
237: /**
238: * Enable or disable the automatical saving of modified properties to the disk.
239: *
240: * @param autoSave <code>true</code> to enable, <code>false</code> to disable
241: * @since 1.1
242: */
243: void setAutoSave(boolean autoSave);
244:
245: /**
246: * Tells if properties are automatically saved to the disk.
247: *
248: * @return <code>true</code> if auto-saving is enabled, <code>false</code> otherwise
249: * @since 1.1
250: */
251: boolean isAutoSave();
252:
253: /**
254: * Return the reloading strategy.
255: *
256: * @return the reloading strategy currently used
257: * @since 1.1
258: */
259: ReloadingStrategy getReloadingStrategy();
260:
261: /**
262: * Set the reloading strategy.
263: *
264: * @param strategy the reloading strategy to use
265: * @since 1.1
266: */
267: void setReloadingStrategy(ReloadingStrategy strategy);
268:
269: /**
270: * Reload the configuration.
271: *
272: * @since 1.1
273: */
274: void reload();
275:
276: /**
277: * Return the encoding used to store the configuration file. If the value
278: * is null the default encoding is used.
279: *
280: * @return the current encoding
281: * @since 1.1
282: */
283: String getEncoding();
284:
285: /**
286: * Set the encoding used to store the configuration file. Set the encoding
287: * to null to use the default encoding.
288: *
289: * @param encoding the encoding to use
290: * @since 1.1
291: */
292: void setEncoding(String encoding);
293:
294: }
|