org.apache.commons.configuration
Class XMLConfiguration

java.lang.Object
  extended byorg.apache.commons.configuration.AbstractConfiguration
      extended byorg.apache.commons.configuration.HierarchicalConfiguration
          extended byorg.apache.commons.configuration.XMLConfiguration
All Implemented Interfaces:
Configuration, FileConfiguration
Direct Known Subclasses:
HierarchicalXMLConfiguration

public class XMLConfiguration
extends HierarchicalConfiguration
implements FileConfiguration

A specialized hierarchical configuration class that is able to parse XML documents.

The parsed document will be stored keeping its structure. The class also tries to preserve as much information from the loaded XML document as possible, including comments and processing instructions. These will be contained in documents created by the save() methods, too.

Since:
commons-configuration 1.0
Version:
$Revision$, $Date: 2005-03-05 11:26:22 +0100 (Sat, 05 Mar 2005) $
Author:
Jörg Schaible, Oliver Heger

Nested Class Summary
 
Nested classes inherited from class org.apache.commons.configuration.HierarchicalConfiguration
HierarchicalConfiguration.BuilderVisitor, HierarchicalConfiguration.Node, HierarchicalConfiguration.NodeVisitor
 
Field Summary
 
Fields inherited from class org.apache.commons.configuration.AbstractConfiguration
END_TOKEN, START_TOKEN
 
Constructor Summary
XMLConfiguration()
          Creates a new instance of XMLConfiguration.
XMLConfiguration(File file)
          Creates a new instance of XMLConfiguration.
XMLConfiguration(String fileName)
          Creates a new instance of XMLConfiguration.
XMLConfiguration(URL url)
          Creates a new instance of XMLConfiguration.
 
Method Summary
protected  void addPropertyDirect(String key, Object obj)
          Adds the property with the specified key.
 void clearProperty(String key)
          Remove a property from the configuration.
 void clearTree(String key)
          Removes all values of the property with the given name and of keys that start with this name.
protected  Document createDocument()
          Creates a DOM document from the internal tree of configuration nodes.
protected  HierarchicalConfiguration.Node createNode(String name)
          Creates a new node object.
 String getBasePath()
          Return the base path.
 Document getDocument()
          Returns the XML document this configuration was loaded from.
 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.
 ReloadingStrategy getReloadingStrategy()
          Return the reloading strategy.
 String getRootElementName()
          Returns the name of the root element.
 URL getURL()
          Return the URL where the configuration is stored.
 void initProperties(Document document, boolean elemRefs)
          Initializes this configuration from an XML document.
 boolean isAutoSave()
          Tells if properties are automatically saved to the disk.
 void load()
          Load the configuration from the underlying URL.
 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(Reader in)
          Load the properties from the given reader.
 void load(String fileName)
          Locate the specified file and load the configuration.
 void load(URL url)
          Load the configuration from the specified URL.
 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 save(Writer writer)
          Saves the configuration to the specified writer.
 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 setProperty(String key, Object value)
          Set a property, this will replace any previously set values.
 void setReloadingStrategy(ReloadingStrategy strategy)
          Set the reloading strategy.
 void setRootElementName(String name)
          Sets the name of the root element.
 void setURL(URL url)
          The URL where the configuration is stored.
 
Methods inherited from class org.apache.commons.configuration.HierarchicalConfiguration
addNodes, clearNode, containsKey, createAddPath, fetchAddNode, fetchNodeList, findLastPathNode, findPropertyNodes, getKeys, getKeys, getMaxIndex, getProperty, getRoot, isEmpty, nodeDefined, removeNode, setRoot, subset
 
Methods inherited from class org.apache.commons.configuration.AbstractConfiguration
addProperty, clear, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getList, getList, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, interpolate, interpolateHelper, isThrowExceptionOnMissing, resolveContainerStore, setDelimiter, setThrowExceptionOnMissing
 
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.Configuration
addProperty, clear, containsKey, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getKeys, getKeys, getList, getList, getLong, getLong, getLong, getProperties, getProperty, getShort, getShort, getShort, getString, getString, getStringArray, isEmpty, subset
 

Constructor Detail

XMLConfiguration

public XMLConfiguration()
Creates a new instance of XMLConfiguration.


XMLConfiguration

public XMLConfiguration(String fileName)
                 throws ConfigurationException
Creates a new instance of XMLConfiguration. The configuration is loaded from the specified file

Parameters:
fileName - the name of the file to load
Throws:
ConfigurationException - if the file cannot be loaded

