The GBean architecture

The Apache Geronimo application server offers a sleek architectural design in which the kernel has no direct dependency on any of its components. The kernel is a framework for services that controls the service life cycle and registry. The kernel is not based on Java™ 2 Platform, Enterprise Edition (J2EE). It works with the services and components to build specific configurations -- one of which is a full J2EE stack. A majority of the Geronimo services are added and configured through GBeans to become a part of the overall application server. A GBean is the interface that connects the component to the kernel. Each GBean can maintain state, depend on, and interrelate with other GBeans, and operate on events from the kernel and other GBeans. Figure 1 shows a graphic depiction of the Geronimo kernel with GBeans.

You can plug the GBeans into the kernel with Inversion of Control (IoC) and dependency injection through a configuration file called a plan. This means that you can use GBeans in Geronimo through XML declarations in the plan and that you might have dependencies on other GBeans that are configured through the attributes and references. Listing 1 shows an example GBean configuration.

<gbean name="DefaultThreadPool" class="org.apache.geronimo.pool.ThreadPool">
    <attribute name="keepAliveTime">5000</attribute>
    <attribute name="poolSize">30</attribute>
    <attribute name="poolName">DefaultThreadPool</attribute>
</gbean>>

The most interesting part of this architecture is that you can add and remove complete components from the Geronimo stack by editing the plan files and changing the XML declaration of the GBeans.

Many of the GBeans allow other open source projects and code -- such as Jetty, Tomcat, and OpenEJB -- to become a part of the Geronimo stack, while providing JSR-77 life cycle capabilities to these components. An example of a powerful Java-based component is OpenSymphony's Quartz scheduler. This article demonstrates how to create a Quartz GBean to integrate the Quartz scheduler into Geronimo.

Back to top

The Quartz scheduler

Most application servers don't ship with capabilities to run cron or daemon jobs without significant modifications. Although some application servers offer APIs to create daemon-like applications, nearly all of them lack a rich and full feature set.

Quartz, developed by OpenSymphony, is a powerful open source Java-based scheduler. Its features include customized scheduling, schedule persistence (which you can use with many types of persistence mechanisms), remote scheduling capabilities, fault tolerance, clustering, and much more. Although you can run Quartz on its own, its rich features make it an excellent candidate for inclusion in a J2EE application server stack. You can integrate Quartz into Geronimo by creating a GBean to start and stop the scheduler service.

Back to top

Developing a GBean

Developing a GBean is a simple task that involves a few steps. To develop a GBean, you need to download the Geronimo source code from the unstable -- or Milestone 4 (M4) -- branch and be familiar with how to build Geronimo (see Resources for a link to the Geronimo Wiki for more information). A GBean can have attributes, references, and operations. Minimally, each GBean must adhere to the following guidelines:

1. Implement the org.apache.geronimo.gbean.GBeanLifecycle interface if you want to handle life cycle events.
2. Provide a constructor.
3. Implement the doStart(), doStop(), and doFail() methods.
4. Provide a GBeanInfo static initializer that describes the constructor.
5. Implement a public static GBeanInfo getGBeanInfo() method.
6. Create a plan, or edit an existing plan, to use the GBean.

With these guidelines in mind, each GBean should minimally look similar to the following skeleton shown in Listing 2.

/**
 * Quartz GBean
 */
public class QuartzGBean implements GBeanLifecycle {

    private static final Log log = LogFactory.getLog(QuartzGBean.class);

    public QuartzGBean() {
    }

    public void doFail() {
        log.info("Service failed");
        //Insert failure code here
    }

    public void doStart() throws Exception {
        log.info("Starting service");
	    //Insert startup code here
    }

    public void doStop() throws Exception {
        log.info("Stopping service");
	    //Insert stopping code here
    }

    public static final GBeanInfo GBEAN_INFO;

    static {
        GBeanInfoBuilder infoFactory = new GBeanInfoBuilder("QuartzGBean",
                QuartzGBean.class);

        GBEAN_INFO = infoFactory.getBeanInfo();
    }

    public static GBeanInfo getGBeanInfo() {
        return GBEAN_INFO;
    }

}

I use minimally with emphasis because all GBeans must contain the declarations and implementations as shown in Listing 2. If a non-default constructor is used, or if attributes, references, or callable operations are needed, then the GBEAN_INFO static initializer needs to call setConstructor(), addAttribute(), addReference(), and addOperation(), respectively. This instance doesn't have any special constructors, operations, attributes, or references, so these calls aren't required.

Quartz is a great project to integrate with a GBean because it only requires you to start and stop it with the life cycle of the Geronimo application server. This means that you want Quartz to start when Geronimo starts, and you want it to stop when Geronimo shuts down.

To keep this example simple, the Quartz configuration uses the defaults that come with the Quartz distribution. These defaults are in the quartz.properties file that is a part of the .jar file. To configure Quartz to use a database for a persistence layer, remote scheduling, and other advanced options, you must create a custom quartz.properties file. (See Resources for a link to the OpenSymphony Web site, which has more information on configuring these options.)

