## org.apache.commons.configuration
Class AbstractHierarchicalFileConfiguration

    java.lang.Object
      org.apache.commons.configuration.event.EventSource
          org.apache.commons.configuration.AbstractConfiguration
              org.apache.commons.configuration.HierarchicalConfiguration
                  org.apache.commons.configuration.AbstractHierarchicalFileConfiguration

All Implemented Interfaces:
  Serializable, Cloneable, Configuration, ConfigurationListener, FileConfiguration

Direct Known Subclasses:
  PropertyListConfiguration, XMLConfiguration, XMLPropertyListConfiguration

    public abstract class AbstractHierarchicalFileConfiguration

extends HierarchicalConfiguration
implements FileConfiguration, ConfigurationListener

Base class for implementing file based hierarchical configurations.

This class serves an analogous purpose as the ``AbstractFileConfiguration`` class for non hierarchical configurations. It behaves in exactly the same way, so please refer to the documentation of `AbstractFileConfiguration` for further details.

Since:
  1.2
Version:
  $Revision: 439648 $, $Date: 2006-09-02 22:42:10 +0200 (Sa, 02 Sep 2006) $
Author:
  Emmanuel Bourg
See Also:
  Serialized Form

Nested Class Summary
`protected class` `AbstractHierarchicalFileConfiguration.FileConfigurationDelegate` A special implementation of the `FileConfiguration` interface that is used internally to implement the `FileConfiguration` methods for hierarchical configurations.

Nested classes/interfaces inherited from class org.apache.commons.configuration.HierarchicalConfiguration
`HierarchicalConfiguration.BuilderVisitor, HierarchicalConfiguration.CloneVisitor, HierarchicalConfiguration.DefinedKeysVisitor, HierarchicalConfiguration.DefinedVisitor, HierarchicalConfiguration.Node, HierarchicalConfiguration.NodeVisitor`

Field Summary

Fields inherited from class org.apache.commons.configuration.HierarchicalConfiguration
`EVENT_ADD_NODES, EVENT_CLEAR_TREE`

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
`protected` `AbstractHierarchicalFileConfiguration()`
`` `AbstractHierarchicalFileConfiguration(File file)` Creates and loads the configuration from the specified file.
`` `AbstractHierarchicalFileConfiguration(String fileName)` Creates and loads the configuration from the specified file.
`` `AbstractHierarchicalFileConfiguration(URL url)` Creates and loads the configuration from the specified URL.

Method Summary
`protected void` `addPropertyDirect(String key, Object obj)` Adds the property with the specified key.
`void` `clearProperty(String key)` Removes the property with the given key.
`void` `clearTree(String key)` Removes all values of the property with the given name and of keys that start with this name.
`void` `configurationChanged(ConfigurationEvent event)` Reacts on configuration change events triggered by the delegate.
`boolean` `containsKey(String key)` Checks if the specified key is contained in this configuration.
`protected AbstractHierarchicalFileConfiguration.FileConfigurationDelegate` `createDelegate()` Creates the file configuration delegate, i.e. the object that implements functionality required by the `FileConfiguration` interface.
`String` `getBasePath()` Return the base path.
`protected AbstractHierarchicalFileConfiguration.FileConfigurationDelegate` `getDelegate()` Returns the file configuration delegate.
`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(String prefix)` Returns an iterator with all keys defined in this configuration that start with the given prefix.
`Object` `getProperty(String key)` Fetches the specified property.
`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()` Checks if this configuration is empty.
`void` `load()` Load the configuration from the underlying URL.
`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 `FileConfiguration.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.
`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 `FileConfiguration.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.
`protected void` `setDelegate(AbstractHierarchicalFileConfiguration.FileConfigurationDelegate delegate)` Allows to set the file configuration delegate.
`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` `setProperty(String key, Object value)` Sets the value of the specified property.
`void` `setReloadingStrategy(ReloadingStrategy strategy)` Set the reloading strategy.
`void` `setURL(URL url)` The URL where the configuration is stored.

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

`addNodes, clearNode, clearNode, clone, configurationAt, configurationsAt, createAddPath, createNode, createSubnodeConfiguration, fetchAddNode, fetchNodeList, findLastPathNode, findPropertyNodes, getDefaultExpressionEngine, getExpressionEngine, getKeys, getMaxIndex, getRoot, getRootNode, nodeDefined, nodeDefined, removeNode, removeNode, setDefaultExpressionEngine, setExpressionEngine, setRoot, setRootNode, subset`

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

