BeanPot

Introduction

BeanPot is a tiny-footprint bean container which provides dependency injection and, optionally, JMX registration for beans.

Features

• Beans are held as singletons in the container (if you want more than one copy of a bean, it must be explicitly specified with the appropriate number of different keys);
• Beans are easily configured via an XML file;
• Beans enjoy dependency injection;
• Beans are placed into an MBean container (for JMX) provided that:
  1. the bean is a valid MBean (see the description of JMX for details on this);
  2. an implementer of MBeanPot has been registered using the MBeanPot tag. Example: <MBeanPot prefix="mBeanPotTest"> </MBeanPot>

Usage - introduction

There are five steps in the usage of the BeanPot:

1. Get Instance: get the (singleton) instance of the bean pot (you can skip this if you use the class method setConfiguration in the following step);
2. Set Configuration: specify how the bean pot is to be configured;
3. Init: initialize the bean pot (this step can be skipped because the configure() step will invoke it if necessary;
4. Configure: configure the bean pot (this step can be skipped because the run() step will invoke it if necessary;
5. Run: run the bean pot (this step is optional);

The XML configuration file is very much along the lines of those of the Spring Framework. In some places, the exact syntax may be slightly different.

Usage - code samples

The best and, by definition valid, source for code samples are the unit tests which you can find in the distribution under src/test/java (under the appropriate package). The corresponding XML files can be found in src/test/resources (under the appropriate package).

Here, for example, is the main program of BeanPot. Note that this is purely for testing, an application of BeanPot running on its own wouldn't be very interesting.

	public final static void main(final String[] args) {
		String beansFilename = "beans.xml";
		if (args.length > 0)
			beansFilename = args[0];
		final URL url = BeanPot.class.getResource(beansFilename);
		if (url != null) {
			try {
				BeanPot.setConfiguration(url).run();
				// count should be 1
				BeanPot.getWriter().println("BeanPot running with " + BeanPot.count() + " beans.");
				String integerBeanKey = "integer";
				Integer bean = (Integer) BeanPot.getBean(integerBeanKey);
				if (bean != null) {
					// integer value should be 99
					BeanPot.getWriter().println(integerBeanKey + " value: " + bean.intValue());
				} else
					System.err.println("cannot find bean " + integerBeanKey);
			} catch (final Exception e) {
				e.printStackTrace();
			}
		} else
			System.err.println("resource not found: " + beansFilename);
	}

and here is the beans.xml file that configures it:

	<?xml version="1.0" encoding="ISO-8859-1" ?>
	<configuration>
		<!-- the definition of writer may be left out if using ConsoleWriter -->
		<writer class="com.rubecula.beanpot.ConsoleWriter">
		</writer>
		<beans>
			<bean id="integer" class="Integer">
				<constructor-arg class="String">
					<value>99</value>
				</constructor-arg>
			</bean>
		</beans>
	</configuration>

Usage - general remarks

Singleton and non-singleton beans

A bean which is an instance of a singleton class should be defined with the annotation singleton="true" as part of the bean tag. The default for the singleton attribute is false. In the case of a singleton, there must be a public class method named getInstance() which takes no parameters and returns the singleton instance for the class. When the singleton attribute is false, a constructor will be called (see below for information on constructor arguments).

Constructor Arguments

Constructor arguments which are primitives are automatically converted from the corresponding object type. But if the argument is, for example, a long, it is still necessary to specify the class in the constructor-arg tag as "Long". Constructors which take a (single) array argument can also be invoked, provided that the elements are added as a list, and that the class and valueClass are specified. See testBeans13.xml for an example.

Lists, Maps, etc.

Properties which are lists or maps can be configured in the same way you would for Spring (see unit tests for examples). A property which is in fact an array will be automatically converted from a list (thus, pretending that the property is a list is the only way to set the array properly). This only works if the array is of some Object type (and provided that the object type has a valueOf method), or if it is an array of ints or doubles.

Possible New Features

Possibly coordinate the identifier of the bean (its name) and the key. Normally, we don't really need to specify both independently (some beans won't have an identifier in any case);
possibly allow for JMX notifications on MBeans.