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, ConfigurationErrorListener, ConfigurationListener, FileConfiguration, FileSystemBased, Reloadable

Direct Known Subclasses:

HierarchicalINIConfiguration, MultiFileHierarchicalConfiguration, PatternSubtreeConfigurationWrapper, PropertyListConfiguration, XMLConfiguration, XMLPropertyListConfiguration

public abstract class AbstractHierarchicalFileConfiguration
extends HierarchicalConfiguration
implements FileConfiguration, ConfigurationListener, ConfigurationErrorListener, FileSystemBased, Reloadable

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:

$Id: AbstractHierarchicalFileConfiguration.java 1206575 2011-11-26 20:07:52Z oheger $

Author:

Emmanuel Bourg

See Also:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
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 HierarchicalConfiguration

HierarchicalConfiguration.BuilderVisitor, HierarchicalConfiguration.Node, HierarchicalConfiguration.NodeVisitor

Field Summary

Fields inherited from class HierarchicalConfiguration

EVENT_ADD_NODES, EVENT_CLEAR_TREE, EVENT_SUBNODE_CHANGED

Fields inherited from class AbstractConfiguration

END_TOKEN, EVENT_ADD_PROPERTY, EVENT_CLEAR, EVENT_CLEAR_PROPERTY, EVENT_READ_PROPERTY, EVENT_SET_PROPERTY, START_TOKEN

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractHierarchicalFileConfiguration()	Creates a new instance of 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.
protected	AbstractHierarchicalFileConfiguration(HierarchicalConfiguration c)	Creates a new instance of AbstractHierarchicalFileConfiguration and copies the content of the specified configuration into this object.

Method Summary

Modifier and Type	Method	Description
void	addNodes(String key, Collection<? extends ConfigurationNode> nodes)	Directly adds sub nodes to this configuration.
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.
void	configurationError(ConfigurationErrorEvent event)	Notifies this listener that in an observed configuration an error occurred.
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.
protected List<ConfigurationNode>	fetchNodeList(String key)	Fetches a list of nodes, which are selected by the specified key.
String	getBasePath()	Returns 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.
FileSystem	getFileSystem()	Retrieve the FileSystem being used.
Iterator<String>	getKeys()	Returns an iterator with all keys defined in this configuration.
Iterator<String>	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.
Object	getReloadLock()	Returns the object to synchronize on a reload.
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	refresh()	Reloads the associated configuration file.
void	reload()	Reload the configuration.
void	resetFileSystem()	Reset the FileSystem to the default;
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.
void	setAutoSave(boolean autoSave)	Enable or disable the automatically saving of modified properties to the disk.
void	setBasePath(String basePath)	Sets 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	setFileSystem(FileSystem fileSystem)	Set the FileSystem to be used for this Configuration.
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.
protected void	subnodeConfigurationChanged(ConfigurationEvent event)	Reacts on changes of an associated subnode configuration.

Methods inherited from class HierarchicalConfiguration

clear, clearNode, clearNode, clearReferences, clone, configurationAt, configurationAt, configurationsAt, createAddPath, createNode, createSubnodeConfiguration, createSubnodeConfiguration, fetchAddNode, findLastPathNode, findPropertyNodes, getDefaultExpressionEngine, getExpressionEngine, getMaxIndex, getRoot, getRootNode, interpolatedConfiguration, nodeDefined, nodeDefined, removeNode, removeNode, setDefaultExpressionEngine, setExpressionEngine, setRoot, setRootNode, subset

Methods inherited from class AbstractConfiguration

addErrorLogListener, addProperty, append, clearPropertyDirect, copy, createInterpolator, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDefaultListDelimiter, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getList, getList, getListDelimiter, getLogger, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, getSubstitutor, interpolate, interpolate, interpolateHelper, isDelimiterParsingDisabled, isScalarValue, isThrowExceptionOnMissing, resolveContainerStore, setDefaultListDelimiter, setDelimiter, setDelimiterParsingDisabled, setListDelimiter, setLogger, setThrowExceptionOnMissing

Methods inherited from class EventSource

addConfigurationListener, addErrorListener, clearConfigurationListeners, clearErrorListeners, createErrorEvent, createEvent, fireError, fireEvent, getConfigurationListeners, getErrorListeners, isDetailEvents, removeConfigurationListener, removeErrorListener, setDetailEvents

