eronimo is built around an Inversion of Control (IoC) kernel that consumes and manages components called GBeans. The GBean framework is the vehicle by which new behaviors are added to the Geronimo kernel. Almost everything in Geronimo?including containers, adapters, and applications?is a GBean.

This article introduces you to the GBean framework architecture and shows you how to build and deploy a simple GBean.

Introducing Apache Geronimo
Apache Geronimo is an enterprise-grade J2EE application server created from the efforts of a vast worldwide community of Java open source developers.

In addition to being a powerful J2EE application server, Apache Geronimo provides an extremely modular and loosely-coupled infrastructure allowing pieces of the infrastructure to be used only as needed.

Apache Geronimo combines its modular infrastructure with outstanding open source technologies to support current J2EE specifications. Some of these technologies include:

• EJB?OpenEJB
• JDBC and Persistence?TranQL
• JMS?ActiveMQ
• JMX?MX4J
• Logging?HOWL
• Servlets and JSP?Apache Tomcat and/or Jetty
• Web Services?Apache Axis

Part of Geronimo’s powerful infrastructure includes an IoC-based framework for creating loosely-coupled, configurable, runtime environments from components known as GBeans. Runtime environments in this context refer to any situation needing to load, execute, and manage Java objects in order to fulfill a specific technological scenario. Scenarios might include: entire distributed messaging platforms; small, discrete kernels for object pooling frameworks; clustering frameworks; plug-in capable desktop applications; and others. The powerful benefit derived from using this GBean-based framework is that the concepts and component interactions remain constant for each scenario.

The following sections discuss the components and structures of the Geronimo GBean framework.

Figure 1. Geronimo Basic Architecture: The figure shows the basic architecture of the Geronimo GBean framework, along with the persistence framework.

Introducing Geronimo’s GBean Framework
The Geronimo GBean framework facilitates Java-based execution environments by defining their capabilities through a configuration of components known as GBeans. At the heart of each execution environment is a GBean component known as the kernel that consumes and manages other GBeans.

The kernel manages GBean dependencies, state, and lifecycle. A GBean relies on the kernel to “inject” dependencies into the GBean at runtime according to rules defined in a configuration file called a deployment plan. The following code is an example of a GBean declaration within a deployment plan:

          buenos dias       Jeff Hanson       Simply for show   

GBeans execute around a lifecycle that defines specific execution states in respect to the kernel to which they are deployed.

Figure 1 illustrates the basic architecture of the Geronimo GBean framework, along with the persistence framework.

The Lifecycle of a GBean
Geronimo GBeans handle lifecycle events and maintain states and association dependencies. Geronimo’s IoC execution environment revolves around a web of GBeans and relies on being able to query the current state of each GBean. In addition, the execution environment must be able to save the state of each GBean and restore that state as needed. This need is met by the GBean framework’s persistence sub-system.

Table 1 shows all the possible lifecycle states a GBean might be in at any given time:

The GBean Persistence Framework
The GBean persistence framework enables storing and retrieving GBeans along with their current state to and from permanent storage. You can define each GBean attribute as persistent or non-persistent. Persistent attributes retain their state/value across all instances of the GBean, while non-persistent attributes retain their state/value only during the lifetime of a specific Gbean instance.

By default, the framework persists GBeans persisted to permanent storage in Java serialized format, but Geronimo provides support for third-party storage providers to handle the actual GBean storage.

A Geronimo deployment plan defines a collection of services that can be loaded into a Geronimo execution environment. The components in a deployment plan include information needed to locate classes, parent/child relationships, and a hierarchy of GBean definitions to be loaded. The GBean definitions and the state of all GBeans will be serialized to permanent storage when the artifact defined by the deployment plan is stored.

When a stored deployment artifact is restarted, the persistence framework de-serializes any stored GBeans and restores them to their pre-saved state. After restoring the GBeans, the framework restores their dependencies and references, and then restarts the GBeans.

The GBean Dependency and Reference Manager
When the Geronimo kernel targets a GBean to be loaded, it first loads any dependencies (ancillary GBeans of the target GBean). The GBean dependency manager looks for dependencies declared in a GBean’s deployment plan and attempts to load these before loading the target GBean.

After loading and launching a GBean’s dependencies, the dependency manager generates references to these dependencies and connects them to the both target GBean and its dependencies. References are proxies to the actual object, ensuring a loose coupling between the target GBean and its dependencies.

