Declaring and Creating BeansOften 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. Basic ConceptsBeans (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:
An ExampleAfter 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:
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. Extending the Basic MechanismAs 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:
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:
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:
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. |