Methods inherited from class Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface Configuration

addProperty, clear, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getList, getList, getLong, getLong, getLong, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, subset

Methods inherited from interface FileConfiguration

load, save

Constructor Details

AbstractHierarchicalFileConfiguration

protected AbstractHierarchicalFileConfiguration()

Creates a new instance of AbstractHierarchicalFileConfiguration.

AbstractHierarchicalFileConfiguration

protected AbstractHierarchicalFileConfiguration(HierarchicalConfiguration c)

Creates a new instance of AbstractHierarchicalFileConfiguration and copies the content of the specified configuration into this object.

Parameters:

c - the configuration to copy

Since:

1.4

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 Details

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.

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

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.

Specified by:

getBasePath in interface FileConfiguration

Returns:

the base path

See Also:

• AbstractFileConfiguration.setBasePath(String)

setBasePath

public void setBasePath(String basePath)

Description copied from interface: FileConfiguration

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.

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

refresh

public void refresh()
             throws ConfigurationException

Reloads the associated configuration file. This method first clears the content of this configuration, then the associated configuration file is loaded again. Updates on this configuration which have not yet been saved are lost. Calling this method is like invoking reload() without checking the reloading strategy.

Throws:

ConfigurationException - if an error occurs

Since:

1.7

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

getReloadLock

public Object getReloadLock()

Description copied from class: HierarchicalConfiguration

Returns the object to synchronize on a reload. This class is not reloadable so this object isn't important

Specified by:

getReloadLock in interface Reloadable

Overrides:

getReloadLock in class HierarchicalConfiguration

Returns:

the lock object

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<String> getKeys()

Description copied from class: HierarchicalConfiguration

Returns an iterator with all keys defined in this configuration. Note that the keys returned by this method will not contain any indices. This means that some structure will be lost.

Specified by:

getKeys in interface Configuration

Overrides:

getKeys in class HierarchicalConfiguration

Returns:

an iterator with the defined keys in this configuration

getKeys

public Iterator<String> 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. This implementation tries to locate a node whose key is the same as the passed in prefix. Then the subtree of this node is traversed, and the keys of all nodes encountered (including attributes) are added to the result set.

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

addNodes

public void addNodes(String key,
 Collection<? extends ConfigurationNode> nodes)

Directly adds sub nodes to this configuration. This implementation checks whether auto save is necessary after executing the operation.

Overrides:

addNodes in class HierarchicalConfiguration

Parameters:

key - the key where the nodes are to be added

nodes - a collection with the nodes to be added

Since:

1.5

fetchNodeList

protected List<ConfigurationNode> fetchNodeList(String key)

Fetches a list of nodes, which are selected by the specified key. This implementation will perform a reload if necessary.

Overrides:

fetchNodeList in class HierarchicalConfiguration

Parameters:

key - the key

Returns:

a list with the selected nodes

subnodeConfigurationChanged

protected void subnodeConfigurationChanged(ConfigurationEvent event)

Reacts on changes of an associated subnode configuration. If the auto save mechanism is active, the configuration must be saved.

Overrides:

subnodeConfigurationChanged in class HierarchicalConfiguration

Parameters:

event - the event describing the change

Since:

1.5

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

configurationError

public void configurationError(ConfigurationErrorEvent event)

Description copied from interface: ConfigurationErrorListener

Notifies this listener that in an observed configuration an error occurred. All information available about this error, including the causing Throwable object, can be obtained from the passed in event object.

Specified by:

configurationError in interface ConfigurationErrorListener

Parameters:

event - the event object with information about the error

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

setFileSystem

public void setFileSystem(FileSystem fileSystem)

Set the FileSystem to be used for this Configuration.

Specified by:

setFileSystem in interface FileSystemBased

Parameters:

fileSystem - The FileSystem to use.

resetFileSystem

public void resetFileSystem()

Reset the FileSystem to the default;

Specified by:

resetFileSystem in interface FileSystemBased

getFileSystem

public FileSystem getFileSystem()

Retrieve the FileSystem being used.

Specified by:

getFileSystem in interface FileSystemBased

Returns:

The FileSystem.