C
Migration From EJB 1.1 to EJB 2.0 Container Managed Persistence

Previous to Oracle9iAS Release 2 (9.0.3), container managed persistence and relationships were defined in the Oracle-specific deployment descriptor, which employed an Oracle-specific implementation of EJB 2.0 features that had not been completely designed at that time. For example, you used to define a finder method with its SQL statement in the orion-ejb-jar.xml file; currently, you define finder methods using EJBQL SQL within the ejb-jar.xml file. The following sections describe how to migrate the Oracle-specific EJB 2.0 features to the actual EJB 2.0 specification methodology:

Introduction to Migrating EJB 1.1 Applications to EJB 2.0

The most significant change in the EJB 2.0 specification was in both Container Managed Persistence (CMP) and Container Managed Relationships (CMR). Beginning in Oracle9iAS Release 2 (9.0.3), OC4J is J2EE 1.3 compatible and implements the entire EJB 2.0 specification. Prior versions of Oracle9iAS provided an Oracle-specific implementation for some of the EJB 2.0 features before the EJB 2.0 specification was complete. Now that the EJB 2.0 specification is final, applications using these Oracle-specific preview features should be modified to use the EJB 2.0 functionality.

This document guides you to migrate any EJB applications that use the Oracle-specific preview features to using the standard EJB 2.0 functionality--specifically for the EJB 2.0 CMP and CMR features. You only need to read this document if you used CMP based entity beans and any of the following features:

relationships between entity beans
dependent objects and database table mappings

Use EJB 2.0 Deployment Descriptor Identification

The following changes are basic to all applications that use EJB 2.0 features:

Change your EJB deployment descriptor.

To use EJB 2.0, the EJB deployment descriptor requires the following changes:
1. Update the DOCTYPE tag to specify the EJB 2.0 DTD, which validates the document, as follows:
```
<!DOCTYPE ejb-jarPUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise 
JavaBeans 2.0//EN" "http://java.sun.com/dtd/ejb-jar_2_0.dtd">
```
  This tells the XML parser to validate your ejb-jar.xml file using the EJB 2.0 DTD.
2. Configure the EJB container to use the EJB 2.0 CMP mechanism. Specify the <cmp-version> element to 2.x within the body of the <entity> element.
```
<entity>
  ...
  <cmp-version>2.x</cmp-version>

  ...
</entity>
```
3. Provide an abstract schema name for your bean. This name is used within EJBQL queries to refer to the bean.
```
<entity>
  ...
  <abstract-schema-name>Topping</abstract-schema-name>
  ...
</entity>
```

Use Abstract Bean Implementations

In EJB 2.0, entity beans that use CMP are defined as abstract beans. You must provide only the definition of the bean class, not the code implementation. During deployment, the container looks at the deployment descriptor and the methods you have defined for the bean, and then generates the required implementation class for your abstract bean definition. The container-generated implementation defines the instance fields required to hold the bean state and the accessor methods used to manipulate the state of the bean. Thus, the container is more intimately involved with the operations that are being performed on the bean and puts the container in a position to make optimizations on the way it is managing and controlling the bean.

To make an existing bean class abstract, do the following:

Change the definition of your bean class so that it is now declared as an abstract class.

public class EmployeeBean implements javax.ejb.EntityBean

{

  ..

}

becomes

public abstract class EmployeeBean implements javax.ejb.EntityBean

{

  ..

}

Replace the instance fields you use to hold the entity bean state with abstract accessor methods. Change the method signature to add the abstract keyword and remove the code from the method body. The container generates the code required to get and set the values for the instance fields.

For example, the standard EJB 1.1 accessor model for the age field:
```
public int getAge()

{

  return _age;

}



public void setAge(int age)

{

  this._age = age;

}
```
become the following in the EJB 2.0 accessor model:
```
public abstract int getAge();

public abstract setAge(int age);
```
For any non-accessor methods in the bean implementation, modify any code that directly accesses the instance fields to use the corresponding get or set accessor method instead. Since the instance fields are no longer defined directly in the bean class, the fields cannot be used to obtain and manipulate the state of the bean. Instead, the accessors methods must be used to access the bean fields.

Use Standard EJB 2.0 Relationships

Prior to Oracle9iAS Release 2 (9.0.3), the relationships in object models were supported using Oracle-specific mechanisms, which was based on an early version of the EJB 2.0 specification. You could program simple one-to-many relationships within the bean implementation class. You could construct more complex object models that used dependent objects, other entity beans, or collections of objects through configuring the Oracle-specific EJB deployment descriptor. None of these approaches resulted in the creation of a portable EJB application.

In this release, OC4J provides a fully compliant implementation; thus, you should migrate any code you have that uses the Oracle-specific relationship mechanisms to use the standard EJB 2.0 mechanism.

The Oracle-specific relationships are defined with the <cmp-field-mapping> element in the orion-ejb-jar.xml file. Each relationship must be removed and redefined using the <relationship> element in the ejb-jar.xml file. In the EJB 2.0 specification, a relationship between two objects (entity beans) is defined using the <relationship> element in the standard ejb-jar.xml deployment descriptor. This relationship is automatically managed by the EJB container and is deployable to any J2EE product that supports EJB 2.0.

