WebSphere migrations: Migrating applications from JOnAS to WebSphere Application Server Community Edition

Dave Dougherty (ddougher@us.ibm.com), Senior Engineer and Certified IT Specialist, IBM India Software Lab Services and Solutions

Dave Dougherty is a Senior Engineer and Certified IT Specialist with the Business Partner Technical Enablement team within IBM Software Group. He has over twenty years of experience in the IT industry and has spent the last eleven years working in the distributed systems environment.

Summary: This article discusses the ease of migrating from JOnAS to IBM®'s open source WebSphere® Application Server Community Edition.

Tag this!

Date: 07 Feb 2007
Level: Introductory
Activity: 333 views

Introduction

IBM WebSphere Application Server Community Edition, an open source Java™ 2, Enterprise Edition (J2EE™) application server originally based on Apache Geronimo, was introduced into the WebSphere Application Server product family in late 2005. Its small memory footprint, ease-of-use, and free availability make it ideal for helping small- and medium-sized organizations take advantage of the J2EE programming model and runtime environment.

JOnAS (Java Open Application Server) is an open source application server offering, produced by ObjectWeb, with a primary presence in the European community. It is a J2EE compliant platform and has passed Sun™'s J2EE 1.4 Certification Test Suite. JOnAS supports Tomcat and Jetty for the Web container tier used to run Web applications.

Backed by the support and infrastructure of the WebSphere Application Server and open source communities, WebSphere Application Server Community Edition (hereafter referred to as Community Edition) is a superior alternative to JOnAS and other open source application servers. While migrating your applications from JOnAS to Community Edition is relatively easy, like all migrations, complications can occur. This article discusses some of the migration issues you might encounter when porting an application from JOnAS to Community Edition.

See Resources for articles to help you migrate to Community Edition from JBoss, WebLogic, and others.

About J2EE migrations

The application porting process is extremely simple for applications that:

Strictly adhere to the J2EE specification.
Do not utilize any J2EE component with an implementation that is vendor specific.
Do not make use of any vendor specific feature that is outside of the J2EE specification.

In cases where all three of these conditions are true, all you need to do is deploy the application using the target platform's deployment method. For other applications, varying degrees of additional work is necessary depending on the extent of deviation from these conditions.

The primary Web container implementation for both JOnAS and Community Edition environments is based on Apache Tomcat. This greatly simplifies the WAR porting process. The Community Edition Web container is based on the Tomcat 5.5.x core engine and supports the Servlet 2.4 and JSP 1.2 specifications. If you are porting between engines with different core specification levels, the migration task can become somewhat more involved, which is true of any environment and is not a platform specific condition. (See Resources for additional migration articles.)

Converting deployment descriptor files

A primary task in any porting effort is to address the differences in the deployment descriptors for a particular application. The standard deployment descriptors for J2EE applications are:

application.xml for the EAR module
web.xml for a WAR module
ejb-jar.xml for an EJB module.

These files support the configuration, parameters, and options detailed in the J2EE specification. In addition to these files, every J2EE application server has vendor specific deployment descriptors that support vendor specific implementations of various features required by the specification, or to support vendor extensions to the specification.

Table 1 lists the deployment descriptors for Community Edition and JOnAS environments and shows their relationship to the J2EE deployment descriptors.

Table 1. Deployment descriptor relationships

File type	J2EE	Community Edition	JOnAS
EAR	application.xml	geronimo-application.xml	--
WAR	web.xml	geronimo-web.xml	jonas-web.xml
EJB	ejb-jar.xml	openejb-jar.xml	jonas-ejb-jar.xml

The J2EE deployment descriptors should port between application server environments without change, as long as the supported J2EE specification level is the same. This article assumes this to be the case.

Platform (vendor) specific deployment descriptors need to be converted from one format to the other; in this case, from JOnAS format to Community Edition format. The next sections detail the transformations for several of the more common features in this migration scenario:

Reference mapping
Resource references
EJB JNDI names

Reference mapping

Mapping the various types of references to the global JNDI names of the target objects is a common porting task. A reference is an application specific pointer to an object that usually lives in a larger context, such as a server or cluster, and is used by multiple parties. While the object has a global name, every entity that uses the resource can use an application specific name, which is the reference. This target name for this pointer can be specified at deployment time, and does not require the application to be rebuilt. Two of the most common reference types are EJB references and resource references that point to JDBC data sources.

