Introduction

Geronimo Beans or GBeans are entities in the Geronimo Application Server that are available for use within the Geronimo system. GBeans allow loosely coupled interactions with other entities in the system and dependency injection between subsystems. GBeans are interoperable with JMX tools but are implemented separately from JMX MBeans. GBeans are able to be accessed via JMX technology through adapter classes in the geronimo-system module.

What is a GBean?

A GBean is a Java object that has a method called getGBeanInfo() that returns an instance of the GBeanInfo class. GBeanInfo has three main purposes. One is to define the methods that should be exposed to the other subsystems, the second is to define attributes and references so that they can injected at runtime and the third is to define information about the GBean so that it can be located later. Each of these will be discussed in detail below. When defining the instance of the GBeanInfo object for the GBean, GBeanInfo shouldn't be constructed directly. Instead there is a GBeanInfoBuilder class that will simplify the process (see //1 below). Below is an example of creating a GBeanInfo from the MailGBean class and then returning it in the getGBeanInfo() method:

//...
static {
        GBeanInfoBuilder infoFactory = GBeanInfoBuilder.createStatic(Log4jService.class, "SystemLog"); //1

        infoFactory.addAttribute("configFileName", String.class, true);//2
        infoFactory.addAttribute("refreshPeriodSeconds", int.class, true);
        infoFactory.addAttribute("configuration", String.class, false);
        infoFactory.addAttribute("rootLoggerLevel", String.class, false);

        infoFactory.addReference("ServerInfo", ServerInfo.class, "GBean");//3

        infoFactory.addOperation("reconfigure");//4
        infoFactory.addOperation("setLoggerLevel", new Class[]{String.class, String.class});
        infoFactory.addOperation("getLoggerLevel", new Class[]{String.class});
        infoFactory.addOperation("getLoggerEffectiveLevel", new Class[]{String.class});
        infoFactory.addInterface(SystemLog.class);//5

        infoFactory.setConstructor(new String[]{"configFileName", "refreshPeriodSeconds", "ServerInfo"});//6

        GBEAN_INFO = infoFactory.getBeanInfo();
}

public static GBeanInfo getGBeanInfo() {
       return GBEAN_INFO;
}
//...

<gbean name="Logger" class="org.apache.geronimo.system.logging.log4j.Log4jService">
        <attribute name="configFileName">var/log/server-log4j.properties</attribute>
        <attribute name="refreshPeriodSeconds">60</attribute>
        <reference name="ServerInfo">
            <name>ServerInfo</name>
       </reference>
</gbean>

There are a few important things to note from above. By convention, the GBeanInfo object is constructed in a static initializer. Also by convention, the GBeanInfo object is named GBEAN_INFO.

Attributes

In the above snippet of code //2 points to an adding of an attribute to a GBean. It defines the name of the attribute (in this case "configFileName", it's type (String) and whether or not it's persistant (true). Now that the attribute is defined in the GBeanInfo, that attribute can be injected via the Geronimo Kernel. To inject a value into this GBean, it needs to be specified in the deployment plan.

Executing Methods

Methods can be executed on a GBean via two ways. One way is to retrieve the GBean from the kernel and then just execute the method. The other is to allow reflective method invocation of the GBean by adding an operation to the GBeanInfo object associated to the GBean. To do this, a line of code like

Attributes

Defining an attribute in the GBeanInfo object will allow a value to be automatically injected when loading the GBean. To add an attribute to a GBean, a line like:

GBeanLifeCycle

Although implementing the GBeanLifeCycle interface is not required, it's often useful. There are three methods in the GBeanLifecycle interface: doStart(), doStop() and doFail(). The appropriate method will be executed at that point in the GBean Lifecycle. For instance, once a GBean is deployed, it must be started. Once the deployer has started the GBean, the GBeans doStart() method will be executed.