JBoss to Geronimo - Security Migration

Migrating to Apache Geronimo

JBoss to Geronimo - Web Services Migration

In this article will help you migrate servlets and JSPs deployed JBoss v4.0.5 to Apache Geronimo v1.1. This article is part of a series of migration articles covering different types of applications migration.

This article covers the migration of one of the most fundamental aspects of J2EE; servlets and JSPs. The sample application used for this migration exercise is College Fest which just contains servlets and JSPs for handling the flow of control. The College Fest sample application does not use any database, for details on migrating JDBC applications refer to the JBoss to Geronimo - JDBC Migration article.

After reading this article you should be able to reconfigure the JBoss build files and the deployment descriptors to set up the Apache Geronimo destination environment and then deploy simple Web applications.

This article is organized in the following sections:

• Servlets and JSPs implementation analysis
• Sample application
• The JBoss environment
• The Geronimo environment
• Step-by-step migration
• Summary

Servlets and JSPs implementation analysis

Servlets and JSPs implementations may vary from one application server to another. The purpose of this section is to provide servlets and JSPs specific feature-to-feature comparison between JBoss and Apache Geronimo so you can clearly identify the differences and plan accordingly before migration.

Apache Geronimo includes a Web application container supporting J2EE Web applications. The Web container itself supports basic configuration such as network ports and SSL options, and each Web application may include Geronimo-specific configuration information as well. Web applications participate in the Geronimo security infrastructure, so authenticating to a Web application allows access to secure EJBs and Connectors as well.

Apache Geronimo currently supports two Web containers: Jetty and Tomcat.

Jetty

Jetty is a 100% Java HTTP Server and Servlet Container. This means that you do not need to configure and run a separate Web server in order to use servlets and JSPs to generate dynamic content. Jetty is a fully featured Web server for static and dynamic content.

Unlike separate server/container solutions, Jetty's Web server and Web application run in the same process without interconnection overheads and complications. Furthermore, as a pure Java component, Jetty can be easily included in your application for demonstration, distribution or deployment. Jetty is available on all Java supported platforms.

In Geronimo, you need to explicitly configure the pathways used by browsers attempting to connect to the Web container. In the case of Jetty, the default Web container, these pathways are known as connectors. The standard configuration includes a Jetty connector supporting HTTP on port 8080, as well as a HTTPS connector on port 8443.

Each Jetty connector is a GBean, so the process of configuring a Jetty connector involves configuring a GBean.

Apache Tomcat

Apache Tomcat is the servlet container that is used in the official Reference Implementation for the Java Servlet and JavaServer Pages technologies.

http://java.sun.com/products/servlet
http://java.sun.com/products/jsp

The differences

JBoss v4.0.5 supports only Tomcat v5.5, which is the default Web container. The embedded Tomcat service is the expanded SAR jbossweb-tomcat55.sar in the <jboss_home>/deploy directory. The web.xml file that provides a default configuration set for Web application is also found in this exapanded SAR directory structure.

The HTTP connector is set up on port 8080 and port 8009 is used if you want to connect via a separate Web server such as Apache HTTP.

In addition to the default Web container, the second major difference lies in the deployment plan. A deployment plan in Geronimo is similar to a both J2EE deployment descriptor and a Maven 2 build file in the sense that it is an XML file that contains the configuration information for a specific application module or service.

For extremely simple Web applications with no security or resource references, a Geronimo deployment plan is not required, a default context root and dependencies will be provided automatically at deployment time.

The Geronimo Web application deployment plan is geronimo-web.xml. The corresponding deployment descriptor in JBoss is jboss-web.xml.

Another difference with servlets and JSPs lies in the way the Web application is deployed. In Geronimo, the application package (ear, war, rar or jar) can be deployed either using the Geronimo console, deployer tool or hot deployment.

1. Geronimo application server comes with a sophisticated web console, which can be used to deploy application packages.
2. Deployer tool which can be found under <geronimo_home>/bin folder is another option the user can use to deploy their applications.
3. Geronimo also supports hot deployment facility. Copying your applications into the <geronimo_home>/deploy folder will automatically deploy the applications.

In contrast, a JBoss user has only one option of deploying package (ear, war, rar or jar) into the <jboss_home>/server/<your_server_name>/deploy directory from where the server detects its presence and deploys it accordingly.

The following table summarizes the differences between JBoss and Geronimo.

Sample application

The College Fest application handles registration for events at a college festival. This is an extremely simple application that does not use any type of database. The College Fest application has the following four pages:

• Welcome page
• Event List page
• Event Details page
• Registration page

The following figure illustrates the application flow:

Application classes and JSP pages

The College Fest sample application consists of the following two servlets:

• org.apache.geronimo.samples.college.web
  • WelcomeServlet - Handles user login and then grabs the user name and dispatches this to the next servlet.
  • PersonalServlet - Personalizes the page for the user and hands over control to welcome.jsp.

