org.apache.commons.configuration

Class ConfigurationFactory

public class ConfigurationFactory extends Object

Factory class to create a CompositeConfiguration from a .xml file using Digester. By default it can handle the Configurations from commons- configuration. If you need to add your own, then you can pass in your own digester rules to use. It is also namespace aware, by providing a digesterRuleNamespaceURI.

Note: Almost all of the features provided by this class and many more are also available for the DefaultConfigurationBuilder class. DefaultConfigurationBuilder also has a more robust merge algorithm for constructing combined configurations. So it is recommended to use this class instead of ConfigurationFactory.

Version: $Id: ConfigurationFactory.java 524006 2007-03-30 09:33:17Z oheger $

Author: Eric Pugh Henning P. Schmiedehausen Oliver Heger

Nested Class Summary
static classConfigurationFactory.AdditionalConfigurationData
A simple data class that holds all information about a configuration from the <additional> section.
static classConfigurationFactory.CallOptionalMethodRule
A special implementation of Digester's CallMethodRule that is internally used for calling a file configuration's load() method.
static classConfigurationFactory.ConfigurationBuilder
An internally used helper class for constructing the composite configuration object.
classConfigurationFactory.DigesterConfigurationFactory
A base class for digester factory classes.
classConfigurationFactory.FileConfigurationFactory
A tiny inner class that allows the Configuration Factory to let the digester construct FileConfiguration objects that already have the correct base Path set.
classConfigurationFactory.JNDIConfigurationFactory
A tiny inner class that allows the Configuration Factory to let the digester construct JNDIConfiguration objects.
classConfigurationFactory.PropertiesConfigurationFactory
A factory that returns an XMLPropertiesConfiguration for .xml files and a PropertiesConfiguration for the others.
classConfigurationFactory.PropertyListConfigurationFactory
A factory that returns an XMLPropertyListConfiguration for .xml files and a PropertyListConfiguration for the others.
classConfigurationFactory.SystemConfigurationFactory
A tiny inner class that allows the Configuration Factory to let the digester construct SystemConfiguration objects.
Field Summary
static StringATTR_FILENAME
Constant for the fileName attribute.
static StringATTR_OPTIONAL
Constant for the optional attribute.
StringbasePath
The basePath to prefix file paths for file based property files.
StringconfigurationFileName
The XML file with the details about the configuration to load
URLconfigurationURL
The URL to the XML file with the details about the configuration to load.
StringdigesterRuleNamespaceURI
The digester namespace to parse
URLdigesterRules
URL for xml digester rules file
static StringDEF_BASE_PATH
Constant for the default base path (points to actual directory).
StringimplicitBasePath
The implicit base path for included files.
static Loglog
static logger
static StringMETH_LOAD
Constant for the load method.
static StringSEC_ADDITIONAL
Constant for the additional section.
static StringSEC_OVERRIDE
Constant for the override section.
static StringSEC_ROOT
Constant for the root element in the info file.
Constructor Summary
ConfigurationFactory()
Constructor
ConfigurationFactory(String configurationFileName)
Constructor with ConfigurationFile Name passed
Method Summary
voidconfigureNamespace(Digester digester)
Configure the current digester to be namespace aware and to have a Configuration object to which all of the other configurations should be added
protected voidenableDigesterSubstitutor(Digester digester)
Adds a substitutor to interpolate system properties
StringgetBasePath()
Returns the Base path from which this Configuration Factory operates.
ConfigurationgetConfiguration()
Return the configuration provided by this factory.
StringgetConfigurationFileName()
Returns the configurationFile.
URLgetConfigurationURL()
Returns the URL of the configuration file to be loaded.
StringgetDigesterRuleNamespaceURI()
Returns the digesterRuleNamespaceURI.
URLgetDigesterRules()
Returns the digesterRules.
protected voidinitDefaultDigesterRules(Digester digester)
Initializes the parsing rules for the default digester This allows the Configuration Factory to understand the default types: Properties, XML and JNDI.
protected voidinitDigesterSectionRules(Digester digester, String matchString, boolean additional)
Sets up digester rules for a specified section of the configuration info file.
voidsetBasePath(String basePath)
Sets the basePath for all file references from this Configuration Factory.
voidsetConfigurationFileName(String configurationFileName)
Sets the configurationFile.
voidsetConfigurationURL(URL url)
Sets the URL of the configuration to load.
voidsetDigesterRuleNamespaceURI(String digesterRuleNamespaceURI)
Sets the digesterRuleNamespaceURI.
voidsetDigesterRules(URL digesterRules)
Sets the digesterRules.
protected voidsetupDigesterInstance(Digester digester, String matchString, ObjectCreationFactory factory, String method, boolean additional)
Sets up digester rules for a configuration to be loaded.
protected voidsetupUnionRules(Digester digester, String matchString)
Sets up rules for configurations in the additional section.

Field Detail

ATTR_FILENAME

private static final String ATTR_FILENAME
Constant for the fileName attribute.

ATTR_OPTIONAL

private static final String ATTR_OPTIONAL
Constant for the optional attribute.

basePath