EJB references can be defined in a WAR module for use by JSPs and servlets. EJB references can also be defined in an EJB module for EJB-to-EJB interaction, such as a session bean calling an entity bean. The mapping of this type of reference is addressed in the J2EE specification, and both Community Edition and JOnAS adhere to this definition. Consequently, no further action is required for handling ejb-references; the web.xml and ejb-jar.xml files will contain all of the necessary information and do not need to be altered. This is true for both local and remote EJB references.

Listing 1 shows the pertinent fragment from the web.xml.

Listing 1

<ejb-ref id="'EjbRef_1152738645974"'>
<description></description>
	<ejb-ref-name>ejb/SessionReference</ejb-ref-name>
	<ejb-ref-type>Session</ejb-ref-type>
	<home>ejbs.SessionHome</home>
	<remote>ejbs.Session</remote>
	<ejb-link>HelloJonasEJB.jar#Session</ejb-link>
</ejb-ref>

<ejb-local-ref id="'EJBLocalRef_1152738602724"'>
	<description></description>
	<ejb-ref-name>ejb/SessionLocalReference</ejb-ref-name>
	<ejb-ref-type>Session</ejb-ref-type>
	<local-home>ejbs.SessionLocalHome</local-home>
	<local>ejbs.SessionLocal</local>
	<ejb-link>HelloJonasEJB.jar#Session</ejb-link>
</ejb-local-ref>

Resource references

The implementation for resource references is a bit different and requires a small amount of additional work. The J2EE specification requires an application server to implement support for resource references but does not dictate the mechanism for mapping the reference to the target object. Thus, the mapping information is usually defined in a vendor specific deployment descriptor, such as jonas-web.xml and geronimo-web.xml.

This is the fragment from the jonas-web.xml file:

<jonas-resource>
      <res-ref-name>jdbc/dsreference</res-ref-name>
      <jndi-name>jdbc/MyDatasourceDB2</jndi-name>
</jonas-resource>

And the equivalent geronimo-web.xml:

<naming:resource-ref>
	<naming:ref-name>jdbc/dsreference</naming:ref-name>
	<naming:resource-link>jdbc/MyDatasourceDB2</naming:resource-link>
</naming:resource-ref>

The use of the naming prefix above is only possible if the associated namespace is defined in the file, as in: xmlns:naming=http://geronimo.apache.org/xml/ns/naming-1.0. The prefix is not required and is only shown as an example. The code below is perfectly acceptable:

<resource-ref>
	<ref-name>jdbc/dsreference</ref-name>
	<resource-link>jdbc/MyDatasourceDB2</resource-link>
</resource-ref>

For Community Edition, this information can be stored in the Web module definition in the geronimo-application.xml file and will override anything in the module specific geronimo-web.xml file. For a resource reference defined on an EJB module, the XML is quite similar. The code for a resource reference in the jonas-ejb-jar.xml could be:

<jonas-resource>
      <res-ref-name>jdbc/dsreference</res-ref-name>
      <jndi-name>jdbc/MyDatasourceDB2</jndi-name>
</jonas-resource>

The equivalent XML inside of the openejb-jar.xml:

<resource-ref>
	<ref-name>jdbc/dsreference</ref-name>
	<resource-link>jdbc/MyDatasourceDB2</resource-link>
</resource-ref>

For Community Edition, this information can be stored in the EJB module definition in the geronimo-application.xml file and will override anything in the module specific openejb-jar.xml file.

EJB JNDI names

Enterprise Java Beans register a name in JNDI at deployment time as required by the J2EE specification. The specification does not define where this information is stored and the ejb-jar.xml format does not contain a specific field for a bean's JNDI name. Consequently, this value is defined in a vendor specific deployment descriptor. In our case, it is jonas-ejb-jar.xml for JOnAS, and openejb-jar.xml for Community Edition.

This is the fragment from the jonas-ejb-jar.xml file:

<jonas-session>
    <ejb-name>Session</ejb-name>
    <jndi-name>ejb/ejbs/SessionHome</jndi-name>
</jonas-session>

This is the equivalent in the openejb-jar.xml:

<session>
     <ejb-name>Session</ejb-name>
     <jndi-name>ejb/ejbs/SessionHome</jndi-name>
</session>

For Community Edition, this information can be stored in the EJB module definition in the geronimo-application.xml file and will override anything in the module specific openejb-jar.xml file.

