Geronimo Plugins

Developing a plugin

In this section, we will develop our very own plugin, the World Clock plugin. This is a very simple plugin that provides the time in different locales. We will go through all of the steps required to develop it from scratch. These steps are as follows:

  • Creating the plugin project
    • Generating the plugin project, using maven2
    • Writing the plugin interface and implementation
    • Creating a deployment plan
  • Installing the plugin

Creating a plugin project

There are many ways in which you can develop plugins. You can manually create all of the plugin artifacts and package them. We will use the easiest method, that is, by using Maven's geronimo-plugin-archetype. This will generate the plugin project with all of the artifacts with the default values filled in.

To generate the plugin project, run the following command:

mvn archetype:create -DarchetypeGroupId=org.apache.geronimo.buildsupport 
-DarchetypeArtifactId=geronimo-plugin-archetype -DarchetypeVersion=2.1.4
-DgroupId=com.packt.plugins -DartifactId=WorldClock

This will create a plugin project called WorldClock. A directory called WorldClock will be created, with the following artifacts in it:

  • pom.xml
  • pom.sample.xml
  • src/main/plan/plan.xml
  • src/main/resources

In the same directory in which the WorldClock directory is created, you will need to create a java project that will contain the source code of the plugin. We can create this by using the following command:

mvn archetype:create -DgroupId=com.packt.plugins -DartifactId=WorldClock

This will create a java project with the same groupId and artifactId in a directory called WorldClockModule. This directory will contain the following artifacts:

  • pom.xml
  • src/main/java/com/packt/plugins/
  • src/test/java/com/packt/plugins/

You can safely remove the second and third artifacts, as they are just sample stubs generated by the archetype.

In this project, we will need to modify the pom.xml to have a dependency on the Geronimo kernel, so that we can compile the GBean that we are going to create and include in this module. The modified pom.xml is shown below:

<project xmlns="" 

For simplicity, we have only one GBean in our sample. In a real world scenario, there may be many GBeans that you will need to create. Now we need to create the GBean that forms the core functionality of our plugin. Therefore, we will create two classes, namely, Clock and ClockGBean. These classes are shown below:

