XMLBeanDeclaration (Apache Commons Configuration 2.7 API)

java.lang.Object
- org.apache.commons.configuration2.beanutils.XMLBeanDeclaration

All Implemented Interfaces:

BeanDeclaration

Direct Known Subclasses:

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 fragment:
```
   ...
   <personBean config-class="my.model.PersonBean"
       lastName="Doe" firstName="John">
       <config-constrarg config-value="ID03493" config-type="java.lang.String"/>
       <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.

If the bean should be created using a specific constructor, the constructor arguments have to be specified. This is done by an arbitrary number of nested <config-constrarg> elements. Each element can either have the config-value attribute - then it defines a simple value - or must be again a bean declaration (conforming to the format defined here) defining the complex value of this constructor argument.

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

Field Summary

Fields
Modifier and Type	Field and Description
`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

Constructors
Constructor and Description
`XMLBeanDeclaration(HierarchicalConfiguration<T> config)` Creates a new instance of `XMLBeanDeclaration` and initializes it from the given configuration.
`XMLBeanDeclaration(HierarchicalConfiguration<T> config, String key)` Creates a new instance of `XMLBeanDeclaration` and initializes it from the given configuration.
`XMLBeanDeclaration(HierarchicalConfiguration<T> config, String key, boolean optional)` Creates a new instance of `XMLBeanDeclaration` and initializes it from the given configuration supporting optional declarations.
`XMLBeanDeclaration(HierarchicalConfiguration<T> config, String key, boolean optional, String defBeanClsName)` Creates a new instance of `XMLBeanDeclaration` and initializes it from the given configuration supporting optional declarations and a default bean class name.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected Set<String>`	`getAttributeNames()` Returns a set with the names of the attributes of the configuration node holding the data of this bean declaration.
`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<String,Object>`	`getBeanProperties()` Returns a map with the bean's (simple) properties.
`HierarchicalConfiguration<?>`	`getConfiguration()` Returns the configuration object this bean declaration is based on.
`Collection<ConstructorArg>`	`getConstructorArgs()` Returns a collection with constructor arguments.
`String`	`getDefaultBeanClassName()` Returns the name of the default bean class.
`Map<String,Object>`	`getNestedBeanDeclarations()` Returns a map with bean declarations for the complex properties of the bean to be created.
`protected Object`	`interpolate(Object value)` Performs interpolation for the specified value.
`protected boolean`	`isReservedAttributeName(String name)` Checks if the specified attribute name is reserved and thus does not point to a property of the bean to be created.
`protected boolean`	`isReservedChildName(String name)` Checks if the specified child node name is reserved and thus should be ignored.
`protected boolean`	`isReservedName(String name)` Checks if the specified name of a node or attribute 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<T> 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.
    
    Type Parameters:
    
    T - the node type of the configuration
    
    Parameters:
    
    config - the configuration (must not be null)
    
    key - the key to the bean declaration (this key must point to exactly one bean declaration or a IllegalArgumentException exception will be thrown)
    
    Throws:
    
    IllegalArgumentException - if required information is missing to construct the bean declaration
  - XMLBeanDeclaration
```
public XMLBeanDeclaration(HierarchicalConfiguration<T> config,
                          String key,
                          boolean optional)
```
    Creates a new instance of XMLBeanDeclaration and initializes it from the given configuration supporting optional declarations.
    
    Type Parameters:
    
    T - the node type of the configuration
    
    Parameters:
    
    config - the configuration (must not be null)
    
    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
    
    Throws:
    
    IllegalArgumentException - if required information is missing to construct the bean declaration
  - XMLBeanDeclaration
```
public XMLBeanDeclaration(HierarchicalConfiguration<T> config,
                          String key,
                          boolean optional,
                          String defBeanClsName)
