## org.apache.commons.configuration
Class AbstractFileConfiguration

    java.lang.Object
      org.apache.commons.configuration.event.EventSource
          org.apache.commons.configuration.AbstractConfiguration
              org.apache.commons.configuration.BaseConfiguration
                  org.apache.commons.configuration.AbstractFileConfiguration

All Implemented Interfaces:
  Cloneable, Configuration, FileConfiguration

Direct Known Subclasses:
  AbstractHierarchicalFileConfiguration.FileConfigurationDelegate, PropertiesConfiguration

    public abstract class AbstractFileConfiguration

extends BaseConfiguration
implements FileConfiguration

Partial implementation of the `FileConfiguration` interface. Developpers of file based configuration may want to extend this class, the two methods left to implement are ``FileConfiguration.load(Reader)`` and ``FileConfiguration.save(Writer)`.`

This base class already implements a couple of ways to specify the location of the file this configuration is based on. The following possibilities exist:

- URLs: With the method `setURL()` a full URL to the configuration source can be specified. This is the most flexible way. Note that the `save()` methods support only file: URLs.
- Files: The `setFile()` method allows to specify the configuration source as a file. This can be either a relative or an absolute file. In the former case the file is resolved based on the current directory.
- As file paths in string form: With the `setPath()` method a full path to a configuration file can be provided as a string.
- Separated as base path and file name: This is the native form in which the location is stored. The base path is a string defining either a local directory or a URL. It can be set using the `setBasePath()` method. The file name, non surprisingly, defines the name of the configuration file.

Note that the `load()` methods do not wipe out the configuration's content before the new configuration file is loaded. Thus it is very easy to construct a union configuration by simply loading multiple configuration files, e.g.

     config.load(configFile1);
     config.load(configFile2);

After executing this code fragment, the resulting configuration will contain both the properties of configFile1 and configFile2. On the other hand, if the current configuration file is to be reloaded, `clear()` should be called first. Otherwise the properties are doubled. This behavior is analogous to the behavior of the `load(InputStream)` method in `java.util.Properties`.

Since:
  1.0-rc2
Version:
  $Revision: 439648 $, $Date: 2006-09-02 22:42:10 +0200 (Sa, 02 Sep 2006) $
Author:
  Emmanuel Bourg

Field Summary
`protected boolean` `autoSave` The auto save flag.
`protected String` `basePath` Stores the base path.
`static int` `EVENT_RELOAD` Constant for the configuration reload event.
`protected String` `fileName` Stores the file name.
`protected ReloadingStrategy` `strategy` Holds a reference to the reloading strategy.

Fields inherited from class org.apache.commons.configuration.AbstractConfiguration
`END_TOKEN, EVENT_ADD_PROPERTY, EVENT_CLEAR, EVENT_CLEAR_PROPERTY, EVENT_SET_PROPERTY, START_TOKEN`

Constructor Summary
`AbstractFileConfiguration()` Default constructor
`AbstractFileConfiguration(File file)` Creates and loads the configuration from the specified file.
`AbstractFileConfiguration(String fileName)` Creates and loads the configuration from the specified file.
`AbstractFileConfiguration(URL url)` Creates and loads the configuration from the specified URL.

