Implementing Container-Manager Relationships

In this section, we examine the sample implementations of different kinds of relationships. Later today, we'll design and implement a complete example of one-to-many bidirectional relationship between order and line items.

Implementing One-to-One Relationships

Figure 12.1 shows a StudentEJB entity bean with a one-to-one unidirectional relationship to an AddressEJB entity bean. Student-Address is the name of the relationship. Student-has-address is the role name of the StudentEJB, and Address-belongs-to-student is the role name of the AddressEJB in this relationship.

The following code snippet shows the implementation of the relationship in Figure 12.1 using container-managed relationships:

public abstract class StudentEJB implements EntityBean{
...
public abstract AddressLocal getAddress();
public abstract void setAddress(AddressLocal address);
...
}

StudentEJB declares a public abstract get method, and sets the accessor methods for the address relationship field. Also notice that the methods use the AddressLocal local interface.

AddressEJB, as follows, contains no relationship fields:

public abstract class AddressEJB implements EntityBean{
...
/* no cmr-fields */
}

Because AddressEJB does not know about StudentEJB, there are no accessor methods in AddressEJB for accessing StudentEJB.

The relationship fields must be declared in the deployment descriptor. A single deployment descriptor describes both the entity beans and their relationships. The deployment descriptor corresponding to the Student-Address relationship is written as follows:

<ejb-jar>
  ...
  <enterprise-beans>
  ...
  </enterprise-beans>
  <relationships>
     <ejb-relation>
      <!--ONE-TO-ONE uni-directional : Student Address -->
      <ejb-relation-name>Student-Address</ejb-relation-name>

      <ejb-relationship-role>
        <ejb-relationship-role-name>
          Student-has-address
        </ejb-relationship-role-name>
        <multiplicity>One</multiplicity>
        <relationship-role-source>
          <ejb-name>StudentEJB</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-belongs-to-student
        </ejb-relationship-role-name>
        <multiplicity>One</multiplicity>
        <relationship-role-source>
          <ejb-name>AddressEJB</ejb-name>
        </relationship-role-source>
      </ejb-relationship-role>

    </ejb-relation>
</relationships>
...
</ejb-jar>

The ejb-relation element declares a relationship. The name of the relation Student-Address is declared using the ejb-relation-name element. Each ejb-relation element contains a pair of ejb-relationship-role elements to describe the two roles in the relationship. Each ejb-relationship-role element describes a relationship role: its name, its multiplicity, and its navigability within a relation. Each relationship role refers to an entity bean by means of an ejb-name element contained in the relationship-role-source element. For example, the student side of the relationship declares the Student-has-address role name using the ejb-relationship-role-name element, cardinality of One using the multiplicity element, and StudentEJB as the EJB name using the ejb-name element in the relationship-role-source element. In addition, the student side of the relationship also specifies the container-managed relationship field address using the cmp-field-name element in the cmp-field element. Similarly, the deployment descriptor contains the address side of the relationship. Because the address does not know about the student, there is no cmr-field in address for accessing a student.

Implementing One-to-Many Relationships

Figure 12.2 shows an OrderEJB entity bean with a one-to-many bidirectional relationship to LineItemEJB entity beans. OrderEJB is composed of many LineItemEJBs.

Order-LineItems is the name of this relationship. Order-has-lineitems is the role name of OrderEJB, and Lineitems-belongs-to-order is the role name of LineItemEJB in this relationship.

The following shows the code template for the OrderEJB class:

public abstract class OrderEJB implements EntityBean{
...
public abstract Collection getLineItems();
public abstract void setLineItems(Collection lineItems);
...
}

OrderEJB declares abstract get and set accessor methods for the line items relationship field. You need to use a collection of local interfaces for a collection-valued container-managed relationship field. The getLineItems() method returns a collection of java.util.Collection of LineItemLocal local interfaces. The setLineItems() method takes a collection of entity beans' LineItemLocal local interfaces as an argument.

The following snippet shows the code template for the LineItemEJB class:

public abstract class LineItemEJB implements EntityBean{
...
public abstract OrderLocal getOrder();
public abstract void setOrder(OrderLocal order);
...
}

