Published on ONJava.com (http://www.onjava.com/)
 See this if you're having trouble printing code examples

Migrating a WebLogic EJB Application to JBoss

by Deepak Vohra

WebLogic server is a leading commercial application server. But for small scale developers, the open source, standards-based, application server JBoss is a viable alternative to commercial application servers such as WebLogic or WebSphere. Unfortunately, an application developed in WebLogic is not deployable in JBoss. JBoss Migration Services offers support to migrate an application to JBoss. As an alternative, an application may be migrated to JBoss by converting the vendor-specific deployment descriptors to JBoss. To demonstrate the migration of applications to JBoss, we shall migrate an EJB application developed in WebLogic with the Oracle database to the JBoss application server with the open source MySQL as the database.

This tutorial has the following sections:

  1. Preliminary Setup
  2. Overview
  3. Configuring JBoss with MySQL
  4. Converting the WebLogic EJB Application
  5. Deploying the EJB Application in JBoss

Preliminary Setup

The MySQL database driver classes are required to configure a JDBC connection with the MySQL database.

  1. Download the MySQL JDBC driver .jar file.
  2. Download and install the MySQL database server.
  3. Download and install the JBoss 4.0 application server.

Develop a Java application, which shall be used to transform the WebLogic deployment descriptors to JBoss deployment descriptors with an XSLT. The deployment descriptors may also be transformed with an XSLT utility.


Without modifications, an application developed for WebLogic does not deploy in JBoss. The deployment descriptors for the JBoss application server are different than the WebLogic deployment descriptors. In this tutorial, we shall migrate an example entity EJB application developed in WebLogic to JBoss by converting the WebLogic deployment descriptors to JBoss deployment descriptors.

Related Reading

Enterprise JavaBeans
By Richard Monson-Haefel, Bill Burke, Sacha Labourey

The example application consists of a Catalog entity EJB. The EJB's bean class (CatalogBean.java), remote interface (Catalog.java), and home interface (CatalogHome.java) are available in the weblogic-jboss-resources.zip example file listed in the Resources section below. The MySQL open source database shall be used to configure the JBoss application. The entity EJB classes do not need to be modified for deploying a WebLogic EJB application to JBoss. Only the deployment descriptors for an EJB must be modified.

Configuring JBoss with MySQL

MySQL is an open source database suitable for open source projects and small organizations. The following modifications are needed to configure JBoss with the MySQL database.

Configuring the JBoss Classpath

To use JBoss 4.0 with MySQL, we first copy the driver class .jar file mysql-connector-java-3.0.9-stable-bin.jar to the <JBoss>/server/default/lib directory. <JBoss> is the directory in which the JBoss application server is installed. The lib directory .jar and .zip files are in the Classpath of the JBoss server.

Configuring the MySQL Datasource

To use the MySQL data source, copy <JBoss>/docs/examples/jca/mysql-ds.xml to the <JBoss>/server/default/deploy directory. The datasource configuration files in the deploy directory get deployed when the JBoss server is started. Modify the mysql-ds.xml configuration file as follows:

The modified mysql-ds.xml looks like this:

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

A JDBC connection may be obtained from the datasource with the datasource JNDI name:

    InitialContext initialContext = new InitialContext();
    javax.sql.DataSource ds = (javax.sql.DataSource)
    java.sql.Connection conn = ds.getConnection();

Configuring Login

Next, we modify the login-config.xml configuration file with MySQL database settings. The application policy MySqlDbRealm is required to log in to the MySQL database. Add the following <application-policy/> element to login-config.xml:

<application-policy name = "MySqlDbRealm"> 
      <login-module code =  
                     flag = "required"> 
         <module-option name ="principal"></module-option> 
         <module-option name ="userName">root</module-option> 
         <module-option name ="password"></module-option> 
         <module-option name ="managedConnectionFactoryName">  

By modifying the mysql-ds.xml and login-config.xml files, the JBoss 4.0 server is configured to work with the MySQL database. In addition to the settings specified in the previous sections, additional modifications may be required to the JBoss deployment descriptors and the JBoss JDBC configuration files.

If the "create table" option is selected (by setting the create-table element in jbosscmp-jdbc.xml to true) for deploying CMP entity EJBs, and the primary key (or unique key) length for a MySQL table exceeds 500 bytes, the deployment of the application generates a SQL syntax error in the MySQL database. For the java.lang.String type CMP fields, the primary key (or unique key) length may be reduced by setting the sql-type for the java-type java.lang.String to a lower VARCHAR value for the mySQL type mapping in the standardjbosscmp-jdbc.xml deployment descriptor. Another possible problem involves the column-name element in the jbosscmp-jdbc.xml deployment descriptor. If a MySQL table column name is the same as a MySQL reserved word, an error gets produced upon deploying a J2EE application in JBoss. The fix is to set the column name to a value that is not a MySQL reserved word.

Converting the WebLogic EJB Application

Having set up JBoss to use MySQL, we now need to convert the WebLogic EJB application to a JBoss EJB application, which involves changing the deployment descriptors. A WebLogic entity EJB application consists of the EJB deployment descriptors (ejb-jar.xml, weblogic-ejb-jar.xml, and weblogic-cmp-rdbms-jar.xml), the bean class (CatalogBean.java), the remote interface (Catalog.java), and the home interface (CatalogHome.java). To deploy the entity EJB in the WebLogic server, an EJB .jar file is created; this EJB .jar file has the structure:


The structural and application assembly information for an EJB is specified in the deployment descriptors. Structural information includes specifying the EJB as a session EJB or an entity EJB. The application assembly information in the ejb-jar.xml deployment descriptor is specified in the assembly-descriptor element. The entity EJB deployment descriptors for WebLogic are ejb-jar.xml, weblogic-ejb-jar.xml, and weblogic-cmp-rdbms-jar.xml. The corresponding deployment descriptors for JBoss are ejb-jar.xml, jboss.xml, and jbosscmp-jdbc.xml. Converting between these files will be described below.

The ejb-jar.xml deployment descriptor is the same for WebLogic and JBoss, except for the multiplicity element. The multiplicity element in the ejb-jar.xml file for the JBoss server is required to be upper case; i.e., One or Many instead of one or many.

The ejb-jar.xml deployment descriptor for the example entity EJB is available in the sample code. The example ejb-jar.xml defines an entity EJB with the EJB name "Catalog." The example EJB has the CMP fields catalogId, journal, and publisher. The primary key field is catalogId.

Converting weblogic-ejb-jar.xml to jboss.xml

The weblogic-ejb-jar.xml and jboss.xml deployment descriptors are vendor-specific deployment descriptors for EJBs. To deploy a WebLogic EJB application to the JBoss application server, convert the weblogic-ejb-jar.xml deployment descriptor to jboss.xml.

The root element in weblogic-ejb-jar.xml is weblogic-ejb-jar. The root element in jboss.xml is jboss. The JNDI name for a EJB is specified in the jboss.xml and weblogic-ejb-jar.xml deployment descriptors with the jndi-name element or the local-jndi-name element. A weblogic-ejb-jar.xml deployment descriptor for the example entity EJB is available in the sample code. The DOCTYPE element for the weblogic-ejb-jar.xml deployment descriptor is:

<!DOCTYPE weblogic-ejb-jar PUBLIC 
"-//BEA Systems, Inc.//DTD WebLogic 8.1.0 EJB//EN"
"http://www.bea.com/servers/wls810/dtd/weblogic-ejb-jar.dtd" >

The DOCTYPE for the jboss.xml deployment descriptor is:

<!DOCTYPE jboss PUBLIC "-//JBoss//DTD JBOSS 4.0//EN"

Convert the deployment descriptor weblogic-ejb-jar.xml to the deployment descriptor jboss.xml with a custom XSLT stylesheet, jboss.xslt, available in the resource code .zip file. For further details about converting with XSLT, refer to Sun's XSLT tutorial. The stylesheet creates jboss.xml, the JBoss equivalent of WebLogic's weblogic-ejb-jar.xml deployment descriptor. The jboss.xml file generated with the jboss.xslt stylesheet is available in the sample code.

Converting weblogic-cmp-rdbms-jar.xml to jbosscmp-jdbc.xml

The weblogic-cmp-rdbms-jar.xml deployment specifies the database persistence information for a CMP entity EJB. The weblogic-cmp-rdbms-jar.xml file includes the table name for a entity EJB, the datasource to connect to the database, and the columns corresponding to the entity EJB CMP fields. The weblogic-cmp-rdbms-jar.xml deployment descriptor for the example entity EJB is available in the .zip file. The JBoss deployment descriptor that specifies the CMP entity EJB persistence information is jbosscmp-jdbc.xml.

The root element of weblogic-cmp-rdbms-jar.xml is weblogic-rdbms-jar. The root element in jbosscmp-jdbc.xml is jbosscmp-jdbc. The data-source-name element, which specifies the data source to connect to the database in the weblogic-cmp-rdbms-jar.xml file, is equivalent to the datasource element in the jbosscmp-jdbc.xml deployment descriptor. The field-map element, which specifies the mapping of the entity EJB CMP fields to database table columns in weblogic-cmp-rdbms-jar.xml, is the equivalent of the cmp-field element in jbosscmp-jdbc.xml. The dbms-column element, which specifies a column name in weblogic-cmp-rdbms-jar.xml, is the equivalent of the column-name element in jbosscmp-jdbc.xml. The DOCTYPE for the weblogic-cmp-rdbms-jar.xml deployment descriptor is:

<!DOCTYPE weblogic-rdbms-jar PUBLIC 
 '-//BEA Systems, Inc.//DTD WebLogic 8.1.0 EJB RDBMS Persistence//EN'

The DOCTYPE for jbosscmp-jdbc.xml is:

<!DOCTYPE jbosscmp-jdbc PUBLIC "-//JBoss//DTD JBOSSCMP-JDBC 4.0//EN"

Convert the deployment descriptor weblogic-cmp-rdbms-jar.xml to jbosscmp-jdbc.xml with the custom XSLT stylesheet, jbosscmp-jdbc.xslt, available in the sample code. The stylesheet creates jbosscmp-jdbc.xml, the JBoss equivalent of WebLogic's weblogic-cmp-rdbms-jar.xml deployment descriptor. jbosscmp-jdbc.xml is available in the .zip file.

The DTDs for the WebLogic deployment descriptors are different from the JBoss deployment descriptors. With custom XSLTs, which may be modified if additional elements are present in the deployment descriptors, the WebLogic deployment descriptors get converted to JBoss deployment descriptors. In the following section, the EJB application is deployed in the JBoss server.

Deploying the EJB Application in JBoss

Having converted the WebLogic EJB deployment descriptors to JBoss deployment descriptors, you need to create an EJB .jar file to deploy in the JBoss server. The structure of the JBoss .jar file is:


Compile the example EJB classes and interfaces.

java Catalog.java CatalogBean.java CatalogHome.java

Copy the JBoss deployment descriptors, ejb-jar.xml, jboss.xml, and jbosscmp-jdbc.xml, to the META-INF directory. Create a .jar file from the JBoss deployment descriptors, classes, and interfaces with the jar utility.

jar cf CatalogEJB.jar CatalogBean.class 
     Catalog.class CatalogHome.class META-INF/*.xml 

To deploy the JBoss entity EJB application, copy the .jar file, EntityEJB.jar, to the <JBoss>\server\default\deploy directory, where <JBoss> is the directory in which JBoss is installed. The EJB application gets deployed on the JBoss server when the server is started. The deploy directory in the JBoss application server is the directory that corresponds to the applications directory in the WebLogic application server.


An entity EJB application developed in WebLogic may be migrated to the JBoss application server by converting the deployment descriptors. Using a similar process, a WebLogic J2EE web application may be migrated to JBoss by converting the weblogic.xml deployment descriptor to jboss-web.xml.


Deepak Vohra is a NuBean consultant and a web developer.

Return to ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.