It injects these references into a GBean using either getter/setter method injection or constructor-based injection. The following code illustrates how a GBean specifies a reference (BeanRef1) that is to be injected by means of the GBeans constructor:

   public class TestGBean      implements GBeanLifecycle   {      private final String AnotherGBean beanRef1;         static       {         GBeanInfoBuilder infoBuilder = new             GBeanInfoBuilder(TestGBean.class.getName(),            TestGBean.class);            // attributes         infoBuilder.addReferance("BeanRef1", AnotherGBean.class);                // operations         infoBuilder.setConstructor(new String[] { "BeanRef1" });            GBEAN_INFO = infoBuilder.getBeanInfo();      }         public TestGBean(AnotherGBean beanRef1)      {         this. beanRef1= beanRef1;      }      ...   }

Exposing GBean Meta-information
GBeans provide information to the kernel about their publicly-available attributes, operations, and notifications via the GBeanInfo getGBeanInfo() method. This method returns an instance of the GBeanInfo class; which, by convention, is created within a static initialization block, similar to the following:

   public class TestGBean implements GBeanLifecycle   {      private static final GBeanInfo GBEAN_INFO;         static      {         GBeanInfoBuilder infoBuilder = new             GBeanInfoBuilder(TestGBean.class.getName(),            TestGBean.class);            boolean isPersistent = true;            // attributes         infoBuilder.addAttribute("message", String.class,             isPersistent);         infoBuilder.addAttribute("createtime", long.class,             isPersistent);            infoBuilder.addOperation("setMessage",             new Class[]{String.class});         infoBuilder.addOperation("getMessage");         infoBuilder.addOperation("setCreatetime",             new Class[] {long.class});         infoBuilder.addOperation("getCreatetime");            GBEAN_INFO = infoBuilder.getBeanInfo();      }         public static GBeanInfo getGBeanInfo()      {         return GBEAN_INFO;      }         ...   }

If you use a non-default constructor?or if attributes, references, or callable operations are needed?then the GBEAN_INFO static initializer needs to call the methods setConstructor(), addAttribute(), addReference(), and addOperation(), respectively. The example instance doesn’t have any special constructors, operations, attributes, or references, so these calls aren’t required.

Attributes and references must be compliant with the following naming conventions:

• Attributes must start with a lower case first character.
• References must start with an upper case first character.

This simple naming convention should simplify the configuration of a GBean. Keeping this basic framework architecture and conventions in mind, to help fill in the details, the rest of this article shows you how to build an example GBean, integrate it into the Geronimo framework, deploy it to Geronimo, and test it.An Example GBean
A GBean is a simple Java class that is extended to implement the org.apache.geronimo.gbean.GBeanLifecycle interface and to define attributes, references, and operations via a public static method with the signature, GBeanInfo getGBeanInfo. A GBean should, by convention, also create an instance of GBeanInfo in a static initializer block and expose this instance as a public static final field called GBEAN_INFO.

According to these rules, a very simple GBean would look similar to the class shown in Listing 1.

Integrating a GBean into Geronimo
With the GBean class defined, you must compile and encapsulate it within an archive file (.ear, .war, .jar, etc.). The archive must contain the deployment plan for the GBean, and that plan must conform one of the deployment schemas found in the /schema directory. This example deploys the TestGBean as a standalone module; therefore it must conform to the geronimo-module-1.x.xsd schema.

Here’s a simple standalone module plan for the TestGBean shown in Listing 1:

                                 com.example.gbeans            TestGBean            1.1                                    buenos dias         

Now that the plan is in place, use the jar command-line tool to create a jar file for TestGBean, as follows:

   $ jar -Mcvf mygbean.jar com/example/*.class

After creating the .jar file, start the Geronimo server by executing the startup script you’ll find in /bin. The Geronimo startup console will appear and when the server is ready, you should see output similar to the following:

   Startup completed in 27 seconds     Listening on Ports:       1099 0.0.0.0 RMI Naming       1527 0.0.0.0 Derby Connector       4201 0.0.0.0 ActiveIO Connector EJB       4242 0.0.0.0 Remote Login Listener       8080 0.0.0.0 Jetty Connector HTTP       8443 0.0.0.0 Jetty Connector HTTPS       9999 0.0.0.0 JMX Remoting Connector      61613 0.0.0.0 ActiveMQ Transport Connector      61616 0.0.0.0 ActiveMQ Transport Connector        Started Application Modules:       EAR: org.apache.geronimo.configs/webconsole-jetty6/2.0-M1/car       RAR: org.apache.geronimo.configs/activemq/2.0-M1/car       RAR: org.apache.geronimo.configs/system-database/2.0-M1/car       WAR: org.apache.geronimo.configs/dojo-jetty6/2.0-M1/car       WAR: org.apache.geronimo.configs/remote-deploy-jetty/          2.0-M1/car       WAR: org.apache.geronimo.configs/welcome-jetty/2.0-M1/car        Web Applications:       http://localhost:8080/       http://localhost:8080/console       http://localhost:8080/console-standard       http://localhost:8080/dojo       http://localhost:8080/remote-deploy

At this point, you’re ready to deploy your GBean to Geronimo.

Deploying the GBean to Geronimo
You can deploy GBeans using either the Geronimo console portal found at http://localhost:8080/console or by executing the Geronimo deployer tool. With the Geronimo server running, you can deploy the TestGBean using the following command:

   java -jar bin/deployer.jar deploy       TestGBean.jar plan.xml   Username: system   Password: manager

The output from the deployment step will look similar to the following:

   Username: system   Password: *******      Deployed com.example.gbeans/TestGBean/1.1/car

To verify the success of the deployment, run the deployer tool with the list-modules command, as follows:

   java -jar /bin/deployer.jar list-modules   Username: system   Password: *******

The list-modules command displays all the currently deployed modules and should show a line detailing the abstract name for the TestGBean deployment, similar to the following:

   Found n  modules     + com.example.gbeans/TestGBean/1.1/car     ...

Testing the GBean
After deploying the GBean successfully, you can execute the test code shown in Listing 2 to test the deployment and view information about the GBean using JMX remoting:

After running the test, you should see the following output on the console:

Figure 2. Geronimo Admin Console: Although you can run the test code to print out information about the TestGBean in the console, you can also see GBean information through the Geronimo Admin Console management application.

   TestGBean ObjectInstance Class Name: com.example.TestGBean      Attribute Infos:         org.apache.geronimo.gbean.AbstractName abstractName         org.apache.geronimo.kernel.Kernel kernel         org.apache.geronimo.gbean.GBeanInfo GBeanInfo         java.lang.ClassLoader classLoader         java.lang.String message         java.lang.String objectName      Operation Infos:          getMessage()         void doFail()         void doStop()         void doStart()

You can also view information about the GBean using the Geronimo Admin Console found at http://localhost:8080/console. Log into the console and select the JMX Viewer link to see a list of Mbeans. Expand the “ServiceModule MBeans” node and then expand the “TestGBean” node. You will see a page similar to Figure 2.

That completes this introduction to the GBean framework architecture. You’ve seen how to build and deploy a simple GBean.