Method Summary
`void` `addProperty(String key, Object value)` Adds a new property to this configuration.
`void` `clearProperty(String key)` Removes the specified property from this configuration.
`Object` `clone()` Creates a copy of this configuration.
`boolean` `containsKey(String key)` check if the configuration contains the key
`protected void` `enterNoReload()` Enters the "No reloading mode".
`protected void` `exitNoReload()` Leaves the "No reloading mode".
`protected void` `fireEvent(int type, String propName, Object propValue, boolean before)` Sends an event to all registered listeners.
`String` `getBasePath()` Return the base path.
`String` `getEncoding()` Return the encoding used to store the configuration file.
`File` `getFile()` Return the file where the configuration is stored.
`String` `getFileName()` Return the name of the file.
`Iterator` `getKeys()` Get the list of the keys contained in the configuration repository.
`String` `getPath()` Returns the full path to the file this configuration is based on.
`Object` `getProperty(String key)` Read property from underlying map.
`ReloadingStrategy` `getReloadingStrategy()` Return the reloading strategy.
`URL` `getURL()` Return the URL where the configuration is stored.
`boolean` `isAutoSave()` Tells if properties are automatically saved to the disk.
`boolean` `isEmpty()` Check if the configuration is empty
`void` `load()` Load the configuration from the underlying location.
`void` `load(File file)` Load the configuration from the specified file.
`void` `load(InputStream in)` Load the configuration from the specified stream, using the encoding returned by `getEncoding()`.
`void` `load(InputStream in, String encoding)` Load the configuration from the specified stream, using the specified encoding.
`void` `load(String fileName)` Locate the specified file and load the configuration.
`void` `load(URL url)` Load the configuration from the specified URL.
`protected void` `possiblySave()` Save the configuration if the automatic persistence is enabled and if a file is specified.
`void` `reload()` Reload the configuration.
`void` `save()` Save the configuration.
`void` `save(File file)` Save the configuration to the specified file.
`void` `save(OutputStream out)` Save the configuration to the specified stream, using the encoding returned by `getEncoding()`.
`void` `save(OutputStream out, String encoding)` Save the configuration to the specified stream, using the specified encoding.
`void` `save(String fileName)` Save the configuration to the specified file.
`void` `save(URL url)` Save the configuration to the specified URL if it's a file URL.
`void` `setAutoSave(boolean autoSave)` Enable or disable the automatical saving of modified properties to the disk.
`void` `setBasePath(String basePath)` Set the base path.
`void` `setEncoding(String encoding)` Set the encoding used to store the configuration file.
`void` `setFile(File file)` Set the file where the configuration is stored.
`void` `setFileName(String fileName)` Set the name of the file.
`void` `setPath(String path)` Sets the location of this configuration as a full or relative path name.
`void` `setProperty(String key, Object value)` Sets a new value for the specified property.
`void` `setReloadingStrategy(ReloadingStrategy strategy)` Set the reloading strategy.
`void` `setURL(URL url)` Set the location of this configuration as a URL.

Methods inherited from class org.apache.commons.configuration.BaseConfiguration
`addPropertyDirect, clear, clearPropertyDirect`

Methods inherited from class org.apache.commons.configuration.AbstractConfiguration

`getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDefaultListDelimiter, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getKeys, getList, getList, getListDelimiter, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, interpolate, interpolate, interpolateHelper, isDelimiterParsingDisabled, isThrowExceptionOnMissing, resolveContainerStore, setDefaultListDelimiter, setDelimiter, setDelimiterParsingDisabled, setListDelimiter, setThrowExceptionOnMissing, subset`

Methods inherited from class org.apache.commons.configuration.event.EventSource
`addConfigurationListener, clearConfigurationListeners, createEvent, getConfigurationListeners, isDetailEvents, removeConfigurationListener, setDetailEvents`

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface org.apache.commons.configuration.FileConfiguration
`load, save`

Methods inherited from interface org.apache.commons.configuration.Configuration
`clear, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getKeys, getList, getList, getLong, getLong, getLong, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, subset`

Field Detail

### EVENT_RELOAD

    public static final int EVENT_RELOAD

  Constant for the configuration reload event.

  See Also:
    Constant Field Values

### fileName

    protected String fileName

  Stores the file name.

### basePath

    protected String basePath

  Stores the base path.

### autoSave

    protected boolean autoSave

  The auto save flag.

### strategy

    protected ReloadingStrategy strategy

  Holds a reference to the reloading strategy.

Constructor Detail

### AbstractFileConfiguration

    public AbstractFileConfiguration()

  Default constructor

  Since:
    1.1

### AbstractFileConfiguration

    public AbstractFileConfiguration(String fileName)
                              throws ConfigurationException

  Creates and loads the configuration from the specified file. The passed in string must be a valid file name, either absolute or relativ.

  Parameters:
    `fileName` - The name of the file to load.
  Throws:
    `ConfigurationException` - Error while loading the file
  Since:
    1.1

### AbstractFileConfiguration

    public AbstractFileConfiguration(File file)
                              throws ConfigurationException

  Creates and loads the configuration from the specified file.

  Parameters:
    `file` - The file to load.
  Throws:
    `ConfigurationException` - Error while loading the file
  Since:
    1.1

### AbstractFileConfiguration

    public AbstractFileConfiguration(URL url)
                              throws ConfigurationException

  Creates and loads the configuration from the specified URL.

  Parameters:
    `url` - The location of the file to load.
  Throws:
    `ConfigurationException` - Error while loading the file
  Since:
    1.1

