Class BeanHelper


  • public final class BeanHelper
    extends java.lang.Object

    A helper class for creating bean instances that are defined in configuration files.

    This class provides utility methods related to bean creation operations. These methods simplify such operations because a client need not deal with all involved interfaces. Usually, if a bean declaration has already been obtained, a single method call is necessary to create a new bean instance.

    This class also supports the registration of custom bean factories. Implementations of the BeanFactory interface can be registered under a symbolic name using the registerBeanFactory() method. In the configuration file the name of the bean factory can be specified in the bean declaration. Then this factory will be used to create the bean.

    In order to create beans using BeanHelper, create and instance of this class and initialize it accordingly - a default BeanFactory can be passed to the constructor, and additional bean factories can be registered (see above). Then this instance can be used to create beans from BeanDeclaration objects. BeanHelper is thread-safe. So an instance can be passed around in an application and shared between multiple components.

    Since:
    1.3
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private static class  BeanHelper.BeanCreationContextImpl
      An implementation of the BeanCreationContext interface used by BeanHelper to communicate with a BeanFactory.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static org.apache.commons.beanutils.BeanUtilsBean BEAN_UTILS_BEAN
      A special instance of BeanUtilsBean which is used for all property set and copy operations.
      private java.util.Map<java.lang.String,​BeanFactory> beanFactories
      Stores a map with the registered bean factories.
      private BeanFactory defaultBeanFactory
      Stores the default bean factory, which is used if no other factory is provided in a bean declaration.
      static BeanHelper INSTANCE
      A default instance of BeanHelper which can be shared between arbitrary components.
    • Constructor Summary

      Constructors 
      Constructor Description
      BeanHelper()
      Constructs a new instance of BeanHelper with the default instance of DefaultBeanFactory as default BeanFactory.
      BeanHelper​(BeanFactory defaultBeanFactory)
      Constructs a new instance of BeanHelper and sets the specified default BeanFactory.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static void copyProperties​(java.lang.Object dest, java.lang.Object orig)
      Copies matching properties from the source bean to the destination bean using a specially configured PropertyUtilsBean instance.
      java.lang.Object createBean​(BeanDeclaration data)
      Creates a bean instance for the specified declaration.
      java.lang.Object createBean​(BeanDeclaration data, java.lang.Class<?> defaultClass)
      Creates a bean instance for the specified declaration.
      java.lang.Object createBean​(BeanDeclaration data, java.lang.Class<?> defaultClass, java.lang.Object param)
      The main method for creating and initializing beans from a configuration.
      private BeanCreationContext createBeanCreationContext​(BeanDeclaration data, java.lang.Class<?> defaultClass, java.lang.Object param, BeanFactory factory)
      Creates a BeanCreationContext object for the creation of the specified bean.
      private static java.util.Collection<java.lang.Object> createPropertyCollection​(java.lang.String propName, java.lang.Class<?> propertyClass)
      Creates a concrete collection instance to populate a property of type collection.
      static org.apache.commons.beanutils.DynaBean createWrapDynaBean​(java.lang.Object bean)
      Creates a DynaBean instance which wraps the passed in bean.
      BeanFactory deregisterBeanFactory​(java.lang.String name)
      Deregisters the bean factory with the given name.
      private static java.lang.Class<?> fetchBeanClass​(BeanDeclaration data, java.lang.Class<?> defaultClass, BeanFactory factory)
      Determines the class of the bean to be created.
      private BeanFactory fetchBeanFactory​(BeanDeclaration data)
      Obtains the bean factory to use for creating the specified bean.
      BeanFactory getDefaultBeanFactory()
      Gets the default bean factory.
      private static java.lang.Class<?> getDefaultClass​(java.lang.Object bean, java.lang.String propName)
      Gets the Class of the property if it can be determined.
      void initBean​(java.lang.Object bean, BeanDeclaration data)
      Initializes the passed in bean.
      static void initBeanProperties​(java.lang.Object bean, BeanDeclaration data)
      Initializes the beans properties.
      private static org.apache.commons.beanutils.BeanUtilsBean initBeanUtilsBean()
      Initializes the shared BeanUtilsBean instance.
      private static void initProperty​(java.lang.Object bean, java.lang.String propName, java.lang.Object value)
      Sets a property on the given bean using Common Beanutils.
      private static boolean isPropertyWriteable​(java.lang.Object bean, java.lang.String propName)
      Tests whether the specified property of the given bean instance supports write access.
      (package private) static java.lang.Class<?> loadClass​(java.lang.String name)
      Loads a Class object for the specified name.
      void registerBeanFactory​(java.lang.String name, BeanFactory factory)
      Registers a bean factory under a symbolic name.
      java.util.Set<java.lang.String> registeredFactoryNames()
      Gets a set with the names of all currently registered bean factories.
      static void setProperty​(java.lang.Object bean, java.lang.String propName, java.lang.Object value)
      Sets a property on the bean only if the property exists
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • INSTANCE

        public static final BeanHelper INSTANCE
        A default instance of BeanHelper which can be shared between arbitrary components. If no special configuration is needed, this instance can be used throughout an application. Otherwise, new instances can be created with their own configuration.
      • BEAN_UTILS_BEAN

        private static final org.apache.commons.beanutils.BeanUtilsBean BEAN_UTILS_BEAN
        A special instance of BeanUtilsBean which is used for all property set and copy operations. This instance was initialized with BeanIntrospector objects which support fluent interfaces. This is required for handling builder parameter objects correctly.
      • beanFactories

        private final java.util.Map<java.lang.String,​BeanFactory> beanFactories
        Stores a map with the registered bean factories.
      • defaultBeanFactory

        private final BeanFactory defaultBeanFactory
        Stores the default bean factory, which is used if no other factory is provided in a bean declaration.
    • Constructor Detail

      • BeanHelper

        public BeanHelper()
        Constructs a new instance of BeanHelper with the default instance of DefaultBeanFactory as default BeanFactory.
      • BeanHelper

        public BeanHelper​(BeanFactory defaultBeanFactory)
        Constructs a new instance of BeanHelper and sets the specified default BeanFactory.
        Parameters:
        defaultBeanFactory - the default BeanFactory (can be null, then a default instance is used)
    • Method Detail

      • copyProperties

        public static void copyProperties​(java.lang.Object dest,
                                          java.lang.Object orig)
                                   throws java.lang.IllegalAccessException,
                                          java.lang.reflect.InvocationTargetException,
                                          java.lang.NoSuchMethodException
        Copies matching properties from the source bean to the destination bean using a specially configured PropertyUtilsBean instance. This method ensures that enhanced introspection is enabled when doing the copy operation.
        Parameters:
        dest - the destination bean
        orig - the source bean
        Throws:
        java.lang.NoSuchMethodException - exception thrown by PropertyUtilsBean
        java.lang.reflect.InvocationTargetException - exception thrown by PropertyUtilsBean
        java.lang.IllegalAccessException - exception thrown by PropertyUtilsBean
        Since:
        2.0
      • createPropertyCollection

        private static java.util.Collection<java.lang.Object> createPropertyCollection​(java.lang.String propName,
                                                                                       java.lang.Class<?> propertyClass)
        Creates a concrete collection instance to populate a property of type collection. This method tries to guess an appropriate collection type. Mostly the type of the property will be one of the collection interfaces rather than a concrete class; so we have to create a concrete equivalent.
        Parameters:
        propName - the name of the collection property
        propertyClass - the type of the property
        Returns:
        the newly created collection
      • createWrapDynaBean

        public static org.apache.commons.beanutils.DynaBean createWrapDynaBean​(java.lang.Object bean)
        Creates a DynaBean instance which wraps the passed in bean.
        Parameters:
        bean - the bean to be wrapped (must not be null)
        Returns:
        a DynaBean wrapping the passed in bean
        Throws:
        java.lang.IllegalArgumentException - if the bean is null
        Since:
        2.0
      • fetchBeanClass

        private static java.lang.Class<?> fetchBeanClass​(BeanDeclaration data,
                                                         java.lang.Class<?> defaultClass,
                                                         BeanFactory factory)
        Determines the class of the bean to be created. If the bean declaration contains a class name, this class is used. Otherwise it is checked whether a default class is provided. If this is not the case, the factory's default class is used. If this class is undefined, too, an exception is thrown.
        Parameters:
        data - the bean declaration
        defaultClass - the default class
        factory - the bean factory to use
        Returns:
        the class of the bean to be created
        Throws:
        ConfigurationRuntimeException - if the class cannot be determined
      • getDefaultClass

        private static java.lang.Class<?> getDefaultClass​(java.lang.Object bean,
                                                          java.lang.String propName)
        Gets the Class of the property if it can be determined.
        Parameters:
        bean - The bean containing the property.
        propName - The name of the property.
        Returns:
        The class associated with the property or null.
      • initBeanProperties

        public static void initBeanProperties​(java.lang.Object bean,
                                              BeanDeclaration data)
        Initializes the beans properties.
        Parameters:
        bean - the bean to be initialized
        data - the bean declaration
        Throws:
        ConfigurationRuntimeException - if a property cannot be set
      • initBeanUtilsBean

        private static org.apache.commons.beanutils.BeanUtilsBean initBeanUtilsBean()
        Initializes the shared BeanUtilsBean instance. This method sets up custom bean introspection in a way that fluent parameter interfaces are supported.
        Returns:
        the BeanUtilsBean instance to be used for all property set operations
      • initProperty

        private static void initProperty​(java.lang.Object bean,
                                         java.lang.String propName,
                                         java.lang.Object value)
        Sets a property on the given bean using Common Beanutils.
        Parameters:
        bean - the bean
        propName - the name of the property
        value - the property's value
        Throws:
        ConfigurationRuntimeException - if the property is not writable or an error occurred
      • isPropertyWriteable

        private static boolean isPropertyWriteable​(java.lang.Object bean,
                                                   java.lang.String propName)
        Tests whether the specified property of the given bean instance supports write access.
        Parameters:
        bean - the bean instance
        propName - the name of the property in question
        Returns:
        true if this property can be written, false otherwise
      • loadClass

        static java.lang.Class<?> loadClass​(java.lang.String name)
                                     throws java.lang.ClassNotFoundException
        Loads a Class object for the specified name. Because class loading can be tricky in some environments the code for retrieving a class by its name was extracted into this helper method. So if changes are necessary, they can be made at a single place.
        Parameters:
        name - the name of the class to be loaded
        Returns:
        the class object for the specified name
        Throws:
        java.lang.ClassNotFoundException - if the class cannot be loaded
      • setProperty

        public static void setProperty​(java.lang.Object bean,
                                       java.lang.String propName,
                                       java.lang.Object value)
        Sets a property on the bean only if the property exists
        Parameters:
        bean - the bean
        propName - the name of the property
        value - the property's value
        Throws:
        ConfigurationRuntimeException - if the property is not writable or an error occurred
      • createBean

        public java.lang.Object createBean​(BeanDeclaration data)
        Creates a bean instance for the specified declaration. This method is a short cut for createBean(data, null);.
        Parameters:
        data - the bean declaration
        Returns:
        the new bean
        Throws:
        ConfigurationRuntimeException - if an error occurs
      • createBean

        public java.lang.Object createBean​(BeanDeclaration data,
                                           java.lang.Class<?> defaultClass)
        Creates a bean instance for the specified declaration. This method is a short cut for createBean(data, null, null);.
        Parameters:
        data - the bean declaration
        defaultClass - the class to be used when in the declaration no class is specified
        Returns:
        the new bean
        Throws:
        ConfigurationRuntimeException - if an error occurs
      • createBean

        public java.lang.Object createBean​(BeanDeclaration data,
                                           java.lang.Class<?> defaultClass,
                                           java.lang.Object param)
        The main method for creating and initializing beans from a configuration. This method will return an initialized instance of the bean class specified in the passed in bean declaration. If this declaration does not contain the class of the bean, the passed in default class will be used. From the bean declaration the factory to be used for creating the bean is queried. The declaration may here return null, then a default factory is used. This factory is then invoked to perform the create operation.
        Parameters:
        data - the bean declaration
        defaultClass - the default class to use
        param - an additional parameter that will be passed to the bean factory; some factories may support parameters and behave different depending on the value passed in here
        Returns:
        the new bean
        Throws:
        ConfigurationRuntimeException - if an error occurs
      • createBeanCreationContext

        private BeanCreationContext createBeanCreationContext​(BeanDeclaration data,
                                                              java.lang.Class<?> defaultClass,
                                                              java.lang.Object param,
                                                              BeanFactory factory)
        Creates a BeanCreationContext object for the creation of the specified bean.
        Parameters:
        data - the bean declaration
        defaultClass - the default class to use
        param - an additional parameter that will be passed to the bean factory; some factories may support parameters and behave different depending on the value passed in here
        factory - the current bean factory
        Returns:
        the BeanCreationContext
        Throws:
        ConfigurationRuntimeException - if the bean class cannot be determined
      • deregisterBeanFactory

        public BeanFactory deregisterBeanFactory​(java.lang.String name)
        Deregisters the bean factory with the given name. After that this factory cannot be used any longer.
        Parameters:
        name - the name of the factory to be deregistered
        Returns:
        the factory that was registered under this name; null if there was no such factory
      • fetchBeanFactory

        private BeanFactory fetchBeanFactory​(BeanDeclaration data)
        Obtains the bean factory to use for creating the specified bean. This method will check whether a factory is specified in the bean declaration. If this is not the case, the default bean factory will be used.
        Parameters:
        data - the bean declaration
        Returns:
        the bean factory to use
        Throws:
        ConfigurationRuntimeException - if the factory cannot be determined
      • getDefaultBeanFactory

        public BeanFactory getDefaultBeanFactory()
        Gets the default bean factory.
        Returns:
        the default bean factory
      • initBean

        public void initBean​(java.lang.Object bean,
                             BeanDeclaration data)
        Initializes the passed in bean. This method will obtain all the bean's properties that are defined in the passed in bean declaration. These properties will be set on the bean. If necessary, further beans will be created recursively.
        Parameters:
        bean - the bean to be initialized
        data - the bean declaration
        Throws:
        ConfigurationRuntimeException - if a property cannot be set
      • registerBeanFactory

        public void registerBeanFactory​(java.lang.String name,
                                        BeanFactory factory)
        Registers a bean factory under a symbolic name. This factory object can then be specified in bean declarations with the effect that this factory will be used to obtain an instance for the corresponding bean declaration.
        Parameters:
        name - the name of the factory
        factory - the factory to be registered
      • registeredFactoryNames

        public java.util.Set<java.lang.String> registeredFactoryNames()
        Gets a set with the names of all currently registered bean factories.
        Returns:
        a set with the names of the registered bean factories