Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Upgrade and Migration Guide

Migrating Enterprise EJB Modules

Application Server 6.x supports EJB 1.1, and the Application Server supports EJB 2.0. Therefore, both can support:

Stateful or stateless session beans
Entity beans with bean-managed persistence (BMP), or container-managed persistence (CMP)

EJB 2.0, however, introduces a new type of enterprise bean, called a message-driven bean (MDB).

J2EE 1.4 specification dictates that the different components of an EJB must be grouped together in a JAR file with the following structure:

META-INF/ directory with an XML deployment descriptor named ejb-jar.xml
The .class files corresponding to the home interface, remote interface, the implementation class, and the auxiliary classes of the bean with their package

Application Server 6.x use this archive structure. However, the EJB 1.1 specification leaves each EJB container vendor to implement certain aspects as they see fit:

Database persistence of CMP EJBs (particularly the configuration of mapping between the bean’s CMP fields and columns in a database table).
Implementation of the custom finder method logic for CMP beans.
Application Server 6.x andApplication Server 8.1do not handle migrations in the same way, which means that some XML files must be modified:
The <!DOCTYPE definition must be modified to point to the latest DTD url (in the case of J2EE standard DDs, like ejb-jar.xml).
Replace the ias-ejb-jar.xml file with the modified version of this file (for example, file sun-ejb-jar.xml, which is created manually according to the DTDs). For more information, see http://wwws.sun.com/software/dtd/appserver/sun-ejb-jar_2_1-1.dtd
Replace all the <ejb-name>-ias-cmp.xml files with one sun-cmp-mappings.xml file, which is created manually. For more information, see http://wwws.sun.com/software/dtd/appserver/sun-cmp-mapping_1_2.dtd
Optionally, for CMP entity beans, use the capture-schema utility in the Application Server’s bin directory to generate the dbschema. Then place it above the META-INF directory for the entity beans.

EJB Migration

As mentioned in Chapter 4, Understanding Migration, while Application Server 6.x supports the EJB 1.1 specification, Application Server also supports the EJB 2.0 specification. The EJB 2.0 specification introduces the following new features and functions to the architecture:

Message Driven Beans (MDBs)
Improvements in Container-Managed Persistence (CMP)
Container-managed relationships for entity beans with CMP
Local interfaces
EJB Query Language (EJB QL)

Although the EJB 1.1 specification continues to be supported in the Application Server, the use of the EJB 2.0 architecture is recommended to leverage its enhanced capabilities.

For detailed information on migrating from EJB 1.1 to EJB 2.0, please refer to Chapter 5, Migrating from EJB 1.1 to EJB 2.0

EJB Changes Specific to Application Server Platform Edition 8.1

Migrating EJBs from Application Server 6.x to Application Server 8.1 is done without making any changes to the EJB code. However, the following DTD changes are required.

Session Beans

The <!DOCTYPE> definition must be modified to point to the latest DTDs with J2EE standard DDs, such as ejb-jar.xml.
Replace ias-ejb-jar.xml file with the modified version of this file, named sun-ejb-jar.xml,created manually according to the DDs. For more details, see hhttp://ttp://wwws.sun.com/software/dtd/appserver/sun-ejb-jar_2_1-1.dtd
In the sun-ejb-jar.xml file, the JNDI name for all the EJBs must be added before ”ejb/’ in all the JNDI names. This is required because, in Application Server 6.5, the JNDI name of the EJB can only be ejb/<ejb-name> where <ejb-name> is the name of the EJB as declared inside the ejb-jar.xml file.

In the Application Server, a new tag has been introduced in the sun-ejb-jar.xml. This is where the JNDI name of the EJB is declared.

Note –

To avoid changing JNDI names throughout the application, declare the JNDI name of the EJB as ejb/<ejb-name> inside the <jndi-name> tag.

Migrating EJB Applications that Support SFSB Failover (Enterprise Edition)

Sun ONE Application Server 6.5 supports failover of stateful session beans. To take advantage of the SFSB failover in 6.5, the session bean need to be configured with failover and DSync. The DSync (Distributed Store) mechanism is used to save the session beans’s conversational state during runtime.

Note –

Sun ONE Application Server 6.5 does not support failover of stateful session beans for rich clients on the RMI/IIOP path. Such applications can take advantage of SFSB failover on the RMI/IIOP path in Sun Java System Application Server 8.1. For more information on SFSB failover configuration, see Stateful Session Bean Failover in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide.