package com.packt.plugins;
import java.util.Date;
import java.util.Locale;
public interface Clock {
public void setTimeZone(String timeZone);
public String getTime();


package com.packt.plugins;
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.Calendar;
import java.util.Date;
import java.util.GregorianCalendar;
import java.util.Locale;
import java.util.TimeZone;
import org.apache.geronimo.gbean.GBeanInfo;
import org.apache.geronimo.gbean.GBeanInfoBuilder;
import org.apache.geronimo.gbean.GBeanLifecycle;
import sun.util.calendar.CalendarDate;
public class ClockGBean implements GBeanLifecycle, Clock{
public static final GBeanInfo GBEAN_INFO;
private String name;
private String timeZone;
public String getTime() {
GregorianCalendar cal = new GregorianCalendar(TimeZone.
int hour12 = cal.get(Calendar.HOUR); // 0..11
int minutes = cal.get(Calendar.MINUTE); // 0..59
int seconds = cal.get(Calendar.SECOND); // 0..59
boolean am = cal.get(Calendar.AM_PM) == Calendar.AM;
return (timeZone +":"+hour12+":"+minutes+":"+seconds+":"+((am)?
public void setTimeZone(String timeZone) {
this.timeZone = timeZone;
public ClockGBean(String name){ = name;
timeZone = TimeZone.getDefault().getID();
public void doFail() {
public void doStart() throws Exception {
System.out.println("Started............"+name+" "+getTime());
public void doStop() throws Exception {
static {
GBeanInfoBuilder infoFactory = GBeanInfoBuilder.createStatic
infoFactory.addAttribute("name", String.class, true);
infoFactory.setConstructor(new String[] {"name"});
GBEAN_INFO = infoFactory.getBeanInfo();
public static GBeanInfo getGBeanInfo() {
return GBEAN_INFO;

As you can see, Clock is an interface and ClockGBean  is a GBean that implements this interface. The Clock interface exposes the functionality that is provided by the ClockGBean. The doStart(),   doStop(), and doFail()  methods are provided by the GBeanLifeCycle interface, and provide lifecycle callback functionality. The next step is to run Maven to build this module. Go to the command prompt, and change the directory to the WorldClockModule directory. To build the module, run the following command:

mvn clean install

Once the build completes, you will find a WorldClockModule-1.0-SNAPSHOT.jar in the WorldClockModule/target directory.

Now change the directory to WorldClock, and open the generated pom.xml file. You will need to uncomment the deploymentConfigs for the gbeanDeployer, and add the following module that you want to include in the plugin:


You will notice that we are using the car-maven-plugin in the pom.xml file. The car-maven-plugin is used to build Apache Geronimo configuration archives without starting the server.

The final step is to create the deployment plan in order to deploy the module that we just created into the Apache Geronimo server. This deployment plan will be used by the car-maven-plugin to actually create the artifacts that will be created during deployment to Apache Geronimo. The deployment plan is shown below:

<module xmlns="">
<gbean name="ClockGBean" class="com.packt.clock.ClockGBean">
<attribute name="name">ClockGBean</attribute>

Once the plan is ready, go to the command prompt and change the directory to the WorldClock directory. Run the following command to build the plugin:

mvn clean install

You will notice that the car-maven-plugin is invoked and a file is created in the WorldClock/target directory. We have now completed the steps required to create an Apache Geronimo plugin. In the next section, we will see how we can install the plugin in Apache Geronimo.

Installing a plugin

We can install a plugin in three different ways. One way is to   use the deploy.bat or script, another way is to use the install-plugin command in GShell, and the third way is to use the Administration Console to  install a plugin from a plugin repository. We will discuss each of these methods:

  • Using deploy.bat or file:

    The deploy.bat or script is found in the <GERONIMO_HOME>/bin directory. It has an option install-plugin, which can be used to install plugins onto the server. The command syntax is shown below:

    deploy install-plugin <path to the plugin car file>

    Running this command, and passing the path to the plugin .car archive on the disk, will result in the plugin being installed onto the Geronimo server. Once the installation has finished, an Installation Complete message will be displayed, and the command will exit.

  • Using GShell:

    Invoke  the gsh command from the command prompt, after changing the current directory to <GERONIMO_HOME>/bin. This will bring up the GShell prompt. In the GShell prompt, type the following command to install the plugin:

    deploy/install-plugin <path to the plugin car file>

    Please note that, you should escape special characters in the path by using a leading "" (back slash) before the character.

    Another way to install plugins that are available in remote plugin repository is by using the list-plugins command. The syntax of this command is as given below:

    deploy/list-plugins <URI of the remote repository>

    If a remote repository is not specified, then the one configured in Geronimo will be used instead. Once this command has been invoked, the list of available plugins in the remote repository is shown, along with their serial numbers, and you will be prompted to enter a comma separated list of the serial numbers of the plugins that you want to install.

  • Using the Administration Console:

    The Administration Console has a Plugins portlet that can be used to list the plugins available in a repository specified by the user. You can use the Administration Console to select and install the plugins that you want from this list. This portlet also has the capability to export applications or services in your server instance as Geronimo plugins, so that they can be installed on other server instances. See the Plugin portlet section for details of the usage of this portlet.

Available plugins

The  web  site hosts Apache Geronimo plugins. It has many plugins listed for Apache Geronimo. There are plugins for Quartz, Apache Directory Server, and many other popular software packages. However, they are not always available for the latest versions of Apache Geronimo. A couple of fairly up-to-date plugins that are available for Apache Geronimo are the Windows Service Wrapper plugin and the Apache Tuscany plugin for Apache Geronimo. The Windows Service Wrapper provides the ability for Apache Geronimo to be registered as a windows service. The Tuscany plugin is an implementation of the SCA Java EE Integration specification by integrating Apache Tuscany as an Apache Geronimo plugin. Both of these plugins are available from the Apache Geronimo web site.

Pluggable Administration Console

Older versions of Apache Geronimo came with a monolithic Administration Console. However, the server was extendable through plugins. This introduced a problem: How to administer the new plugins that were added to the server? To resolve this problem, the Apache Geronimo developers rewrote the Administration Console to be extensible through console plugins called Administration Console Extensions. In this section, we will look into how to create an Administration Console portlet for the World Clock plugin that we developed in the previous section.


The pluggable Administration Console functionality is based on the support provided by the Apache Pluto portlet container for dynamically adding and removing portlets and pages without requiring a restart. Apache Geronimo exposes this functionality through two GBeans, namely, the Administration Console Extension (ACE) GBean  (org.apache.geronimo.pluto.AdminConsoleExtensionGBean) and the Portal Container Services GBean (org.apache.geronimo.pluto. PortalContainerServicesGBean). The PortalContainerServicesGBean exposes the features of the Pluto container in order to add and remove portlets and pages at runtime. The ACE GBean invokes these APIs to add and remove the portlets or pages. The  ACE GBean should be specified in the Geronimo-specific deployment plan of your web application or plugin, that is, geronimo-web.xml. The architecture is shown in the following figure:

Apache Geronimo 2.1: Quick Reference

Developing an Administration Console extension

We will now go through the steps to develop an Administration Console Extension for the World Clock plugin that we created in the previous section.

  1. We will use Maven WAR archetype to create a web application project. To create the project, run the following command from the command-line console:

    mvn archetype:create -DgroupId=com.packt.plugins -
    DartifactId=ClockWebApp -DarchetypeArtifactId=maven-archetype-

    This will result in the Maven web project being created, named ClockWebApp.

  2. A default pom.xml will be created. This will need to be edited to add dependencies to the two modules, as shown in the following code snippet:


    We add these dependencies because the portlet that we are going to write will use the classes mentioned in the above two modules.

  • In the src/main/java directory, add the class ClockPortlet shown below, and create the corresponding package directory structure.

    package com.packt.plugins;
    import java.util.Date;
    import java.util.TimeZone;
    import javax.portlet.GenericPortlet;
    import javax.portlet.PortletException;
    import javax.portlet.RenderRequest;
    import javax.portlet.RenderResponse;
    import org.apache.geronimo.kernel.GBeanNotFoundException;
    import org.apache.geronimo.kernel.InternalKernelException;
    import org.apache.geronimo.kernel.Kernel;
    import org.apache.geronimo.kernel.KernelRegistry;
    * This portlet displays time from the WorldClock GBean
    public class ClockPortlet extends GenericPortlet {
    // called when user clicks on this portlets link
    public void doView(RenderRequest request, RenderResponse
    throws PortletException, IOException {
    // Set the response to read HTML
    // Get the writer to the response
    PrintWriter out = response.getWriter();
    Kernel kernel = KernelRegistry.getSingleKernel();
    try {
    Clock cl = (Clock)kernel.getGBean("ClockGBean");
    String[] ids = TimeZone.getAvailableIDs();
    for(int i=0;i<ids.length;i++){
    } catch (GBeanNotFoundException e) {
    } catch (InternalKernelException e) {
    } catch (IllegalStateException e) {

    This class gets the kernel from the KernelRegistry and then gets the ClockGBean. It then proceeds to invoke the setTimeZone and getTime methods for all available time zones and prints them to the response.

  • In the src/main/webapp/WEB-INF directory, we create the web.xml, geronimo-web.xml, and portlet.xml files, as shown below:

  • In the web.xml file shown above, we configure org.apache.pluto.core.PortletServlet at the URL /PlutoInvoker/WorldClockPortlet with the portlet-name parameter set to the name of the portlet that we created, namely, WorldClockPortlet. This should be the same as the portlet-name that we specify in the portlet.xml file.

    The deployment plan geronimo-web.xml is shown below:

    <web-app xmlns="">
    <!-- This is where the files are accessed from. (aka -
    portletContext) -->
    <!-- Start off a ACEGBean, this is the lifecycle for the
    portlet -->
    <gbean name="PlutoTest" class="org.apache.geronimo.pluto.
    <attribute name="pageTitle">World Clock</attribute>
    <attribute name="portletContext">/WorldClockPortlet
    <attribute name="portletList">[WorldClockPortlet]
    <reference name="PortalContainerServices">

    In  the geronimo-web.xml file, we add dependencies to the pluto-support plugin and the World Clock plugin, as both of these will be used by our portlet. The Pluto-support plugin will provide the Pluto functionality, as well as both the ACE GBean and PortalContainerServicesGBean. We also specify an instance of the ACE GBean to start with this web module so that it can add the portlets to the Administration Console. We specify three attributes, namely, pageTitle, portletContext, and portletList, which specify the page title, portlet context, and the portlets that this GBean is going to add to the Administration Console, respectively. We also add a reference to the PortalContainerServicesGBean.

  • Finally, we create a portlet.xml file, as shown below, which specifies the portlet mode, title, and name.

    <description>Clock Plugin portlet</description>
    <display-name>World Clock Portlet</display-name>
    <supports> <!-- Defines which views are available
    [view,edit,help] -->
    <title>World Clock Portlet</title>

    Ensure that the portlet-name matches the one in web.xml.

  • Once you have created these files, build the web application by invoking the following command from the ClockWebApp directory:

    mvn clean install
  • Deploy the WAR file created to the Apache Geronimo server where you had previously deployed the World Clock plugin.

  • Once you log in to the Administration Console, you will notice a World Clock link at the bottom of the console navigation menu in the Other section. Clicking on it will bring up the page shown in the following screenshot:

    Apache Geronimo 2.1: Quick Reference

    Plugins portlet

    The Plugins portlet enables a user to dynamically install new features into the Geronimo server, create plugins out of existing configurations on the server, and create server assemblies consisting of some or all of the existing plugins in the server. By using the Install Geronimo Plugins section, you can search for plugins in a plugin repository or add new repositories for plugin searches. You can also download running configurations from another Geronimo server, just as if you're browsing and installing third-party plugins by using the repository URL http://remote-geronimo-server:8080/plugin/maven-repo/ and providing the administrator username and password.

    In order to search for plugins, select the repository URL, and click on Show Plugins in selected repository. This will show all of the available plugins in that repository, as shown in the next screenshot:

    Apache Geronimo 2.1: Quick Reference

    A check mark in the Installable column for the plugin name indicates that the plugin is installable. You can click on the plugin name to view the details of the plugin. You can select one or more plugins, and click on Install to install the plugins. The portlet will show the status as the plugins are installing and display a confirmation message once completed.

    The Create Geronimo Plugin section lets you create a new plugin out of an existing configuration on the server. Select the configuration to be exported as a plugin, and click on the Export Plugin button. On the next page, you can fill in various details, such as Download Repositories that need to be looked in for downloading Dependencies, a Description of the plugin, the Geronimo Versions on which the plugin can be installed, JVM versions, the dependencies of this plugin on other configurations or artifacts, Prerequisite configurations, and so on. The fields have detailed explanation on this page. After completing the fields, click on Save Plugin Data. On the next screen, click on the Export Plugin button to save the plugin to filesystem. The configuration will be saved as a configuration archive (CAR) file.

    Custom server assemblies and server profiles

    Apache Geronimo provides a feature known as custom server assemblies. This allows users to assemble servers that are customized to their needs. They can assemble the application servers that contain their applications or plugins prepackaged with only the additional dependent modules that their applications or plugins require. We will go through the steps to assemble a custom server that contains the World Clock plugin as follows:

    1. Log in to the Administration Console, and go to the Plugins portlet.
    2. In the Assemble Server portlet, click on the Assemble a server button. This will bring up the screen shown in the following screenshot:
      Apache Geronimo 2.1: Quick Reference
    3. Enter the groupId, artifactId, version, and the target path where the assembly should be saved under the <GERONIMO_HOME> directory, and select the required format. Select the plugins that need to be included in the assembly, and click on the Assemble  button. Always select Geronimo Assemblies :: Boilerplate Minimal. Select the WorldClock plugin. The WorldClock plugin does not need any other Apache Geronimo's services, so we need not include any other assemblies.
    4. Click on the Assemble button at the bottom of the screen. This will bring up the screen shown in the next screenshot:
      Apache Geronimo 2.1: Quick Reference
    5. Click on the Assemble button to assemble the custom server. Once the server assembly process is complete, a screen with the status and the location of the created assembly will pop up.
    6. Now stop the current server, and start the server you just assembled. You will see that the WorldClock plugin is started, as the time will be printed out during startup. You can also assemble custom servers through deploy/assemble command in GShell.


    In this article, we saw how Apache Geronimo's plugin architecture provides the capability for users to extend the functionality of the server. We saw how we can develop a plugin and deploy it to the server. We also had a look at the pluggable administration console, and how to create and plug in a new Administration Console portlet. We also saw how Apache Geronimo allows users to export custom server assemblies. In conclusion, Apache Geronimo turns out to be a very modular, customizable, and flexible application server. In the next chapter, we will see how we can administer Apache Geronimo. We will look into administering the different resources, plugins, and applications that are deployed on the server, as well as other server configuration options.

    If you have read this article you may be interested to view :

    You've been reading an excerpt of:

    Apache Geronimo 2.1: Quick Reference

    Explore Title