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:

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 AbstractFileConfiguration#save(Reader).

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 the save() 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.

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-03-05 11:26:22 +0100 (Sat, 05 Mar 2005) $

Author:

Emmanuel Bourg

Field Summary

protected boolean	autoSave
protected String	basePath
protected String	fileName
protected ReloadingStrategy	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.
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 of 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, 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

basePath

protected String basePath

autoSave

protected boolean autoSave

strategy

protected ReloadingStrategy 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.

Specified by:

load in interface FileConfiguration

Parameters:

fileName - the name of the file loaded

Throws:

ConfigurationException

load

public void load(File file)
          throws ConfigurationException

Load the configuration from the specified file.

Specified by:

load in interface FileConfiguration

Parameters:

file - the loaded file

Throws:

ConfigurationException

load

public void load(URL url)
          throws ConfigurationException

Load the configuration from the specified URL.

Specified by:

load in interface FileConfiguration

Parameters:

url - the URL of the file loaded

Throws:

ConfigurationException

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

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

save

public void save()
          throws ConfigurationException

Save the configuration.

Specified by:

save in interface FileConfiguration

Throws:

ConfigurationException

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 -

Throws:

ConfigurationException

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 -

Throws:

ConfigurationException

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 -

Throws:

ConfigurationException

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 -

Throws:

ConfigurationException

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 -

encoding -

Throws:

ConfigurationException

getFileName

public String getFileName()

Return the name of the file.

Specified by:

getFileName in interface FileConfiguration

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

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

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 of disable the automatical 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

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

Parameters:

key - key to use for mapping

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

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

setReloadingStrategy

public void setReloadingStrategy(ReloadingStrategy strategy)

Description copied from interface: FileConfiguration

Set the reloading strategy.

Specified by:

setReloadingStrategy in interface FileConfiguration

reload

public void reload()

Description copied from interface: FileConfiguration

Reload the configuration.

Specified by:

reload in interface FileConfiguration

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

Parameters:

key - key to use for mapping

Returns:

object associated with the given configuration 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

Returns:

true if Configuration is empty, 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

Parameters:

key - the configuration key

Returns:

true if Configuration contain given key, false otherwise.

getKeys

public Iterator getKeys()

Description copied from interface: Configuration

Get the list of the keys contained in the configuration.

Specified by:

getKeys in interface Configuration

Overrides:

getKeys in class BaseConfiguration

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

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