Sun Java System Application Server 8.1, Enterprise Edition supports failover of stateful session beans. Application Server 8.1 uses the High Availability Database (HADB) for storing session data. The principle followed in supporting SFSB failover in saving the conversational state of an SFSB at predefined points in its lifecycle to a persistent store. This mechanism is referred to as checkpointing. In case of a server crash, the checkpointed state of an SFSB can be retrieved from the persistent store. In order to use HADB for storing session data, you must configure HADB as the persistent store. The underlying store for the HTTP sessions and stateful session beans is same and the configuration of persistent store is exactly similar to configuration of session store.

For information on configuring HADB for session failover, see Chapter 8, Configuring High Availability Session Persistence and Failover, in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide.

Migration of stateful session beans deployed in Sun ONE Application Server 6.5 to Sun Java System Application Server 8.1 does not require any changes in the EJB code. However, the following steps must be performed:

Modify the <!DOCTYPE definition to point to the latest DTD url in case of J2EE standard DDs, like ejb-jar.xml.
Replace ias-ejb-jar.xml with the modified version of this file, i.e., sun-ejb-jar.xml, which is created manually according to the DTDs.
Replace all the <ejb-name>-ias-cmp.xml files with one sun-cmp-mappings.xml file, which is created manually.
No changes are required in the application source code for taking advantage of the SFSB state failover support. All configuration needed for checkpointing SFSBs will be applied at the Application Server specific deployment descriptor (sun-ejb-jar.xml), or in the domain configuration file (domain.xml).

However, if you are accessing theEJBs through servlets then you need to store the EJB home and remote references in the session. The following is the code example to store ejbHome and ejbRemote interfaces in the session:
```
session.setAttribute("ejbhome", ejbHome);
session.setAttribute("ejbremote", ejbRemote);
```
The following code example demonstrates how to retrieve the ejbHome and ejbRemote from the session:
```
ejbHome = session.getAttribute("ejbhome");
ejbRemote = session.getAttribute("ejbremote");
```
In the domain.xml, make sure that the availability-enabled attribute of availability-service element is set to TRUE. If availability-enabled attribute is set to TRUE indicates that failover is enabled at the server instance level. That is, if a server instance fails to process a request, the request is routed to the next available server instance.

SFSB checkpointing adds performance overhead on the EJB container, you may want to restrict checkpointing to a list of SFSBs whose state failover is critical to the application.

You can enable/disable the checkpointing at the method level in sun-ejb-jar.xml. For more details seeSpecifying Methods to Be Checkpointed in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide.

If, in the deployment descriptor for the SFSB ejb module in 6.5 (ias-ejb-jar.xml), the failoverrequired attribute of the session element is set to TRUE, you might want to enable availability-service for such ejb modules in the Application Server 8.1 environment.

Entity Beans

The <!DOCTYPE> definition must be modified to point to the latest DTDs containing J2EE standard DDs, such as ejb-jar.xml.
Update the <cmp-version> tag with the value 1.1, for all CMPs in the ejb-jar.xml file.
Replace all the <ejb-name>-ias-cmp.xml files with the manually created sun-cmp-mappings.xml file. For more information, see http://wwws.sun.com/software/dtd/appserver/sun-cmp-mapping_1_2.dtd
Generate dbschema by using the capture-schema utility in the Application Server installation’s bin directory and place it above META-INF folder for Entity beans.
Replace the ias-ejb-jar.xml with the sun-ejb.jar.xml in Application Server.
In Application Server 6.5, the finder's SQL was directly embedded into the <ejb-name>-ias-cmp.xml. In Application Server, mathematical expressions are used to declare the <query-filter> for the various finder methods.

Message Driven Beans

Application Server provides seamless Message Driven Support through the tight integration of Sun Java System Message Queue with the Application Server, providing a native, built-in JMS Service.

This installation provides Application Server with a JMS messaging system that supports any number of Application Server instances. Each server instance, by default, has an associated built-in JMS Service that supports all JMS clients running in the instance.

Both container-managed and bean-managed transactions, as defined in the Enterprise JavaBeans Specification, v2.0, are supported.

Message Driven Bean support in iPlanet Application Server was restricted to developers, and used many of the older proprietary APIs. Messaging services were provided by iPlanet Message Queue for Java 2.0. An LDAP directory was also required under iPlanet Application Server to configure the Queue Connection Factory object.

The QueueConnectionFactory, and other elements required to configure Message Driven Beans in Application Server are now specified in the ejb-jar.xml file.

For more information on the changes to deployment descriptors, see Migrating Deployment Descriptors For information on Message Driven Beans see Using Message-Driven Beans in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Developer’s Guide.