Method Detail

### load

    public void load()
              throws ConfigurationException

  Load the configuration from the underlying location.

  Specified by:
    `load` in interface `FileConfiguration`
  Throws:
    `ConfigurationException` - if loading of the configuration fails

### load

    public void load(String fileName)
              throws ConfigurationException

  Locate the specified file and load the configuration. This does not change the source of the configuration (i.e. the internally maintained file name). Use one of the setter methods for this purpose.

  Specified by:
    `load` in interface `FileConfiguration`
  Parameters:
    `fileName` - the name of the file to be loaded
  Throws:
    `ConfigurationException` - if an error occurs

### load

    public void load(File file)
              throws ConfigurationException

  Load the configuration from the specified file. This does not change the source of the configuration (i.e. the internally maintained file name). Use one of the setter methods for this purpose.

  Specified by:
    `load` in interface `FileConfiguration`
  Parameters:
    `file` - the file to load
  Throws:
    `ConfigurationException` - if an error occurs

### load

    public void load(URL url)
              throws ConfigurationException

  Load the configuration from the specified URL. This does not change the source of the configuration (i.e. the internally maintained file name). Use on of the setter methods for this purpose.

  Specified by:
    `load` in interface `FileConfiguration`
  Parameters:
    `url` - the URL of the file to be loaded
  Throws:
    `ConfigurationException` - if an error occurs

### load

    public void load(InputStream in)
              throws ConfigurationException

  Load the configuration from the specified stream, using the encoding returned by `getEncoding()`.

  Specified by:
    `load` in interface `FileConfiguration`
  Parameters:
    `in` - the input stream
  Throws:
    `ConfigurationException` - if an error occurs during the load operation

### load

    public void load(InputStream in,
                     String encoding)
              throws ConfigurationException

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

  Specified by:
    `load` in interface `FileConfiguration`
  Parameters:
    `in` - the input stream
    `encoding` - the encoding used. `null` to use the default encoding
  Throws:
    `ConfigurationException` - if an error occurs during the load operation

### save

    public void save()
              throws ConfigurationException

  Save the configuration. Before this method can be called a valid file name must have been set.

  Specified by:
    `save` in interface `FileConfiguration`
  Throws:
    `ConfigurationException` - if an error occurs or no file name has been set yet

### save

    public void save(String fileName)
              throws ConfigurationException

  Save the configuration to the specified file. This doesn't change the source of the configuration, use setFileName() if you need it.

  Specified by:
    `save` in interface `FileConfiguration`
  Parameters:
    `fileName` - the file name
  Throws:
    `ConfigurationException` - if an error occurs during the save operation

### save

    public void save(URL url)
              throws ConfigurationException

  Save the configuration to the specified URL if it's a file URL. This doesn't change the source of the configuration, use setURL() if you need it.

  Specified by:
    `save` in interface `FileConfiguration`
  Parameters:
    `url` - the URL
  Throws:
    `ConfigurationException` - if an error occurs during the save operation

### save

    public void save(File file)
              throws ConfigurationException

  Save the configuration to the specified file. The file is created automatically if it doesn't exist. This doesn't change the source of the configuration, use `setFile(java.io.File)` if you need it.

  Specified by:
    `save` in interface `FileConfiguration`
  Parameters:
    `file` - the target file
  Throws:
    `ConfigurationException` - if an error occurs during the save operation

### save

    public void save(OutputStream out)
              throws ConfigurationException

  Save the configuration to the specified stream, using the encoding returned by `getEncoding()`.

  Specified by:
    `save` in interface `FileConfiguration`
  Parameters:
    `out` - the output stream
  Throws:
    `ConfigurationException` - if an error occurs during the save operation

### save

    public void save(OutputStream out,
                     String encoding)
              throws ConfigurationException

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

  Specified by:
    `save` in interface `FileConfiguration`
  Parameters:
    `out` - the output stream
    `encoding` - the encoding to use
  Throws:
    `ConfigurationException` - if an error occurs during the save operation

### getFileName

    public String getFileName()

  Return the name of the file.

  Specified by:
    `getFileName` in interface `FileConfiguration`
  Returns:
    the file name

