org.apache.commons.configuration

Class AbstractFileConfiguration

public abstract class AbstractFileConfiguration extends BaseConfiguration implements FileConfiguration

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

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:

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

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

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

Since: 1.0-rc2

Version: $Revision: 497574 $, $Date: 2007-01-18 22:02:55 +0100 (Do, 18 Jan 2007) $

Author: Emmanuel Bourg

Field Summary
protected booleanautoSave
The auto save flag.
protected StringbasePath
Stores the base path.
Stringencoding
Stores the encoding of the configuration file.
static intEVENT_RELOAD
Constant for the configuration reload event.
protected StringfileName
Stores the file name.
intnoReload
A counter that prohibits reloading.
ObjectreloadLock
A lock object for protecting reload operations.
URLsourceURL
Stores the URL from which the configuration file was loaded.
protected ReloadingStrategystrategy
Holds a reference to the reloading strategy.
Constructor Summary
AbstractFileConfiguration()
Default constructor
AbstractFileConfiguration(String fileName)
Creates and loads the configuration from the specified file.
AbstractFileConfiguration(File file)
Creates and loads the configuration from the specified file.
AbstractFileConfiguration(URL url)
Creates and loads the configuration from the specified URL.
Method Summary
voidaddProperty(String key, Object value)
Adds a new property to this configuration.
voidclearProperty(String key)
Objectclone()
Creates a copy of this configuration.
booleancontainsKey(String key)
voidcreatePath(File file)
Create the path to the specified file.
protected voidenterNoReload()
Enters the "No reloading mode".
protected voidexitNoReload()
Leaves the "No reloading mode".
protected voidfireEvent(int type, String propName, Object propValue, boolean before)
Sends an event to all registered listeners.
StringgetBasePath()
Return the base path.
StringgetEncoding()
FilegetFile()
Return the file where the configuration is stored.
StringgetFileName()
Return the name of the file.
IteratorgetKeys()
StringgetPath()
Returns the full path to the file this configuration is based on.
ObjectgetProperty(String key)
ReloadingStrategygetReloadingStrategy()
URLgetURL()
Return the URL where the configuration is stored.
voidinitReloadingStrategy()
Helper method for initializing the reloading strategy.
booleanisAutoSave()
booleanisEmpty()
voidload()
Load the configuration from the underlying location.
voidload(String fileName)
Locate the specified file and load the configuration.
voidload(File file)
Load the configuration from the specified file.
voidload(URL url)
Load the configuration from the specified URL.
voidload(InputStream in)
Load the configuration from the specified stream, using the encoding returned by getEncoding.
voidload(InputStream in, String encoding)
Load the configuration from the specified stream, using the specified encoding.
protected voidpossiblySave()
Save the configuration if the automatic persistence is enabled and if a file is specified.
voidreload()
Performs a reload operation if necessary.
voidsave()
Save the configuration.
voidsave(String fileName)
Save the configuration to the specified file.
voidsave(URL url)
Save the configuration to the specified URL if it's a file URL.
voidsave(File file)
Save the configuration to the specified file.
voidsave(OutputStream out)
Save the configuration to the specified stream, using the encoding returned by getEncoding.
voidsave(OutputStream out, String encoding)
Save the configuration to the specified stream, using the specified encoding.
voidsetAutoSave(boolean autoSave)
voidsetBasePath(String basePath)
Sets the base path.
voidsetEncoding(String encoding)
voidsetFile(File file)
Set the file where the configuration is stored.
voidsetFileName(String fileName)
Set the name of the file.
voidsetPath(String path)
Sets the location of this configuration as a full or relative path name.
voidsetProperty(String key, Object value)
Sets a new value for the specified property.
voidsetReloadingStrategy(ReloadingStrategy strategy)
voidsetURL(URL url)
Set the location of this configuration as a URL.

Field Detail

autoSave

protected boolean autoSave
The auto save flag.

basePath

protected String basePath
Stores the base path.

encoding

private String encoding
Stores the encoding of the configuration file.

EVENT_RELOAD

public static final int EVENT_RELOAD
Constant for the configuration reload event.

fileName

protected String fileName
Stores the file name.

noReload

private int noReload
A counter that prohibits reloading.

reloadLock

private Object reloadLock
A lock object for protecting reload operations.

sourceURL

private URL sourceURL
Stores the URL from which the configuration file was loaded.

strategy

protected ReloadingStrategy strategy
Holds a reference to the reloading strategy.

Constructor Detail

AbstractFileConfiguration

public AbstractFileConfiguration()
Default constructor

Since: 1.1

AbstractFileConfiguration

public AbstractFileConfiguration(String fileName)
Creates and loads the configuration from the specified file. The passed in string must be a valid file name, either absolute or relativ.

Parameters: fileName The name of the file to load.

Throws: ConfigurationException Error while loading the file

Since: 1.1

AbstractFileConfiguration

