Overview

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

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 to Apache Geronimo v1 (milestone build M5). 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 in 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 of 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 occurences 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 Search a Phone Directory Web services application from the following URL:

http://opensource2.atlassian.com/confluence/oss/download/attachments/1141/webservices.zip

After extracting the ZIP file, a webservices directory is created, from now on this directory will be referred as <webservices_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 <webservices_home>/web/WEB-INF/wsdl.

Back to Top

Application classes and JSP pages

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

• com.ibm.j2g.webservices.server - Implementation of the server endpoint of the Web service:
  • SearchPhonesServer classes - Implements business logic of the service.
  • PersonPhone, Search, SearchPhonesPortType and SearchResponse classes - Generated from the WSDL document by Java Web Services Development Pack.
• com.ibm.j2g.webservices.client - Implementation of the client endpoint of the Web service:
  • 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 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 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 environment

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 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 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.

Back to Top

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

Back to Top

Build the sample application

The Search a 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 URL:

http://opensource2.atlassian.com/confluence/oss/download/attachments/1141/webservices.zip

After extracting the zip file, a webservices directory is created. From now on this directory will be referred as <webservices_home>. In that directory open the build.properties file and edit the properties starting with the prefix jboss to match your environment as shown in the following example.

You should also ensure that the property server.port specifies the actual port used by JBoss on the local host. This number will be parsed to the <webservices_home>/web/WEB-INF/search-phones-service.wsdl file which is used by the Web service client endpoint to locate the server endpoint of the service. The remaining properties are not relevant at this point in time, you will use them later to build the Geronimo version of the sample application.

# Name of the server to build the application for:
server.name = jboss

# Port number occupied by the server on the local host
# (used by the web services client to locate the server
# endpoint):
server.port = 8080

# Home directory of JBoss 4.0.2 J2ee Application Server and
# name of the server instance on which the application
# should be deployed (this instance should be either a copy
# of the default JBoss server or the default server itself
# because its libs are also used for building the source
# code):
jboss.home = <jboss_home>
jboss.server = <your_server_name>

# Home directory of Geronimo 1.0M5 J2ee Application Server
# and its administrator credentials:
geronimo.home = <geronimo_home>
geronimo.user = system
geronimo.password = manager

From a command prompt or shell go to the <webservices_home> directory and run the ant build command. This will create the WAR file and place it directly into the <webservices_home> 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 the following example.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jboss-web PUBLIC
        "-//JBoss//DTD Web Application 2.3//EN"
        "http://www.jboss.org/j2ee/dtd/jboss-web_3_2.dtd">

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

Back to Top

The Geronimo environment

Back to Top

Step-by-step migration

Back to Top

Summary

Back to Top