JBoss to Geronimo - Servlets and JSPs Migration

Migrating to Apache Geronimo

This article will help you migrate Web services applications developed for JBoss v4.0.5 to Apache Geronimo 1.1. This is part of a series of migration articles covering different types of applications migration from JBoss to Apache Geronimo application server.

This article provides some details on the differences between these two application servers as well as a detailed step-by-step migration procedure for porting Web services applications from JBoss v4.0.5 to Apache Geronimo. To define a common starting point (the source environment) we provide steps for deploying the sample Search a Phone Directory Web services application into the JBoss source environment. Then, you will be guided through the application migration and deployment process onto Apache Geronimo.

This article is organized into the following sections:

• Web Services implementation analysis
• Sample application
• The JBoss environment
• The Geronimo environment
• Step-by-step migration
• Summary

Web Services implementation analysis

Web services implementation may vary from one vendor to another. The purpose of this section is to provide comparison of JBoss and Apache Geronimo features which are used in the implementation of the sample application described further in this article. You can use the information below to identify the differences between these two servers and plan for migration accordingly.

The described Geronimo requirement for names of request elements and operations is be illustrated by the following example where names which must be the same are marked with bold:

The following example illustrates the requirement from Geronimo of having the same name the request elements. Look for the three occurrences of "myOperation".

<wsdl:definitions targetNamespace="http://myService.com/service"
        xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:tns="http://myService.com/service"
        xmlns:types="http://myService.com/service/types">
    
    <wsdl:types>
        <xsd:schema targetNamespace="http://myService.com/service/types">
            <xsd:element name="myOperation">...</xsd:element>
            <xsd:element name="myOperationResponse">...</xsd:element>
        </xsd:schema>
    </wsdl:types>

    <wsdl:message name="myOperationRequest">
        <wsdl:part element="types:myOperation" name="parameters"/>
    </wsdl:message>
    <wsdl:message name="myOperationResponse">
        <wsdl:part element="types:myOperationResponse" name="result"/>
    </wsdl:message>

    <wsdl:portType name="myServicePortType">
        <wsdl:operation name="myOperation">
            <wsdl:input message="tns:myOperationRequest"
                    name="myOperationRequest"/>
            <wsdl:output message="tns:myOperationResponse"
                    name="myOperationResponse"/>
        </wsdl:operation>
    </wsdl:portType>
    ...
</wsdl:definitions>

Back to Top

Sample application

This article contains the Search a Phone Directory Web services application to demonstrate Web services migration from JBoss to Geronimo. The application implements both server and Web-client sides of a simple service which searches through a phone directory. The user works with the Web-client to test the application. The user specifies a search criterion and receives the search results.

Download the Phone Directory Web services application from the following link:
Phone Directory

After extracting the ZIP file, a phonebook directory is created, from now on this directory will be referred as <phonebook_home>.

The Web service is generic in implementation and is based on the document/literal encoding style. The WSDL document describing the service can be found in the directory <phonebook_home>/web/WEB-INF/wsdl.

Application classes and JSP pages

The sample application consists of the following packages, the source code can be found in the <phonebook_home>/src directory.

• org.apache.geronimo.samples.phone.server - Implementation of the server endpoint of the Web service:
  o SearchPhonesServer classes - Implements business logic of the service.
  o PersonPhone, Search, SearchPhonesPortType and SearchResponse classes - Generated from the WSDL document by Java Web Services Development Pack.
• org.apache.geronimo.samples.phone.client - Implementation of the client endpoint of the Web service:
  o PersonPhone, Search, SearchPhonesPortType, SearchPhonesService and SearchResponse classes - Generated from the WSDL document.

In addition to these packages, the client endpoint of the Web service also consists a single JSP page. This JSP displays a search form, sends request to the server endpoint and displays the search results.

Tools used

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

Java Web Services Development Pack (JWSDP)

JWSDP provides a number of tools useful in development of different Web services. It was used for generation of JAXP-RPC mapping files located in the directory <webservices_home>/web and auxiliary Java classes and interfaces described above. Java Web Services Development Pack can be downloaded from the following URL:
http://java.sun.com/webservices

Eclipse