The Quartz scheduler is simple to start up and shut down; it simply retrieves a scheduler object by calling StdSchedulerFactory.getDefaultScheduler(). To launch Quartz, execute the Scheduler.startup() method. To stop Quartz, execute the Scheduler.shutdown() method. To enable Quartz's life cycle to follow Geronimo, place the startup() call in the GBean's doStart() method, and place the shutdown() call in the GBean's doStop() method. Listing 3 shows the complete GBean after adding the Quartz code.

package org.apache.geronimo.quartz;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.apache.geronimo.gbean.GBeanInfo;
import org.apache.geronimo.gbean.GBeanInfoBuilder;
import org.apache.geronimo.gbean.GBeanLifecycle;
import org.quartz.Scheduler;
import org.quartz.SchedulerException;
import org.quartz.impl.StdSchedulerFactory;

/**
 * Quartz GBean
 */
public class QuartzGBean implements GBeanLifecycle {

    private static final Log log = LogFactory.getLog(QuartzGBean.class);

    public QuartzGBean() {
    }

    public void doFail() {
        log.info("Service failed");
        try {
            doStop();
        } catch (Exception e) {
            log.error("doStop() failed", e);
        }
    }

    public void doStart() throws Exception {
        log.info("Starting service");
        Scheduler scheduler = StdSchedulerFactory.getDefaultScheduler();
       scheduler.start();
    }

    public void doStop() throws Exception {
        log.info("Stopping service");

        try {
            Scheduler scheduler = StdSchedulerFactory.getDefaultScheduler();
            scheduler.shutdown();
        } catch (SchedulerException se) {
            log.error("Cannot shutdown scheduler.", se);
        }

    }

    public static final GBeanInfo GBEAN_INFO;

    static {
        GBeanInfoBuilder infoFactory = new GBeanInfoBuilder("QuartzGBean",
                QuartzGBean.class);

        GBEAN_INFO = infoFactory.getBeanInfo();
    }

    public static GBeanInfo getGBeanInfo() {
        return GBEAN_INFO;
    }

}

The QuartzGBean code seems simple enough, but you still need to compile it and build a proper .jar file. Because Geronimo uses Apache Maven as a build tool, this example uses a Maven module for Quartz (see Resources for a link to the Maven Web site). To create a Maven module, you need a project.xml file, a project.properties file, a maven.xml file, and your source code. The code in the download for this article contains a complete Maven build module for compiling the QuartzGBean with Geronimo. To compile this code, complete the following steps:

1. Download the archive file to the geronimo/modules directory, and unpack it there. It will create a quartz directory with the build infrastructure beneath it, including the QuartzGBean.java code and a unit test.
2. Be sure you are in the geronimo/modules/quartz directory, and type maven at the command line. This will compile, unit test, and package the GBean into a geronimo-quartz-1.0-snapshot.jar file, which is stored in your Maven repository.

Back to top

Integrating the QuartzGBean into Geronimo

Now that you've created the .jar file, you need to make a few changes to the Geronimo build to use your GBean. When creating GBeans, you normally create a plan for deploying the GBean. In this case, you'll edit some of the existing files to launch the GBean on server startup without manually starting or deploying a configuration. The following steps will configure Geronimo to use the new QuartzGBean.

1. Add the Quartz version to the Geronimo build so that Maven will automatically download the proper version. Edit the project.properties file that is in the geronimo/etc directory by adding the following line:

   quartz_version=1.4.5

   
   

2. Prepare the assembly module to use Quartz and the new .jar file. In the geronimo/modules/assembly directory, add the bold code shown in Listing 4 to the project.xml file in the dependencies section:

   
   Listing 4. Assembly project.xml dependencies
   

   <dependencies> . . . <!--Quartz --> <dependency> <groupId>opensymphony</groupId> <artifactId>quartz</artifactId> <version>${quartz_version}</version> <properties> <repository>true</repository> </properties> </dependency> <dependency> <groupId>geronimo</groupId> <artifactId>geronimo-quartz</artifactId> <version>${pom.currentVersion}</version> <properties> <repository>true</repository> </properties> </dependency> . . . </dependencies>

   
   

   The <repository>true</repository> code causes the Geronimo build to add the .jar file into the .jar repository included with the final Geronimo assembly, so the Geronimo build will ship with the specified .jar file.

3. Write the GBean and dependencies into a plan. Although you could create your own plan, it's much easier to edit an existing plan to be sure the QuartzGBean launches when Geronimo starts. To do this, edit the j2ee-server-plan.xml file, which is in the geronimo/modules/assembly/src/plan directory. Add your dependencies to the plan after the last </dependency> tag and before the first <gbean> tag, as shown in Listing 5.

   
   Listing 5. j2ee-server-plan.xml dependency addition
   

   <!-- Quartz --> <dependency> <uri>opensymphony/jars/quartz-${quartz_version}.jar</uri> </dependency> <dependency> <uri>geronimo/jars/geronimo-quartz-${geronimo_version}.jar</uri> </dependency>

   
   

