Basic Concepts

Beans (we use the term bean here to name any plain old Java object that is defined in a configuration file and can be instantiated by Commons Configuration) are defined in configuration files in a specific format, a so-called Bean declaration. Such a declaration contains all information needed to create an instance of this bean class, e.g. the fully-qualified name of the class and initialization parameters. We will explain how a bean declaration looks like in short.

On the Java side three entities are involved in the creation of a bean:

• A bean factory: This is an object that implements the BeanFactory interface and knows how to create an instance of a bean class. In most cases calling code does not directly deal with a bean factory.
• An implementation of the BeanDeclaration interface. This object knows how the bean declaration in the configuration file is organized and how the needed information can be extracted. So the way the bean is declared in the configuration file must match the expectations of this object.
• The helper class BeanHelper brings all these together and performs the bean creation operation. Usually client code will create a BeanDeclaration object from a Configuration implementation and then pass it to one of the createBean() methods of BeanHelper. That's it!

An Example

After this theory let's get into practice using an example. Consider a GUI application that makes use of a Window manager to display its windows and dialogs to the user. There is a WindowManager interface containing methods for opening, displaying, hiding, and disposing windows. Different implementations of this interface exist, e.g. providing different look & feel or special functionality. The concrete set of methods of the interface does not matter for this example.

Now in the application's configuration it shall be specified that the concrete implementation DefaultWindowManager should be used as WindowManager. This is a plain Java class implementing the WindowManager interface. Some fragments are shown in the following listing:

package examples.windows;

public class DefaultWindowManager implements WindowManager
{
    // are windows allowed to be resized?
    private boolean resizable;
    // do windows have a close button?
    private boolean closable;

    // Default size of new windows
    private int defaultWidth;
    private int defaultHeight;

    WindowStyleDefinition styleDefinition;

    // getters and setters ommitted, also the WindowManager methods
}

As you can see, the DefaultWindowManager class has some simple properties for defining the windows. There is also a property named StyleDefinition whose type is another bean (such a style definition may contain information about themes, colors, fonts of the window and so on). How can we now write a configuration file so that a bean of the DefaultWindowManager class is declared and initialization properties are defined? In an XML configuration file this will look as follows:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<config>
  <gui>
    <windowManager config-class="examples.windows.DefaultWindowManager"
      closable="false" resizable="true" defaultWidth="400"
      defaultHeight="250">
      <styleDefinition config-class="examples.windows.WindowStyleDefinition"
        backColor="#ffffff" foreColor="0080ff" iconName="myicon" />
    </windowManager>
  </gui>
</config>

This XML document contains a valid bean declaration starting with the windowManager element and including its sub elements. Note the following points:

• The (fully-qualified) class of the bean is specified using the config-class attribute. (Attributes starting with the prefix "config-" are reserved; they contain special meta data for the bean creation process.)
• Other attributes of the windowManager element correspond to properties of the DefaultWindowManager class. These properties will be initialized with the values specified here.
• For the styleDefinition property, which is itself a bean, a sub element (matching the property's name) exists. The structure of this element is analogous to the structure of the windowManager element; indeed it could even have further sub elements defining bean properties of the WindowStyleDefinition class.

Now let's see how we can access this declaration and create an instance. This is demonstrated in the code fragment below:

Parameters params = new Parameters();
FileBasedConfigurationBuilder<XMLConfiguration> builder =
    new FileBasedConfigurationBuilder<XMLConfiguration>(XMLConfiguration.class)
    .configure(params.xml()
        .setFileName("windowconfig.xml"));
XMLConfiguration config = builder.getConfiguration();
BeanDeclaration decl = new XMLBeanDeclaration(config, "gui.windowManager");
WindowManager wm = (WindowManager) BeanHelper.INSTANCE.createBean(decl);

This fragment loads the configuration file using a XMLConfiguration object. Then a bean declaration object is created, in this case an instance of the XMLBeanDeclaration class, which can deal with bean declarations in XML documents. This declaration is passed to the createBean() method of the default instance of the BeanHelper class, which returns the new bean instance.

A BeanHelper object does the hard work behind the scenes to create a bean instance. It determines the class of the bean to be created and delegates to a BeanFactory to create an instance. Then all initialization properties defined in the bean declaration are evaluated and set on the newly created bean. The BeanFactory to be used is determined based on the bean helper's configuration:

• A BeanHelper can be configured with a number of BeanFactory objects that are registered under a specific key. The BeanDeclaration can contain the key of the BeanFactory to be used. Please refer to the Javadocs of XMLBeanDeclaration for further information.
• When a BeanHelper object is constructed a default BeanFactory is set. This one is used if no specific factory is referenced by the bean declaration.

BeanHelper defines some overloaded versions of the createBean() method. Some allow passing in a default bean class; then it is not necessary to define the class in the bean declaration - an instance of this default class will be created if it is missing in the configuration file. If the bean cannot be created for some reason (e.g. a wrong class name was specified), a ConfigurationRuntimeException will be thrown.

Constructor arguments

In the examples so far we assumed that beans are created using their standard constructor. This is appropriate for classes conforming to the Java Beans specification which requires bean classes to have such a no-argument constructor. Commons Configuration also supports invoking an arbitrary constructor passing in the corresponding constructor arguments. Let's extend the example from the previous section and assume that the WindowStyleDefinition class is now an immutable class which has to be initialized by passing parameters to its constructor. The constructor may look as follows:

public class WindowStyleDefinition
{
    ...
    public WindowStyleDefinition(String foreground, String background,
        Font stdFont)
    {
        ...
    }
    ...
}

In order to create an instance of WindowStyleDefinition, we have to pass the foreground and background colors and a standard font to the constructor. The colors are simple strings while a font is again a complex object. The following code fragment shows the complete bean declaration for this scenario:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<config>
  <gui>
    <windowManager config-class="examples.windows.DefaultWindowManager"
      closable="false" resizable="true" defaultWidth="400"
      defaultHeight="250">
      <styleDefinition config-class="examples.windows.WindowStyleDefinition">
        <config-constrarg config-value="#0080ff"/>
        <config-constrarg config-value="#ffffff"/>
        <config-constrarg config-class="java.awt.Font">
          <config-constrarg config-value="Monospaced"/>
          <config-constrarg config-value="0"/>
          <config-constrarg config-value="12"/>
        </config-constrarg>
      </styleDefinition>
    </windowManager>
  </gui>
</config>

The styleDefinition property is still defined as a nested bean declaration in the body of the <windowManager> element. But this time there are nested <config-constrarg> elements. Each element defines one constructor argument. In this example there are three constructor arguments for the foreground color, the background color, and the standard font. The first two arguments are simple values (i.e. primitive Java data types) and are defined using the config-value attribute. The third argument, the font, is actually another nested bean declaration. This is indicated by the presence of the config-class attribute which defines the class of this constructor argument. To create a Font instance, we again have to define constructor arguments: the font name, its style, and its size. Note that corresponding type conversions are performed automatically; while all values in the XML configuration file are strings, they are converted to the correct parameter type when calling the constructor.

Commons Configuration uses a pretty simple algorithm to determine the constructor to be invoked: it is mainly based on the number of constructor arguments. This works as expected as long as there are not multiple constructors with the same number of arguments. If this is the case, the developer has to provide some hints indicating which constructor to select. Consider a bean class with the following constructors:

public class MyBean
{
    ...
    public MyBean(String svalue)
    {
        ...
    }

    public MyBean(int ivalue)
    {
        ...
    }
    ...
}

This bean class has two constructors expecting a single argument. A bean declaration like the following one will not work because it is not clear which constructor to choose:

<config>
  <!-- This will not work as the constructor is ambiguous! -->
  <bean config-class="examples.MyBean">
    <config-constrarg config-value="100"/>
  </bean>
</config>

The solution is to explicitly specify the data type (the fully-qualified Java class) of the constructor argument. This can be done by adding the config-type attribute as in the following fragment:

<config>
  <bean config-class="examples.MyBean">
    <config-constrarg config-value="100" config-type="int"/>
  </bean>
</config>

Now it is clear that the constructor expecting an int argument is desired. The config-type attribute can be used for both simple constructor arguments and nested bean declarations. It does not have to be specified for all arguments; it is sufficient to define a minimum number of data types so that there is no ambiguity any more. The type specified for the attribute must be the exact same type as expected by the constructor. This is not necessarily the same type as the value passed to this argument. (For instance, the constructor expects an object implementing a specific interface, while the actual argument value is an instance of a concrete implementation class.) Also, the config-type attribute is only evaluated to determine a matching constructor; it is not related to data type conversion.

Extending the Basic Mechanism

As was pointed out in the introduction of this chapter, support for creating beans is focused on the basics. But there are some possibilities of hooking in and add custom extensions. This can be done in the following ways:

• By defining a custom BeanDeclaration implementation
• By providing a custom BeanFactory implementation

A specialized bean declaration is needed when you have to deal with configuration files that contain bean declarations in a different format than the ones supported by the available default implementations. Then it is the responsibility of your implementation to parse the configuration data and extract the required information to create the bean. Basically your BeanDeclaration implementation must be able to provide the following data:

• The name of the class for which an instance is to be created.
• The name of the bean factory that is used to create the bean. Here null can be returned, then a default factory is used. (See below for more information about working with custom bean factories.)
• An optional parameter to be passed to the bean factory. If a factory is used that supports additional parameters, the current parameter values are also obtained from the bean declaration.
• A map with the properties to be set on the newly created bean. This map's keys are names of properties, its values are the corresponding property values. The default bean factory will process this map and call the corresponding setter methods on the newly created bean object.
• A map with further BeanDeclaration objects for initializing properties of the new bean that are itself beans. These bean declarations are treated exactly as the one that is currently processed. The resulting beans will then be set as properties on the processed bean (the names of these properties are again obtained from the keys of the map).

While creating a custom BeanDeclaration implementation allows you to adapt the format of bean declarations in configuration files, you can manipulate the bean creation mechanism itself by creating a specialized implementation of the BeanFactory interface. For this purpose the following steps are necessary:

1. Create a class implementing the BeanFactory interface. This interface is quite simple. It defines one method for creating an instance of a class whose Class object is provided, and another method, which is called for querying a default class.
2. Register this new factory class at the BeanHelper instanced used for bean creation.
3. In the bean declaration in your configuration file refer to the factory that should be used for creating the bean (unless this factory is used as the BeanHelper's default bean factory).

We will provide an example that covers all these steps. This example deals with a singleton factory, i.e. an implementation of BeanFactory that returns always the same instance of a provided bean class.

We start with the creation of the factory class. The basic idea is that the functionality for creating and initializing beans is already provided by the DefaultBeanFactory class, so we extend this class. Our implementation only has to deal with the singleton stuff: We keep a map that stores already created bean instances and can be accessed by the name of their classes. In the factory's createBean() method we check if for the passed in class already an instance exists. If this is the case, it is directly returned. Otherwise we call the inherited createBean() method and store its result in the map. (Note that this implementation is a bit simplistic. A real world implementation would also have to take initialization parameters into account and use a more sophisticated approach to deal with concurrency issues. But for the purpose of an example it should be good enough). Here is the code:

public class SingletonBeanFactory extends DefaultBeanFactory
{
    /** A map for the so far created instances.*/
    private final Map<String, Object> beans;

    public SingletonBeanFactory()
    {
        super();
        beans = new HashMap<String, Object>();
    }

    // Creates the bean. Checks if already an instance exists.
    public synchronized Object createBean(BeanCreationContext bcc) throws Exception
    {
        Object bean = beans.get(bcc.getBeanClass().getName());
        if (bean != null)
        {
            // Yes, there is already an instance
            return bean;
        }
        else
        {
            // No, create it now (done by the super class)
            bean = super.createBean(bcc);
            // Store it in map
            beans.put(beanClass.getName(), bean);
            return bean;
        }
    }
}

The main method to define is createBean(). It is passed a BeanCreationContext object which contains all information required for creating a bean (e.g. via reflection). Note the synchronized key word, which is necessary because the method can be accessed by multiple threads concurrently.

Now we have to register an instance of this class at a BeanHelper instance. There are multiple ways how this can be done. For applications making use of the default BeanHelper instance, the factory can be added using the registerBeanFactory() method. This can happen in the initialization phase of your application and looks as follows:

BeanHelper.INSTANCE.registerBeanFactory("SINGLETON", new SingletonBeanFactory());

To make use of the new factory a bean declaration must contain an attribute that refers to the name under which the factory was registered. This is demonstrated by the fragment below:

<config>
...
    <services>
      <fileService config-class="my.package.services.FileServiceImpl"
        config-factory="SINGLETON"
        property1="value1" property2="value2">
        <!-- Here can be nested bean declarations -->
      </fileService>
      ...
</config>

In this fragment the fileService element contains a bean declaration for some service object. Apart from the config-class attribute the important part is the config-factory attribute. This attribute tells the BeanHelper class that it should use a special factory when it processes this bean declaration.

Alternatively, a separate BeanHelper instance can be created passing in the new factory object as its default bean factory. In the bean declarations, it is then no longer necessary to refer to a specific bean factory. Below is an example showing this approach:

BeanHelper singletonBeanHelper = new BeanHelper(new SingletonBeanFactory());
BeanDeclaration decl = ... // somehow obtain the bean declaration
Object mySingletonBean = singletonBeanHelper.createBean(decl);

Of course, this new BeanHelper instance must now be used everywhere where singleton beans are required. So it has to be made available globally. Because a BeanHelper object is thread-safe this can be done safely. As was demonstrated by this example, it should not be too difficult to extend the custom mechanism for creating beans.