`addProperty, clear, clearPropertyDirect, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDefaultListDelimiter, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, 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`

Methods inherited from class org.apache.commons.configuration.event.EventSource
`addConfigurationListener, clearConfigurationListeners, createEvent, fireEvent, 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
`addProperty, 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`

Constructor Detail

### AbstractHierarchicalFileConfiguration

    protected AbstractHierarchicalFileConfiguration()

### AbstractHierarchicalFileConfiguration

    public AbstractHierarchicalFileConfiguration(String fileName)
                                          throws ConfigurationException

  Creates and loads the configuration from the specified file.

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

### AbstractHierarchicalFileConfiguration

    public AbstractHierarchicalFileConfiguration(File file)
                                          throws ConfigurationException

  Creates and loads the configuration from the specified file.

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

### AbstractHierarchicalFileConfiguration

    public AbstractHierarchicalFileConfiguration(URL url)
                                          throws ConfigurationException

  Creates and loads the configuration from the specified URL.

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

Method Detail

### addPropertyDirect

    protected void addPropertyDirect(String key,
                                     Object obj)

  Description copied from class: `HierarchicalConfiguration`
  Adds the property with the specified key. This task will be delegated to the associated `ExpressionEngine`, so the passed in key must match the requirements of this implementation.

  Overrides:
    `addPropertyDirect` in class `HierarchicalConfiguration`
  Parameters:
    `key` - the key of the new property
    `obj` - the value of the new property

### clearProperty

    public void clearProperty(String key)

  Description copied from class: `HierarchicalConfiguration`
  Removes the property with the given key. Properties with names that start with the given key (i.e. properties below the specified key in the hierarchy) won't be affected.

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

### clearTree

    public void clearTree(String key)

  Description copied from class: `HierarchicalConfiguration`
  Removes all values of the property with the given name and of keys that start with this name. So if there is a property with the key "foo" and a property with the key "foo.bar", a call of `clearTree("foo")` would remove both properties.

  Overrides:
    `clearTree` in class `HierarchicalConfiguration`
  Parameters:
    `key` - the key of the property to be removed

### setProperty

    public void setProperty(String key,
                            Object value)

  Description copied from class: `HierarchicalConfiguration`
  Sets the value of the specified property.

  Specified by:
    `setProperty` in interface `Configuration`
  Overrides:
    `setProperty` in class `HierarchicalConfiguration`
  Parameters:
    `key` - the key of the property to set
    `value` - the new value of this property

### load

    public void load()
              throws ConfigurationException

  Description copied from interface: `FileConfiguration`
  Load the configuration from the underlying URL. If the URL is not specified, it attempts to locate the specified file name.

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

### load

    public void load(String fileName)
              throws ConfigurationException

  Description copied from interface: `FileConfiguration`
  Locate the specified file and load the configuration.

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

### load

    public void load(File file)
              throws ConfigurationException

  Description copied from interface: `FileConfiguration`
  Load the configuration from the specified file.

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

### load

    public void load(URL url)
              throws ConfigurationException

  Description copied from interface: `FileConfiguration`
  Load the configuration from the specified URL.

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

### load

    public void load(InputStream in)
              throws ConfigurationException

  Description copied from interface: `FileConfiguration`
  Load the configuration from the specified stream, using the encoding returned by `FileConfiguration.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

  Description copied from interface: `FileConfiguration`
  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

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

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

### save

    public void save(String fileName)
              throws ConfigurationException

  Description copied from interface: `FileConfiguration`
  Save the configuration to the specified file.

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

### save

    public void save(File file)
              throws ConfigurationException

  Description copied from interface: `FileConfiguration`
  Save the configuration to the specified file.

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

### save

    public void save(URL url)
              throws ConfigurationException

  Description copied from interface: `FileConfiguration`
  Save the configuration to the specified URL if it's a file URL.

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

