Java tutorial
/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.configuration.beanutils; import java.util.HashMap; import java.util.Iterator; import java.util.Map; import org.apache.commons.configuration.HierarchicalConfiguration; import org.apache.commons.configuration.PropertyConverter; import org.apache.commons.configuration.SubnodeConfiguration; import org.apache.commons.configuration.tree.ConfigurationNode; import org.apache.commons.configuration.tree.DefaultConfigurationNode; /** * <p> * An implementation of the <code>BeanDeclaration</code> interface that is * suitable for XML configuration files. * </p> * <p> * 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: * </p> * <p> * * <pre> * ... * <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> * </pre> * * </p> * <p> * The bean declaration can be contained in an arbitrary element. Here it is the * <code><personBean></code> element. In the attributes of this element * there can occur some reserved attributes, which have the following meaning: * <dl> * <dt><code>config-class</code></dt> * <dd>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 * <code>defaultClass</code> passed to the <code>BeanHelper</code> class.</dd> * <dt><code>config-factory</code></dt> * <dd>This attribute can contain the name of the * <code>{@link BeanFactory}</code> that should be used for creating the bean. * If it is defined, a factory with this name must have been registered at the * <code>BeanHelper</code> class. If this attribute is missing, the default * bean factory will be used.</dd> * <dt><code>config-factoryParam</code></dt> * <dd>With this attribute a parameter can be specified that will be passed to * the bean factory. This may be useful for custom bean factories.</dd> * </dl> * </p> * <p> * All further attributes starting with the <code>config-</code> 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. * </p> * <p> * 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. * </p> * <p> * A <code>XMLBeanDeclaration</code> object is usually created from a * <code>HierarchicalConfiguration</code>. From this it will derive a * <code>SubnodeConfiguration</code>, which is used to access the needed * properties. This subnode configuration can be obtained using the * <code>{@link #getConfiguration()}</code> 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. * </p> * * @since 1.3 * @author Oliver Heger * @version $Id: XMLBeanDeclaration.java 670739 2008-06-23 20:36:37Z oheger $ */ public class XMLBeanDeclaration implements BeanDeclaration { /** Constant for the prefix of reserved attributes. */ public static final String RESERVED_PREFIX = "config-"; /** Constant for the prefix for reserved attributes.*/ public static final String ATTR_PREFIX = "[@" + RESERVED_PREFIX; /** Constant for the bean class attribute. */ public static final String ATTR_BEAN_CLASS = ATTR_PREFIX + "class]"; /** Constant for the bean factory attribute. */ public static final String ATTR_BEAN_FACTORY = ATTR_PREFIX + "factory]"; /** Constant for the bean factory parameter attribute. */ public static final String ATTR_FACTORY_PARAM = ATTR_PREFIX + "factoryParam]"; /** Stores the associated configuration. */ private SubnodeConfiguration configuration; /** Stores the configuration node that contains the bean declaration. */ private ConfigurationNode node; /** * Creates a new instance of <code>XMLBeanDeclaration</code> and * initializes it from the given configuration. The passed in key points to * the bean declaration. * * @param config the configuration * @param key the key to the bean declaration (this key must point to * exactly one bean declaration or a <code>IllegalArgumentException</code> * exception will be thrown) */ public XMLBeanDeclaration(HierarchicalConfiguration config, String key) { this(config, key, false); } /** * Creates a new instance of <code>XMLBeanDeclaration</code> 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 <b>true</b>, 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 <b>false</b>, * a <code>IllegalArgumentException</code> exception will be thrown. * * @param config the configuration * @param key the key to the bean declaration * @param optional a flag whether this declaration is optional; if set to * <b>true</b>, no exception will be thrown if the passed in key is * undefined */ public XMLBeanDeclaration(HierarchicalConfiguration config, String key, boolean optional) { if (config == null) { throw new IllegalArgumentException("Configuration must not be null!"); } try { configuration = config.configurationAt(key); node = configuration.getRootNode(); } catch (IllegalArgumentException iex) { // If we reach this block, the key does not have exactly one value if (!optional || config.getMaxIndex(key) > 0) { throw iex; } configuration = config.configurationAt(null); node = new DefaultConfigurationNode(); } initSubnodeConfiguration(getConfiguration()); } /** * Creates a new instance of <code>XMLBeanDeclaration</code> and * initializes it from the given configuration. The configuration's root * node must contain the bean declaration. * * @param config the configuration with the bean declaration */ public XMLBeanDeclaration(HierarchicalConfiguration config) { this(config, (String) null); } /** * Creates a new instance of <code>XMLBeanDeclaration</code> and * initializes it with the configuration node that contains the bean * declaration. * * @param config the configuration * @param node the node with the bean declaration. */ public XMLBeanDeclaration(SubnodeConfiguration config, ConfigurationNode node) { if (config == null) { throw new IllegalArgumentException("Configuration must not be null!"); } if (node == null) { throw new IllegalArgumentException("Node must not be null!"); } this.node = node; configuration = config; initSubnodeConfiguration(config); } /** * Returns the configuration object this bean declaration is based on. * * @return the associated configuration */ public SubnodeConfiguration getConfiguration() { return configuration; } /** * Returns the node that contains the bean declaration. * * @return the configuration node this bean declaration is based on */ public ConfigurationNode getNode() { return node; } /** * Returns the name of the bean factory. This information is fetched from * the <code>config-factory</code> attribute. * * @return the name of the bean factory */ public String getBeanFactoryName() { return getConfiguration().getString(ATTR_BEAN_FACTORY); } /** * Returns a parameter for the bean factory. This information is fetched * from the <code>config-factoryParam</code> attribute. * * @return the parameter for the bean factory */ public Object getBeanFactoryParameter() { return getConfiguration().getProperty(ATTR_FACTORY_PARAM); } /** * Returns the name of the class of the bean to be created. This information * is obtained from the <code>config-class</code> attribute. * * @return the name of the bean's class */ public String getBeanClassName() { return getConfiguration().getString(ATTR_BEAN_CLASS); } /** * Returns a map with the bean's (simple) properties. The properties are * collected from all attribute nodes, which are not reserved. * * @return a map with the bean's properties */ public Map getBeanProperties() { Map props = new HashMap(); for (Iterator it = getNode().getAttributes().iterator(); it.hasNext();) { ConfigurationNode attr = (ConfigurationNode) it.next(); if (!isReservedNode(attr)) { props.put(attr.getName(), interpolate(attr.getValue())); } } return props; } /** * 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. * * @return a map with bean declarations for complex properties */ public Map getNestedBeanDeclarations() { Map nested = new HashMap(); for (Iterator it = getNode().getChildren().iterator(); it.hasNext();) { ConfigurationNode child = (ConfigurationNode) it.next(); if (!isReservedNode(child)) { nested.put(child.getName(), createBeanDeclaration(child)); } } return nested; } /** * 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. * * @param value the value that is to be interpolated * @return the interpolated value */ protected Object interpolate(Object value) { return PropertyConverter.interpolate(value, getConfiguration().getParent()); } /** * 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. * * @param nd the node to be checked * @return a flag whether this node is reserved (and does not point to a * property) */ protected boolean isReservedNode(ConfigurationNode nd) { return nd.isAttribute() && (nd.getName() == null || nd.getName().startsWith(RESERVED_PREFIX)); } /** * Creates a new <code>BeanDeclaration</code> for a child node of the * current configuration node. This method is called by * <code>getNestedBeanDeclarations()</code> for all complex sub properties * detected by this method. Derived classes can hook in if they need a * specific initialization. This base implementation creates a * <code>XMLBeanDeclaration</code> that is properly initialized from the * passed in node. * * @param node the child node, for which a <code>BeanDeclaration</code> is * to be created * @return the <code>BeanDeclaration</code> for this child node * @since 1.6 */ protected BeanDeclaration createBeanDeclaration(ConfigurationNode node) { return new XMLBeanDeclaration(getConfiguration().configurationAt(node.getName()), node); } /** * Initializes the internally managed subnode configuration. This method * will set some default values for some properties. * * @param conf the configuration to initialize */ private void initSubnodeConfiguration(SubnodeConfiguration conf) { conf.setThrowExceptionOnMissing(false); conf.setExpressionEngine(null); } }