LineItemEJB declares abstract get and set accessor methods for the order relationship field.

The deployment descriptor corresponding Order-LineItems relationship is written as follows:

<ejb-jar>
  ...
  <enterprise-beans>
  ...
  </enterprise-beans>
  <relationships>
    <!--ONE-TO-MANY bi-directional : Order LineItem -->
    <ejb-relation>
      <ejb-relation-name>Order-LineItems</ejb-relation-name>
      <ejb-relationship-role>
        <ejb-relationship-role-name>
          Order-has-lineitems
        </ejb-relationship-role-name>
        <multiplicity>one</multiplicity>
        <relationship-role-source>
          <ejb-name>OrderEJB</ejb-name>
        </relationship-role-source>
        <cmr-field>
          <cmr-field-name>lineItems</cmr-field-name>
          <cmr-field-type>java.util.Collection</cmr-field-type>
        </cmr-field>
      </ejb-relationship-role>

      <ejb-relationship-role>
        <ejb-relationship-role-name>
          LineItems-belongs-to-order
        </ejb-relationship-role-name>
        <multiplicity>many</multiplicity>
        <relationship-role-source>
          <ejb-name>LineItemEJB</ejb-name>
        </relationship-role-source>
        <cmr-field>
          <cmr-field-name>order</cmr-field-name>
        </cmr-field>
      </ejb-relationship-role>
    </ejb-relation>
</relationships>
...
</ejb-jar>

The deployment descriptor declares the Order-LineItems relation using ejb-relation-name. The order side of the relationship declares the Order-has-lineitems role name with cardinality of One. It also declares StudentEJB as the EJB name using the ejb-name element in the relationship-role-source element. It specifies the container-managed relationship field lineItems using the cmp-field-name element in the cmp-field element. Similarly, the deployment descriptor contains the line items' side of the relationship.

Implementing Many-to-Many Relationships

Figure 12.3 shows a StudentEJB entity bean with a many-to-many bidirectional relationship to a CourseEJB entity bean.

StudentEJB defines the abstract accessor methods for the course relationship field as follows:

public abstract class StudentEJB implements EntityBean{
...
public abstract Collection getCourses();
public abstract void setCourses(Collection courses);
...
}

CourseEJB defines the abstract accessor methods for the student relationship field as follows:

public abstract class CourseEJB implements EntityBean{
...
public abstract Collection getStudents();
public abstract void setStudents(Collection students);
...
}

The deployment descriptor is written as follows:

<ejb-jar>
  ...
  <enterprise-beans>
  ...
  </enterprise-beans>
  <relationships>
    <!--MANY-TO-MANY bi-directional: Student Course  -->
    <ejb-relation>
      <ejb-relation-name>Student-Course</ejb-relation-name>
      <ejb-relationship-role>
        <ejb-relationship-role-name>
          Students-register-in-courses
        </ejb-relationship-role-name>
        <multiplicity>many</multiplicity>
        <relationship-role-source>
          <ejb-name>StudentEJB</ejb-name>
        </relationship-role-source>
        <cmr-field>
          <cmr-field-name>courses</cmr-field-name>
          <cmr-field-type>java.util.Collection</cmr-field-type>
        </cmr-field>
      </ejb-relationship-role>

      <ejb-relationship-role>
        <ejb-relationship-role-name>
          Courses-have-registered-students
        </ejb-relationship-role-name>
        <multiplicity>many</multiplicity>
        <relationship-role-source>
          <ejb-name>CourseEJB</ejb-name>
        </relationship-role-source>
        <cmr-field>
          <cmr-field-name>students</cmr-field-name>
          <cmr-field-type>java.util.Collection</cmr-field-type>
        </cmr-field>
      </ejb-relationship-role>
    </ejb-relation>
</relationships>
...
</ejb-jar>

The student side of the Student-Course relationship declares Students-register-in-courses role name with cardinality of many. It also specifies the container-managed relationship field courses. Similarly, the deployment descriptor also contains the course side of the relationship.