XMLConfiguration

public XMLConfiguration(File file)
                 throws ConfigurationException
Creates a new instance of XMLConfiguration. The configuration is loaded from the specified file.

Parameters:
file - the file
Throws:
ConfigurationException - if an error occurs while loading the file

XMLConfiguration

public XMLConfiguration(URL url)
                 throws ConfigurationException
Creates a new instance of XMLConfiguration. The configuration is loaded from the specified URL.

Parameters:
url - the URL
Throws:
ConfigurationException - if loading causes an error
Method Detail

getRootElementName

public String getRootElementName()
Returns the name of the root element. If this configuration was loaded from a XML document, the name of this document's root element is returned. Otherwise it is possible to set a name for the root element that will be used when this configuration is stored.

Returns:
the name of the root element

setRootElementName

public void setRootElementName(String name)
Sets the name of the root element. This name is used when this configuration object is stored in an XML file. Note that setting the name of the root element works only if this configuration has been newly created. If the configuration was loaded from an XML file, the name cannot be changed and an UnsupportedOperationException exception is thrown. Whether this configuration has been loaded from an XML document or not can be found out using the getDocument() method.

Parameters:
name - the name of the root element

getDocument

public Document getDocument()
Returns the XML document this configuration was loaded from. The return value is null if this configuration was not loaded from a XML document.

Returns:
the XML document this configuration was loaded from

addPropertyDirect

protected void addPropertyDirect(String key,
                                 Object obj)
Description copied from class: HierarchicalConfiguration

Adds the property with the specified key.

To be able to deal with the structure supported by this configuration implementation the passed in key is of importance, especially the indices it might contain. The following example should clearify this: Suppose the actual configuration contains the following elements:

 tables
    +-- table
            +-- name = user
            +-- fields
                    +-- field
                            +-- name = uid
                    +-- field
                            +-- name = firstName
                    ...
    +-- table
            +-- name = documents
            +-- fields
                   ...
 

In this example a database structure is defined, e.g. all fields of the first table could be accessed using the key tables.table(0).fields.field.name. If now properties are to be added, it must be exactly specified at which position in the hierarchy the new property is to be inserted. So to add a new field name to a table it is not enough to say just

 config.addProperty("tables.table.fields.field.name", "newField");
 

The statement given above contains some ambiguity. For instance it is not clear, to which table the new field should be added. If this method finds such an ambiguity, it is resolved by following the last valid path. Here this would be the last table. The same is true for the field; because there are multiple fields and no explicit index is provided, a new name property would be added to the last field - which is propably not what was desired.

To make things clear explicit indices should be provided whenever possible. In the example above the exact table could be specified by providing an index for the table element as in tables.table(1).fields. By specifying an index it can also be expressed that at a given position in the configuration tree a new branch should be added. In the example above we did not want to add an additional name element to the last field of the table, but we want a complete new field element. This can be achieved by specifying an invalid index (like -1) after the element where a new branch should be created. Given this our example would run:

 config.addProperty("tables.table(1).fields.field(-1).name", "newField");
 

With this notation it is possible to add new branches everywhere. We could for instance create a new table element by specifying

 config.addProperty("tables.table(-1).fields.field.name", "newField2");
 

(Note that because after the table element a new branch is created indices in following elements are not relevant; the branch is new so there cannot be any ambiguities.)

Overrides:
addPropertyDirect in class HierarchicalConfiguration
Parameters:
key - the key of the new property
obj - the value of the new property

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 HierarchicalConfiguration
Parameters:
key - the key of the property to be removed

clearTree

public void clearTree(String key)
Description copied from class: HierarchicalConfiguration
Removes all values of the property with the given name and of keys that start with this name. So if there is a property with the key "foo" and a property with the key "foo.bar", a call of clearTree("foo") would remove both properties.

Overrides:
clearTree in class HierarchicalConfiguration
Parameters:
key - the key of the property to be removed

setProperty

public void setProperty(String key,
                        Object value)
Description copied from interface: Configuration
Set a property, this will replace any previously set values. Set values is implicitly a call to clearProperty(key), addProperty(key, value).

Specified by:
setProperty in interface Configuration
Overrides:
setProperty in class HierarchicalConfiguration

initProperties

public void initProperties(Document document,
                           boolean elemRefs)
Initializes this configuration from an XML document.

Parameters:
document - the document to be parsed
elemRefs - a flag whether references to the XML elements should be set

createDocument

protected Document createDocument()
                           throws ConfigurationException
Creates a DOM document from the internal tree of configuration nodes.

Returns:
the new document
Throws:
ConfigurationException - if an error occurs

createNode

protected HierarchicalConfiguration.Node createNode(String name)
Creates a new node object. This implementation returns an instance of the XMLNode class.

Overrides:
createNode in class HierarchicalConfiguration
Parameters:
name - the node's name
Returns:
the new node

load

public void load()
          throws ConfigurationException
Description copied from interface: FileConfiguration
Load the configuration from the underlying URL. If the URL is not specified, it attempts to locate the specified file name.

Specified by:
load in interface FileConfiguration
Throws:
ConfigurationException

load

public void load(String fileName)
          throws ConfigurationException
Description copied from interface: FileConfiguration
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
Description copied from interface: FileConfiguration
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
Description copied from interface: FileConfiguration
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
Description copied from interface: FileConfiguration
Load the configuration from the specified stream, using the encoding returned by FileConfiguration.getEncoding().

Specified by:
load in interface FileConfiguration
Parameters:
in - the input stream
Throws:
ConfigurationException

load

public void load(InputStream in,
                 String encoding)
          throws ConfigurationException
Description copied from interface: FileConfiguration
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

load

public void load(Reader in)
          throws ConfigurationException
Load the properties from the given reader. Note that the clear() method is not called, so the properties contained in the loaded file will be added to the actual set of properties.

Specified by:
load in interface FileConfiguration
Parameters:
in - An InputStream.
Throws:
ConfigurationException

save

public void save()
          throws ConfigurationException
Description copied from interface: FileConfiguration
Save the configuration.

Specified by:
save in interface FileConfiguration
Throws:
ConfigurationException

save

public void save(String fileName)
          throws ConfigurationException
Description copied from interface: FileConfiguration
Save the configuration to the specified file.

Specified by:
save in interface FileConfiguration
Parameters:
fileName -
Throws:
ConfigurationException

save

public void save(File file)
          throws ConfigurationException
Description copied from interface: FileConfiguration
Save the configuration to the specified file.

Specified by:
save in interface FileConfiguration
Parameters:
file -
Throws:
ConfigurationException

save

public void save(URL url)
          throws ConfigurationException
Description copied from interface: FileConfiguration
Save the configuration to the specified URL if it's a file URL.

Specified by:
save in interface FileConfiguration
Parameters:
url -
Throws:
ConfigurationException

save

public void save(OutputStream out)
          throws ConfigurationException
Description copied from interface: FileConfiguration
Save the configuration to the specified stream, using the encoding returned by FileConfiguration.getEncoding().

Specified by:
save in interface FileConfiguration
Parameters:
out -
Throws:
ConfigurationException

save

public void save(OutputStream out,
                 String encoding)
          throws ConfigurationException
Description copied from interface: FileConfiguration
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

save

public void save(Writer writer)
          throws ConfigurationException
Saves the configuration to the specified writer.

Specified by:
save in interface FileConfiguration
Parameters:
writer - the writer used to save the configuration
Throws:
ConfigurationException - if an error occurs

getFileName

public String getFileName()
Description copied from interface: FileConfiguration
Return the name of the file.

Specified by:
getFileName in interface FileConfiguration

setFileName

public void setFileName(String fileName)
Description copied from interface: FileConfiguration
Set the name of the file.

Specified by:
setFileName in interface FileConfiguration
Parameters:
fileName - the name of the file

getBasePath

public String getBasePath()
Description copied from interface: FileConfiguration
Return the base path.

Specified by:
getBasePath in interface FileConfiguration

setBasePath

public void setBasePath(String basePath)
Description copied from interface: FileConfiguration
Set the base path. Relative configurations are loaded from this path.

Specified by:
setBasePath in interface FileConfiguration
Parameters:
basePath - the base path.

getFile

public File getFile()
Description copied from interface: FileConfiguration
Return the file where the configuration is stored.

Specified by:
getFile in interface FileConfiguration

setFile

public void setFile(File file)
Description copied from interface: FileConfiguration
Set the file where the configuration is stored.

Specified by:
setFile in interface FileConfiguration
Parameters:
file -

getURL

public URL getURL()
Description copied from interface: FileConfiguration
Return the URL where the configuration is stored.

Specified by:
getURL in interface FileConfiguration

setURL

public void setURL(URL url)
Description copied from interface: FileConfiguration
The URL where the configuration is stored.

Specified by:
setURL in interface FileConfiguration
Parameters:
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

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

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


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