 | Level: Introductory Hemapani Srinath Perera (hemapani@gmail.com), Developer, Lanka Software Foundation
09 Aug 2005 Geronimo, the Apache Software Foundation's open source Java™ 2 Platform, Enterprise Edition (J2EE) server, integrates dozens of technologies and concepts. Most of them are projects in their own right, each with its own configuration and deployment model. In Geronimo's quest to bring these heterogeneous systems under one umbrella, it boils down the various approaches to configuration and deployment into a single, homogeneous model. Geronimo developer Srinath Perera explains how Geronimo achieves this objective and links what Geronimo users see to concepts that underlie the server's architecture.
In August 2003, dozens of open source developers gathered under the banner of Apache Software Foundation for the Apache J2EE Server Project, and Apache Geronimo was born. Geronimo can be viewed as an operating system for the enterprise. It brings dozens of open source projects into a single framework, where they coordinate to deliver the enterprise stack.
Geronimo is one of the more complex projects undertaken by the open source community, comparable to Linux in its intricacy. (Some observers believe that Geronimo is a test of the sustainability of open source practices and their ability to handle such a high degree of complexity.) Also, one of Geronimo's principal goals is J2EE 1.4 certification -- a time-consuming effort. Nevertheless, Geronimo has already issued several milestone releases and is moving steadily toward the magical 1.0 release.
Geronimo's architecture
Like most other enterprise operating systems, Geronimo is built on a kernel -- a microkernel that lays the foundation for everything above it. Geronimo's kernel is J2EE agnostic. Its sole purpose is to manage Geronimo's building blocks, called Geronimo Beans, or GBeans for short.
Almost everything in Geronimo -- including containers, connectors, and applications -- is a GBean. The granularity of GBeans varies accordingly. For example, a little servlet that runs on the Web container is a GBean, and the Web container itself is a GBean. GBeans, especially large ones, can aggregate other GBeans.
|
Geronimo's GBeans framework
Geronimo is made up of building blocks called GBeans. The Geronimo kernel is a container for GBeans that handles their life cycles. GBeans have persistent states and can specify the dependencies among themselves. As a net effect, Geronimo is a loosely coupled system built on GBeans. Every action in Geronimo -- starting, stopping, managing, and deploying services -- can be explained in terms of GBeans.
|
|
Geronimo's kernel manages the life cycles of GBeans and the dependencies among them. GBeans can hold states, define dependencies among themselves, and react to life cycle events. A GBean's state can be made persistent with the GBean framework's support. Because a running Geronimo instance is essentially a mesh of running GBeans, this functionality can be used to store Geronimo's current state and to recover that state later. This capability is unique because it doesn't require any configuration files. Instead, all the states are kept in GBeans. Moreover, GBeans can be managed through the management interface, enabling them to be started, stopped, and edited on the fly.
A GBean can register an interest in knowing when other GBeans that follow a specific filename pattern are running. After a GBean that matches the pattern is started, a reference to the started GBean is automatically injected into the GBean that registered the interest. This is called dependency injection. Dependency injection makes GBeans a powerful tool for building loosely coupled systems.
For example, the GBean that represents the Enterprise JavaBeans (EJB) container can register an interest in GBeans that represent EJBs. After a GBean that represents an EJB is started, the kernel notifies the EJB container about it. GBean creators don't need to relate their GBeans to other interested GBeans; registering the interest is sufficient. After a GBean is started, all the other GBeans that are interested in it become aware of it.
Deployment and configuration
The Geronimo deployment architecture is about how to create, start, stop, store, retrieve, and remove the GBeans that represent the J2EE or non-J2EE components deployed in Geronimo.
The configuration is the key deployment unit. A configuration is a logically grouped collection of one or more GBeans and a classloader. Configurations can be stored in a configuration store, the standard Geronimo storage mechanism. Geronimo manages GBeans at the configuration level; the configurations are started with the server, and the user can stop or undeploy them. Each configuration has a physical location in the Geronimo distribution, in a folder called config-store. The configurations that come with the distribution represent core services. Each new application that is deployed creates a new configuration.
Adding a new component to Geronimo takes four steps, whether it's a core component or an application:
- Constructing a GBean or GBeans that capture the component's information and behavior
- Grouping the GBeans into a configuration with the classloader associated with them
- Storing the configuration in the configuration store
- Starting the configuration
After this process is complete, the component's information persists when the server restarts. This explains a singular aspect of Geronimo. The Geronimo distribution has no deployment descriptors, because configurations simply replace them. All the deployment information is converted to GBeans, grouped as configurations, and stored in the configuration store. Figure 1 shows how GBeans are created, run, and stored inside Geronimo.
Figure 1. Geronimo deployment and configuration architecture
As you can see in Figure 1, GBeans are constructed in one of three ways:
|
Geronimo building blocks: Developer and user perspectives compared
Geronimo developers and Geronimo users see the same thing from different perspectives.
The developers see a mesh of related, running GBeans communicating with one another. The identity of everything else dissolves once it's inside the Geronimo kernel. Only two things exist: GBeans and configurations (logical collections of GBeans that are managed as one unit and can be stored and retrieved as a unit). In the most abstract sense, Geronimo is composed only of GBeans. Even configurations matter only until the GBeans are started.
Users are concerned with J2EE-specified entities, such as servlets, EJBs, data sources, connectors, and with the following container-specific deployment descriptors:
- J2EE modules -- deployable software units defined by the J2EE specification
- Deployment plans -- XML files used to provide more information about the module to Geronimo
The Geronimo deployer sits in between and converts everything that exists in the J2EE world to the Geronimo world (see Figure 1).
|
|
-
From plans - A plan is an XML serialization of a GBean. Plans are used to configure Geronimo's core components. Geronimo's configuration builders construct GBeans out of plans and store them in the configuration store. These plans live in Geronimo source code, but they are read and stored as configurations when the binary distribution is built. They aren't included with the binary distribution because they've already served their purpose.
-
From J2EE deployment modules - To deploy anything that is not a GBean in Geronimo, the Geronimo deployer creates a GBean that captures the information it represents. For example, consider an EJB module that includes an ejb-jar.xml file and some classes. The Geronimo deployer creates a GBean that captures the information the module represents and stores the GBean in the configuration store.
-
Programmatically - If a GBean cannot be created from a plan or a deployment module, it should be created programmatically. This is the least-used option.
An integration example
A good example of integrating a project into Geronimo is the integration of an EJB container. You model the EJB container as one or more GBeans, group them as a configuration, and represent the configuration as a plan. Geronimo reads the plan and constructs, stores, and starts the configuration.
The EJB container GBean doesn't know about the EJBs that are deployed in it. But it registers an interest with the kernel for the GBeans that match the GBean representation of an EJB. When a J2EE developer creates an EJB module and deploys it, the Geronimo deployer creates a GBean that represents the EJB module, stores it in the configuration store, and starts the GBean. After the GBean has started, the kernel injects the GBean into the EJB container GBean, because the latter has registered its interest in EJB GBeans. This injection notifies the EJB container about the EJB and enables it to service the requests directed to the EJB.
Behind the curtain
This section explains what happens behind the scenes when the deployment commands are executed. All the commands shown work from the Geronimo installation directory. This command starts the Geronimo server:
$ java -jar bin/server.jar configuration1 ...
|
After you issue this command, the output on the screen looks like the one shown in Listing 1:
Listing 1. Server startup
.......
10:56:10,580 INFO [Configuration] Started configuration org/apache/geronimo/System
10:56:10,668 INFO [RMIRegistryService] Started RMI Registry on port 1099
10:56:10,836 INFO [ReadOnlyRepository] Repository root is
file:/home/hemapani/drafts/dev-works/geronimo-1.0-M3/repository/
10:56:10,890 INFO [ConfigurationManagerImpl] Loaded
Configuration geronimo.config:name="org/apache/geronimo/SystemJMS"
...
|
Geronimo chooses the configurations from the configuration store and starts them one by one. Each configuration starts the GBeans that are associated with it.
Running a configuration
The command to start a configuration is:
$ java -jar bin/server.jar configuration1 ...
|
This starts a configuration along with any dependencies. You can find available configurations in config-store/index.properties, but be careful not to change this file, because that might corrupt your installation. The command starts all the GBeans in each configuration that is starting.
Deploying a module
The command for deploying a module is:
$ java -jar bin/deployer.jar deploy YourApplication.ear
|
This creates GBeans out of a J2EE module, such as an enterprise archive (EAR). It creates a configuration and stores it in the configuration store in a new folder that Geronimo creates inside the Geronimo distribution's config-store folder. After the new configuration is set up, it's started.
Undeploying a module
The command for undeploying a module is:
$ java -jar bin/deployer.jar undeploy module-id
|
The GBeans associated with the module are stopped and then removed from the configuration store.
Deploying a service
The command to deploy a service is:
$ java -jar bin/deployer.jar deploy YourService-plan.xml
|
You can use this command to deploy one or more custom GBeans. The XML file is an XML serialization of the GBeans. This command has nothing to do with J2EE and can be used to deploy custom services in Geronimo. The sample application described in the next section will demonstrate this capability.
A sample application
To demonstrate the concepts covered so far, this article provides a simple echo server written using the Geronimo GBeans architecture. It uses Geronimo command-line deployment to deploy the server. The application shows how a custom component -- one that has nothing to do with J2EE -- can be deployed in Geronimo. Each J2EE application deployer uses this same mechanism to convert a J2EE component to GBeans, store them as configurations, and start them.
Getting started
Follow these steps to prepare for running the application:
- Download the Geronimo distribution (see Resources for a link to the Apache Web site's downloads page), and unpack it into the directory of your choice. From this point on I'll refer to the directory as the Geronimo home directory or $GERONIMO_HOME.
- Download the sample code (see Download), and unpack it. A samples folder containing a build.xml file will be created. Copy the samples folder into the Geronimo home directory.
- Install Apache Ant (see Resources for a link to the Web site).
- Build the sample application by changing the directory to the samples directory and typing
$ant. This will compile and build the sample.jar file and copy it to GERONIMO_HOME/repository/sample/jars.
Understanding the sample
GERONIMO_HOME/sample/src/EchoServer.java has an implementation of the echo server GBean. The GBean's code is shown in Listing 2.
Listing 2. Echo server GBean code
public class EchoServer implements GBeanLifecycle {
private static final GBeanInfo GBEAN_INFO;
private final String objectName;
private int port;
private ServerSocket serversocket;
private boolean started = false;
static {
GBeanInfoBuilder infoFactory =
new GBeanInfoBuilder(EchoServer.class.getName(), EchoServer.class);
// attributes
infoFactory.addAttribute("objectName", String.class, false);
infoFactory.addAttribute("port", int.class, true);
// operations
infoFactory.setConstructor(new String[] { "objectName", "port" });
GBEAN_INFO = infoFactory.getBeanInfo();
}
public EchoServer(String objectName, int port) {
this.objectName = objectName;
this.port = port;
}
public void doStart() throws WaitingException, Exception {
//code to start the echo server
}
public void doStop() throws WaitingException, Exception {
//code to stop the echo server
}
.....
}
|
Listing 3 shows the $GERONIMO_HOME/sample/echo-server.xml file, which is the plan for deploying the echo server inside Geronimo.
Listing 3. Echo server deployment plan
<?xml version="1.0" encoding="UTF-8"?>
<configuration
xmlns="http://geronimo.apache.org/xml/ns/deployment"
configId="deployment/echoserver"
>
<gbean name="geronimo.test:name=echoserver"
class="EchoServer" >
<attribute name="port" type="int">2345</attribute>
</gbean>
<dependency>
<uri>sample/jars/samples.jar</uri>
</dependency>
</configuration>
|
Pay special attention to the port attribute and the dependency that explains where the classes for the echo server can be found. The path is given relative to the repository directory of the Geronimo home directory. The configuration ID is the unique ID that identifies the configuration.
Start the Geronimo server
Change directory to $GERONIMO_HOME and start the Geronimo server:
$ java -jar bin/server.jar
|
Deploy the echo server
In a separate shell, change directory to $GERONIMO_HOME and deploy the echo server:
$ java -jar bin/deployer.jar deploy samples/echo-server.xml
|
Deploy a service
When prompted by the deployer, enter system as the username and manager as the password:
Username: system
Password: manager
Deployed deployment/echoserver
|
Output in the server window states that the GBean is started. The bottom line is the System.out.println() statement at the echo server GBean. Now the echo server is up and running. To test it, use a telnet client or the test case provided with the download.
More commands
You can also try the following commands to stop, start, and undeploy the echo server:
java -jar bin/deployer.jar stop deployment/echoserver
java -jar bin/deployer.jar start deployment/echoserver
java -jar bin/deployer.jar undeploy deployment/echoserver
|
In each case the server window will indicate what happens, including which configurations have started or stopped.
Conclusion
You've learned about the Geronimo deployment model, which brings a number of different open source projects under one umbrella. Geronimo users don't need to know all the detail covered in this article, but if you've been adventurous enough to peek behind the curtain, you've gained a deeper understanding of the concepts underlying the Geronimo deployment architecture.
Download | Description | Name | Size | Download method |
|---|
| Echo server application | deploysample.zip | 10 KB | HTTP |
|---|
Resources Learn
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 Apache Ant, the popular Java-based build tool, from the project Web site.
- 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.
- Download the Apache Geronimo distribution from the Apache Web site.
Discuss
About the author | 
| | Srinath Perera is a Geronimo committer with expertise in Web services, J2EE, and XML-processing technologies. Srinath is active in the Apache Web Services project as a committer for the WS-FX, Enterprise Web Services (EWS), Axis, and Axis 2 projects. He represents Axis2 in the Apache Web Services Project Management Committee. You can reach Srinath at hemapani@gmail.com.
|
Rate this page
| |
