Geronimo serves up one-click upgrades with plug-in support

Document options Document options requiring JavaScript are not displayed Discuss Sample code Learn and share! Exchange know-how with your peers -- try our new Pass It Along beta app Rate this page Help us improve this content

Level: Intermediate

Sing Li (westmakaha@yahoo.com), Author, Wrox Press

22 Aug 2006

The ability to install and create plug-ins is one of the most anticipated new features in the Apache Geronimo 1.1 release. Plug-ins open a new world of instant upgrades for Geronimo users. You can now download new applications and services and have them running on your Geronimo server within minutes. This article introduces you to Geronimo plug-ins and shows you how to find them, install them, and even create them yourself.

Before the availability of plug-ins, installation of new service or application features required either a download of a special build of Geronimo or the manual deployment and configuration of Geronimo modules. Plug-ins simplify life by enabling plug-in providers to bundle in the deployment and configuration in a ready-to-run format along with the module. New server features and applications can be added to the server via a simple download and install.

The Geronimo kitchen

As a Geronimo user, you're already familiar with Geronimo modules; they are WAR, EAR, RAR, and JAR files that you deploy to the server. To deploy one of these modules, you need a Java™ 2 Platform, Enterprise Edition (J2EE) deployment descriptor (such as web.xml for a Web application) and, frequently, also a Geronimo-specific deployment plan (such as geronimo-web.xml for a Web application). The deployment descriptor and deployment plan tell Geronimo how to configure the module for deployment.

Depending on the type of module, internally Geronimo calls different specialized builder components to process the deployment plans and to configure and start the module (for more information, see "The J2EE 1.4 engine that could" [developerWorks, May 2005]). For example, the Enterprise JavaBeans (EJB) builder is exclusively responsible for handling EJB modules. As an analogy, the deployment descriptor and plan are the recipes, and the builders are the cooks; you supply the recipes, and the cooks whip up a tasty module.

Plug-ins, then, are just ready-to-run "cooked" Geronimo modules.

After a module is successfully deployed and started, its configuration (as specified by the deployment plans) is stored in binary form in the repository. The repository acts as a configuration store in this case, as shown in Figure 1.

In Figure 1, both Module 1 and Module 2 are deployed successfully into the Geronimo server A. Internally, Geronimo manages each of these modules together with their configuration information. The plug-in mechanism allows the exporting of these predeployed modules as cooked bundles.

Instant module cooking

A plug-in is created by extracting cooked modules from Geronimo in a form that is instantly reinstallable and restartable from a similarly configured Geronimo server instance. Figure 2 illustrates this extraction.

In Figure 2, both Module 1 and Module 2 are deployed in Geronimo A. They are both exported (extracted) as plug-ins and placed into a public plug-in repository. Another similarly configured Geronimo server, Geronimo B, finds and installs the Module 2 plug-in. Geronimo B can start and run Module 2 without any additional configuration.

To achieve install-and-start status, a plug-in bundle currently includes:

• The binaries of the module.
• The configuration information for the module in binary form.
• A descriptor, geronimo-plugin.xml, that provides metadata and tells the container how to install the plug-in.

Since the deployment and configuration work is already performed on the module within a plug-in, it's ready to start as soon as you install it.

Dependencies and prerequisites

One of the benefits of plug-ins is immediately obvious: You can get expert configuration without doing it yourself.

The work of a plug-in installer extends beyond the deployed module, because a plug-in can depend on other modules. This dependency is supplied to the plug-in installer in the geronimo-plugin.xml file. Along with these dependencies, a list of repositories where the installer should look for them can also be included in geronimo-plugin.xml.

The installer downloads these dependencies before starting the plug-in.

A plug-in can also include a list of prerequisites. Prerequisites must be preinstalled by the user on the server before installing the plug-ins. Any unsatisfied prerequisite will halt the plug-in installation, because the plug-in installer can't automatically install prerequisites.

When creating a plug-in, you have a choice of bundling dependency JAR files within the plug-in distribution or leaving it for external and separate download. Bundling in the dependency JARs ensures that they are available for your plug-in, but makes the distribution larger. Leaving it for external inclusion keeps the distribution smaller and enables the sharing of the dependency JARs by other modules running in the server. However, leaving it for external inclusion means that there is a small risk that the dependency can't be downloaded and the plug-in can't be started.

Environmental requirements

To realize the install-and-run benefit of a plug-in, the plug-in creator and the plug-in installer must be similar. This similarity requirement can include the following details:

• Matching version of the Geronimo server
• Web container flavor -- either Tomcat or Jetty
• The Java Virtual Machine (JVM) level that the Geronimo instance is running under
• The availability of an externally configured J2EE resource, such as a shared Java Database Connectivity (JDBC) pool
• If the module or dependencies rely on external network endpoints -- say, a Relational Database Management System (RDBMS) server -- those endpoints must also be reachable from the installing server.

