FoeDeployer: Deploying non-JBoss J2EE applications

What Is FoeDeployer

FoeDeployer is a JBoss service that allows to deploy non-JBoss J2EE applications (i.e. the applications that were developed for other application servers such as BEA WebLogic, etc) into the JBoss J2EE server.

See also PortingFromWeblogic

License

FoeDeployer is licensed under LGPL and distributed as a SAR (Service ARchive, the SAR format packaging is covered in JBoss Getting Started Guide) package.

Installation

FoeDeployer service is installed as any other SAR-packaged JBoss service, i.e. the SAR package with the service should be dropped into the JBoss deploy directory. If the service was deployed correctly, in Web console under the System icon among JMX MBeans under jboss domain you will see service jboss:service=FoeDeployer.

The package can be found in the varia module and is called foe-deployer-3.2.sar or be downloaded from this site.

What It Actually Does

Once the deployer is installed, it is ready to do its job. Now you can deploy your non-JBoss J2EE applications into the JBoss server the same way as any other JBoss J2EE application, i.e. just dropping the package with the application into the deploy directory. When it's done, the deployment descriptors are extracted from the package and transformed (with XSLT) into the corresponding JBoss-specific ones. The package then is reassembled and deployed again, this time as a native JBoss J2EE application.

Converters

FoeDeployer itself does not perform any transformations. In fact, it represents a registry of different converters. It is the converters that actually transform deployment descriptors and do repackaging. Each converter is specifc to an application server and can transform only applications developed for this specific application server. For example, FoeDeployer is distributed with the WebLogic converter that transforms applications developed for BEA WebLogic.

A converter is an MBean. It can be deployed and undeployed independently of the deployer. When a converter is deployed, it registers itself with the deployer and since that moment the deployer can use the converter for transformations.

When a new non-JBoss application is found in the deploy directory the FoeDeployer iterates through the list of registered converters until one of the them accepts the application, i.e. one of the converters found that is able to transform the application into JBoss application. The first converter that accepted the application will be used. If none of the available converters accepts the application, the application will be put into the waiting-for-deployer list. Once a deployer or converter that can deploy the application is installed, the application will be removed from the waiting list and deployed.

WebLogic Converter

WebLogic converter is a JBoss service. It is distributed in one package with the FoeDeployer and installed automatically after the deployer. To check the fact that the WebLogic converter is installed open the Web console, click on the System icon, then on JMX MBeans and then on jboss domain. Its name is jboss:service=Converter;type=WebLogic.

Now, if you click on the WebLogic converter's name, its managed attributes and operations will be displayed (in the MBean's view). Managed operations (and some attributes) are not supposed to be used by the user but by the JBoss and FoeDeployer. The user can configure the converter with attributes. The following attributes are available:

• Datasource is the JNDI name of the datasource that should be used for entity beans (the default value is java:/DefaultDS);

• DatasourceMapping is one of the type-mapping's name that are defined in the conf/standardjbosscmp-jdbc.xml file (the default value is Hypersonic SQL);

• RemoveTable tells whether the JBossCMP should remove tables when the application is undeployed. Possible values are: true - do remove tables, false - do not remove the tables, create-default-dbms-tables - the default value that means that the value of create-default-dbms-tables element from the weblogic-cmp-rdbms-jar.xml will be used for this attribute and if it missing the value will be false.

Other attributes are used internally by the JBoss and should not be changed by the user.

Deploying WebLogic applications

You can deploy EJB JAR, WAR and EAR applications developed for BEA WebLogic 5.x and 6.X versions (7.X is partly supported). In fact, only EJB deployment descriptors are transformed, i.e. weblogic-ejb-jar.xml, weblogic-cmp-rdbms-jar.xml and EjbName-cmp-rdbms.xml. WAR and EAR are only repackaged. For most of the cases, it is enough to get the application deployed and working, which is the purpose of the FoeDeployer.