The following example is an EJB 2.0 configuration of a one-to-many relationship. A single department has multiple employees. The department is implemented in the DeptBean; the employee is implemented within the EmpBean. See Chapter 3, "CMP Entity Beans" for information on container managed persistence; see Chapter 4, "Entity Relationship Mapping" for more information on relationships.

<ejb-relation>
 <ejb-relation-name>Dept-Emps</ejb-relation-name>
 <ejb-relationship-role>
  <ejb-relationship-role-name>Dept-has-Emps</ejb-relationship-role-name>
  <multiplicity>One</multiplicity>
  <relationship-role-source>
    <ejb-name>DeptBean</ejb-name>
  </relationship-role-source>
  <cmr-field>
    <cmr-field-name>employees</cmr-field-name>
    <cmr-field-type>java.util.Collection</cmr-field-type>
  </cmr-field>
 </ejb-relationship-role>
 <ejb-relationship-role>
  <ejb-relationship-role-name>Emps-have-Dept</ejb-relationship-role-name>
  <multiplicity>Many</multiplicity>
  <relationship-role-source>
   <ejb-name>EmpBean</ejb-name>
  </relationship-role-source>
  <cmr-field><cmr-field-name>dept</cmr-field-name></cmr-field>
 </ejb-relationship-role>
</ejb-relation>

Each entity bean that forms part of a relationship specified within the ejb-jar.xml file must be deployed within the same EJB-JAR file.

Use Local Interfaces for Beans with Relationships

Oracle recommends that the entity beans inside the EJB-JAR file are constructed using local interfaces. Your client can look up a local interface from components that are deployed within the same application (the same JAR file) and are running inside the same OC4J JVM.

All entity beans should be modified to provide the local interface to their clients, in addition to the remote interface.

Use EJB Query Language (EJBQL)

In the Oracle9iAS version previous to Release 2 (9.0.3), all finder methods and its SQL were defined in an Oracle-specific manner in the orion-ejb-jar.xml file using the <finder-method> element. Once the EJB 2.0 specification was complete, this Oracle-specific methodology was not necessary anymore. As denoted in Chapter 5, "EJB Query Language", your pre-existing finder methods will still work, if you do not want to change them. However, you can eliminate them and use the EJB 2.0 method for finders within the <query> element in the ejb-jar.xml file. These finder methods use EJBQL to define the SQL for the queries.

The following is an example of an EJBQL finder method where the SQL selects all departments.

<query>
 <description></description>
 <query-method>
  <method-name>findAll</method-name>
  <method-params/>
 </query-method>
 <result-type-mapping>Local</result-type-mapping>
 <ejb-ql>Select OBJECT(d) From Dept d</ejb-ql>
</query>

At deployment time, the EJB deployment descriptor (ejb-jar.xml file) is parsed. If it is available, the Oracle-specific deployment descriptor (orion-ejb-jar.xml file) is also parsed. If the orion-ejb-jar.xml file is not provided, one is created for you with the defaults and other configuration based upon what you configured in the ejb-jar.xml file. In the case of EJBQL, the SQL is placed in the orion-ejb-jar.xml file. You can customize your SQL further by modifying the orion-ejb-jar.xml file.

Example C-1 One-to-One Unidirectional

Below are the elements from the ejb-jar.xml file that describe the one-to-one unidirectional relationship between an employee and an address. The employee is represented by the EmpBean EJB and the address by the AddressBean EJB.

<ejb-relation>
	<ejb-relation-name>Emp-Address</ejb-relation-name>
	<ejb-relationship-role>
		<ejb-relationship-role-name>Emp-has-Address
		</ejb-relationship-role-name>
		<multiplicity>One</multiplicity>
		<relationship-role-source>
			<ejb-name>EmpBean</ejb-name>
		</relationship-role-source>
		<cmr-field>
			<cmr-field-name>address</cmr-field-name>
		</cmr-field>
	</ejb-relationship-role>
	<ejb-relationship-role>
		<ejb-relationship-role-name>Address-has-Emp
		</ejb-relationship-role-name>
		<multiplicity>One</multiplicity>
		<cascade-delete/>
		<relationship-role-source>
			<ejb-name>AddressBean</ejb-name>
		</relationship-role-source>
	</ejb-relationship-role>
</ejb-relation>

There are two main differences between this example and the one-to-many relationship. Both sides of the relationship have the multiplicity of One to define the one-to-one nature. Secondly the Address relation does not have a <cmr-field> element. This means that the relationship is unidirectional.

Conclusion

Modeling relationships between EJBs was not simple with EJB 1.1. As of EJB 2.0, the definition of relationships and persistence was addressed. We also strongly recommend that you try Oracle JDeveloper, which provides alternative methods with wizards to alleviate the tedious and error prone manual method of managing the deployment descriptors. You can download JDeveloper at the following site: http://otn.oracle.com/software/products/jdev/content.html.

CMigration From EJB 1.1 to EJB 2.0 Container Managed Persistence