Often it is good practice to make heavy use of Java interfaces and program an application or components against these interfaces rather than concrete implementation classes. This makes it possible to switch to different implementations without having to modify calling code. However the problem remains how a concrete implementation of an interface is obtained. Simply using the new operator on a specific implementation class would somehow break the interface concept because then the code would have an explicit reference to a concrete implementation.
A solution to this problem is to define the concrete implementation class that should be used in a configuration file. Client code would obtain an object (or a bean) from the configuration and cast it to the service interface. This way the caller would have no knowledge about which concrete implementation is used; it would only interact with the service through the interface. By changing the configuration file and entering a different class name for the implementation class the behavior of the application can be altered, e.g. to inject a test stub for the used service.
Note: The concept of defining service objects in configuration files and let them be created by a special container has grown popular these days. Especially IoC containers like HiveMind or Spring offer wide functionality related to this topic. Commons Configuration is not and has no ambitions to become an IoC container. The provided functionality for declaring and creating beans is very basic and limited compared to the specialists. So if you are in need of enhanced features like the creation of complete networks of service objects, life cycle handling and such things, you should in any case use a real IoC container. For simple use cases however the functionality of Commons Configuration might be sufficient, and we have tried to provide hooks for extending the predefined mechanisms.
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 full 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:
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.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.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!
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:
config-class
attribute. (Attributes starting with the
prefix "config-" are reserved; they contain special meta
data for the bean creation process.)windowManager
element correspond
to properties of the DefaultWindowManager
class. These
properties will be initialized with the values specified here.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:
XMLConfiguration config = new XMLConfiguration("windowconfig.xml"); BeanDeclaration decl = new XMLBeanDeclaration(config, "gui.windowManager"); WindowManager wm = (WindowManager) BeanHelper.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 static createBean()
method of
the BeanHelper
class, which returns the new bean instance.
BeanHelper
defines some overloaded versions of the
createBean()
method. Some allow to pass 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 lacking 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.
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:
BeanDeclaration
implementationBeanFactory
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:
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:
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.BeanHelper
class.
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
simplicistic; a real world implementation would also have to take the
initialization parameters into account. 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 Map beans; public SingletonBeanFactory() { super(); beans = new HashMap(); } // Creates the bean. Checks if already an instance exists. public synchronized Object createBean(Class beanClass, BeanDeclaration decl, Object param) throws Exception { Object bean = beans.get(beanClass.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(beanClass, decl, param); // Store it in map beans.put(beanClass.getName(), bean); return bean; } } }
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 the BeanHelper
class.
This can be done in the initialization phase of your application and
looks as follows:
BeanHelper.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. As was
demonstrated by this example, it should not be too difficult to extend
the custom mechanism for creating beans.