org.apache.commons.configuration.beanutils
Class XMLBeanDeclaration

java.lang.Object
  org.apache.commons.configuration.beanutils.XMLBeanDeclaration

All Implemented Interfaces:

BeanDeclaration

Direct Known Subclasses:

DefaultConfigurationBuilder.ConfigurationDeclaration

public class XMLBeanDeclaration

extends Object

implements BeanDeclaration

An implementation of the BeanDeclaration interface that is suitable for XML configuration files.

This class defines the standard layout of a bean declaration in an XML configuration file. Such a declaration must look like the following example fragement:

   ...
   <personBean config-class="my.model.PersonBean"
       lastName="Doe" firstName="John">
       <address config-class="my.model.AddressBean"
           street="21st street 11" zip="1234"
           city="TestCity"/>
   </personBean>
 

The bean declaration can be contained in an arbitrary element. Here it is the <personBean> element. In the attributes of this element there can occur some reserved attributes, which have the following meaning:

config-class

Here the full qualified name of the bean's class can be specified. An instance of this class will be created. If this attribute is not specified, the bean class must be provided in another way, e.g. as the defaultClass passed to the BeanHelper class.

config-factory

This attribute can contain the name of the BeanFactory that should be used for creating the bean. If it is defined, a factory with this name must have been registered at the BeanHelper class. If this attribute is missing, the default bean factory will be used.

config-factoryParam

With this attribute a parameter can be specified that will be passed to the bean factory. This may be useful for custom bean factories.

All further attributes starting with the config- prefix are considered as meta data and will be ignored. All other attributes are treated as properties of the bean to be created, i.e. corresponding setter methods of the bean will be invoked with the values specified here.

If the bean to be created has also some complex properties (which are itself beans), their values cannot be initialized from attributes. For this purpose nested elements can be used. The example listing shows how an address bean can be initialized. This is done in a nested element whose name must match the name of a property of the enclosing bean declaration. The format of this nested element is exactly the same as for the bean declaration itself, i.e. it can have attributes defining meta data or bean properties and even further nested elements for complex bean properties.

A XMLBeanDeclaration object is usually created from a HierarchicalConfiguration. From this it will derive a SubnodeConfiguration, which is used to access the needed properties. This subnode configuration can be obtained using the getConfiguration() method. All of its properties can be accessed in the usual way. To ensure that the property keys used by this class are understood by the configuration, the default expression engine will be set.

Since:

1.3

Version:

$Id: XMLBeanDeclaration.java 439648 2006-09-02 20:42:10Z oheger $

Author:

Oliver Heger

Field Summary

static String	ATTR_BEAN_CLASS Constant for the bean class attribute.
static String	ATTR_BEAN_FACTORY Constant for the bean factory attribute.
static String	ATTR_FACTORY_PARAM Constant for the bean factory parameter attribute.
static String	ATTR_PREFIX Constant for the prefix for reserved attributes.
static String	RESERVED_PREFIX Constant for the prefix of reserved attributes.

Constructor Summary

XMLBeanDeclaration(HierarchicalConfiguration config)
Creates a new instance of XMLBeanDeclaration and initializes it from the given configuration.

XMLBeanDeclaration(HierarchicalConfiguration config, String key)
Creates a new instance of XMLBeanDeclaration and initializes it from the given configuration.

XMLBeanDeclaration(HierarchicalConfiguration config, String key, boolean optional)
Creates a new instance of XMLBeanDeclaration and initializes it from the given configuration.

XMLBeanDeclaration(SubnodeConfiguration config, ConfigurationNode node)
Creates a new instance of XMLBeanDeclaration and initializes it with the configuration node that contains the bean declaration.

Method Summary

String	getBeanClassName() Returns the name of the class of the bean to be created.
String	getBeanFactoryName() Returns the name of the bean factory.
Object	getBeanFactoryParameter() Returns a parameter for the bean factory.
Map	getBeanProperties() Returns a map with the bean's (simple) properties.
SubnodeConfiguration	getConfiguration() Returns the configuration object this bean declaration is based on.
Map	getNestedBeanDeclarations() Returns a map with bean declarations for the complex properties of the bean to be created.
ConfigurationNode	getNode() Returns the node that contains the bean declaration.
protected Object	interpolate(Object value) Performs interpolation for the specified value.
protected boolean	isReservedNode(ConfigurationNode nd) Checks if the specified node is reserved and thus should be ignored.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

RESERVED_PREFIX

public static final String RESERVED_PREFIX

Constant for the prefix of reserved attributes.