The College Fest sample application also includes the following JSP pages:

• welcome.jsp - Displays the events list to the user so that s/he can choose the event to register.
• dc.jsp - Displays the details for the Dumb Charades event.
• pp.jsp - Displays the details for the Pot Potpourri event.
• wtgw.jsp - Displays the details for the What's The Good Word event.
• gq.jsp - Displays the details for the General Quiz event.
• team_reg.jsp - Handles the user registration for one event.

Tools Used

The tools used for developing and building the College Fest sample application are:

Eclipse

The Eclipse IDE was used for development of the sample application. This is a very powerful and popular open source development tool. Integration plug-ins are available for both JBoss and Geronimo. Eclipse can be downloaded from the following URL:
http://www.eclipse.org

Apache Ant

Ant is a pure Java build tool. It is used for building the war files for the College Fest application. Ant can be downloaded from the following URL:
http://ant.apache.org

Back to Top

The JBoss enviroment

This section shows you how and where the sample JBoss reference environment was installed so you can map this scenario to your own implementation.

Detailed instructions for installing, configuring, and managing JBoss are provided in the product documentation. Check the product Web site for the most updated documents.

The following list highlights the general tasks you will need to complete to install and configure the initial environment as the starting point for deploying the sample application.

1. Download and install JBoss v4.0.5 as explained in the product documentation guides. From now on the installation directory will be referred as <jboss_home>
2. Create a copy of the default JBoss v4.0.5 application server. Copy recursively <jboss_home>/server/default to <jboss_home>/server/<your_server_name>
3. Start a new server by running the run.sh -c <your_server_name> command from the <jboss_home>/bin directory.
4. Once the server is started, you can verify that it is running by opening a Web browser and pointing it to this URL: http://localhost:8080. You should see the JBoss Welcome window and be able to access the JBoss console.
5. Once the application server is up and running, the next step is to install and configure all the remaining pre-requisite software required by the sample application. This step is described in the following section.

As mentioned before, Apache Ant is used to build the binaries for the College Fest application. If you do not have Ant installed this is a good time for doing it and make sure that <ant_home>\bin directory is added to the system's path variable.

Apache Ant can be downloaded from the following URL:
http://ant.apache.org

Build the sample application

The College Fest application included with this article provides an Ant script that you will use in order to build the application. Download the College Fest application from the following link:
College Fest

After extracting the zip file, a college_fest directory is created. Open the config/build.properties file and edit the properties to match your environment as shown in the following example:

## Replace with Geronimo home directory
geronimo.home=<geronimo_home>

This build script depends on Geronimo v1.1 or later version

In the college_fest directory you can find build.xml which has the build information for the both JBoss and Geronimo version of sample application. For this particular sample application the use the jboss target.

From command line, still within the college_fest directory type the following command:

ant jboss

With this command, Ant will use the targets defined in build.xml file to build the College Fest application for the JBoss server. The following example shows the definitions in build.xml file.

<?xml version="1.0"?>
<!-- ====================================================================== 
     JBoss to Geronimo Migration Samples
     ====================================================================== -->
<project name="College" default="all">
	<property name="src.dir" value="src"/>
	<property name="dest.dir" value="releases"/>
	<property name="web.dir" value="web"/>
	<property name="config.dir" value="config"/>
	
	<property file="${config.dir}/build.properties"/>
	
	<target name="all" depends="geronimo,jboss">
		<!-- Delete whole file structure -->
		<delete dir="${dest.dir}/war"/> 	
	</target>
	
	<target name="compile-geronimo" depends="init">
		<copy todir="${dest.dir}/war/geronimo">
			<fileset dir="${web.dir}"/>
		</copy>
		
		<!-- Delete unnecessary file for Geronimo deployment from WAR file -->
		<delete file="${dest.dir}/war/geronimo/WEB-INF/jboss-web.xml"/>
		
		<mkdir dir="${dest.dir}/war/geronimo/WEB-INF/classes"/>
		<javac srcdir="${src.dir}"
			destdir="${dest.dir}/war/geronimo/WEB-INF/classes">
			<classpath
				path=
"${geronimo.home}/repository/org/apache/geronimo/specs/geronimo-j2ee_1.4_spec/1.1/geronimo-j2ee_1.4_spec-1.1.jar"/>
		</javac>
	</target>
	
	<target name="compile-jboss" depends="init">
		<copy todir="${dest.dir}/war/jboss">
			<fileset dir="${web.dir}" />
		</copy>
        
		<!-- Delete unnecessary file for JBoss deployment from WAR file -->
		<delete file="${dest.dir}/war/jboss/WEB-INF/geronimo-web.xml"/>
		
		<mkdir dir="${dest.dir}/war/jboss/WEB-INF/classes"/>
		<javac srcdir="${src.dir}"
			destdir="${dest.dir}/war/jboss/WEB-INF/classes">
			<classpath
				path=