Typically, these requirements are specified via prerequisites in the plug-in metadata. These requirements can be somewhat limiting if you're creating very specific plug-ins dependent on a specific VM version or server configuration for a wide audience (such as distribution of applications over the Internet). In these cases, the metadata included with a plug-in, in the META-INF/geronimo-plugin.xml file, can make sure only systems with the correct configuration are able to install your plug-in.

Configuring multiple instances of Geronimo in an enterprise

The requirement for a similar server is a lesser issue when plug-ins are used within an enterprise. In the controlled environment within an enterprise, you typically have many similarly configured systems and can use plug-ins effectively to expedite repetitive deployment.

Because plug-ins are preconfigured and deployed modules, each running module in a Geronimo server can be considered a plug-in. If you need to identically configure applications for a large set of Geronimo servers, it's possible to stage everything you need on one server, point other server instances to the staging server, and then download and install the new modules as plug-ins -- with the staging server acting as a plug-in repository. This is often called cloning. To do this, you need to:

1. Deploy and test the modules on a staging server.
2. Point a new Geronimo server instance to the staging server as a plug-in repository.
3. Select and install the plug-ins (modules) on the staging server that you want to install on the new server.
4. Repeat steps 2 and 3 until all new servers are cloned.

See the Staging a plug-in repository section for more information on the details of cloning setup.

System modules as plug-ins

Another type of plug-in is the Geronimo system module (or server component module). Geronimo system modules are software components that provide Geronimo with server features. They can contain additional server functionality, such as a Java implementation of the Universal Description, Discovery, and Integration (jUDDI) server or a Lightweight Directory Access Protocol (LDAP) server.

Little-G and on-demand server assembly

Geronimo users are often faced with the tough problem of selecting a suitable Geronimo server configuration (called assembly in Geronimo system developer lingo). With Geronimo 1.1, you can download either the full-fledged, everything-included server or Little-G, which only has the Web container. If you need the Web container plus the Derby RDBMS, you need to download the full-fledged server. However, this can result in a server configuration that's too big for your needs, consuming valuable disk space and memory resources at run time.

Plug-ins, together with the Little-G minimal-server distribution, are designed precisely to solve the above problem. Little-G with plug-ins provides end users with the same mix-and-match Geronimo server configurability that formerly only elite Geronimo contributors and system programmers had access to. With Geronimo plug-ins, you'll eventually be able to configure just enough server features for your specific needs and nothing more.

Working hands-on with Geronimo plug-ins

With a conceptual understanding of the Geronimo plug-in architecture, you're ready to work with a whole new world of available plug-ins. The following sections show where to find them and how to install and create them.

Searching repositories for available plug-ins

To search for available Geronimo plug-ins, you can use one of two tools:

• Command-line deployer
• Web console

Each of these tools can work as a plug-in installer. The plug-in installer performs the following:

1. Accesses one or more repository to determine the plug-ins available
2. Allows you to select an available plug-in to install
3. Examines the plug-in's metadata for dependencies and prerequisites
4. Verifies that prerequisites are satisfied
5. Downloads and installs dependencies
6. Installs and starts the plug-in

The command-line deployer is located in the bin subdirectory of your Geronimo installation in the deployer.jar file. In Geronimo 1.1, the deployer has a new search-plugins command (shown below). In reality, it's a search-and-install plug-in command, because it allows you to install any plug-in it finds in a repository.

This command displays a list of plug-ins available, similar to Figure 3.

To install any of the available plug-ins, just select the number corresponding to the plug-in, and the deployer does the rest.

As an alternative to the command-line deployer, you can search for plug-ins via the Web console, a Web application itself, via the URL http://localhost:8080/console/.

Under Plugins in the left navigation pane, click Create/Install. By default, the server comes without any Geronimo plug-in repository information, as shown in Figure 4.

However, you can get a list of default repositories by clicking the Update Repository List link. One of the most active publicly accessible repositories at this time is www.geronimoplugins.com. Figure 5 shows the list of updated available repositories.

After the list of repositories is populated, you can select one and click the Search for Plugins button to get a list of plug-ins available at the repository.

Figure 6 shows a typical list of plug-ins available at the www.geronimoplugins.com repository.

You can click any of the available plug-ins in Figure 6, and the Web console will download and install the plug-in.

Installing Geronimo plug-ins

Other than pulling plug-ins off repositories, you can also download plug-ins as individual .car or .zip archive files. When you have plug-ins downloaded as .zip (or .car) archives, you can install them using the command-line deployer's install-plugin command. The syntax is:

For example, if you have the Apache directory service plug-in in directory-1.1.zip, the command to install the plug-in is:

This starts the installation process, which can involve the download and installation of many required dependencies. When completed, the console output may be similar to Figure 7.

In Figure 7, you can see that the directory service plug-in installation has resulted in the automatic download and installation of 18 other dependency modules -- almost 5MB of additional modules. The plug-in mechanism can easily save you hours of downloads and deployment, not to mention time spent in configuration of modules.

Once installed, modules from Geronimo plug-ins are indistinguishable from modules that you deploy and configure manually. To undeploy any of them, use either the Web console or command-line deployer in the same manner you would with regular modules that you deploy.

The Download section contains a plug-in with an enterprise application that you can try installing on your own Geronimo server.

Creating your own Geronimo plug-in

Since plug-ins are modules + binary configuration + metadata, you must first deploy the module successfully in your server instance before you can create a plug-in out of it.

After you have the target plug-in module up and running, the easiest way to create a Geronimo plug-in is to use the Web console. You can do this using the Export Plugin feature of the Create/Install plug-in portlet.

Under Plugins in the left navigation pane, click Create/Install. Then, in the right navigation pane, select the module that you want to make into a plug-in. Figure 8 shows dw/bigpetstore/1.1/car as the module chosen to create a plug-in from.

Next, the portlet guides you to fill in many of the elements in the geronimo-plugin.xml file. Simply answer the questions and fill in the blanks. Make sure you specify all the dependencies you need to successfully deploy your module. In the case of dw/bigpetstore/1.1/car, the EJB container, geronimo/openejb//car, is required to work. Note that you can skip the version to indicate that the dependency is not version sensitive.

Geronimo 1.1 plug-in pitfalls There are several small bugs in Geronimo 1.1 that make working with plug-ins somewhat tricky: It's not possible to add a new repository to the repository list in the Web console. You must stop the server and edit the config.xml file, as shown in this article. The generated geronimo-plugins.xml file from the GeronimoAsMavenServlet may not have a valid default-repository list. The file name of the exported plug-in may be mangled with special characters. All of these bugs are slated to be fixed with an upcoming minor refresh of Geronimo.

Finally, click the Export Plugin button, and the portlet will create a car-exportX.X.car file. This is the plug-in in a CAR archive. The file can be downloaded by any compatible Geronimo server and installed (see the Geronimo 1.1 plug-in pitfalls sidebar).

If you unarchive the CAR file using the jar tool (jar xvf <archive name >), you can see its composition consists of:

• The binaries of the original module.
• A .ser file containing the configuration of the module in serialized binary format (and other support files, such as hash and info files).
• A META-INF/geronimo-plugin.xml file that contains the metadata required for the plug-in installer.

The information that you filled in while creating the plug-in is used to generate the geronimo-plugin.xml content. You can also create this file and the entire CAR manually. The geronimo-plugin.xml metadata file should contain one <geronimo-plugin> element. The details of this element are shown in Table 1.

Staging a plug-in repository

