org.apache.commons.configuration
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:
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.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.setPath()
method a
full path to a configuration file can be provided as a string.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: 497574 $, $Date: 2007-01-18 22:02:55 +0100 (Do, 18 Jan 2007) $
Field Summary | |
---|---|
protected boolean | autoSave The auto save flag. |
protected String | basePath Stores the base path. |
String | encoding Stores the encoding of the configuration file. |
static int | EVENT_RELOAD Constant for the configuration reload event. |
protected String | fileName Stores the file name. |
int | noReload A counter that prohibits reloading. |
Object | reloadLock A lock object for protecting reload operations. |
URL | sourceURL Stores the URL from which the configuration file was loaded. |
protected ReloadingStrategy | strategy 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 | |
---|---|
void | addProperty(String key, Object value)
Adds a new property to this configuration. |
void | clearProperty(String key) |
Object | clone()
Creates a copy of this configuration. |
boolean | containsKey(String key) |
void | createPath(File file)
Create the path to the specified file.
|
protected void | enterNoReload()
Enters the "No reloading mode". |
protected void | exitNoReload()
Leaves the "No reloading mode".
|
protected void | fireEvent(int type, String propName, Object propValue, boolean before)
Sends an event to all registered listeners. |
String | getBasePath()
Return the base path.
|
String | getEncoding() |
File | getFile()
Return the file where the configuration is stored. |
String | getFileName()
Return the name of the file.
|
Iterator | getKeys() |
String | getPath()
Returns the full path to the file this configuration is based on. |
Object | getProperty(String key) |
ReloadingStrategy | getReloadingStrategy() |
URL | getURL()
Return the URL where the configuration is stored.
|
void | initReloadingStrategy()
Helper method for initializing the reloading strategy. |
boolean | isAutoSave() |
boolean | isEmpty() |
void | load()
Load the configuration from the underlying location.
|
void | load(String fileName)
Locate the specified file and load the configuration. |
void | load(File file)
Load the configuration from the specified file. |
void | load(URL url)
Load the configuration from the specified URL. |
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. |
protected void | possiblySave()
Save the configuration if the automatic persistence is enabled
and if a file is specified. |
void | reload()
Performs a reload operation if necessary. |
void | save()
Save the configuration. |
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 | 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 | setAutoSave(boolean autoSave) |
void | setBasePath(String basePath)
Sets the base path. |
void | setEncoding(String encoding) |
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 or relative path name.
|
void | setProperty(String key, Object value)
Sets a new value for the specified property. |
void | setReloadingStrategy(ReloadingStrategy strategy) |
void | setURL(URL url)
Set the location of this configuration as a URL. |
Since: 1.1
Parameters: fileName The name of the file to load.
Throws: ConfigurationException Error while loading the file
Since: 1.1
Parameters: file The file to load.
Throws: ConfigurationException Error while loading the file
Since: 1.1
Parameters: url The location of the file to load.
Throws: ConfigurationException Error while loading the file
Since: 1.1
Parameters: key the key of the new property value the value
Returns: the copy
Since: 1.3
Parameters: file the target file
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.See Also: enterNoReload
Parameters: type the event type propName the name of the property propValue the value of the property before the before update flag
Returns: the base path
See Also: getBasePath
Returns: the file where the configuration is stored; this can be null
Returns: the file name
Returns: the full path to the configuration file
Returns: the configuration's location as URL
Throws: ConfigurationException if loading of the configuration fails
Parameters: fileName the name of the file to be loaded
Throws: ConfigurationException if an error occurs
Parameters: file the file to load
Throws: ConfigurationException if an error occurs
Parameters: url the URL of the file to be loaded
Throws: ConfigurationException if an error occurs
Parameters: in the input stream
Throws: ConfigurationException if an error occurs during the load operation
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
EVENT_RELOAD
and contains the exception that caused the
event.Throws: ConfigurationException if an error occurs or no file name has been set yet
Parameters: fileName the file name
Throws: ConfigurationException if an error occurs during the save operation
Parameters: url the URL
Throws: ConfigurationException if an error occurs during the save operation
Parameters: file the target file
Throws: ConfigurationException if an error occurs during the save operation
Parameters: out the output stream
Throws: ConfigurationException if an error occurs during the save operation
Parameters: out the output stream encoding the encoding to use
Throws: ConfigurationException if an error occurs during the save operation
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.
Parameters: file the file where the configuration is stored
setPath()
to set a full qualified file name.
Parameters: fileName the name of the file
Parameters: path the full path name of the configuration file
Parameters: key the key of the affected property value the value
Parameters: url the location of this configuration as URL