org.apache.commons.configuration
Class AbstractFileConfiguration

java.lang.Object
  |
  +--org.apache.commons.configuration.AbstractConfiguration
        |
        +--org.apache.commons.configuration.BaseConfiguration
              |
              +--org.apache.commons.configuration.AbstractFileConfiguration
All Implemented Interfaces:
Configuration, FileConfiguration
Direct Known Subclasses:
AbstractHierarchicalFileConfiguration.FileConfigurationDelegate, PropertiesConfiguration

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

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$, $Date: 2005-12-14 20:59:07 +0100 (Wed, 14 Dec 2005) $
Author:
Emmanuel Bourg

Field Summary
protected  boolean autoSave
          The auto save flag.
protected  String basePath
          Stores the base path.
protected  String fileName
          Stores the file name.
protected  ReloadingStrategy strategy
          Holds a reference to the reloading strategy.
 
Fields inherited from class org.apache.commons.configuration.AbstractConfiguration
END_TOKEN, START_TOKEN
 
Constructor Summary
AbstractFileConfiguration()
          Default constructor
AbstractFileConfiguration(File file)
          Creates and loads the configuration from the specified file.
AbstractFileConfiguration(String fileName)
          Creates and loads the configuration from the specified file.
AbstractFileConfiguration(URL url)
          Creates and loads the configuration from the specified URL.
 
Method Summary
protected  void addPropertyDirect(String key, Object obj)
          Adds a key/value pair to the map.
 void clearProperty(String key)
          Remove a property from the configuration.
 boolean containsKey(String key)
          Check if the configuration contains the specified key.
protected  void enterNoReload()
          Enters the "No reloading mode".
protected  void exitNoReload()
          Leaves the "No reloading mode".
 String getBasePath()
          Return the base path.
 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()
          Get the list of the keys contained in the configuration.
 String getPath()
          Returns the full path to the file this configuration is based on.
 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 location.
 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.
protected  void possiblySave()
          Save the configuration if the automatic persistence is enabled and if a file is specified.
 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.
 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 setPath(String path)
          Sets the location of this configuration as a full path name.
 void setReloadingStrategy(ReloadingStrategy strategy)
          Set the reloading strategy.
 void setURL(URL url)
          Set the location of this configuration as a URL.
 
Methods inherited from class org.apache.commons.configuration.BaseConfiguration
clear
 
Methods inherited from class org.apache.commons.configuration.AbstractConfiguration
addProperty, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getKeys, getList, getList, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, interpolate, interpolate, interpolateHelper, isThrowExceptionOnMissing, resolveContainerStore, setDelimiter, setProperty, setThrowExceptionOnMissing, subset
 
Methods inherited from class java.lang.Object
clone, 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, setProperty, subset
 

Field Detail

fileName

protected String fileName
Stores the file name.

basePath

protected String basePath
Stores the base path.

autoSave

protected boolean autoSave
The auto save flag.

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)
                          throws ConfigurationException
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)
                          throws ConfigurationException
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)
                          throws ConfigurationException
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

load

public void load()
          throws ConfigurationException
Load the configuration from the underlying location.
Specified by:
load in interface FileConfiguration
Throws:
ConfigurationException - if loading of the configuration fails

load

public void load(String fileName)
          throws ConfigurationException
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.
Specified by:
load in interface FileConfiguration
Parameters:
fileName - the name of the file to be loaded
Throws:
ConfigurationException - if an error occurs

load

public void load(File file)
          throws ConfigurationException
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.
Specified by:
load in interface FileConfiguration
Parameters:
file - the file to load
Throws:
ConfigurationException - if an error occurs

load

public void load(URL url)
          throws ConfigurationException
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.
Specified by:
load in interface FileConfiguration
Parameters:
url - the URL of the file to be loaded
Throws:
ConfigurationException - if an error occurs

load

public void load(InputStream in)
          throws ConfigurationException