See Also:

Constant Field Values

ATTR_PREFIX

public static final String ATTR_PREFIX

Constant for the prefix for reserved attributes.

See Also:

Constant Field Values

ATTR_BEAN_CLASS

public static final String ATTR_BEAN_CLASS

Constant for the bean class attribute.

See Also:

Constant Field Values

ATTR_BEAN_FACTORY

public static final String ATTR_BEAN_FACTORY

Constant for the bean factory attribute.

See Also:

Constant Field Values

ATTR_FACTORY_PARAM

public static final String ATTR_FACTORY_PARAM

Constant for the bean factory parameter attribute.

See Also:

Constant Field Values

Constructor Detail

XMLBeanDeclaration

public XMLBeanDeclaration(HierarchicalConfiguration config,
                          String key)

Creates a new instance of XMLBeanDeclaration and initializes it from the given configuration. The passed in key points to the bean declaration.

Parameters:

config - the configuration

key - the key to the bean declaration (this key must point to exactly one bean declaration or a IllegalArgumentException exception will be thrown)

XMLBeanDeclaration

public XMLBeanDeclaration(HierarchicalConfiguration config,
                          String key,
                          boolean optional)

Creates a new instance of XMLBeanDeclaration and initializes it from the given configuration. The passed in key points to the bean declaration. If the key does not exist and the boolean argument is true, the declaration is initialized with an empty configuration. It is possible to create objects from such an empty declaration if a default class is provided. If the key on the other hand has multiple values or is undefined and the boolean argument is false, a IllegalArgumentException exception will be thrown.

Parameters:

config - the configuration

key - the key to the bean declaration

optional - a flag whether this declaration is optional; if set to true, no exception will be thrown if the passed in key is undefined

XMLBeanDeclaration

public XMLBeanDeclaration(HierarchicalConfiguration config)

Creates a new instance of XMLBeanDeclaration and initializes it from the given configuration. The configuration's root node must contain the bean declaration.

Parameters:

config - the configuration with the bean declaration

XMLBeanDeclaration

public XMLBeanDeclaration(SubnodeConfiguration config,
                          ConfigurationNode node)

Creates a new instance of XMLBeanDeclaration and initializes it with the configuration node that contains the bean declaration.

Parameters:

config - the configuration

node - the node with the bean declaration.

Method Detail

getConfiguration

public SubnodeConfiguration getConfiguration()

Returns the configuration object this bean declaration is based on.

Returns:

the associated configuration

getNode

public ConfigurationNode getNode()

Returns the node that contains the bean declaration.

Returns:

the configuration node this bean declaration is based on

getBeanFactoryName

public String getBeanFactoryName()

Returns the name of the bean factory. This information is fetched from the config-factory attribute.

Specified by:

getBeanFactoryName in interface BeanDeclaration

Returns:

the name of the bean factory

getBeanFactoryParameter

public Object getBeanFactoryParameter()

Returns a parameter for the bean factory. This information is fetched from the config-factoryParam attribute.

Specified by:

getBeanFactoryParameter in interface BeanDeclaration

Returns:

the parameter for the bean factory

getBeanClassName

public String getBeanClassName()

Returns the name of the class of the bean to be created. This information is obtained from the config-class attribute.

Specified by:

getBeanClassName in interface BeanDeclaration

Returns:

the name of the bean's class

getBeanProperties

public Map getBeanProperties()

Returns a map with the bean's (simple) properties. The properties are collected from all attribute nodes, which are not reserved.

Specified by:

getBeanProperties in interface BeanDeclaration

Returns:

a map with the bean's properties

getNestedBeanDeclarations

public Map getNestedBeanDeclarations()

Returns a map with bean declarations for the complex properties of the bean to be created. These declarations are obtained from the child nodes of this declaration's root node.

Specified by:

getNestedBeanDeclarations in interface BeanDeclaration

Returns:

a map with bean declarations for complex properties

interpolate

protected Object interpolate(Object value)

Performs interpolation for the specified value. This implementation will interpolate against the current subnode configuration's parent. If sub classes need a different interpolation mechanism, they should override this method.

Parameters:

value - the value that is to be interpolated

Returns:

the interpolated value

isReservedNode

protected boolean isReservedNode(ConfigurationNode nd)

Checks if the specified node is reserved and thus should be ignored. This method is called when the maps for the bean's properties and complex properties are collected. It checks whether the given node is an attribute node and if its name starts with the reserved prefix.

Parameters:

nd - the node to be checked

Returns:

a flag whether this node is reserved (and does not point to a property)