Class AbstractFileConfiguration
- All Implemented Interfaces:
Cloneable
,Configuration
,FileConfiguration
,FileSystemBased
- Direct Known Subclasses:
AbstractHierarchicalFileConfiguration.FileConfigurationDelegate
,INIConfiguration
,PropertiesConfiguration
Partial implementation of the FileConfiguration
interface.
Developers 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 thesave()
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.
The configuration source to be loaded can be specified using one of the
methods described above. Then the parameterless load()
method can be
called. Alternatively, one of the load()
methods can be used which is
passed the source directly. These methods typically do not change the
internally stored file; however, if the configuration is not yet associated
with a configuration source, the first call to one of the load()
methods sets the base path and the source URL. This fact has to be taken
into account when calling load()
multiple times with different file
paths.
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:
- $Id: AbstractFileConfiguration.java 1234118 2012-01-20 20:36:04Z oheger $
- Author:
- Emmanuel Bourg
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected boolean
The auto save flag.protected String
Stores the base path.static final int
Constant fro the configuration changed event.static final int
Constant for the configuration reload event.protected String
Stores the file name.protected Object
A lock object for protecting reload operations.protected ReloadingStrategy
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_READ_PROPERTY, EVENT_SET_PROPERTY, START_TOKEN
-
Constructor Summary
ConstructorsConstructorDescriptionDefault constructorCreates and loads the configuration from the specified file.AbstractFileConfiguration
(String fileName) Creates and loads the configuration from the specified file.Creates and loads the configuration from the specified URL. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addProperty
(String key, Object value) Adds a new property to this configuration.void
clearProperty
(String key) Removes the specified property from this configuration.clone()
Creates a copy of this configuration.protected void
closeSilent
(OutputStream out) A helper method for closing an output stream.void
Send notification that the configuration has changed.boolean
containsKey
(String key) check if the configuration contains the keyprotected void
Enters the "No reloading mode".protected void
Leaves the "No reloading mode".protected void
Sends an event to all registered listeners.Return the base path.Return the encoding used to store the configuration file.getFile()
Return the file where the configuration is stored.Return the name of the file.getKeys()
Returns anIterator
with the keys contained in this configuration.getPath()
Returns the full path to the file this configuration is based on.getProperty
(String key) Read property from underlying map.Return the reloading strategy.getURL()
Return the URL where the configuration is stored.boolean
Tells if properties are automatically saved to the disk.boolean
isEmpty()
Check if the configuration is emptyvoid
load()
Load the configuration from the underlying location.void
Load the configuration from the specified file.void
load
(InputStream in) Load the configuration from the specified stream, using the encoding returned bygetEncoding()
.void
load
(InputStream in, String encoding) Load the configuration from the specified stream, using the specified encoding.void
Locate the specified file and load the configuration.void
Load the configuration from the specified URL.protected void
Save the configuration if the automatic persistence is enabled and if a file is specified.void
refresh()
Reloads the associated configuration file.void
reload()
Performs a reload operation if necessary.boolean
reload
(boolean checkReload) void
void
save()
Save the configuration.void
Save the configuration to the specified file.void
save
(OutputStream out) Save the configuration to the specified stream, using the encoding returned bygetEncoding()
.void
save
(OutputStream out, String encoding) Save the configuration to the specified stream, using the specified encoding.void
Save the configuration to the specified file.void
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.void
setEncoding
(String encoding) Set the encoding used to store the configuration file.void
Set the file where the configuration is stored.void
setFileName
(String fileName) Set the name of the file.void
setFileSystem
(FileSystem fileSystem) void
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
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
addErrorLogListener, append, copy, createInterpolator, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDefaultListDelimiter, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getKeys, getList, getList, getListDelimiter, getLogger, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, getSubstitutor, interpolate, interpolate, interpolatedConfiguration, interpolateHelper, isDelimiterParsingDisabled, isScalarValue, isThrowExceptionOnMissing, resolveContainerStore, setDefaultListDelimiter, setDelimiter, setDelimiterParsingDisabled, setListDelimiter, setLogger, setThrowExceptionOnMissing, subset
Methods inherited from class org.apache.commons.configuration.event.EventSource
addConfigurationListener, addErrorListener, clearConfigurationListeners, clearErrorListeners, createErrorEvent, createEvent, fireError, getConfigurationListeners, getErrorListeners, isDetailEvents, removeConfigurationListener, removeErrorListener, 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.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
Methods inherited from interface org.apache.commons.configuration.FileConfiguration
load, save
-
Field Details
-
EVENT_RELOAD
Constant for the configuration reload event.- See Also:
-
EVENT_CONFIG_CHANGED
Constant fro the configuration changed event.- See Also:
-
fileName
Stores the file name. -
basePath
Stores the base path. -
autoSave
The auto save flag. -
strategy
Holds a reference to the reloading strategy. -
reloadLock
A lock object for protecting reload operations.
-
-
Constructor Details
-
AbstractFileConfiguration
public AbstractFileConfiguration()Default constructor- Since:
- 1.1
-
AbstractFileConfiguration
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
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
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 Details
-
setFileSystem
- Specified by:
setFileSystem
in interfaceFileSystemBased
-
resetFileSystem
- Specified by:
resetFileSystem
in interfaceFileSystemBased
-
getFileSystem
- Specified by:
getFileSystem
in interfaceFileSystemBased
-
getReloadLock
-
load
Load the configuration from the underlying location.- Specified by:
load
in interfaceFileConfiguration
- Throws:
ConfigurationException
- if loading of the configuration fails
-
load
Locate the specified file and load the configuration. If the configuration is already associated with a source, the current source is not changed. Otherwise (i.e. this is the first load operation), the source URL and the base path are set now based on the source to be loaded.- Specified by:
load
in interfaceFileConfiguration
- Parameters:
fileName
- the name of the file to be loaded- Throws:
ConfigurationException
- if an error occurs
-
load
Load the configuration from the specified file. If the configuration is already associated with a source, the current source is not changed. Otherwise (i.e. this is the first load operation), the source URL and the base path are set now based on the source to be loaded.- Specified by:
load
in interfaceFileConfiguration
- Parameters:
file
- the file to load- Throws:
ConfigurationException
- if an error occurs
-
load
Load the configuration from the specified URL. If the configuration is already associated with a source, the current source is not changed. Otherwise (i.e. this is the first load operation), the source URL and the base path are set now based on the source to be loaded.- Specified by:
load
in interfaceFileConfiguration
- Parameters:
url
- the URL of the file to be loaded- Throws:
ConfigurationException
- if an error occurs
-
load
Load the configuration from the specified stream, using the encoding returned bygetEncoding()
.- Specified by:
load
in interfaceFileConfiguration
- Parameters:
in
- the input stream- Throws:
ConfigurationException
- if an error occurs during the load operation
-
load
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 interfaceFileConfiguration
- Parameters:
in
- the input streamencoding
- the encoding used.null
to use the default encoding- Throws:
ConfigurationException
- if an error occurs during the load operation
-
save
Save the configuration. Before this method can be called a valid file name must have been set.- Specified by:
save
in interfaceFileConfiguration
- Throws:
ConfigurationException
- if an error occurs or no file name has been set yet
-
save
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 interfaceFileConfiguration
- Parameters:
fileName
- the file name- Throws:
ConfigurationException
- if an error occurs during the save operation
-
save
Save the configuration to the specified URL. This doesn't change the source of the configuration, use setURL() if you need it.- Specified by:
save
in interfaceFileConfiguration
- Parameters:
url
- the URL- Throws:
ConfigurationException
- if an error occurs during the save operation
-
save
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, usesetFile(java.io.File)
if you need it.- Specified by:
save
in interfaceFileConfiguration
- Parameters:
file
- the target file- Throws:
ConfigurationException
- if an error occurs during the save operation
-
save
Save the configuration to the specified stream, using the encoding returned bygetEncoding()
.- Specified by:
save
in interfaceFileConfiguration
- Parameters:
out
- the output stream- Throws:
ConfigurationException
- if an error occurs during the save operation
-
save
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 interfaceFileConfiguration
- Parameters:
out
- the output streamencoding
- the encoding to use- Throws:
ConfigurationException
- if an error occurs during the save operation
-
getFileName
Return the name of the file.- Specified by:
getFileName
in interfaceFileConfiguration
- Returns:
- the file name
-
setFileName
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. UsesetPath()
to set a full qualified file name.- Specified by:
setFileName
in interfaceFileConfiguration
- Parameters:
fileName
- the name of the file
-
getBasePath
Return the base path.- Specified by:
getBasePath
in interfaceFileConfiguration
- Returns:
- the base path
- See Also:
-
setBasePath
Sets the base path. The base path is typically either a path to a directory or a URL. Together with the value passed to thesetFileName()
method it defines the location of the configuration file to be loaded. The strategies for locating the file are quite tolerant. For instance if the file name is already an absolute path or a fully defined URL, the base path will be ignored. The base path can also be a URL, in which case the file name is interpreted in this URL's context. Because the base path is used by some of the derived classes for resolving relative file names it should contain a meaningful value. If other methods are used for determining the location of the configuration file (e.g.setFile()
orsetURL()
), the base path is automatically set.- Specified by:
setBasePath
in interfaceFileConfiguration
- Parameters:
basePath
- the base path.
-
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 interfaceFileConfiguration
- Returns:
- the file where the configuration is stored; this can be null
-
setFile
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 interfaceFileConfiguration
- Parameters:
file
- the file where the configuration is stored
-
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
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
Return the URL where the configuration is stored.- Specified by:
getURL
in interfaceFileConfiguration
- Returns:
- the configuration's location as URL
-
setURL
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 interfaceFileConfiguration
- Parameters:
url
- the location of this configuration as URL
-
setAutoSave
Description copied from interface:FileConfiguration
Enable or disable the automatically saving of modified properties to the disk.- Specified by:
setAutoSave
in interfaceFileConfiguration
- Parameters:
autoSave
-true
to enable,false
to disable
-
isAutoSave
Description copied from interface:FileConfiguration
Tells if properties are automatically saved to the disk.- Specified by:
isAutoSave
in interfaceFileConfiguration
- Returns:
true
if auto-saving is enabled,false
otherwise
-
possiblySave
Save the configuration if the automatic persistence is enabled and if a file is specified. -
addProperty
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 interfaceConfiguration
- Overrides:
addProperty
in classAbstractConfiguration
- Parameters:
key
- the key of the new propertyvalue
- the value
-
setProperty
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 interfaceConfiguration
- Overrides:
setProperty
in classAbstractConfiguration
- Parameters:
key
- the key of the affected propertyvalue
- the value
-
clearProperty
Description copied from class:AbstractConfiguration
Removes the specified property from this configuration. This implementation performs some preparations and then delegates toclearPropertyDirect()
, which will do the real work.- Specified by:
clearProperty
in interfaceConfiguration
- Overrides:
clearProperty
in classAbstractConfiguration
- Parameters:
key
- the key to be removed
-
getReloadingStrategy
Description copied from interface:FileConfiguration
Return the reloading strategy.- Specified by:
getReloadingStrategy
in interfaceFileConfiguration
- Returns:
- the reloading strategy currently used
-
setReloadingStrategy
Description copied from interface:FileConfiguration
Set the reloading strategy.- Specified by:
setReloadingStrategy
in interfaceFileConfiguration
- Parameters:
strategy
- the reloading strategy to use
-
reload
Performs a reload operation if necessary. This method is called on each access of this configuration. It asks the associated reloading strategy whether a reload should be performed. If this is the case, the configuration is cleared and loaded again from its source. If this operation causes an exception, the registered error listeners will be notified. The error event passed to the listeners is of typeEVENT_RELOAD
and contains the exception that caused the event.- Specified by:
reload
in interfaceFileConfiguration
-
reload
-
refresh
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 invokingreload()
without checking the reloading strategy.- Throws:
ConfigurationException
- if an error occurs- Since:
- 1.7
-
configurationChanged
Send notification that the configuration has changed. -
enterNoReload
Enters the "No reloading mode". As long as this mode is active no reloading will be performed. This is necessary for some implementations ofsave()
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 ofexitNoReload()
later! (If necessary,finally
blocks must be used to ensure this. -
exitNoReload
Leaves the "No reloading mode".- See Also:
-
fireEvent
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 classEventSource
- Parameters:
type
- the event typepropName
- the name of the propertypropValue
- the value of the propertybefore
- the before update flag
-
getProperty
Description copied from class:BaseConfiguration
Read property from underlying map.- Specified by:
getProperty
in interfaceConfiguration
- Overrides:
getProperty
in classBaseConfiguration
- Parameters:
key
- key to use for mapping- Returns:
- object associated with the given configuration key.
-
isEmpty
Description copied from class:BaseConfiguration
Check if the configuration is empty- Specified by:
isEmpty
in interfaceConfiguration
- Overrides:
isEmpty
in classBaseConfiguration
- Returns:
true
if Configuration is empty,false
otherwise.
-
containsKey
Description copied from class:BaseConfiguration
check if the configuration contains the key- Specified by:
containsKey
in interfaceConfiguration
- Overrides:
containsKey
in classBaseConfiguration
- Parameters:
key
- the configuration key- Returns:
true
if Configuration contain given key,false
otherwise.
-
getKeys
Returns anIterator
with the keys contained in this configuration. This implementation performs a reload if necessary before obtaining the keys. TheIterator
returned by this method points to a snapshot taken when this method was called. Later changes at the set of keys (including those caused by a reload) won't be visible. This is because a reload can happen at any time during iteration, and it is impossible to determine how this reload affects the current iteration. When using the iterator a client has to be aware that changes of the configuration are possible at any time. For instance, if after a reload operation some keys are no longer present, the iterator will still return those keys because they were found when it was created.- Specified by:
getKeys
in interfaceConfiguration
- Overrides:
getKeys
in classBaseConfiguration
- Returns:
- an
Iterator
with the keys of this configuration
-
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 interfaceFileConfiguration
- Returns:
- the current encoding
-
setEncoding
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 interfaceFileConfiguration
- Parameters:
encoding
- the encoding to use
-
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 classBaseConfiguration
- Returns:
- the copy
- Since:
- 1.3
-
closeSilent
A helper method for closing an output stream. Occurring exceptions will be ignored.- Parameters:
out
- the output stream to be closed (may be null)- Since:
- 1.5
-