Class XMLBeanDeclaration
- java.lang.Object
-
- org.apache.commons.configuration2.beanutils.XMLBeanDeclaration
-
- All Implemented Interfaces:
BeanDeclaration
- Direct Known Subclasses:
ConfigurationDeclaration
public class XMLBeanDeclaration extends java.lang.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 theBeanHelper
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 theBeanHelper
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 theconfig-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 aHierarchicalConfiguration
. From this it will derive aSubnodeConfiguration
, which is used to access the needed properties. This subnode configuration can be obtained using thegetConfiguration()
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
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description (package private) static class
XMLBeanDeclaration.NodeData<T>
An internal helper class which wraps the node with the bean declaration and the corresponding node handler.
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
ATTR_BEAN_CLASS
Constant for the bean class attribute.private static java.lang.String
ATTR_BEAN_CLASS_NAME
Constant for the name of the bean class attribute.static java.lang.String
ATTR_BEAN_FACTORY
Constant for the bean factory attribute.private static java.lang.String
ATTR_CTOR_TYPE
Constant for the name of the attribute with the data type of a constructor argument.private static java.lang.String
ATTR_CTOR_VALUE
Constant for the name of the attribute with the value of a constructor argument.static java.lang.String
ATTR_FACTORY_PARAM
Constant for the bean factory parameter attribute.static java.lang.String
ATTR_PREFIX
Constant for the prefix for reserved attributes.private HierarchicalConfiguration<?>
configuration
Stores the associated configuration.private java.lang.String
defaultBeanClassName
The name of the default bean class.private static java.lang.String
ELEM_CTOR_ARG
Constant for the name of the element for constructor arguments.private XMLBeanDeclaration.NodeData<?>
nodeData
Stores the configuration node that contains the bean declaration.static java.lang.String
RESERVED_PREFIX
Constant for the prefix of reserved attributes.
-
Constructor Summary
Constructors Constructor Description XMLBeanDeclaration(HierarchicalConfiguration<?> config, XMLBeanDeclaration.NodeData<?> node)
Constructs a new instance ofXMLBeanDeclaration
and initializes it with the configuration node that contains the bean declaration.XMLBeanDeclaration(HierarchicalConfiguration<T> config)
Constructs a new instance ofXMLBeanDeclaration
and initializes it from the given configuration.XMLBeanDeclaration(HierarchicalConfiguration<T> config, java.lang.String key)
Constructs a new instance ofXMLBeanDeclaration
and initializes it from the given configuration.XMLBeanDeclaration(HierarchicalConfiguration<T> config, java.lang.String key, boolean optional)
Constructs a new instance ofXMLBeanDeclaration
and initializes it from the given configuration supporting optional declarations.XMLBeanDeclaration(HierarchicalConfiguration<T> config, java.lang.String key, boolean optional, java.lang.String defBeanClsName)
Constructs a new instance ofXMLBeanDeclaration
and initializes it from the given configuration supporting optional declarations and a default bean class name.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description (package private) BeanDeclaration
createBeanDeclaration(XMLBeanDeclaration.NodeData<?> nodeData)
Creates a newBeanDeclaration
for a child node of the current configuration node.private ConstructorArg
createConstructorArg(XMLBeanDeclaration.NodeData<?> child)
Creates aConstructorArg
object for the specified configuration node.private static <T> XMLBeanDeclaration.NodeData<T>
createNodeDataFromConfiguration(HierarchicalConfiguration<T> config)
Creates aNodeData
object from the root node of the given configuration.private java.lang.String
getAttribute(XMLBeanDeclaration.NodeData<?> nodeData, java.lang.String attribute)
Gets an attribute of a configuration node.protected java.util.Set<java.lang.String>
getAttributeNames()
Gets a set with the names of the attributes of the configuration node holding the data of this bean declaration.java.lang.String
getBeanClassName()
Gets the name of the class of the bean to be created.java.lang.String
getBeanFactoryName()
Gets the name of the bean factory.java.lang.Object
getBeanFactoryParameter()
Gets a parameter for the bean factory.java.util.Map<java.lang.String,java.lang.Object>
getBeanProperties()
Gets a map with the bean's (simple) properties.HierarchicalConfiguration<?>
getConfiguration()
Gets the configuration object this bean declaration is based on.java.util.Collection<ConstructorArg>
getConstructorArgs()
Gets a collection with constructor arguments.java.lang.String
getDefaultBeanClassName()
Gets the name of the default bean class.java.util.Map<java.lang.String,java.lang.Object>
getNestedBeanDeclarations()
Gets a map with bean declarations for the complex properties of the bean to be created.(package private) XMLBeanDeclaration.NodeData<?>
getNode()
Gets the data about the associated node.private void
initSubnodeConfiguration(HierarchicalConfiguration<?> conf)
Initializes the internally managed sub configuration.protected java.lang.Object
interpolate(java.lang.Object value)
Performs interpolation for the specified value.private static boolean
isBeanDeclarationArgument(XMLBeanDeclaration.NodeData<?> nodeData)
Tests whether the constructor argument represented by the given configuration node is a bean declaration.protected boolean
isReservedAttributeName(java.lang.String name)
Tests if the specified attribute name is reserved and thus does not point to a property of the bean to be created.protected boolean
isReservedChildName(java.lang.String name)
Tests if the specified child node name is reserved and thus should be ignored.protected boolean
isReservedName(java.lang.String name)
Tests if the specified name of a node or attribute is reserved and thus should be ignored.
-
-
-
Field Detail
-
RESERVED_PREFIX
public static final java.lang.String RESERVED_PREFIX
Constant for the prefix of reserved attributes.- See Also:
- Constant Field Values
-
ATTR_PREFIX
public static final java.lang.String ATTR_PREFIX
Constant for the prefix for reserved attributes.- See Also:
- Constant Field Values
-
ATTR_BEAN_CLASS
public static final java.lang.String ATTR_BEAN_CLASS
Constant for the bean class attribute.- See Also:
- Constant Field Values
-
ATTR_BEAN_FACTORY
public static final java.lang.String ATTR_BEAN_FACTORY
Constant for the bean factory attribute.- See Also:
- Constant Field Values
-
ATTR_FACTORY_PARAM
public static final java.lang.String ATTR_FACTORY_PARAM
Constant for the bean factory parameter attribute.- See Also:
- Constant Field Values
-
ATTR_BEAN_CLASS_NAME
private static final java.lang.String ATTR_BEAN_CLASS_NAME
Constant for the name of the bean class attribute.- See Also:
- Constant Field Values
-
ELEM_CTOR_ARG
private static final java.lang.String ELEM_CTOR_ARG
Constant for the name of the element for constructor arguments.- See Also:
- Constant Field Values
-
ATTR_CTOR_VALUE
private static final java.lang.String ATTR_CTOR_VALUE
Constant for the name of the attribute with the value of a constructor argument.- See Also:
- Constant Field Values
-
ATTR_CTOR_TYPE
private static final java.lang.String ATTR_CTOR_TYPE
Constant for the name of the attribute with the data type of a constructor argument.- See Also:
- Constant Field Values
-
configuration
private final HierarchicalConfiguration<?> configuration
Stores the associated configuration.
-
nodeData
private final XMLBeanDeclaration.NodeData<?> nodeData
Stores the configuration node that contains the bean declaration.
-
defaultBeanClassName
private final java.lang.String defaultBeanClassName
The name of the default bean class.
-
-
Constructor Detail
-
XMLBeanDeclaration
XMLBeanDeclaration(HierarchicalConfiguration<?> config, XMLBeanDeclaration.NodeData<?> node)
Constructs a new instance ofXMLBeanDeclaration
and initializes it with the configuration node that contains the bean declaration. This constructor is used internally.- Parameters:
config
- the configurationnode
- the node with the bean declaration.
-
XMLBeanDeclaration
public XMLBeanDeclaration(HierarchicalConfiguration<T> config)
Constructs a new instance ofXMLBeanDeclaration
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
-
XMLBeanDeclaration
public XMLBeanDeclaration(HierarchicalConfiguration<T> config, java.lang.String key)
Constructs a new instance ofXMLBeanDeclaration
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 aIllegalArgumentException
exception will be thrown)- Throws:
java.lang.IllegalArgumentException
- if required information is missing to construct the bean declaration
-
XMLBeanDeclaration
public XMLBeanDeclaration(HierarchicalConfiguration<T> config, java.lang.String key, boolean optional)
Constructs a new instance ofXMLBeanDeclaration
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 declarationoptional
- a flag whether this declaration is optional; if set to true, no exception will be thrown if the passed in key is undefined- Throws:
java.lang.IllegalArgumentException
- if required information is missing to construct the bean declaration
-
XMLBeanDeclaration
public XMLBeanDeclaration(HierarchicalConfiguration<T> config, java.lang.String key, boolean optional, java.lang.String defBeanClsName)
Constructs a new instance ofXMLBeanDeclaration
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, aIllegalArgumentException
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 declarationoptional
- a flag whether this declaration is optional; if set to true, no exception will be thrown if the passed in key is undefineddefBeanClsName
- a default bean class name- Throws:
java.lang.IllegalArgumentException
- if required information is missing to construct the bean declaration- Since:
- 2.0
-
-
Method Detail
-
createNodeDataFromConfiguration
private static <T> XMLBeanDeclaration.NodeData<T> createNodeDataFromConfiguration(HierarchicalConfiguration<T> config)
Creates aNodeData
object from the root node of the given configuration.- Type Parameters:
T
- the type of the nodes- Parameters:
config
- the configuration- Returns:
- the
NodeData
object
-
isBeanDeclarationArgument
private static boolean isBeanDeclarationArgument(XMLBeanDeclaration.NodeData<?> nodeData)
Tests whether the constructor argument represented by the given configuration node is a bean declaration.- Parameters:
nodeData
- the configuration node in question- Returns:
- a flag whether this constructor argument is a bean declaration
-
createBeanDeclaration
BeanDeclaration createBeanDeclaration(XMLBeanDeclaration.NodeData<?> nodeData)
Creates a newBeanDeclaration
for a child node of the current configuration node. This method is called bygetNestedBeanDeclarations()
for all complex sub properties detected by this method. Derived classes can hook in if they need a specific initialization. This base implementation creates aXMLBeanDeclaration
that is properly initialized from the passed in node.- Parameters:
nodeData
- the child node, for which aBeanDeclaration
is to be created- Returns:
- the
BeanDeclaration
for this child node
-
createConstructorArg
private ConstructorArg createConstructorArg(XMLBeanDeclaration.NodeData<?> child)
Creates aConstructorArg
object for the specified configuration node.- Parameters:
child
- the configuration node- Returns:
- the corresponding
ConstructorArg
object
-
getAttribute
private java.lang.String getAttribute(XMLBeanDeclaration.NodeData<?> nodeData, java.lang.String attribute)
Gets an attribute of a configuration node. This method also takes interpolation into account.- Parameters:
nodeData
- the nodeattribute
- the name of the attribute- Returns:
- the string value of this attribute (can be null)
-
getAttributeNames
protected java.util.Set<java.lang.String> getAttributeNames()
Gets 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
-
getBeanClassName
public java.lang.String getBeanClassName()
Gets the name of the class of the bean to be created. This information is obtained from theconfig-class
attribute.- Specified by:
getBeanClassName
in interfaceBeanDeclaration
- Returns:
- the name of the bean's class
-
getBeanFactoryName
public java.lang.String getBeanFactoryName()
Gets the name of the bean factory. This information is fetched from theconfig-factory
attribute.- Specified by:
getBeanFactoryName
in interfaceBeanDeclaration
- Returns:
- the name of the bean factory
-
getBeanFactoryParameter
public java.lang.Object getBeanFactoryParameter()
Gets a parameter for the bean factory. This information is fetched from theconfig-factoryParam
attribute.- Specified by:
getBeanFactoryParameter
in interfaceBeanDeclaration
- Returns:
- the parameter for the bean factory
-
getBeanProperties
public java.util.Map<java.lang.String,java.lang.Object> getBeanProperties()
Gets a map with the bean's (simple) properties. The properties are collected from all attribute nodes, which are not reserved.- Specified by:
getBeanProperties
in interfaceBeanDeclaration
- Returns:
- a map with the bean's properties
-
getConfiguration
public HierarchicalConfiguration<?> getConfiguration()
Gets the configuration object this bean declaration is based on.- Returns:
- the associated configuration
-
getConstructorArgs
public java.util.Collection<ConstructorArg> getConstructorArgs()
Gets 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 nameconfig-constrarg
. If such a node has aconfig-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 interfaceBeanDeclaration
- Returns:
- a collection with the arguments to be passed to the bean class's constructor
-
getDefaultBeanClassName
public java.lang.String getDefaultBeanClassName()
Gets 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
-
getNestedBeanDeclarations
public java.util.Map<java.lang.String,java.lang.Object> getNestedBeanDeclarations()
Gets 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 interfaceBeanDeclaration
- Returns:
- a map with bean declarations for complex properties
-
getNode
XMLBeanDeclaration.NodeData<?> getNode()
Gets the data about the associated node.- Returns:
- the node with the bean declaration
-
initSubnodeConfiguration
private void initSubnodeConfiguration(HierarchicalConfiguration<?> conf)
Initializes the internally managed sub configuration. This method will set some default values for some properties.- Parameters:
conf
- the configuration to initialize
-
interpolate
protected java.lang.Object interpolate(java.lang.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
-
isReservedAttributeName
protected boolean isReservedAttributeName(java.lang.String name)
Tests 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 toisReservedName(String)
.- Parameters:
name
- the name of the attribute to be checked- Returns:
- a flag whether this name is reserved
- Since:
- 2.0
-
isReservedChildName
protected boolean isReservedChildName(java.lang.String name)
Tests 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 toisReservedName(String)
.- Parameters:
name
- the name of the child node to be checked- Returns:
- a flag whether this name is reserved
- Since:
- 2.0
-
isReservedName
protected boolean isReservedName(java.lang.String name)
Tests 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
-
-