"${geronimo.home}/repository/org/apache/geronimo/specs/geronimo-j2ee_1.4_spec/1.1/geronimo-j2ee_1.4_spec-1.1.jar"/>
		</javac>
	</target>

    <target name="geronimo" depends="compile-geronimo">
	  <jar destfile="${dest.dir}/geronimo/college_fest.war">
			<zipfileset dir="${dest.dir}/war/geronimo"/>
	   </jar>
    </target>
	
	<target name="jboss" depends="compile-jboss">
	  	<jar destfile="${dest.dir}/jboss/college_fest.war">
			<zipfileset dir="${dest.dir}/war/jboss"/>
		</jar>	
	</target>
	
	<target name="init">
		<mkdir dir="${dest.dir}/war"/>
	   	<mkdir dir="${dest.dir}/war/geronimo"/>
	   	<mkdir dir="${dest.dir}/war/jboss"/>
	   	<mkdir dir="${dest.dir}/geronimo"/>
		<mkdir dir="${dest.dir}/jboss"/>
	</target>	

</project>

The war created by the ant build contains a JBoss specific deployment descriptor, the jboss-web.xml file in the WEB-INF directory of the WAR is shown in the following example.

<?xml version="1.0" encoding="UTF-8"?>

<jboss-web>
    <context-root>college_fest</context-root>
</jboss-web>

Deploy the sample application

The previous step showed how to build the application using Ant. It will create college_fest.war file in the college_fest/releases/jboss directory. To deploy the College Fest application in JBoss, copy the college_fest.war file you just built with Ant to the following directory:

<jboss_home>/server/<your_server_name>/deploy

If JBoss is already started, it will automatically deploy and start the application; otherwise, the application will be deployed and started at the next startup.

Testing the application

To test the application, open a Web browser and access the following URL:

http://localhost:8080/college_fest

You should see the Welcome screen where you can login with your name and college. When you enter your name, a college and click Submit you will see a message at the end on the page stating your name with a link to "Click here" to enter the site. Browse the site and check the options, at this point the College Fest application is configured and running.

Back to Top

The Geronimo enviroment

Download and install Geronimo from the following URL:

http://geronimo.apache.org/downloads.html

The release notes available there provide clear instructions on system requirements and how to install and start Geronimo. Throughout the rest of this article we will refer to the Geronimo installation directory as <geronimo_home>.

TCP/IP ports conflict If you are planning to run JBoss and Geronimo on the same machine consider to change the default service ports on, at least, one of these servers.

Back to Top

Step-by-step migration

In order to migrate the College Fest application to Geronimo you need to replace the jboss-web.xml file with a geronimo-web.xml file which is the Geronimo specific descriptor file. The geronimo-web.xml file is located in the WEB-INF directory withing the college_fest directory structure. The Geronimo deployment plan geronimo-web.xml is illustrated in the following example.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1" xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1">
  <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1">
    <dep:moduleId>
      <dep:groupId>org.apache.geronimo.samples</dep:groupId>
      <dep:artifactId>college_fest</dep:artifactId>
      <dep:version>1.0</dep:version>
      <dep:type>car</dep:type>
    </dep:moduleId>
    <dep:dependencies/>	
    <dep:hidden-classes/>
    <dep:non-overridable-classes/>
  </dep:environment>
  <context-root>/college_fest</context-root> 
</web-app>

Given that College Fest is a very simple application, the Geronimo deployment plan will also be very simple. Remember that this application does not use any database access nor has security configured. While reading other articles in the JBoss to Geronimo migration series, you will notice how the complexity of the deployment plan increases as the sample applications for the different migration scenarios also grow in complexity.

Last time you built the College Fest sample application it was configured for ant to use the jboss-war target. To Geronimo specific building for the sample application use geronimo target providing ant geronimo in a command prompt. It will create college_fest.war file under the college_fest/releases/geronimo folder.

Deploy the migrated sample application

Deploying sample application is pretty straight forward as we are going to use the Geronimo Console.

1. Scroll down to Deploy New link from the Console Navigation.
2. Load college_fest.war from college_fest/releases/geronimo folder in to the Archive input box.
3. Press Install button to deploy application in the server.

Repeat the steps you did when testing the application on the JBoss environment.

Back to Top

Summary

This article has shown you how to migrate a simple Servlet and JSPs application, from JBoss to the Apache Geronimo application server. You followed step-by-step instructions to build the application, deploy and run it, and then migrate it to the Geronimo environment.

Some remarks after reading this article:

• Apache Geronimo provides two different Web containers, Jetty and Apache Tomcat.
• You learnt how to use the deployer tool for deploying an application in Geronimo.
• A Geronimo deployment plan is not always needed, if the application does not use resource references you can accept the deployment defaults from Geronimo.