Author: oheger Date: Wed Feb 15 12:12:34 2006 New Revision: 378081 URL: http://svn.apache.org/viewcvs?rev=378081&view=rev Log: New interfaces for declaring beans in configuration files
Added: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/beanutils/BeanDeclaration.java (with props) jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/beanutils/BeanFactory.java (with props) Added: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/beanutils/BeanDeclaration.java URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/beanutils/BeanDeclaration.java?rev=378081&view=auto ============================================================================== --- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/beanutils/BeanDeclaration.java (added) +++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/beanutils/BeanDeclaration.java Wed Feb 15 12:12:34 2006 @@ -0,0 +1,99 @@ +/* + * Copyright 2006 The Apache Software Foundation. + * + * Licensed 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.Map; + +/** + * <p> + * Definition of an interface for declaring a bean in a configuration file. + * </p> + * <p> + * Commons Configurations allows to define beans (i.e. simple Java objects) in + * configuration files, which can be created at runtime. This is especially + * useful if you program against interfaces and want to define the concrete + * implementation class is a configuration file. + * </p> + * <p> + * This interface defines methods for retrieving all information about a bean + * that should be created from a configuration file, e.g. the bean's properties + * or the factory to use for creating the instance. With different + * implementations different "layouts" of bean declarations can be + * supported. For instance if an XML configuration file is used, all features of + * XML (e.g. attributes, nested elements) can be used to define the bean. In a + * properties file the declaration format is more limited. The purpose of this + * interface is to abstract from the concrete declaration format. + * </p> + * + * @since 1.3 + * @author Oliver Heger + * @version $Id$ + */ +public interface BeanDeclaration +{ + /** + * Returns the name of the <code>BeanFactory</code> that should be used + * for creating the bean instance. This can be <b>null</b>, then a default + * factory will be used. + * + * @return the name of the bean factory + */ + String getBeanFactoryName(); + + /** + * Here an arbitrary object can be returned that will be passed to the bean + * factory. Its meaning is not further specified. The purpose of this + * additional parameter is to support a further configuration of the bean + * factory that can be placed directly at the bean declaration. + * + * @return a parameter for the bean factory + */ + Object getBeanFactoryParameter(); + + /** + * Returns the name of the bean class, from which an instance is to be + * created. This value must be defined unless a default class is provided + * for the bean creation operation. + * + * @return the name of the bean class + */ + String getBeanClassName(); + + /** + * Returns a map with properties that should be initialized on the newly + * created bean. The map's keys are the names of the properties; the + * corresponding values are the properties' values. The return value can be + * <b>null</b> if no properties should be set. + * + * @return a map with properties to be initialized + */ + Map getBeanProperties(); + + /** + * Returns a map with declarations for beans that should be set as + * properties of the newly created bean. This allows for complex + * initialization szenarios: a bean for a bean that contains complex + * properties (e.g. other beans) can have nested declarations for defining + * these complex properties. The returned map's key are the names of the + * properties to initialze. The values are <code>BeanDeclaration</code> + * implementations. They will be treated like this declaration (in a + * recursive manner), and the resulting beans are assigned to the + * corresponding properties. + * + * @return a map with nested bean declarations + */ + Map getNestedBeanDeclarations(); +} Propchange: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/beanutils/BeanDeclaration.java ------------------------------------------------------------------------------ svn:eol-style = native Propchange: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/beanutils/BeanDeclaration.java ------------------------------------------------------------------------------ svn:keywords = Date Author Id Revision HeadURL Propchange: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/beanutils/BeanDeclaration.java ------------------------------------------------------------------------------ svn:mime-type = text/plain Added: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/beanutils/BeanFactory.java URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/beanutils/BeanFactory.java?rev=378081&view=auto ============================================================================== --- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/beanutils/BeanFactory.java (added) +++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/beanutils/BeanFactory.java Wed Feb 15 12:12:34 2006 @@ -0,0 +1,72 @@ +/* + * Copyright 2006 The Apache Software Foundation. + * + * Licensed 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; + +/** + * <p> + * Definition of an interface for bean factories. + * </p> + * <p> + * Beans defined in configuration files are not directly created, but by so + * called <em>bean factories</em>. This additional level of indirection + * provides for high flexibility in the creation process. For instance one + * implementation of this interface could be very simple and create a new + * instance of the specified class for each invocation. A different + * implementation could cache already created beans and ensure that always the + * same bean of the given class will be returned - this would be an easy mean + * for creating singleton objects. + * </p> + * <p> + * The interface itself is quite simple. There is a single method for creating a + * bean of a given class. All necessary parameters are obtained from an also + * passed in <code>[EMAIL PROTECTED] BeanDeclaration}</code> object. It is also possible + * (but optional) for a bean factory to declare the default class of the bean it + * creates. Then it is not necessary to specify a bean class in the bean + * declaration. + * </p> + * + * @since 1.3 + * @author Oliver Heger + * @version $Id$ + */ +public interface BeanFactory +{ + /** + * Returns a bean instance for the given class. The bean will be initialized + * from the specified bean declaration object. It is up to a concrete + * implementation how the bean will be created and initialized. + * + * @param beanClass the class for the bean + * @param data the bean declaration object containing all data about the + * bean to be created + * @return the new bean instance (should not be <b>null</b>) + * @throws Exception if an error occurs (the helper classes for creating + * beans will catch this unspecific exception and wrap it in a configuration + * exception) + */ + Object createBean(Class beanClass, BeanDeclaration data) throws Exception; + + /** + * Returns the default bean class of this bean factory. If an implementation + * here returns a non <b>null</b> value, bean declarations using this + * factory do not need to provide the name of the bean class. In such a case + * an instance of the default class will be created. + * + * @return the default class of this factory or <b>null</b> if there is + * none + */ + Class getDefaultBeanClass(); +} Propchange: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/beanutils/BeanFactory.java ------------------------------------------------------------------------------ svn:eol-style = native Propchange: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/beanutils/BeanFactory.java ------------------------------------------------------------------------------ svn:keywords = Date Author Id Revision HeadURL Propchange: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/beanutils/BeanFactory.java ------------------------------------------------------------------------------ svn:mime-type = text/plain --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]