```
    Creates a new instance of XMLBeanDeclaration and initializes it from the given configuration supporting optional declarations and a default bean class name. 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. It is possible to set a default bean class name; this name is used if the configuration does not contain a bean class.
    
    Type Parameters:
    
    T - the node type of the configuration
    
    Parameters:
    
    config - the configuration (must not be null)
    
    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
    
    defBeanClsName - a default bean class name
    
    Throws:
    
    IllegalArgumentException - if required information is missing to construct the bean declaration
    
    Since:
    
    2.0
  - XMLBeanDeclaration
```
public XMLBeanDeclaration(HierarchicalConfiguration<T> config)
```
    Creates a new instance of XMLBeanDeclaration and initializes it from the given configuration. The configuration's root node must contain the bean declaration.
    
    Type Parameters:
    
    T - the node type of the configuration
    
    Parameters:
    
    config - the configuration with the bean declaration
- Method Detail
  - getConfiguration
```
public HierarchicalConfiguration<?> getConfiguration()
```
    Returns the configuration object this bean declaration is based on.
    
    Returns:
    
    the associated configuration
  - getDefaultBeanClassName
```
public String getDefaultBeanClassName()
```
    Returns the name of the default bean class. This class is used if no bean class is specified in the configuration. It may be null if no default class was set.
    
    Returns:
    
    the default bean class name
    
    Since:
    
    2.0
  - 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<String,Object> 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<String,Object> 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
  - getConstructorArgs
```
public Collection<ConstructorArg> getConstructorArgs()
```
    Returns a collection with constructor arguments. This data is used to determine the constructor of the bean class to be invoked. The values of the arguments are passed to the constructor. An implementation can return null or an empty collection; then the standard constructor of the bean class is called. This implementation processes all child nodes with the name config-constrarg. If such a node has a config-class attribute, it is considered a nested bean declaration; otherwise it is interpreted as a simple value. If no nested constructor argument declarations are found, result is an empty collection.
    
    Specified by:
    
    getConstructorArgs in interface BeanDeclaration
    
    Returns:
    
    a collection with the arguments to be passed to the bean class's constructor
  - 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
  - isReservedChildName
```
protected boolean isReservedChildName(String name)
```
    Checks if the specified child node name is reserved and thus should be ignored. This method is called when processing child nodes of this bean declaration. It is then possible to ignore some nodes with a specific meaning. This implementation delegates to isReservedName(String) .
    
    Parameters:
    
    name - the name of the child node to be checked
    
    Returns:
    
    a flag whether this name is reserved
    
    Since:
    
    2.0
  - isReservedAttributeName
```
protected boolean isReservedAttributeName(String name)
```
    Checks if the specified attribute name is reserved and thus does not point to a property of the bean to be created. This method is called when processing the attributes of this bean declaration. It is then possible to ignore some attributes with a specific meaning. This implementation delegates to isReservedName(String).
    
    Parameters:
    
    name - the name of the attribute to be checked
    
    Returns:
    
    a flag whether this name is reserved
    
    Since:
    
    2.0
  - isReservedName
```
protected boolean isReservedName(String name)
```
    Checks if the specified name of a node or attribute is reserved and thus should be ignored. This method is called per default by the methods for checking attribute and child node names. It checks whether the passed in name starts with the reserved prefix.
    
    Parameters:
    
    name - the name to be checked
    
    Returns:
    
    a flag whether this name is reserved
  - getAttributeNames
```
protected Set<String> getAttributeNames()
```
    Returns a set with the names of the attributes of the configuration node holding the data of this bean declaration.
    
    Returns:
    
    the attribute names of the underlying configuration node

Class XMLBeanDeclaration

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

RESERVED_PREFIX

ATTR_PREFIX

ATTR_BEAN_CLASS

ATTR_BEAN_FACTORY

ATTR_FACTORY_PARAM

Constructor Detail

XMLBeanDeclaration

XMLBeanDeclaration

XMLBeanDeclaration

XMLBeanDeclaration

Method Detail

getConfiguration

getDefaultBeanClassName

getBeanFactoryName

getBeanFactoryParameter

getBeanClassName

getBeanProperties

getNestedBeanDeclarations

getConstructorArgs

interpolate

isReservedChildName

isReservedAttributeName

isReservedName

getAttributeNames