Load the configuration from the specified stream, using the encoding returned by 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
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
Save the configuration. Before this method can be called a valid file name must have been set.
Specified by:
save in interface FileConfiguration
Throws:
ConfigurationException - if an error occurs or no file name has been set yet

save

public void save(String fileName)
          throws ConfigurationException
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 interface FileConfiguration
Parameters:
fileName - the file name
Throws:
ConfigurationException - if an error occurs during the save operation

save

public void save(URL url)
          throws ConfigurationException
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.
Specified by:
save in interface FileConfiguration
Parameters:
url - the URL
Throws:
ConfigurationException - if an error occurs during the save operation

save

public void save(File file)
          throws ConfigurationException
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 setFile(java.io.File) if you need it.
Specified by:
save in interface FileConfiguration
Parameters:
file - the target file
Throws:
ConfigurationException - if an error occurs during the save operation

save

public void save(OutputStream out)
          throws ConfigurationException
Save the configuration to the specified stream, using the encoding returned by 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
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 use
Throws:
ConfigurationException - if an error occurs during the save operation

getFileName

public String getFileName()
Return the name of the file.
Specified by:
getFileName in interface FileConfiguration
Returns:
the file name

setFileName

public void setFileName(String fileName)
Set the name of the file. The passed in file name should not contain a path. Use setPath() to set a full qualified file name.
Specified by:
setFileName in interface FileConfiguration
Parameters:
fileName - the name of the file

getBasePath

public String getBasePath()
Return the base path.
Specified by:
getBasePath in interface FileConfiguration
Returns:
the base path

setBasePath

public void setBasePath(String basePath)
Set the base path. Relative configurations are loaded from this path. The base path can be either a path to a directory or a URL.
Specified by:
setBasePath in interface FileConfiguration
Parameters:
basePath - the base path.

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", the return value will not point to a valid file object.
Specified by:
getFile in interface FileConfiguration
Returns:
the file where the configuration is stored; this can be null

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.
Specified by:
setFile in interface FileConfiguration
Parameters:
file - the file where the configuration is stored

getPath

public String getPath()
Returns the full path to the file this configuration is based on. The return value is valid only if this configuration is based on a file on the local disk.
Returns:
the full path to the configuration file

setPath

public void setPath(String path)
Sets the location of this configuration as a full path name. The passed in path should represent a valid file name.
Parameters:
path - the full path name of the configuration file

getURL

public URL getURL()
Return the URL where the configuration is stored.
Specified by:
getURL in interface FileConfiguration
Returns:
the configuration's location as URL

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.
Specified by:
setURL in interface FileConfiguration
Parameters:
url - the location of this configuration as 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

possiblySave

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

addPropertyDirect

protected void addPropertyDirect(String key,
                                 Object obj)
Description copied from class: BaseConfiguration
Adds a key/value pair to the map. This routine does no magic morphing. It ensures the keylist is maintained
Overrides:
addPropertyDirect in class BaseConfiguration
Following copied from class: org.apache.commons.configuration.BaseConfiguration
Parameters:
key - key to use for mapping
value - object to store

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 BaseConfiguration
Following copied from interface: org.apache.commons.configuration.Configuration
Parameters:
key - the key to remove along with corresponding value.

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

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

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 BaseConfiguration
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 BaseConfiguration
Following copied from interface: org.apache.commons.configuration.Configuration
Returns:
true if the configuration contains no property, false otherwise.

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 BaseConfiguration
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()
Description copied from interface: Configuration
Get the list of the keys contained in the configuration. The returned iterator can be used to obtain all defined keys. Note that the exact behavior of the iterator's remove() method is specific to a concrete implementation. It may remove the corresponding property from the configuration, but this is not guaranteed. In any case it is no replacement for calling Configuration.clearProperty(String) for this property. So it is highly recommended to avoid using the iterator's remove() method.
Specified by:
getKeys in interface Configuration
Overrides:
getKeys in class BaseConfiguration
Following copied from interface: org.apache.commons.configuration.Configuration
Returns:
An Iterator.

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


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