Sample application

The sample application included with this article is a working example of all the above constructs and includes the deployment descriptors for both environments. The application consists of a single WAR module and a single EJB module. The contents of each module is:

Application: HelloJonasWeb

Simple.jsp -- Basic JSP that outputs two statements, one via HTML and one via a PrintWriter.
HelloServlet -- Standard HelloWorld servlet.
InfoServlet -- Exercises various APIs of the servlet interface.
TestLocal -- Calls the session bean local interface via lookup of EJB reference.
TestRemote -- Calls the session bean remote interface via lookup of EJB reference .
Lookup -- Looks up a datasource reference and then calls a session bean to lookup the same reference. (Note the commented out code for JOnAS which uses the global JNDI name for lookup.)

Application: HelloJonasEJB

Session -- Stateless session bean with thress methods.
- ping() -- Outputs a message to the server log.
- echo() -- Outputs a message to the server log and returns the message to the caller.
- lookup() -- Looks up a datasource reference. (Note the commented out code for JOnAS which uses the global JNDI name for lookup.)

Deployment descriptors

The deployment descriptors included within the Hello.Jonas.ear application are shown below to enable a visual comparison:

The deployment descriptors for J2EE, Community Edition, and JOnAS are displayed where applicable.
For the EAR structure, the application.xml and geronimo-application.xml files are shown.
For the WAR structure, the web.xml, jonas-web.xml, and geronimo-web.xml files are shown.
For the EJB modules, the ejb-jar.xml, jonas-ejb-jar.xml, and openejb-jar.xml files are displayed.

Listing 2. application.xml

<?xml version="1.0" encoding="UTF-8"?>
<application id="HelloJonas" version="1.4" 
xmlns="http://java.sun.com/xml/ns/j2ee" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/application_1_4.xsd">
    <display-name>HelloJonas</display-name>
    <module id="EjbModule_1152731275709">
    	<ejb>HelloJonasEJB.jar</ejb>
    </module>
    <module id="WebModule_1152729750334">
    	<web>
    		<web-uri>HelloJonasWeb.war</web-uri>
    		<context-root>HelloJonasWeb</context-root>
    	</web>
    </module>
</application>

Listing 3. geronimo-application.xml

<application 
 xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-1.1"
 xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1"
 xmlns:sec="http://geronimo.apache.org/xml/ns/security-1.1"
 xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1">

 <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1">
		<dep:moduleId>
			<dep:groupId>HelloJonas</dep:groupId>
			<dep:artifactId>HelloJonasApp</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>

 
  <!--if module def's present module dd's  e.g. geronimo-web.xml ignored-->
 
  <module>
    <web>HelloJonasWeb.war</web>
    <web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1">
      <sys:environment>
        <sys:moduleId>
          <sys:groupId>HelloJonas</sys:groupId>
          <sys:artifactId>HelloJonasWeb</sys:artifactId>
          <sys:version>1.0</sys:version>
          <sys:type>war</sys:type>
        </sys:moduleId>
         <sys:dependencies>
          <sys:dependency>
                <sys:groupId>HelloJonas</sys:groupId>
                <sys:artifactId>MyDataSourceDB2</sys:artifactId>
            </sys:dependency>
    	</sys:dependencies>        
        <sys:hidden-classes/>
        <sys:non-overridable-classes/>
      </sys:environment>
      <context-root>/HelloJonasWeb</context-root>
      <naming:resource-ref>
        <naming:ref-name>jdbc/dsreference</naming:ref-name>
        <naming:resource-link>jdbc/MyDataSourceDB2</naming:resource-link>
      </naming:resource-ref>
    </web-app>
  </module>
     
  <module>
    <ejb>HelloJonasEJB.jar</ejb>
    <openejb-jar xmlns="http://www.openejb.org/xml/ns/openejb-jar-2.1">
      <sys:environment>
        <sys:moduleId>
          <sys:groupId>HelloJonas</sys:groupId>
          <sys:artifactId>HelloJonasEJB</sys:artifactId>
          <sys:version>1.0</sys:version>
          <sys:type>car</sys:type>
        </sys:moduleId>
        <sys:dependencies>
          <sys:dependency>
                <sys:groupId>HelloJonas</sys:groupId>
                <sys:artifactId>MyDataSourceDB2</sys:artifactId>
            </sys:dependency>
    	</sys:dependencies>
        <sys:hidden-classes/>
        <sys:non-overridable-classes/>
      </sys:environment>
      <enterprise-beans>
        <session>
          <ejb-name>Session</ejb-name>
          <jndi-name>ejb/ejbs/SessionHome</jndi-name>
          <resource-ref>
            <ref-name>jdbc/dsreference</ref-name>
            <resource-link>jdbc/MyDataSourceDB2</resource-link>
          </resource-ref>
        </session>
      </enterprise-beans>
    </openejb-jar>
  </module>
 <!-- -->