Staging a plug-in repository requires the setup of a Web server with a Maven 2 repository. Details of a full Maven 2 repository setup is beyond the scope of this article (see Resources for a link if you're interested in setting up your own repository). However, there are public Geronimo plug-in repositories that you can submit your plug-in creations to (see Resources for a link).

In addition to public Geronimo plug-in repositories, Geronimo comes with the ability to act as a Maven 2 repository and generate plug-in metadata dynamically -- on an on-demand basis. This generation of metadata, the content of the geronimo-plugins.xml file, is provided by a GeronimoAsMavenServlet (repository). This servlet essentially enables you to expose the installed components in a Geronimo server as plug-ins. This capability is implemented by a servlet in the console-standard application. To try generating the geronimo-plugins.xml file, use the URL http://localhost:8080/console-standard/maven-repo/geronimo-plugins.xml.

Here, the /maven-repo/* URL is mapped by the Web container to the GeronimoAsMavenServlet class in the console-standard Web application. The console-standard Web application is installed and running by default on a Geronimo server. It's part of the standard Web console implementation.

This automated generation of the geronimo-plugins.xml metadata is used in Geronimo server cloning, mentioned earlier.

To clone a newly installed server, go to the Web console's plug-in portlet, and then select the staging server as your repository, using the URL above (http://localhost:8080/console-standard/maven-repo/geronimo-plugins.xml) to get the staging server to generate its configuration as a list of plug-ins.

For Geronimo 1.1, the only way to add your own staging server to the repository list is to edit the config.xml file (see the sidebar Geronimo 1.1 plug-in pitfalls for more information). Remember that you must first stop the Geronimo server before editing config.xml because the server may write to it at any time. Edit the config.xml file, located under the var/config directory, to include the URL to the master server's GeronimoAsMavenServlet. Listing 1 shows the highlighted lines to add.

...
<gbean name="DownloadedPluginRepos">
  <attribute name="repositoryList">
  http://people.apache.org/~ammulder/plugin-repository-list-1.1.txt
  </attribute>
  
  <attribute name="userRepositories">
  [http://stagingserver:8080/console-standard/maven-repo/]
  </attribute>
  
</gbean>
 

If you're setting up a Maven 2 repository yourself, make sure that a geronimo-plugins.xml file is available at the root of the repository. The plug-in installer examines this file for available plug-ins and their metadata. The content of this file should be similar to Listing 2.

<?xml version="1.0" encoding="UTF-8" ?>
<geronimo-plugin-list
  xmlns="http://geronimo.apache.org/xml/ns/plugins-1.1">	
  <plugin>
   ...
  </plugin>
  <plugin>
   ...
  </plugin>
    ...	
  <plugin>
    ...
  </plugin>
  <default-repository>
    http://www.geronimoplugins.com/repository/geronimo-1.1
  </default-repository> 
  <default-repository>
    http://www.ibiblio.org/maven2/
  </default-repository> 
</geronimo-plugin-list>
 

In the geronimo-plugins.xml file above, each of the <plugin> elements should contain the description of a plug-in and all the subelements of the <geronimo-plugin> element, as detailed in Table 1. The <default-repository> entry points to repositories where these plug-ins and their dependencies can be downloaded. This default list of repositories should always include the name of the current repository -- the one you're setting up (unless the associated Maven repository is located somewhere else).

The future of Geronimo plug-ins

The ability to add preconfigured modules instantly to a running server is compelling. There's a lot of excitement building around this new feature in the Geronimo community. And whenever there is excitement among creative people, you can count on innovation and rapid evolution. The open source, widely accessible, and modify-at-will nature of the technology will likely expedite the adoption of this feature at rates not achievable by proprietary or more restrictively licensed servers.

Some of the more exciting upcoming possibilities include:

• The ability to upgrade the Little-G server distribution incrementally using plug-ins to EJB, EJB + ActiveMQ, EJB + Derby, EJB + ActiveMQ + Derby, and so on. This will allow users to install just enough server for their specific needs.
• Drop-in clustering capabilities, enabling a bank of Geronimo server instances to appear as a single super server.

Of course, there's no need to wait. With the information presented in this article, you stand ready to make creative use of plug-ins with your Geronimo installations!

Back to top

Download

	Information about download methods

Resources

• Get the details on how to set up Maven 2 repositories (the same as Geronimo plug-in repositories) at the official Maven 2 Web site.
  
  
• Submit your plug-in creations to public Geronimo plug-in repositories, such as the Geronimo Plugins site, which has a growing selection of system, application, open source, and commerical plug-ins that you can download and add to your Geronimo server immediately.
  
  
• The latest version of Geronimo is always available for download at the Apache Geronimo Web site.
  
  
• Read the developerWorks feature article "The Geronimo renegade: The Apache Geronimo of the future" (developerWorks, June 2006) for information on all the new features available in Geronimo 1.1.
  
  
• Check out the developerWorks Apache Geronimo project area for articles, tutorials, and other resources to help you get started developing with Geronimo today.
  
  
• Find helpful resources for beginners and experienced users at the Get started now with Apache Geronimo section of developerWorks.
  
  
• Check out the IBM® Support for Apache Geronimo offering, which lets you develop Geronimo applications backed by world-class IBM support.
  
  
• 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.
  
  
• Browse for books on these and other technical topics at the Safari bookstore.

• Download a free trial version of WebSphere Application Server, Version 6.0.
  
  
• Innovate your next open source development project with IBM trial software, available for download or on DVD.
  
  
• Download your free copy of IBM WebSphere® Application Server Community Edition V1.0 -- a lightweight J2EE application server built on Apache Geronimo open source technology that is designed to help you accelerate your development and deployment efforts.
  
  

• Participate in the discussion forum.
  
  
• Stay up to date on Geronimo developments at the Apache Geronimo blog.
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  

About the author

		Sing Li is a consultant and an active author with more than two decades of industry experience. He has contributed to Professional Apache Geronimo, Beginning JavaServer Pages, Professional Apache Tomcat 5, Pro JSP - Third Edition, Early Adopter JXTA, Professional Jini, Beginning J2ME: From Novice to Professional, Third Edition, Professional Apache Geronimo, and numerous other books. Sing also writes for technical magazines and participates in open source communities. He is an evangelist of the open source, VOIP, and P2P movements. You can reach Sing at westmakaha@yahoo.com.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Share this.... Digg this story del.icio.us Slashdot it!

Back to top