public AbstractFileConfiguration(File file)
Creates and loads the configuration from the specified file.

Parameters: file The file to load.

Throws: ConfigurationException Error while loading the file

Since: 1.1

AbstractFileConfiguration

public AbstractFileConfiguration(URL url)
Creates and loads the configuration from the specified URL.

Parameters: url The location of the file to load.

Throws: ConfigurationException Error while loading the file

Since: 1.1

Method Detail

addProperty

public void addProperty(String key, Object value)
Adds a new property to this configuration. This implementation checks if the auto save mode is enabled and saves the configuration if necessary.

Parameters: key the key of the new property value the value

clearProperty

public void clearProperty(String key)

clone

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

Returns: the copy

Since: 1.3

containsKey

public boolean containsKey(String key)

createPath

private void createPath(File file)
Create the path to the specified file.

Parameters: file the target file

enterNoReload

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

exitNoReload

protected void exitNoReload()
Leaves the "No reloading mode".

See Also: enterNoReload

fireEvent

protected void fireEvent(int type, String propName, Object propValue, boolean before)
Sends an event to all registered listeners. This implementation ensures that no reloads are performed while the listeners are invoked. So infinite loops can be avoided that can be caused by event listeners accessing the configuration's properties when they are invoked.

Parameters: type the event type propName the name of the property propValue the value of the property before the before update flag

getBasePath

public String getBasePath()
Return the base path.

Returns: the base path

See Also: getBasePath

getEncoding

public String getEncoding()

getFile

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

Returns: the file where the configuration is stored; this can be null

getFileName

public String getFileName()
Return the name of the file.

Returns: the file name

getKeys

public Iterator getKeys()

getPath

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

Returns: the full path to the configuration file

getProperty

public Object getProperty(String key)

getReloadingStrategy

public ReloadingStrategy getReloadingStrategy()

getURL

public URL getURL()
Return the URL where the configuration is stored.

Returns: the configuration's location as URL

initReloadingStrategy

private void initReloadingStrategy()
Helper method for initializing the reloading strategy.

isAutoSave

public boolean isAutoSave()

isEmpty

public boolean isEmpty()

load

public void load()
Load the configuration from the underlying location.

Throws: ConfigurationException if loading of the configuration fails

load

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

Parameters: fileName the name of the file to be loaded

Throws: ConfigurationException if an error occurs

load

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

Parameters: file the file to load

Throws: ConfigurationException if an error occurs

load

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

Parameters: url the URL of the file to be loaded

Throws: ConfigurationException if an error occurs

load

public void load(InputStream in)
Load the configuration from the specified stream, using the encoding returned by getEncoding.

Parameters: in the input stream

Throws: ConfigurationException if an error occurs during the load operation

load

public void load(InputStream in, String encoding)
Load the configuration from the specified stream, using the specified encoding. If the encoding is null the default encoding is used.

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

possiblySave

protected void possiblySave()
Save the configuration if the automatic persistence is enabled and if a file is specified.

reload

public void 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 type EVENT_RELOAD and contains the exception that caused the event.

save

public void save()
Save the configuration. Before this method can be called a valid file name must have been set.

Throws: ConfigurationException if an error occurs or no file name has been set yet

save

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

Parameters: fileName the file name

Throws: ConfigurationException if an error occurs during the save operation

save

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

Parameters: url the URL

Throws: ConfigurationException if an error occurs during the save operation

save

public void save(File file)
Save the configuration to the specified file. The file is created automatically if it doesn't exist. This doesn't change the source of the configuration, use AbstractFileConfiguration if you need it.

Parameters: file the target file

Throws: ConfigurationException if an error occurs during the save operation

save

public void save(OutputStream out)
Save the configuration to the specified stream, using the encoding returned by getEncoding.

Parameters: out the output stream

Throws: ConfigurationException if an error occurs during the save operation

save

public void save(OutputStream out, String encoding)
Save the configuration to the specified stream, using the specified encoding. If the encoding is null the default encoding is used.

Parameters: out the output stream encoding the encoding to use

Throws: ConfigurationException if an error occurs during the save operation

setAutoSave

public void setAutoSave(boolean autoSave)

setBasePath

public void setBasePath(String basePath)
Sets the base path. The base path is typically either a path to a directory or a URL. Together with the value passed to the setFileName() 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() or setURL()), the base path is automatically set.

Parameters: basePath the base path.

setEncoding

public void setEncoding(String encoding)

setFile

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

Parameters: file the file where the configuration is stored

setFileName

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

Parameters: fileName the name of the file

setPath

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

Parameters: path the full path name of the configuration file

setProperty

public void setProperty(String key, Object value)
Sets a new value for the specified property. This implementation checks if the auto save mode is enabled and saves the configuration if necessary.

Parameters: key the key of the affected property value the value

setReloadingStrategy

public void setReloadingStrategy(ReloadingStrategy strategy)

setURL

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

Parameters: url the location of this configuration as URL