### setFileName

    public void setFileName(String fileName)

  Set the name of the file. The passed in file name can contain a relative path. It must be used when referring files with relative paths from classpath. Use ``setPath()`` to set a full qualified file name.

  Specified by:
    `setFileName` in interface `FileConfiguration`
  Parameters:
    `fileName` - the name of the file

### getBasePath

    public String getBasePath()

  Return the base path.

  Specified by:
    `getBasePath` in interface `FileConfiguration`
  Returns:
    the base path

### setBasePath

    public void setBasePath(String basePath)

  Set the base path. Relative configurations are loaded from this path. The base path can be either a path to a directory or a URL.

  Specified by:
    `setBasePath` in interface `FileConfiguration`
  Parameters:
    `basePath` - the base path.

### getFile

    public File getFile()

  Return the file where the configuration is stored. If the base path is a URL with a protocol different than "file", or the configuration file is within a compressed archive, the return value will not point to a valid file object.

  Specified by:
    `getFile` in interface `FileConfiguration`
  Returns:
    the file where the configuration is stored; this can be null

### setFile

    public void setFile(File file)

  Set the file where the configuration is stored. The passed in file is made absolute if it is not yet. Then the file's path component becomes the base path and its name component becomes the file name.

  Specified by:
    `setFile` in interface `FileConfiguration`
  Parameters:
    `file` - the file where the configuration is stored

### getPath

    public String getPath()

  Returns the full path to the file this configuration is based on. The return value is a valid File path only if this configuration is based on a file on the local disk. If the configuration was loaded from a packed archive the returned value is the string form of the URL from which the configuration was loaded.

  Returns:
    the full path to the configuration file

### setPath

    public void setPath(String path)

  Sets the location of this configuration as a full or relative path name. The passed in path should represent a valid file name on the file system. It must not be used to specify relative paths for files that exist in classpath, either plain file system or compressed archive, because this method expands any relative path to an absolute one which may end in an invalid absolute path for classpath references.

  Parameters:
    `path` - the full path name of the configuration file

### getURL

    public URL getURL()

  Return the URL where the configuration is stored.

  Specified by:
    `getURL` in interface `FileConfiguration`
  Returns:
    the configuration's location as URL

### setURL

    public void setURL(URL url)

  Set the location of this configuration as a URL. For loading this can be an arbitrary URL with a supported protocol. If the configuration is to be saved, too, a URL with the "file" protocol should be provided.

  Specified by:
    `setURL` in interface `FileConfiguration`
  Parameters:
    `url` - the location of this configuration as URL

### setAutoSave

    public void setAutoSave(boolean autoSave)

  Description copied from interface: `FileConfiguration`
  Enable or disable the automatical saving of modified properties to the disk.

  Specified by:
    `setAutoSave` in interface `FileConfiguration`
  Parameters:
    `autoSave` - `true` to enable, `false` to disable

### isAutoSave

    public boolean isAutoSave()

  Description copied from interface: `FileConfiguration`
  Tells if properties are automatically saved to the disk.

  Specified by:
    `isAutoSave` in interface `FileConfiguration`
  Returns:
    `true` if auto-saving is enabled, `false` otherwise

### possiblySave

    protected void possiblySave()

  Save the configuration if the automatic persistence is enabled and if a file is specified.

### addProperty

    public void addProperty(String key,
                            Object value)

  Adds a new property to this configuration. This implementation checks if the auto save mode is enabled and saves the configuration if necessary.

  Specified by:
    `addProperty` in interface `Configuration`
  Overrides:
    `addProperty` in class `AbstractConfiguration`
  Parameters:
    `key` - the key of the new property
    `value` - the value

### setProperty

    public void setProperty(String key,
                            Object value)

  Sets a new value for the specified property. This implementation checks if the auto save mode is enabled and saves the configuration if necessary.

  Specified by:
    `setProperty` in interface `Configuration`
  Overrides:
    `setProperty` in class `AbstractConfiguration`
  Parameters:
    `key` - the key of the affected property
    `value` - the value

### clearProperty

    public void clearProperty(String key)

  Description copied from class: `AbstractConfiguration`
  Removes the specified property from this configuration. This implementation performs some preparations and then delegates to `clearPropertyDirect()`, which will do the real work.

  Specified by:
    `clearProperty` in interface `Configuration`
  Overrides:
    `clearProperty` in class `AbstractConfiguration`
  Parameters:
    `key` - the key to be removed

