Migration Guide

This chapter describes the modification to perform when we want to use an Enterprise bean previously developped and deployed on JOnAS 1.xx with the new JOnAS 2 version.
EJBs developped with JOnAS 1.xx are not compatible with JOnAS 2.0. It is due to the fact that JOnAS 1.xx was compliant with the EJB1.0 specification, JOnAS 2.0 is now compliant with EJB1.1 specification. Between the two versions of the specification major changes have occured and it was impossible to provide an ascendant compatibility.

The purpose of this guide is to help the user to adapt an existing EJB in order to make it compliant to the new specification. It may seem it is a tedious work but it is worth to do it, the resulting EJB will be an enterprise bean much more portable on other EJB platform compliant 1.1.

The main difference between an EJB 1.0 and a EJB 1.1 is that the bean provider must provide a XML deployment descriptor, but in the following we will review the different domains like

Deployment Descriptor

In the EJB 1.0 specification, there was a deployment descriptor for each enterprise bean. The deployment descriptor was a serialized instance of a javax.ejb.deployment.EntityDescriptor or javax.ejb.deployment.SessionDescriptor object.

In JOnAS 1.xx a proprietary textual representation was used to describe a deployment descriptor (.txt files) and a tool (GenDD) was necessary to generate the corresponding serialized deployment descriptor.

In JOnAS 2.xx .txt files and GenDD does not exist anymore. Now there is no more one deployment descriptor for each enterprise bean, but an XML deployment descriptor may contain description of several enterprise beans.

In fact two XML files are necessary one corresponding to the standard part, the second containing the JOnAS specfic part. Typically the information corresponding to the old .txt file are in the standard part, the information that was previously in a separated.properties file and referenced in the EnvironmentProperties part is now in the jonas specific XML file See the Bean Programmer's Guide § Defining the deployment descriptor

jonas.beans.descriptors property of the jonas.properties does not contain anymore a list of .ser files but a list of .xml files knowing that if you have named the standard XML XX.xml the JOnAS specific part must be called jonas-XX.xml and only XX.xml must appear in the jonas.beans.descriptors property.

The input of the GenIC tool is also the standard XML deployment descriptor.

Ejb-jar file

In the EJB 1.0 specification, the ejb-jar file contained the enterprise beans' class files, and for each bean, its serialized deployment descriptor. An ejb-jar file had to include a manifest file. In the EJB 1.1 specification the manifest file is no longer used and the XML deployment descriptors must be stored under META-INF/ejb-jar.xmland META-INF/jonas-ejb-jar.xml.

Primary Key Class

In JOnAS version 1, a toString() method had to be implemented in the entity bean's primary key class. It is no more necessary in JOnAS version 2. On the other hand, the entity bean's primary key class must provide implementation of the hashCode() and equals(Object other) methods, as it is required in the EJB 1.1 specification.

JNDI Configuration and Initial Naming Context

In JOnAS version 1, the configuration of JNDI was specified in the jonas.properties file. Now in JOnAS 2, the JNDI configuration is declared in the application resource file jndi.properties accessible from the CLASSPATH variable. So, an InitialContext can then be construct as following: InitialContext ic = new InitialContext().

Enterprise Bean's Environment

The enterprise bean's environment is a mechanism that allows customization of the enterprise bean's business logic during deployment (or assembly). The environment naming context introduced in EJB 1.1 replaces the EJB 1.0 concept of environment properties.

In EJB 1.1, the standard way for a bean to access to its environment is to use JNDI interfaces. The enterprise bean's environment entries are stored in thejava:comp/env naming context. The Bean Provider must declare all the environment entries accessed from the bean's code. The environment entries are declared using the env-entry element in the standard XML deployment descriptor.

JOnAS 2 supports the EJB 1.1 standard way but it supports also the EJB1.0 style environment properties. So, beans that used the EJBContext.getEnvironment() method, need not to change their code. In this case, the env-entry elements should be defined as follows: the env-entry-name element contains the name of the environment property into the ejb10-properties subcontext of the environment naming context. env-entry-type must be java.lang.String and the env-entry-value contains the environement property value. See the Bean Programmer's Guide Enterprise Bean Environment.

DataSource object access

 The EJB 1.0 specification didn't specify how to get a DataSource object associated to a JDBC driver and to a database. On JonAS version 1, the DataSource object was available for the bean through its JNDI name, which was the property datasource.namedefined in the environment properties of the bean in the deployment descriptor.

The EJB 1.1 specification introduce the resource manager connection factory references. This mecanism is used in JOnAS version 2 to allow the bean to obtain the DataSource object. See the Bean Programmer's Guide Writing database access operations.

Deprecated use of java.rmi.RemoteException

The EJB 1.0 specification allowed business methods, ejbCreate, ejbPostCreate, ejbFind<Method>, ejbRemove, and the container-invoked callbacks (i.e. the methods defined in the EntityBean, SessionBean, and SessionSynchronization interfaces) implemented in the enterprise bean class to use the java.rmi.RemoteException to report non-application exceptions to the container.

This use of the java.rmi.RemoteExecption is deprecated in EJB 1.1. Enterprise beans written for the EJB 1.1 specification should use the javax.ejb.EJBException.

JOnAS support the deprecated use of the java.rmi.RemoteException.

The container treats the java.rmi.RemoteException thrown by an enterprise bean method in the same way as the javax.ejb.EJBException.