private String basePath
The basePath to prefix file paths for file based property files.

configurationFileName

private String configurationFileName
The XML file with the details about the configuration to load

configurationURL

private URL configurationURL
The URL to the XML file with the details about the configuration to load.

digesterRuleNamespaceURI

private String digesterRuleNamespaceURI
The digester namespace to parse

digesterRules

private URL digesterRules
URL for xml digester rules file

DEF_BASE_PATH

private static final String DEF_BASE_PATH
Constant for the default base path (points to actual directory).

implicitBasePath

private String implicitBasePath
The implicit base path for included files. This path is determined by the configuration to load and used unless no other base path was explicitely specified.

log

private static Log log
static logger

METH_LOAD

private static final String METH_LOAD
Constant for the load method.

SEC_ADDITIONAL

private static final String SEC_ADDITIONAL
Constant for the additional section.

SEC_OVERRIDE

private static final String SEC_OVERRIDE
Constant for the override section.

SEC_ROOT

private static final String SEC_ROOT
Constant for the root element in the info file.

Constructor Detail

ConfigurationFactory

public ConfigurationFactory()
Constructor

ConfigurationFactory

public ConfigurationFactory(String configurationFileName)
Constructor with ConfigurationFile Name passed

Parameters: configurationFileName The path to the configuration file

Method Detail

configureNamespace

private void configureNamespace(Digester digester)
Configure the current digester to be namespace aware and to have a Configuration object to which all of the other configurations should be added

Parameters: digester The Digester to configure

enableDigesterSubstitutor

protected void enableDigesterSubstitutor(Digester digester)
Adds a substitutor to interpolate system properties

Parameters: digester The digester to which we add the substitutor

getBasePath

public String getBasePath()
Returns the Base path from which this Configuration Factory operates. This is never null. If you set the BasePath to null, then a base path according to the configuration to load is returned.

Returns: The base Path of this configuration factory.

getConfiguration

public Configuration getConfiguration()
Return the configuration provided by this factory. It loads the configuration file which is a XML description of the actual configurations to load. It can contain various different types of configuration, e.g. Properties, XML and JNDI.

Returns: A Configuration object

Throws: ConfigurationException A generic exception that we had trouble during the loading of the configuration data.

getConfigurationFileName

public String getConfigurationFileName()
Returns the configurationFile.

Returns: The name of the configuration file. Can be null.

getConfigurationURL

public URL getConfigurationURL()
Returns the URL of the configuration file to be loaded.

Returns: the URL of the configuration to load

getDigesterRuleNamespaceURI

public String getDigesterRuleNamespaceURI()
Returns the digesterRuleNamespaceURI.

Returns: A String with the digesterRuleNamespaceURI.

getDigesterRules

public URL getDigesterRules()
Returns the digesterRules.

Returns: URL

initDefaultDigesterRules

protected void initDefaultDigesterRules(Digester digester)
Initializes the parsing rules for the default digester This allows the Configuration Factory to understand the default types: Properties, XML and JNDI. Two special sections are introduced: <override> and <additional>.

Parameters: digester The digester to configure

initDigesterSectionRules

protected void initDigesterSectionRules(Digester digester, String matchString, boolean additional)
Sets up digester rules for a specified section of the configuration info file.

Parameters: digester the current digester instance matchString specifies the section additional a flag if rules for the additional section are to be added

setBasePath

public void setBasePath(String basePath)
Sets the basePath for all file references from this Configuration Factory. Normally a base path need not to be set because it is determined by the location of the configuration file to load. All relative pathes in this file are resolved relative to this file. Setting a base path makes sense if such relative pathes should be otherwise resolved, e.g. if the configuration file is loaded from the class path and all sub configurations it refers to are stored in a special config directory.

Parameters: basePath The new basePath to set.

setConfigurationFileName

public void setConfigurationFileName(String configurationFileName)
Sets the configurationFile.

Parameters: configurationFileName The name of the configurationFile to use.

setConfigurationURL

public void setConfigurationURL(URL url)
Sets the URL of the configuration to load. This configuration can be either specified by a file name or by a URL.

Parameters: url the URL of the configuration to load

setDigesterRuleNamespaceURI

public void setDigesterRuleNamespaceURI(String digesterRuleNamespaceURI)
Sets the digesterRuleNamespaceURI.

Parameters: digesterRuleNamespaceURI The new digesterRuleNamespaceURI to use

setDigesterRules

public void setDigesterRules(URL digesterRules)
Sets the digesterRules.

Parameters: digesterRules The digesterRules to set

setupDigesterInstance

protected void setupDigesterInstance(Digester digester, String matchString, ObjectCreationFactory factory, String method, boolean additional)
Sets up digester rules for a configuration to be loaded.

Parameters: digester the current digester matchString the pattern to match with this rule factory an ObjectCreationFactory instance to use for creating new objects method the name of a method to be called or null for none additional a flag if rules for the additional section are to be added

setupUnionRules

protected void setupUnionRules(Digester digester, String matchString)
Sets up rules for configurations in the additional section.

Parameters: digester the current digester matchString the pattern to match with this rule