### getReloadingStrategy

    public ReloadingStrategy getReloadingStrategy()

  Description copied from interface: `FileConfiguration`
  Return the reloading strategy.

  Specified by:
    `getReloadingStrategy` in interface `FileConfiguration`
  Returns:
    the reloading strategy currently used

### setReloadingStrategy

    public void setReloadingStrategy(ReloadingStrategy strategy)

  Description copied from interface: `FileConfiguration`
  Set the reloading strategy.

  Specified by:
    `setReloadingStrategy` in interface `FileConfiguration`
  Parameters:
    `strategy` - the reloading strategy to use

### reload

    public void reload()

  Description copied from interface: `FileConfiguration`
  Reload the configuration.

  Specified by:
    `reload` in interface `FileConfiguration`

### enterNoReload

    protected void enterNoReload()

  Enters the "No reloading mode". As long as this mode is active no reloading will be performed. This is necessary for some implementations of `save()` in derived classes, which may cause a reload while accessing the properties to save. This may cause the whole configuration to be erased. To avoid this, this method can be called first. After a call to this method there always must be a corresponding call of ``exitNoReload()`` later! (If necessary, `finally` blocks must be used to ensure this.

### exitNoReload

    protected void exitNoReload()

  Leaves the "No reloading mode".

  See Also:
    `enterNoReload()`

### fireEvent

    protected void fireEvent(int type,
                             String propName,
                             Object propValue,
                             boolean before)

  Sends an event to all registered listeners. This implementation ensures that no reloads are performed while the listeners are invoked. So infinite loops can be avoided that can be caused by event listeners accessing the configuration's properties when they are invoked.

  Overrides:
    `fireEvent` in class `EventSource`
  Parameters:
    `type` - the event type
    `propName` - the name of the property
    `propValue` - the value of the property
    `before` - the before update flag

### getProperty

    public Object getProperty(String key)

  Description copied from class: `BaseConfiguration`
  Read property from underlying map.

  Specified by:
    `getProperty` in interface `Configuration`
  Overrides:
    `getProperty` in class `BaseConfiguration`
  Parameters:
    `key` - key to use for mapping
  Returns:
    object associated with the given configuration key.

### isEmpty

    public boolean isEmpty()

  Description copied from class: `BaseConfiguration`
  Check if the configuration is empty

  Specified by:
    `isEmpty` in interface `Configuration`
  Overrides:
    `isEmpty` in class `BaseConfiguration`
  Returns:
    `true` if Configuration is empty, `false` otherwise.

### containsKey

    public boolean containsKey(String key)

  Description copied from class: `BaseConfiguration`
  check if the configuration contains the key

  Specified by:
    `containsKey` in interface `Configuration`
  Overrides:
    `containsKey` in class `BaseConfiguration`
  Parameters:
    `key` - the configuration key
  Returns:
    `true` if Configuration contain given key, `false` otherwise.

### getKeys

    public Iterator getKeys()

  Description copied from class: `BaseConfiguration`
  Get the list of the keys contained in the configuration repository.

  Specified by:
    `getKeys` in interface `Configuration`
  Overrides:
    `getKeys` in class `BaseConfiguration`
  Returns:
    An Iterator.

### getEncoding

    public String getEncoding()

  Description copied from interface: `FileConfiguration`
  Return the encoding used to store the configuration file. If the value is null the default encoding is used.

  Specified by:
    `getEncoding` in interface `FileConfiguration`
  Returns:
    the current encoding

### setEncoding

    public void setEncoding(String encoding)

  Description copied from interface: `FileConfiguration`
  Set the encoding used to store the configuration file. Set the encoding to null to use the default encoding.

  Specified by:
    `setEncoding` in interface `FileConfiguration`
  Parameters:
    `encoding` - the encoding to use

### clone

    public Object clone()

  Creates a copy of this configuration. The new configuration object will contain the same properties as the original, but it will lose any connection to a source file (if one exists); this includes setting the source URL, base path, and file name to null. This is done to avoid race conditions if both the original and the copy are modified and then saved.

  Overrides:
    `clone` in class `BaseConfiguration`
  Returns:
    the copy
  Since:
    1.3

Copyright © 2001-2006 The Apache Software Foundation. All Rights Reserved.