http://commons.apache.org/configuration/: Tools to assist in the reading of configuration/preferences files in various formats. (The Apache Software Foundation)
  • Konstantin Shaposhnikov (scand.com)
  • Jamie M. Guillemette (TD Bank)
  • Jorge Ferrer ()
  • Gabriele Garuglieri (Infoblu S.p.A)
  • Nicolas De Loof (Cap Gemini)
  • Daniel Rall (CollabNet, Inc.)
  • Jason van Zyl (Zenplex)
  • Martin Poeschl (tucana.at)
  • dIon Gillard (Multitask Consulting)
  • Henning P. Schmiedehausen
  • Eric Pugh (upstate.com)
  • Brian E. Dunbar (dunbarconsulting.org)
  • Emmanuel Bourg (Ariane Software)
  • Oliver Heger (Agfa HealthCare)
  • Jörg Schaible
  • Ralph Goers (Intuit) 
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.commons.configuration;

import java.io.File;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.Reader;
import java.io.Writer;
import java.net.URL;

import org.apache.commons.configuration.reloading.ReloadingStrategy;


A persistent configuration loaded and saved to a file.

Author:Emmanuel Bourg
Version:$Id: FileConfiguration.java 1209883 2011-12-03 10:56:57Z oheger $
Since:1.0-rc2
/**
 * A persistent configuration loaded and saved to a file.
 *
 * @author Emmanuel Bourg
 * @version $Id: FileConfiguration.java 1209883 2011-12-03 10:56:57Z oheger $
 * @since 1.0-rc2
 */
