Apache Geronimo Plugins

Apache Geronimo 2.1 Quick Reference

Apache Geronimo is an open source application server that is suitable for use on everything from development environments to enterprise-level deployments. Geronimo brings together the best-of-breed open source technologies to deliver full Java EE 5 compliance. Distributed under the ASL2.0 license, one of the most liberal open source licenses, Geronimo becomes an application server of choice for enterprises and solution vendors.

This book provides the reader with a comprehensive reference to the Apache Geronimo Application Server from the Apache Server Foundation. The authors have provided a reference for the average Apache Geronimo user that provides the user with the steps required to configure anything and everything in Apache Geronimo. This book covers everything from where to download the server software to how to customize it using custom GBeans. After reading this book, the user will be familiar with most of the features of Apache Geronimo v2.1.

This book provides samples that are relevant to each task being performed. The book provides an in-depth coverage of the Apache Geronimo internals, in order for the user to be able to write custom services on Geronimo. There is also coverage of the Geronimo plugin architecture and how to extend the server functionality through plugins. The authors have made the different configuration items available as self contained chapters that can be referred to independently of the other chapters, so that readers can go straight to whatever part of Geronimo they want to configure.

What This Book Covers

Chapter 1: Introduction - This chapter introduces the reader to the Apache Geronimo Application Server, lists the features that it provides, and the steps that the user has to follow in order to download, install, and start the server.

Chapter 2: Architecture - This chapter gives a high-level overview of the Geronimo architecture. It introduces the reader to the concepts of GBeans, Geronimo Plugins, and the different subsystems of Geronimo.

Chapter 3: Database connectivity - This chapter talks about Geronimo's database connectivity features. It lists the databases supported, and explains how to create database pools and establish connectivity with all of the supported databases using Geronimo.

Chapter 4: JMS - This chapter details the messaging features that Geronimo provides, and guides the user through using the bundled JMS provider, ActiveMQ, to create and use JMS resources.

Chapter 5: Java EE Application deployment - This chapter details the installation of different types of Java EE applications and modules and application clients. It guides users through writing deployment plans for these different Java EE artifacts. This chapter also covers the transaction support provided by Geronimo.

Chapter 6: Security - This chapter takes the user through configuring security in order to secure the server environment and the applications running in Geronimo.

Chapter 7: CORBA - This chapter covers configuring the EJBs running in Geronimo so that they are available through CORBA, and also covers configuring remote EJB references to invoke remote EJBs through CORBA.

Chapter 8: JNDI - This chapter describes the different JNDI environments in Geronimo, gives the steps necessary to bind custom resources to JNDI by using GBeans, and shows us how the global JNDI environment can be leveraged for user's applications.

Chapter 9: Plugins - This chapter educates the user in creating and deploying Geronimo plugins, creating custom server assemblies, and extending Administration Console through plugins.

Chapter 10: Administration - This chapter walks the user through the common administration tasks, such as managing server components, application management, monitoring, working with keystores, and GShell.

Chapter 11: Eclipse Plugin - This chapter introduces the Geronimo Eclipse Plugin (GEP) and explains how to obtain and install it. It takes the user through the various features of the GEP and shows how to develop a sample application by using the Geronimo Eclipse Plugin.

Chapter 12: Clustering - This chapter covers how to configure horizontal and vertical clustering using Geronimo, demonstrates web application clustering using WADI, and explains how to configure load balancing by using the Apache Web Server and mod_jk plugin.

Chapter 13: Logging - This chapter covers all of the configurations required for setting up logging for both the server and user applications. It covers logging frameworks such as log4j JUL, and so on, and the SLF4j wrapper that comes with Geronimo.

Chapter 14: Geronimo Internals – This chapter introduces the user to the internals of Geronimo and the low-level services such as kernel, server info, configuration manager, and so on. It takes the user through developing and deploying new services through GBeans.

Appendix-A: Deployment plans – This appendix covers elements common to all Geronimo deployment plans.

Appendix-B: Troubleshooting – This appendix covers troubleshooting server startup, application deployment, application startup, and runtime problems.

Geronimo Plugins

Apache Geronimo provides a mechanism for users to extend its functionality through plugins. In this chapter, we will explore how to extend the functionality of Apache Geronimo, by using Geronimo plugins. In fact, all of the Java EE functionality in Apache Geronimo is installed as plugins. For example, the web services functionality is provided through the Axis, Axis2, and CXF plugins. EJB functionality is provided through the OpenEJB plugin, and so on. Therefore, if you want to extend the server to provide new functionality, such as job scheduling, then you can write a plugin to integrate a scheduler (such as Quartz) into Apache Geronimo. There are also a large number of plugins available for Apache Geronimo already. We will also cover the custom server assemblies feature in this chapter. This feature will enable you to export custom server assemblies, from either the server's Administration Console or the command-line shell. In this chapter, you will learn about:

• Developing and installing Apache Geronimo plugins
• Extending the Administration Console through plugins
• Creating custom server assemblies

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
Module

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/App.java
• src/test/java/com/packt/plugins/AppTest.java

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="http://maven.apache.org/POM/4.0.0"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
		http://maven.apache.org/maven-v4_0_0.xsd">
		<modelVersion>4.0.0</modelVersion>
		<groupId>com.packt.plugins</groupId>
		<artifactId>WorldClockModule</artifactId>
		<packaging>jar</packaging>
		<version>1.0-SNAPSHOT</version>
		<name>WorldClockModule</name>
		<url>http://maven.apache.org</url>
		<dependencies>
			<dependency>
				<groupId>junit</groupId>
				<artifactId>junit</artifactId>
				<version>3.8.1</version>
				<scope>test</scope>
			</dependency>
			<dependency>
				<groupId>org.apache.geronimo.framework</groupId>
				<artifactId>geronimo-kernel</artifactId>
				<version>2.1.4</version>
			</dependency>
		</dependencies>
	</project>

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();
	}
and
	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.
			getTimeZone(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)?
				"AM":"PM"));
		}
		public void setTimeZone(String timeZone) {
			this.timeZone = timeZone;
		}
		public ClockGBean(String name){
			this.name = name;
			timeZone = TimeZone.getDefault().getID();
		}
		public void doFail() {
			System.out.println("Failed.............");
		}
		public void doStart() throws Exception {
			System.out.println("Started............"+name+" "+getTime());
		}
		public void doStop() throws Exception {
			System.out.println("Stopped............"+name);
		}
		  static {
			GBeanInfoBuilder infoFactory = GBeanInfoBuilder.createStatic
				("ClockGBean",ClockGBean.class);
			infoFactory.addAttribute("name", String.class, true);
			infoFactory.addInterface(Clock.class);
			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. Refer to Chapter 14, Geronimo Internals, for more detailed explanations on writing your own GBeans. 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:

	<module>
		<groupId>com.packt.plugins</groupId>
		<artifactId>WorldClockModule</artifactId>
		<version>1.0</version>
		<type>jar</type>
	</module>

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="http://geronimo.apache.org/xml/ns/deployment-1.2">
		<environment>
			<moduleId>
				<groupId>com.packt.plugins</groupId>
				<artifactId>WorldClock</artifactId>
				<version>1.0</version>
				<type>car</type>
			</moduleId>
			<dependencies/>
			<hidden-classes/>
			<non-overridable-classes/>
			<private-classes/>
		</environment>
		<gbean name="ClockGBean" class="com.packt.clock.ClockGBean">
			<attribute name="name">ClockGBean</attribute>
		</gbean>
	</module>

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 WorldClock-1.0- SNAPSHOT.car 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.