### save

    public void save(OutputStream out)
              throws ConfigurationException

  Description copied from interface: `FileConfiguration`
  Save the configuration to the specified stream, using the encoding returned by `FileConfiguration.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

  Description copied from interface: `FileConfiguration`
  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 be used
  Throws:
    `ConfigurationException` - if an error occurs during the save operation

### getFileName

    public String getFileName()

  Description copied from interface: `FileConfiguration`
  Return the name of the file.

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

### setFileName

    public void setFileName(String fileName)

  Description copied from interface: `FileConfiguration`
  Set the name of the file.

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

### getBasePath

    public String getBasePath()

  Description copied from interface: `FileConfiguration`
  Return the base path.

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

### setBasePath

    public void setBasePath(String basePath)

  Description copied from interface: `FileConfiguration`
  Set the base path. Relative configurations are loaded from this path.

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

### getFile

    public File getFile()

  Description copied from interface: `FileConfiguration`
  Return the file where the configuration is stored.

  Specified by:
    `getFile` in interface `FileConfiguration`
  Returns:
    the configuration file

### setFile

    public void setFile(File file)

  Description copied from interface: `FileConfiguration`
  Set the file where the configuration is stored.

  Specified by:
    `setFile` in interface `FileConfiguration`
  Parameters:
    `file` - the file

### getURL

    public URL getURL()

  Description copied from interface: `FileConfiguration`
  Return the URL where the configuration is stored.

  Specified by:
    `getURL` in interface `FileConfiguration`
  Returns:
    the URL of the configuration

### setURL

    public void setURL(URL url)

  Description copied from interface: `FileConfiguration`
  The URL where the configuration is stored.

  Specified by:
    `setURL` in interface `FileConfiguration`
  Parameters:
    `url` - the 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

### 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`

### 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

### containsKey

    public boolean containsKey(String key)

  Description copied from class: `HierarchicalConfiguration`
  Checks if the specified key is contained in this configuration. Note that for this configuration the term "contained" means that the key has an associated value. If there is a node for this key that has no value but children (either defined or undefined), this method will still return false .

  Specified by:
    `containsKey` in interface `Configuration`
  Overrides:
    `containsKey` in class `HierarchicalConfiguration`
  Parameters:
    `key` - the key to be chekced
  Returns:
    a flag if this key is contained in this configuration

### getKeys

    public Iterator getKeys(String prefix)

  Description copied from class: `HierarchicalConfiguration`
  Returns an iterator with all keys defined in this configuration that start with the given prefix. The returned keys will not contain any indices.

  Specified by:
    `getKeys` in interface `Configuration`
  Overrides:
    `getKeys` in class `HierarchicalConfiguration`
  Parameters:
    `prefix` - the prefix of the keys to start with
  Returns:
    an iterator with the found keys
  See Also:
    `Configuration.getKeys()`

### getProperty

    public Object getProperty(String key)

  Description copied from class: `HierarchicalConfiguration`
  Fetches the specified property. This task is delegated to the associated expression engine.

  Specified by:
    `getProperty` in interface `Configuration`
  Overrides:
    `getProperty` in class `HierarchicalConfiguration`
  Parameters:
    `key` - the key to be looked up
  Returns:
    the found value

### isEmpty

    public boolean isEmpty()

  Description copied from class: `HierarchicalConfiguration`
  Checks if this configuration is empty. Empty means that there are no keys with any values, though there can be some (empty) nodes.

  Specified by:
    `isEmpty` in interface `Configuration`
  Overrides:
    `isEmpty` in class `HierarchicalConfiguration`
  Returns:
    a flag if this configuration is empty

### createDelegate

    protected AbstractHierarchicalFileConfiguration.FileConfigurationDelegate createDelegate()

  Creates the file configuration delegate, i.e. the object that implements functionality required by the `FileConfiguration` interface. This base implementation will return an instance of the `FileConfigurationDelegate` class. Derived classes may override it to create a different delegate object.

  Returns:
    the file configuration delegate

### configurationChanged

    public void configurationChanged(ConfigurationEvent event)

  Reacts on configuration change events triggered by the delegate. These events are passed to the registered configuration listeners.

  Specified by:
    `configurationChanged` in interface `ConfigurationListener`
  Parameters:
    `event` - the triggered event
  Since:
    1.3

### getDelegate

    protected AbstractHierarchicalFileConfiguration.FileConfigurationDelegate getDelegate()

  Returns the file configuration delegate.

  Returns:
    the delegate

### setDelegate

    protected void setDelegate(AbstractHierarchicalFileConfiguration.FileConfigurationDelegate delegate)

  Allows to set the file configuration delegate.

  Parameters:
    `delegate` - the new delegate

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