Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide 10g (9.0.4) Part Number B10324-01 |
|
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:
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:
The following changes are basic to all applications that use EJB 2.0 features:
To use EJB 2.0, the EJB deployment descriptor requires the following changes:
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.
<cmp-version>
element to 2.x within the body of the <entity>
element.
<entity> ... <cmp-version>2.x</cmp-version>
... </entity>
<entity> ... <abstract-schema-name>Topping</abstract-schema-name> ... </entity>
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:
public class EmployeeBean implements javax.ejb.EntityBean
{
..
}
becomes
publicabstract
class EmployeeBean implements javax.ejb.EntityBean
{
..
}
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);
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.
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.
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.
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.
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.
|
Copyright © 2002, 2003 Oracle Corporation. All Rights Reserved. |
|