The Eclipse IDE was used for development of the sample application. This is an extremely 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 and populating the database for the Online Brokerage 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 the 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 prerequisite software required by the sample application. This step is described in the following section.

Install and configure prerequisite software

Compiling the source code of the sample application requires Java libraries that provide J2EE API interfaces. Build scripts included with the sample application package are configured for using JAR files provided by a JBoss installation.

The only additional software required for building the application is Apache Ant. If you still 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 Phone Directory Web services sample application included with this article provides an Ant script that you will use in order to build modules of the application. If you have not downloaded the sample application yet, this is a good time for doing it. Download the Search a Phone Directory application package from the following link:

Phone Directory

After extracting the zip file, a phonebook directory is created. From now on this directory will be referred as <phonebook_home>. In the <phonebook_home>/config directory open the build.properties file and edit the geronimo.home as given in below.

## Set the Geronimo 1.1 home here
geronimo.home=<geronimo_home>

From a command prompt or shell go to the <phonebook_home> directory and run the ant jboss command. This will create the WAR file and place it directly into the <phonebook_home>/releases/jboss directory.

In addition to the compiled Java classes and the previously mentioned WSDL and JAXP-RPC mapping files the WEB-INF directory of the archive contains standard web.xml and webservices.xml deployment descriptors and a descriptor specific to JBoss jboss-web.xml. The JBoss deployment descriptor is illustrated in below.

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

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

Since this sample application does not use any resources, no features specific to JBoss, this file just provides the context root for the application. This path is optional and in case of such a simple descriptor you can build and deploy the application even without it.

Deploy the sample application

To deploy the sample application just copy the phonebook.war will be created under the <phonebook_home>/releases/jboss folder to the <jboss_home>/server/<your_server_name>/deploy folder.

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.

Test the sample application

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

http://localhost:8080/phonebook

This brings up the phone book web page.

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.

Download and install Geronimo from the following URL:
http://geronimo.apache.org/downloads.html

Back to Top

Step-by-step migration

As it was described in the beginning of this article, Geronimo does not allow an XML schema element representing request message of an operation to have a name different from the name of the operation. Hence if your WSDL defines unsupported names you need to correct the WSDL and generate or re-generate required Java classes. This may require manual modification of classes implementing endpoint of the Web service depending on your coding approach.

The Search a Phone Directory Web services sample application uses WSDL names convention supported by both servers. Therefore the only thing that you need to do prior to deploy the application on Geronimo is to replace the deployment descriptor specific to JBoss with one specific to Geronimo. The geronimo-web.xml file is located in the <phonebook_home>/web/WEB-INF directory and its contents is listed below.

<?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>phonebook</dep:artifactId>
      <dep:version>1.0</dep:version>
      <dep:type>car</dep:type>
    </dep:moduleId>
    <dep:dependencies>
    	<dep:dependency>
           <dep:groupId>geronimo</dep:groupId>
           <dep:artifactId>geronimo-webservices</dep:artifactId>
           <dep:type>jar</dep:type>
        </dep:dependency>
		<dep:dependency>
           <dep:groupId>geronimo</dep:groupId>
           <dep:artifactId>geronimo-axis</dep:artifactId>
           <dep:type>jar</dep:type>
        </dep:dependency>
    </dep:dependencies>
    <dep:hidden-classes/>
    <dep:non-overridable-classes/>
  </dep:environment>
  <context-root>/phonebook</context-root> 
</web-app>

Build the sample application

Now run the command ant geronimo. This will create the Geronimo version of the WAR file in which the deployment descriptor jboss-web.xml is replaced with the geronimo-web.xml and place it directly into the <phonebook_home>/releases/geronimo directory.

Deploy the migrated sample application

To deploy the migrated phone book application, make sure the Geronimo server is up and running.

Open Geronimo console in your browser and follow the given steps:

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

Once the application is deployed, open a Web browser and access the following URL:

http://localhost:8080/phonebook

You should see the same JSP page of the application as you tested when running the Web services sample on JBoss.

Back to Top

Summary

This article showed how to migrate a Web services application that uses document/literal encoding from JBoss to Apache Geronimo. It showed that if the WSDL document follows the widely accepted naming conventions then the migration will take minimum effort or even the very same application could be redeployed on any of the servers without any changes at all.