org.apache.commons.configuration
Class AbstractHierarchicalFileConfiguration

java.lang.Object
  |
  +--org.apache.commons.configuration.AbstractConfiguration
        |
        +--org.apache.commons.configuration.HierarchicalConfiguration
              |
              +--org.apache.commons.configuration.AbstractHierarchicalFileConfiguration

All Implemented Interfaces:

Cloneable, Configuration, FileConfiguration, Serializable

Direct Known Subclasses:

PropertyListConfiguration, XMLConfiguration, XMLPropertyListConfiguration

public abstract class AbstractHierarchicalFileConfiguration

extends HierarchicalConfiguration

implements FileConfiguration

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$, $Date: 2005-11-22 21:40:57 +0100 (Tue, 22 Nov 2005) $

Author:

Emmanuel Bourg

See Also:

Serialized Form

Inner 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.

Inner classes inherited from class org.apache.commons.configuration.HierarchicalConfiguration

HierarchicalConfiguration.BuilderVisitor, HierarchicalConfiguration.Node, HierarchicalConfiguration.NodeVisitor

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

END_TOKEN, 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.To be able to deal with the structure supported by this configuration implementation the passed in key is of importance, especially the indices it might contain.
void	clearProperty(String key) Remove a property from the configuration.
void	clearTree(String key) Removes all values of the property with the given name and of keys that start with this name.
boolean	containsKey(String key) Check if the configuration contains the specified key.
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) Get the list of the keys contained in the configuration that match the specified prefix.
Object	getProperty(String key) Gets a property from the configuration.
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 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 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 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) Set a property, this will replace any previously set values.
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, clone, createAddPath, createNode, fetchAddNode, fetchNodeList, findLastPathNode, findPropertyNodes, getKeys, getMaxIndex, getRoot, nodeDefined, removeNode, setRoot, subset

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

addProperty, clear, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getList, getList, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, interpolate, interpolate, interpolateHelper, isThrowExceptionOnMissing, resolveContainerStore, setDelimiter, setThrowExceptionOnMissing

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.

To be able to deal with the structure supported by this configuration implementation the passed in key is of importance, especially the indices it might contain. The following example should clearify this: Suppose the actual configuration contains the following elements:

 tables
    +-- table
            +-- name = user
            +-- fields
                    +-- field
                            +-- name = uid
                    +-- field
                            +-- name = firstName
                    ...
    +-- table
            +-- name = documents
            +-- fields
                   ...
 

In this example a database structure is defined, e.g. all fields of the first table could be accessed using the key tables.table(0).fields.field.name. If now properties are to be added, it must be exactly specified at which position in the hierarchy the new property is to be inserted. So to add a new field name to a table it is not enough to say just

 config.addProperty("tables.table.fields.field.name", "newField");
 

The statement given above contains some ambiguity. For instance it is not clear, to which table the new field should be added. If this method finds such an ambiguity, it is resolved by following the last valid path. Here this would be the last table. The same is true for the field; because there are multiple fields and no explicit index is provided, a new name property would be added to the last field - which is propably not what was desired.

To make things clear explicit indices should be provided whenever possible. In the example above the exact table could be specified by providing an index for the table element as in tables.table(1).fields. By specifying an index it can also be expressed that at a given position in the configuration tree a new branch should be added. In the example above we did not want to add an additional name element to the last field of the table, but we want a complete new field element. This can be achieved by specifying an invalid index (like -1) after the element where a new branch should be created. Given this our example would run:

 config.addProperty("tables.table(1).fields.field(-1).name", "newField");
 

With this notation it is possible to add new branches everywhere. We could for instance create a new table element by specifying

 config.addProperty("tables.table(-1).fields.field.name", "newField2");
 

(Note that because after the table element a new branch is created indices in following elements are not relevant; the branch is new so there cannot be any ambiguities.)

Overrides:

addPropertyDirect in class HierarchicalConfiguration

Following copied from class: org.apache.commons.configuration.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 interface: Configuration

Remove a property from the configuration.

Specified by:

clearProperty in interface Configuration

Overrides:

clearProperty in class HierarchicalConfiguration

Following copied from interface: org.apache.commons.configuration.Configuration

Parameters:

key - the key to remove along with corresponding value.

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

Following copied from class: org.apache.commons.configuration.HierarchicalConfiguration

Parameters:

key - the key of the property to be removed

setProperty

public void setProperty(String key,
                        Object value)

Description copied from interface: Configuration

Set a property, this will replace any previously set values. Set values is implicitly a call to clearProperty(key), addProperty(key, value).

Specified by:

setProperty in interface Configuration

Overrides:

setProperty in class HierarchicalConfiguration

Following copied from interface: org.apache.commons.configuration.Configuration

Parameters:

key - The key of the property to change

value - The new value

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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.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

Following copied from interface: org.apache.commons.configuration.FileConfiguration

Parameters:

encoding - the encoding to use

containsKey

public boolean containsKey(String key)

Description copied from interface: Configuration

Check if the configuration contains the specified key.

Specified by:

containsKey in interface Configuration

Overrides:

containsKey in class HierarchicalConfiguration

Following copied from interface: org.apache.commons.configuration.Configuration

Parameters:

key - the key whose presence in this configuration is to be tested

Returns:

true if the configuration contains a value for this key, false otherwise

getKeys

public Iterator getKeys(String prefix)

Description copied from interface: Configuration

Get the list of the keys contained in the configuration that match the specified prefix.

Specified by:

getKeys in interface Configuration

Overrides:

getKeys in class HierarchicalConfiguration

Following copied from interface: org.apache.commons.configuration.Configuration

Parameters:

prefix - The prefix to test against.

Returns:

An Iterator of keys that match the prefix.

See Also:

Configuration.getKeys()

getProperty

public Object getProperty(String key)

Description copied from interface: Configuration

Gets a property from the configuration.

Specified by:

getProperty in interface Configuration

Overrides:

getProperty in class HierarchicalConfiguration

Following copied from interface: org.apache.commons.configuration.Configuration

Parameters:

key - property to retrieve

Returns:

the value to which this configuration maps the specified key, or null if the configuration contains no mapping for this key.

isEmpty

public boolean isEmpty()

Description copied from interface: Configuration

Check if the configuration is empty.

Specified by:

isEmpty in interface Configuration

Overrides:

isEmpty in class HierarchicalConfiguration

Following copied from interface: org.apache.commons.configuration.Configuration

Returns:

true if the configuration contains no property, false otherwise.

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

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