</application>

Listing 4. web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_ID" version="2.4" 
xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
<display-name>HelloJonasWeb</display-name>
	<servlet>
		<description></description>
		<display-name>HelloServlet</display-name>
		<servlet-name>HelloServlet</servlet-name>
		<servlet-class>HelloServlet</servlet-class>
	</servlet>
	<servlet>
		<description></description>
		<display-name>InfoServlet</display-name>
		<servlet-name>InfoServlet</servlet-name>
		<servlet-class>InfoServlet</servlet-class>
	</servlet>
	<servlet>
		<description></description>
		<display-name>TestLocal</display-name>
		<servlet-name>TestLocal</servlet-name>
		<servlet-class>TestLocal</servlet-class>
	</servlet>
	<servlet>
		<description></description>
		<display-name>TestRemote</display-name>
		<servlet-name>TestRemote</servlet-name>
		<servlet-class>TestRemote</servlet-class>
	</servlet>
	<servlet>
		<description></description>
		<display-name>Lookup</display-name>
		<servlet-name>Lookup</servlet-name>
		<servlet-class>Lookup</servlet-class>
	</servlet>
	<servlet-mapping>
		<servlet-name>HelloServlet</servlet-name>
		<url-pattern>/HelloServlet</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>InfoServlet</servlet-name>
		<url-pattern>/InfoServlet</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>TestLocal</servlet-name>
		<url-pattern>/TestLocal</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>TestRemote</servlet-name>
		<url-pattern>/TestRemote</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>Lookup</servlet-name>
		<url-pattern>/Lookup</url-pattern>
	</servlet-mapping>
	<welcome-file-list>
		<welcome-file>index.html</welcome-file>
		<welcome-file>index.htm</welcome-file>
		<welcome-file>index.jsp</welcome-file>
		<welcome-file>default.html</welcome-file>
		<welcome-file>default.htm</welcome-file>
		<welcome-file>default.jsp</welcome-file>
	</welcome-file-list>
	<ejb-ref id="EjbRef_1152738645974">
		<description>
		</description>
		<ejb-ref-name>ejb/SessionReference</ejb-ref-name>
		<ejb-ref-type>Session</ejb-ref-type>
		<home>ejbs.SessionHome</home>
		<remote>ejbs.Session</remote>
		<ejb-link>HelloJonasEJB.jar#Session</ejb-link>
	</ejb-ref>
	<ejb-local-ref id="EJBLocalRef_1152738602724">
		<description>
		</description>
		<ejb-ref-name>ejb/SessionLocalReference</ejb-ref-name>
		<ejb-ref-type>Session</ejb-ref-type>
		<local-home>ejbs.SessionLocalHome</local-home>
		<local>ejbs.SessionLocal</local>
		<ejb-link>HelloJonasEJB.jar#Session</ejb-link>
	</ejb-local-ref>
	<resource-ref>
		<description>
		</description>
		<res-ref-name>jdbc/dsreference</res-ref-name>
		<res-type>javax.sql.DataSource</res-type>
		<res-auth>Container</res-auth>
		<res-sharing-scope>Shareable</res-sharing-scope>
	</resource-ref>
</web-app>

Listing 5. jonas-web.xml

<?xml version="1.0" encoding="ISO-8859-1"?>

<jonas-web-app xmlns="http://www.objectweb.org/jonas/ns"
	  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	  xsi:schemaLocation="http://www.objectweb.org/jonas/ns
	  http://www.objectweb.org/jonas/ns/jonas-web-app_4_0.xsd" >

    <jonas-resource>
      <res-ref-name>jdbc/dsreference</res-ref-name>
      <jndi-name>jdbc_1</jndi-name>
    </jonas-resource>

</jonas-web-app>

Listing 6. geronimo-web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app configId="HelloJonasWeb"
   xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.0"
   xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.0" 
   xmlns:sec="http://geronimo.apache.org/xml/ns/security-1.0"       
   xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.0">

