Package org.apache.commons.configuration2.beanutils

## Class BeanHelper

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

-     public final class BeanHelper
      extends 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

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `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​(Object dest, Object orig)` | Copies matching properties from the source bean to the destination bean using a specially configured `PropertyUtilsBean` instance.
    `Object` | `createBean​(BeanDeclaration data)` | Creates a bean instance for the specified declaration.
    `Object` | `createBean​(BeanDeclaration data, Class<?> defaultClass)` | Creates a bean instance for the specified declaration.
    `Object` | `createBean​(BeanDeclaration data, Class<?> defaultClass, Object param)` | The main method for creating and initializing beans from a configuration.
    `static org.apache.commons.beanutils.DynaBean` | `createWrapDynaBean​(Object bean)` | Creates a `DynaBean` instance which wraps the passed in bean.
    `BeanFactory` | `deregisterBeanFactory​(String name)` | Deregisters the bean factory with the given name.
    `BeanFactory` | `getDefaultBeanFactory()` | Gets the default bean factory.
    `void` | `initBean​(Object bean, BeanDeclaration data)` | Initializes the passed in bean.
    `static void` | `initBeanProperties​(Object bean, BeanDeclaration data)` | Initializes the beans properties.
    `void` | `registerBeanFactory​(String name, BeanFactory factory)` | Registers a bean factory under a symbolic name.
    `Set<String>` | `registeredFactoryNames()` | Gets a set with the names of all currently registered bean factories.
    `static void` | `setProperty​(Object bean, String propName, 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.

  - ### 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

    - #### registerBeanFactory

          public void registerBeanFactory​(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

    - #### deregisterBeanFactory

          public BeanFactory deregisterBeanFactory​(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

    - #### registeredFactoryNames

          public Set<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

    - #### getDefaultBeanFactory

          public BeanFactory getDefaultBeanFactory()

      Gets the default bean factory.
      Returns:
        the default bean factory

    - #### initBean

          public void initBean​(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

    - #### initBeanProperties

          public static void initBeanProperties​(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

    - #### createWrapDynaBean

          public static org.apache.commons.beanutils.DynaBean createWrapDynaBean​(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:
        `IllegalArgumentException` - if the bean is null
      Since:
        2.0

    - #### copyProperties

          public static void copyProperties​(Object dest,
                                            Object orig)
                                     throws IllegalAccessException,
                                            InvocationTargetException,
                                            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:
        `NoSuchMethodException` - exception thrown by `PropertyUtilsBean`
        `InvocationTargetException` - exception thrown by `PropertyUtilsBean`
        `IllegalAccessException` - exception thrown by `PropertyUtilsBean`
      Since:
        2.0

    - #### setProperty

          public static void setProperty​(Object bean,
                                         String propName,
                                         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 Object createBean​(BeanDeclaration data,
                                   Class<?> defaultClass,
                                   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

    - #### createBean

          public Object createBean​(BeanDeclaration data,
                                   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 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