public interface FileConfiguration extends Configuration
{
    
Load the configuration from the underlying URL. If the URL is not
specified, it attempts to locate the specified file name.

Throws:
  • ConfigurationException – if an error occurs during the load operation
/**
     * Load the configuration from the underlying URL. If the URL is not
     * specified, it attempts to locate the specified file name.
     *
     * @throws ConfigurationException if an error occurs during the load operation
     */
    void load() throws ConfigurationException;

    
Locate the specified file and load the configuration.

Params:
  • fileName – the name of the file loaded
Throws:
/**
     * Locate the specified file and load the configuration.
     *
     * @param fileName the name of the file loaded
     *
     * @throws ConfigurationException if an error occurs during the load operation
     */
    void load(String fileName) throws ConfigurationException;

    
Load the configuration from the specified file.

Params:
  • file – the loaded file
Throws:
/**
     * Load the configuration from the specified file.
     *
     * @param file the loaded file
     *
     * @throws ConfigurationException if an error occurs during the load operation
     */
    void load(File file) throws ConfigurationException;

    
Load the configuration from the specified URL.

Params:
  • url – the URL of the file loaded
Throws:
/**
     * Load the configuration from the specified URL.
     *
     * @param url the URL of the file loaded
     *
     * @throws ConfigurationException if an error occurs during the load operation
     */
    void load(URL url) throws ConfigurationException;

    
Load the configuration from the specified stream, using the encoding returned by getEncoding(). 
Params:
  • in – the input stream
Throws:
/**
     * Load the configuration from the specified stream, using the encoding
     * returned by {@link #getEncoding()}.
     *
     * @param in the input stream
     *
     * @throws ConfigurationException if an error occurs during the load operation
     */
    void load(InputStream in) throws ConfigurationException;

    
Load the configuration from the specified stream, using the specified
encoding. If the encoding is null the default encoding is used.

Params:
  • in – the input stream
  • encoding – the encoding used. null to use the default encoding
Throws:
/**
     * Load the configuration from the specified stream, using the specified
     * encoding. If the encoding is null the default encoding is used.
     *
     * @param in the input stream
     * @param encoding the encoding used. {@code null} to use the default encoding
     *
     * @throws ConfigurationException if an error occurs during the load operation
     */
    void load(InputStream in, String encoding) throws ConfigurationException;

    
Load the configuration from the specified reader.

Params:
  • in – the reader
Throws:
/**
     * Load the configuration from the specified reader.
     *
     * @param in the reader
     *
     * @throws ConfigurationException if an error occurs during the load operation
     */
    void load(Reader in) throws ConfigurationException;

    
Save the configuration.

Throws:
  • ConfigurationException – if an error occurs during the save operation
/**
     * Save the configuration.
     *
     * @throws ConfigurationException if an error occurs during the save operation
     */
    void save() throws ConfigurationException;

    
Save the configuration to the specified file.

Params:
  • fileName – the name of the file to be saved
Throws:
/**
     * Save the configuration to the specified file.
     *
     * @param fileName the name of the file to be saved
     *
     * @throws ConfigurationException if an error occurs during the save operation
     */
    void save(String fileName) throws ConfigurationException;

    
Save the configuration to the specified file.

Params:
  • file – specifies the file to be saved
Throws:
/**
     * Save the configuration to the specified file.
     *
     * @param file specifies the file to be saved
     *
     * @throws ConfigurationException if an error occurs during the save operation
     */
    void save(File file) throws ConfigurationException;

    
Save the configuration to the specified URL.

Params:
  • url – the URL
Throws:
/**
     * Save the configuration to the specified URL.
     *
     * @param url the URL
     *
     * @throws ConfigurationException if an error occurs during the save operation
     */
    void save(URL url) throws ConfigurationException;

    
Save the configuration to the specified stream, using the encoding returned by getEncoding(). 
Params:
  • out – the output stream
Throws:
/**
     * Save the configuration to the specified stream, using the encoding
     * returned by {@link #getEncoding()}.
     *
     * @param out the output stream
     *
     * @throws ConfigurationException if an error occurs during the save operation
     */
    void save(OutputStream out) throws ConfigurationException;

    
Save the configuration to the specified stream, using the specified
encoding. If the encoding is null the default encoding is used.

Params:
  • out – the output stream
  • encoding – the encoding to be used
Throws:
/**
     * Save the configuration to the specified stream, using the specified
     * encoding. If the encoding is null the default encoding is used.
     *
     * @param out the output stream
     * @param encoding the encoding to be used
     * @throws ConfigurationException if an error occurs during the save operation
     */
    void save(OutputStream out, String encoding) throws ConfigurationException;

    
Save the configuration to the specified writer.

Params:
  • out – the writer
Throws:
/**
     * Save the configuration to the specified writer.
     *
     * @param out the writer
     *
     * @throws ConfigurationException if an error occurs during the save operation
     */
    void save(Writer out) throws ConfigurationException;

    
Return the name of the file.

Returns:the file name
/**
     * Return the name of the file.
     *
     * @return the file name
     */
    String getFileName();

    
Set the name of the file.

Params:
  • fileName – the name of the file
/**
     * Set the name of the file.
     *
     * @param fileName the name of the file
     */
    void setFileName(String fileName);

    
Returns the base path. One way to specify the location of a configuration source is by setting its base path and its file name. This method returns this base path. The concrete value returned by this method depends on the way the location of the configuration file was set. If methods like setFile() or setURL() were used, the base path typically points to the parent directory of the configuration file (e.g. for the URL file:/temp/test.properties the base path will be file:/temp/). If the base path was explicitly set using setBasePath(), this method will return the exact value specified here without further modifications. 
See Also:
Returns:the base path
/**
     * Returns the base path. One way to specify the location of a configuration
     * source is by setting its base path and its file name. This method returns
     * this base path. The concrete value returned by this method depends on the
     * way the location of the configuration file was set. If methods like
     * {@code setFile()} or {@code setURL()} were used, the base
     * path typically points to the parent directory of the configuration file
     * (e.g. for the URL {@code file:/temp/test.properties} the base path
     * will be {@code file:/temp/}). If the base path was explicitly set
     * using {@code setBasePath()}, this method will return the exact
     * value specified here without further modifications.
     *
     * @return the base path
     * @see AbstractFileConfiguration#setBasePath(String)
     */
    String getBasePath();

    
Sets the base path. The methods setBasePath() and setFileName() can be used together to specify the location of the configuration file to be loaded. If relative file names are to be resolved (e.g. for the include files supported by PropertiesConfiguration), this base path will be used. 
Params:
  • basePath – the base path.
/**
     * Sets the base path. The methods {@code setBasePath()} and
     * {@code setFileName()} can be used together to specify the location
     * of the configuration file to be loaded. If relative file names are to
     * be resolved (e.g. for the include files supported by
     * {@code PropertiesConfiguration}), this base path will be used.
     *
     * @param basePath the base path.
     */
    void setBasePath(String basePath);

    
Return the file where the configuration is stored.

Returns:the configuration file
/**
     * Return the file where the configuration is stored.
     *
     * @return the configuration file
     */
    File getFile();

    
Set the file where the configuration is stored.

Params:
  • file – the file
/**
     * Set the file where the configuration is stored.
     *
     * @param file the file
     */
    void setFile(File file);

    
Return the URL where the configuration is stored.

Returns:the URL of the configuration
/**
     * Return the URL where the configuration is stored.
     *
     * @return the URL of the configuration
     */
    URL getURL();

    
The URL where the configuration is stored.

Params:
  • url – the URL
/**
     * The URL where the configuration is stored.
     *
     * @param url the URL
     */
    void setURL(URL url);

    
Enable or disable the automatically saving of modified properties to the disk.

Params:
  • autoSave – true to enable, false to disable
Since:1.1
/**
     * Enable or disable the automatically saving of modified properties to the disk.
     *
     * @param autoSave {@code true} to enable, {@code false} to disable
     * @since 1.1
     */
    void setAutoSave(boolean autoSave);

    
Tells if properties are automatically saved to the disk.

Returns:true if auto-saving is enabled, false otherwise
Since:1.1
/**
     * Tells if properties are automatically saved to the disk.
     *
     * @return {@code true} if auto-saving is enabled, {@code false} otherwise
     * @since 1.1
     */
    boolean isAutoSave();

    
Return the reloading strategy.

Returns:the reloading strategy currently used
Since:1.1
/**
     * Return the reloading strategy.
     *
     * @return the reloading strategy currently used
     * @since 1.1
     */
    ReloadingStrategy getReloadingStrategy();

    
Set the reloading strategy.

Params:
  • strategy – the reloading strategy to use
Since:1.1
/**
     * Set the reloading strategy.
     *
     * @param strategy the reloading strategy to use
     * @since 1.1
     */
    void setReloadingStrategy(ReloadingStrategy strategy);

    
Reload the configuration.

Since:1.1
/**
     * Reload the configuration.
     *
     * @since 1.1
     */
    void reload();

    
Return the encoding used to store the configuration file. If the value
is null the default encoding is used.

Returns:the current encoding
Since:1.1
/**
     * Return the encoding used to store the configuration file. If the value
     * is null the default encoding is used.
     *
     * @return the current encoding
     * @since 1.1
     */
    String getEncoding();

    
Set the encoding used to store the configuration file. Set the encoding
to null to use the default encoding.

Params:
  • encoding – the encoding to use
Since:1.1
/**
     * Set the encoding used to store the configuration file. Set the encoding
     * to null to use the default encoding.
     *
     * @param encoding the encoding to use
     * @since 1.1
     */
    void setEncoding(String encoding);

}