<context-root>/HelloJonasWeb</context-root>
<context-priority-classloader>false</context-priority-classloader>

<naming:resource-ref>
	<naming:ref-name>jdbc/dsreference</naming:ref-name>
	<naming:resource-link>jdbc/MyDatasourceDB2</naming:resource-link>
</naming:resource-ref>

</web-app>

Listing 7. ejb-jar.xml

<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar id="ejb-jar_ID" version="2.1" 
xmlns="http://java.sun.com/xml/ns/j2ee" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd">
	<display-name>
	HelloJonasEJB</display-name>
	<enterprise-beans>
        <!-- @generated ejbs.SessionBean#ejb/aejbdd.ejbs.SessionBean -->
		<session id="ejbs.SessionBean">
			<ejb-name>Session</ejb-name>
			<home>ejbs.SessionHome</home>
			<remote>ejbs.Session</remote>
			<local-home>ejbs.SessionLocalHome</local-home>
			<local>ejbs.SessionLocal</local>
			<ejb-class>ejbs.SessionBean</ejb-class>
			<session-type>Stateless</session-type>
			<transaction-type>Container</transaction-type>
			<resource-ref>
				<description>
				</description>
				<res-ref-name>jdbc/dsreference</res-ref-name>
				<res-type>javax.sql.DataSource</res-type>
				<res-auth>Container</res-auth>
				<res-sharing-scope>Shareable</res-sharing-scope>
			</resource-ref>
		</session>
</enterprise-beans>
	<assembly-descriptor>
	</assembly-descriptor>
</ejb-jar>

Listing 8. jonas-ejb-jar.xml

<?xml version="1.0" encoding="ISO-8859-1"?>

<jonas-ejb-jar xmlns="http://www.objectweb.org/jonas/ns"
	      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	      xsi:schemaLocation="http://www.objectweb.org/jonas/ns
		  http://www.objectweb.org/jonas/ns/jonas-ejb-jar_4_0.xsd" >
  <jonas-session>
    <ejb-name>Session</ejb-name>
    <jndi-name>ejb/ejbs/SessionHome</jndi-name>
    <jonas-resource>
      <res-ref-name>jdbc/dsreference</res-ref-name>
      <jndi-name>jdbc_1</jndi-name>
    </jonas-resource>
  </jonas-session>
</jonas-ejb-jar>

Listing 9. openejb-jar.xml


?xml version="1.0" encoding="UTF-8"?>
<openejb-jar
    xmlns="http://www.openejb.org/xml/ns/openejb-jar-2.0"
    xmlns:nam="http://geronimo.apache.org/xml/ns/naming-1.0"
    xmlns:sec="http://geronimo.apache.org/xml/ns/security-1.1"
    xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.0"
    xmlns:pkgen="http://www.openejb.org/xml/ns/pkgen-2.0"
    configId="HelloJonasEJB" parentId="HelloJonas">
 
 <enterprise-beans>
 	<session>
		<ejb-name>Session</ejb-name>
		<jndi-name>ejb/ejbs/SessionHome</jndi-name>
		<local-jndi-name></local-jndi-name>

		<resource-ref>
			<ref-name>jdbc/dsreference</ref-name>
			<resource-link>jdbc/MyDatasourceDB2</resource-link>
		</resource-ref>
			 
    </session> 
  </enterprise-beans>
</openejb-jar>

Conclusion

The information presented here is an introduction to the implementation differences between WebSphere Application Server Community Edition and JOnAS, and can help you migrate to and use Community Edition as a stepping stone into the WebSphere Application Server family of products.

Download

Description	Name	Size	Download method
Sample application	HelloJonas.zip	74 KB	HTTP

Information about download methods

Resources

Learn

Get products and technologies

Download WebSphere Application Server Community Edition (all versions)

About the author

Comments (Undergoing maintenance)

Trademarks | My developerWorks terms and conditions

Close [x]

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Close [x]

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

static.content.url=http://www.ibm.com/developerworks/js/artrating/

SITE_ID=1

Zone=WebSphere, Open source

ArticleID=194674

ArticleTitle=WebSphere migrations: Migrating applications from JOnAS to WebSphere Application Server Community Edition

publish-date=02072007

author1-email=ddougher@us.ibm.com

author1-email-cc=