Configuring table-mapping properties  Chapter 28: Configuring Persistence for Stateful Session Components

Chapter 27: Creating Entity Components

Using relationship components

EAServer uses relationship components to manage relationships between EJB 2.0 CMP entity beans.

EBJ 2.0 CMP entity beans can have container-managed relationships. A relationship allows an entity component to have a container-managed field that contains instances of another (or the same) entity component. For example, an Order component may have an items field that consists of a collection of Inventory objects representing the items being purchased. Or, an Employee component may be related to itself, with manager and employees fields that contain Employee instances.

A relationship can be unidirectional or bidirectional. For example, the Employee-Manager relationship is typically bidirectional: it’s convenient to know who works for a particular employee as well as who reports to that employee. An Order-Inventory relationship is typically unidirectional: it would not be practical to track every order that a line item is added to.

The relationship component name contains one or more hyphens. Only relationship components may have names that contain hyphens. Relationship components created by deploying EJB-JAR files have names of the form:

component1-component2

Or:

component-field

Where component1 and component2 are names of two related components. The component-field form is used when a component is related to itself (such as the employee-manager relationship). In this case,. field is the field name used for maintaining one side of the relationship. For example, an Employee component may have a Manager field, resulting in the relationship component Employee-Manager.

Relationship components are supported only for EJB 2.0 CMP entity beans. Relationship components are themselves CMP entity beans, and must have the relationship properties described below. Related components must be in the same EAServer package. The implementation of a relationship component is generated when you generate skeletons for the components in the relationship.

Maintaining the relationship

The tables represented by related components must be related in the database. There are two techniques to maintain the table relationship:

Foreign keys offer the best performance, but can be used only when one destination instance relates to a given source instance. For example, you can use foreign keys to manage the Employee-to-Manager relationship (an employee has one manager), but must use a join table for the Manager-to-Employee relationship (a manager has many employees). In bidirectional relationships, you must configure the technique for each direction of the relationship.

The Table field in the Persistence/General properties specifies the name of the join table. When configuring components to work with existing database tables, the join table must exist and contain the key pairs to describe the relationship.

Cascading deletes

In some cases, you may want an ejbRemove operation to delete “through” a relation. For example, an Order instance represents an online purchase, and is related to LineItem instances that represent items included in the order. In this case, removal of an Order instance should remove LineItem instances contained in the order.

You can configure the Cascade Delete properties for each side of a one-to-one relationship, and on the “one” side of many-to-one and one-to-many relationships.

Configuring relationship component properties

To configure relationship properties, display the Component Properties for the relationship component, then display the Persistence/Relationship subtab and configure the Relationship Type settings and Relationship Name settings, described in Table 27-4 and Table 27-5, respectively.

NoteRegenerating the relationship component After editing relationship component properties, regenerate the skeletons for the package and refresh the package to ensure the changes take effect.

Table 27-4: Relationship Type properties

Property

Specifies

Type

The cardinality of the relationship. Allowable values are:

  • One to One – one from component instance is related to one to instance.

  • One to Many – one from instance is related to many to instances.

  • Many to One – many from instances are related to one to instance.

  • Many to Many – many from instances are related to many to instances.

From Component

The name of the from component in the relationship, in the form:

package/component

The from component contains a container-managed field that contains instances of the to component specified by the To Component property.

From Field

The name of the container-managed field in the from component that contains related to component instance references.

From Field Type

For one-to-many and many-to-many relationships, specifies the Java type used in the getter and setter methods of the from component. Allowable values are Collection and Set.

For single-valued fields, no value is required. You can set this property by setting the from-field-type property on the Advanced tab.

From Query

When a join table is used, the name of a query used to select the to component’s primary keys that are required to populate the from component field indicated by the From Field setting. This query must be defined by a query mapping property, as described in “Specifying finder- and ejbSelect-method queries”.

From Role

Matches the name of the corresponding ejb-relationship-role element in the EJB-JAR deployment descriptor.

Use Foreign Key

Whether to use a join table or foreign keys to maintain the to-from relationship. A value of true indicates that foreign keys must be used.

You can use foreign keys only on the “one” side of a relationship, as described in “Maintaining the relationship”.

Cascade Delete

Applies only when the relationship-type is one-to-one or one-to-many.

Specifies whether deletion of a an instance on the singleton side of the relation causes deletion of the related instance.

Table 27-5: Relationship Name properties

Property

Specifies

Name

The name of the relationship. Matches the corresponding ejb-relation-name element in the EJB-JAR deployment descriptor.

To Component

The name of the to component in the relationship, in the form:

package/component

For bidirectional relationships, you must also specify values for the To Field, To Field Type, and To Query properties.

To Field

The name of the container-managed field in the to component that contains related from component instance references.

To Field Type

If a to instance can be related to multiple from instances, specifies the Java type used in the getter and setter methods of the from component. Allowable values are Collection and Set.

For single-valued fields, no value is required. You can set this property by setting the to-field-type property on the Advanced tab.

To Query

When a join table is used, the name of a query used to select the from component’s primary keys that are required to populate the to component field indicated by the To Field setting. This query must be defined by a query mapping property, as described in “Specifying finder- and ejbSelect-method queries”.

To Role

Matches the name of the corresponding ejb-relationship-role element in the EJB-JAR deployment descriptor.

Use Foreign Key

Whether to use a join table or foreign keys to maintain the from-to relationship. Enable the option if foreign keys must be used.

You can use foreign keys only on the “one” side of a relationship, as described in “Maintaining the relationship”.

Cascade Delete

Applies only when the relationship-type is one-to-one or many-to-one.

Specifies whether deletion of a an instance on the singleton side of the relation causes deletion of the related instance.

Example properties for a many-to-many bidirectional relationship

The components here are TestCMP/Customer and TestCMP/Account:

relationship-type=many-to-many
relationship-name=Customer-Account
relationship-from=TestCMP/Customer
relationship-to=TestCMP/Account
from-field=accounts
from-field-type=Collection
from-foreign-key=true
from-query=findByCustomer
from-role=customer-has-accounts
to-field-type=Collection
to-field=customers
to-foreign-key=true
to-query=findByAccount
to-role=account-has-customers
cascade-delete=false

Example properties for a recursive, bidirectional, many-to-one relationship

The component here, TestCMP/Employee, is related to itself:

relationship-type=many-to-one
relationship-name=Employee-Manager
relationship-from=TestCMP/Employee
relationship-to=TestCMP/Employee
from-field=managerField
from-foreign-key=true
from-query=findByEmployees
from-role=employees-has-manager
to-field=employeesField
to-field-type=Collection
to-foreign-key=true
to-query=findByManager
to-role=manager-has-employees
cascade-delete=false




Copyright © 2005. Sybase Inc. All rights reserved. Chapter 28: Configuring Persistence for Stateful Session Components