There is one preparation step prior to deployment of WebLogic applications. Since, in JBoss, the JBoss-specific deployment descriptors (jboss.xml, jbosscmp-jdbc.xml, etc) are optional any JAR package that contains META-INF/ejb-jar.xml will be deployed by the JBoss EJB deployer using the default configuration and ignoring any WebLogic-specific deployment descriptors. To prevent this, the .WL extension should be added to the WebLogic applications. For example, mywl-ejb-jar.jar.wl, mywl-war-app.war.wl, mywl-ear-app.ear.wl. Now, the JBoss will know that these applications should be deployed with the FoeDeployer.

When a WebLogic application is transformed into the JBoss application, it is reassembled, the WL extension is removed and you will see the application with its original extension (JAR, WAR or EAR) in the deploy dir which is then deployed by the native JBoss deployers.

Sample application

Sample application demonstrates conversion of simple WebLogic application that includes Enterprise Session and Entity Beans. The purpose of the application is to demonstrate the conversion, not the best architectural practices. The application covers conversion of relationships including one-to-many and many-to-many, EJB references, database mapping, JNDI binding and other configurations. The application was tested with the BEA WebLogic 6.1.

Description

The application includes the following EJB beans:

• SequenceEJB is an entity bean that serves as the primary key generator for other entity beans.

• SequenceSessionEJB is a stateless session bean that uses SequenceEJB to implement Hi-Lo key generator strategy.

• StudentEJB is an entity bean that handles student information. It includes student id provided by the SequenceSessionEJB, many-to-one relationship with GroupEJB (each student belongs to only one group), local EJB reference to SequenceSessionEJB, environment parameter that defines the primary key sequence name.

• TeacherEJB is an entity bean that handles teacher information. It includes the identifier provided by the SequenceSessionEJB, many-to-many relationship with GroupEJB, a local EJB reference to SequenceSessionEJB, an environment parameter that defines the primary key sequence name to use, ejbSelectStudents method that selects all the students the teacher has navigating through Teacher-Group and Group-Student relationships to demonstrate correct mapping conversion.

• GroupEJB is an entity bean that handles information of a group of students. It has a composite primary key that consists of department identifier and group number and established relationships to StudentEJB (one-to-many) and TeacherEJB (many-to-many).

• ManagerSessionEJB is a stateless session bean with remote interfaces that implements a Facade pattern wrapping access to the entity beans and declares local EJB references to StudentEJB, GroupEJB and TeacherEJB.

Client class is remote client application that looks up the ManagerSessionEJB in the JNDI server and performs some operations. The scenario is:

1. look up the ManagerSessionEJB's home interface;

2. create an instance of ManagerSessionEJB;

3. make sure that the database is empty;

4. create several instances of TeacherEJB;

5. create several instances of GroupEJB;

6. create a set of StudentEJB instances establishing relationships with the corresponding GroupEJB instances (note, there should not be a StudentEJB instance that has no GroupEJB instance assigned);

7. establish relationships between teachers and groups;

8. for each teacher fetch all of its students to verify the correctness of conversion.

The result of each operation above is logged to the console. The console output for WebLogic and JBoss should be the same except for vendor-specific JNDI properties.

Deploying And Running Sample Application

To run the sample application you will need JBoss 3.2.x version or later and Jakarta Ant 1.4.1 or a later version. The build.xml file requires the JBOSS_HOME environment variable to be set and point to the directory JBoss 3.2.x is installed to.

The following steps describe how to deploy and run the sample application:

1. run the default target which will compile the sources and assemble a WebLogic application fd-sample-ejb-wl.wlar (note the .WLAR extension instead of .JAR) that is ready to be deployed into the JBoss server and the JBoss application fd-sample-ejb-jboss.jar built just for comparison;

2. start the JBoss server and install the FoeDeployer service (see Installation);

3. execute the deploy-wl target to deploy WebLogic application fd-sample-ejb-wl.wlar into the JBoss (FoeDeployer will convert the WebLogic deployment descriptors and reassamble the application into fd-sample-ejb-wl.jar with JBoss deployment descriptors and put it in the deploy directory next to fd-sample-ejb-wl.wlar which then deployed by the JBoss' EJB deployer);

4. run the test target;

5. execute clean target to undeloy and delete compiled classes and assembled applications.