Configuring a Container-Managed Relationship Field for an EJB 2.1 Entity Bean With Container-Managed Persistence

You do not define container-managed relationship fields in the entity bean class: container-managed relationship fields are virtual only. OC4J supplies the implementation of the container-managed relationship fields.

You must define public, abstract getter and setter methods for the container-managed relationship fields in the local interface of the related entity bean, using the EJB conventions (see "Using Java"). OC4J supplies the implementation of these methods. You must not expose these getter and setter methods in the remote interface of the entity bean.

You may assign only the following Java types to container-managed relationship fields: Java primitive types and Java serializable types. You may assign an entity bean local interface type (or a collection of such) to a container-managed relationship field.

You must specify container-managed relationship fields in the ejb-jar.xml deployment descriptor using the cmr-field element (see "Using Deployment XML"). The names of these fields must be valid Java identifiers and must begin with a lowercase letter, as determined by java.lang.Character.isLowerCase.

The accessor methods must bear the name of the container-managed relationship field (cmr-field) that is specified in the deployment descriptor, and in which the first letter of the name of the cmr-field has been upper cased and prefixed by get or set.

The accessor methods for container-managed relationship fields for one-to-many or many-to-many relationships must utilize one of the following collection interfaces: java.util.Collection or java.util.Set. The collection interfaces used in relationships are specified in the deployment descriptor. The implementation of the collection classes used for the container-managed relationship fields is supplied by the container. The collection classes that are used for container-managed relationships must not be exposed through the remote interface of the entity bean.

For more information, see the following:

Using OC4J and the TopLink persistence API, you can configure how container-managed relationship fields are mapped to your relational schema. For more information, see the following:

"Customizing the TopLink EJB 2.1 Persistence Manager"
"Understanding Relational Mappings" in the Oracle TopLink Developer's Guide

Using Java

Example 14-6 shows the abstract getter and setter methods for the container-managed relationship fields specified in the ejb-jar.xml file (see "Using Deployment XML").

Example 14-6 EJB 2.1 Container-Managed Relationship Fields

package cmpapp;

import javax.ejb.*;
import java.rmi.*;

public abstract class EmployeeBean implements EntityBean {

    private EntityContext ctx;

    // container-managed persistent fields accessors
    public abstract Integer getEmpNo();
    public abstract void setEmpNo(Integer empNo);
 
    public abstract String getEmpName();
    public abstract void setEmpName(String empName);
 
    public abstract Float getSalary();
    public abstract void setSalary(Float salary);

    public abstract void setProjects(Collection projects);
    public abstract Collection getProjects();
...
}

Using Deployment XML

Example 14-7 shows the cmr-field elements for the getter and setter methods specified in the bean class (see "Using Java").

Example 14-7 ejb-jar.xml for an EJB 2.1 Container-Managed Relationship Field

...
    <relationships>
        <ejb-relation>
            <ejb-relation-name>Topic-Faqs</ejb-relation-name>
            <ejb-relationship-role>
                <ejb-relationship-role-name>Topic-has-Faqs</ejb-relationship-role-name>
                <multiplicity>Many</multiplicity>
                <relationship-role-source>
                    <ejb-name>TopicBean</ejb-name>
                </relationship-role-source>
                <cmr-field>
                    <cmr-field-name>faqs</cmr-field-name>
                    <cmr-field-type>java.util.Collection</cmr-field-type>
                </cmr-field>
            </ejb-relationship-role>
        <ejb-relation>
...
    <relationships>