4. Add your GBean to the same file. At the bottom of the file, before the final </configuration> tag, add the following line:

   <gbean name="QuartzService" class="org.apache.geronimo.quartz.QuartzGBean"/>

   
   

Now you only need to rebuild the assembly module. This makes the new configuration and updated plan part of the Geronimo server. To rebuild the assembly module, change your directory to geronimo/modules/assembly and type maven at a command prompt. When the assembly module build finishes, you should have a geronimo-assembly-1.0-SNAPSHOT.jar file in the geronimo/modules/assembly/target directory. To run Geronimo, execute java -jar bin/server.jar-v from the command line. The -v is normally not necessary to run Geronimo, but it's included here to send the log output to the terminal window so you can see what's happening.

When launching Geronimo with the -v, make note of the log, and watch the new GBean launch Quartz, as shown in Listing 6.

    14:53:13,462 INFO  [QuartzGBean] Starting service
14:53:13,615 INFO  [SimpleThreadPool] Job execution threads will use class loader of 
                                      thread: main
14:53:13,697 INFO  [RAMJobStore] RAMJobStore initialized.
14:53:13,699 INFO  [StdSchedulerFactory] Quartz scheduler 'DefaultQuartzScheduler' 
                                         initialized from default resource file in 
                                         Quartz package: 'quartz.properties'
14:53:13,699 INFO  [StdSchedulerFactory] Quartz scheduler version: 1.4.5
14:53:13,701 INFO  [QuartzScheduler] Scheduler DefaultQuartzScheduler_$_NON_CLUSTERED 
                                         started.

When you shut down Geronimo, note the differences in the log.

    14:53:41,426 INFO  [QuartzGBean] Stopping service
14:53:41,450 INFO  [QuartzScheduler] Scheduler DefaultQuartzScheduler_$_NON_CLUSTERED 
                                     shutting down.
14:53:41,452 INFO  [QuartzScheduler] Scheduler DefaultQuartzScheduler_$_NON_CLUSTERED 
                                     paused.
14:53:41,459 INFO  [QuartzScheduler] Scheduler DefaultQuartzScheduler_$_NON_CLUSTERED 
                                     shutdown complete.

Back to top

Conclusion

For most open source projects, implementing a few functions and editing a few configuration files is all it takes to write GBeans. However, some integration initiatives, such as Jetty, Tomcat, or OpenEJB, can require significantly more modification in the coding. These integrations require multiple GBeans, configurations, and hooks in the code. However, an application like Quartz is an excellent candidate for easy integration, because it only needs to be started and shut down. There are many more open source projects that lend themselves to integration as easily as Quartz.

Back to top

Acknowledgements

• I would like to thank Bruce Snyder and Dain Sundstrom from the Apache Geronimo team, who both helped out by reviewing this article.
• This article is available simultaneously on IBM developerWorks and Virtuas Solutions.

Back to top

Download

Information about download methods

Resources

Learn

• See the Apache Geronimo Wiki for up-to-date information on Geronimo, as well as details on downloading the M4 release.
  
  
• Take a look at the Quartz OpenSymphony site for more information on this job-scheduling system.
  
  
• Find out what's new with Apache Geronimo at the official Apache Geronimo Web site.
  
  
• Take a guided tour through Geronimo with author Sing Li in "Geronimo! Part 1: The J2EE 1.4 engine that could" (developerWorks, May 2005). Then get hands-on in "Geronimo! Part 2: Tame this J2EE 1.4 bronco" (developerWorks, May 2005).
  
  
• Visit the developerWorks Apache Geronimo project area to access resources for Geronimo developers.
  
  
• Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
  
  
• Browse all the Apache articles and free Apache tutorials available in the developerWorks Open source zone.
  
  

Get products and technologies

• Visit the Apache Maven Web site for download information and documentation. Maven is a software project management and comprehension tool that automates the deployment of Geronimo applications.
  
  
• Download Gluecode Standard Edition, an open source application server based on Apache Geronimo.
  
  
• Innovate your next open source development project with IBM trial software, available for download or on DVD.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Join the Apache Geronimo team for discussion on the #geronimo IRC channel (IRC client required).
  
  

About the author

Jeff Genender is a Practice Leader for Virtuas Solutions and specializes in leading companies in Java architecture and implementing open source solutions. He is a committer and PMC member for Apache Geronimo. He is the author of Enterprise Java Servlets (September 2001, Addison Wesley Longman), and is currently authoring JBoss Live (SourceBeat Publishing).

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• The GBean architecture
• The Quartz scheduler
• Developing a GBean
• Integrating the QuartzGBean into Geronimo
• Conclusion
• Acknowledgements
• Download
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into Open source on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers