31.5.2. Relationship Declaration
The declaration of relationships in the
ejb-jar.xml
file is complicated and error prone. Although we recommend using a tool like XDoclet to manage the deployment descriptors for CMR fields, it's still important to understand how the descriptor works. The following illustrates the declaration of the organization/gangster relationship:
<ejb-jar> <relationships> <ejb-relation> <ejb-relation-name>Organization-Gangster</ejb-relation-name> <ejb-relationship-role> <ejb-relationship-role-name>org-has-gangsters </ejb-relationship-role-name> <multiplicity>One</multiplicity> <relationship-role-source> <ejb-name>OrganizationEJB</ejb-name> </relationship-role-source> <cmr-field> <cmr-field-name>memberGangsters</cmr-field-name> <cmr-field-type>java.util.Set</cmr-field-type> </cmr-field> </ejb-relationship-role> <ejb-relationship-role> <ejb-relationship-role-name> gangster-belongs-to-org </ejb-relationship-role-name> <multiplicity>Many</multiplicity> <cascade-delete/> <relationship-role-source> <ejb-name>GangsterEJB</ejb-name> </relationship-role-source> <cmr-field> <cmr-field-name>organization</cmr-field-name> </cmr-field> </ejb-relationship-role> </ejb-relation> </relationships> </ejb-jar>
As you can see, each relationship is declared with an
ejb-relation
element within the top level relationships
element. The relation is given a name in the ejb-relation-name
element. This is important because we will need to refer to the role by name in the jbosscmp-jdbc.xml
file. Each ejb-relation
contains two ejb-relationship-role
elements (one for each side of the relationship). The ejb-relationship-role
tags are as follows:
- ejb-relationshiprole-name: This optional element is used to identify the role and match the database mapping the
jbosscmp-jdbc.xml
file. The relationship role names for each side of a relationship must be different. - multiplicity: This indicates the multiplicity of this side of the relationship. The valid values are
One
orMany
. In this example, the multiplicity of the organization isOne
and the multiplicity of the gangster isMany
because the relationship is from one organization to many gangsters. Note, as with all XML elements, this element is case sensitive. - cascade-delete: When this optional element is present, JBoss will delete the child entity when the parent entity is deleted. Cascade deletion is only allowed for a role where the other side of the relationship has a multiplicity of one. The default is to not cascade delete.
- relationship-role-source
- ejb-name: This required element gives the name of the entity that has the role.
- cmr-field
- cmr-field-name: This is the name of the CMR field of the entity has one, if it has one.
- cmr-field-type: This is the type of the CMR field, if the field is a collection type. It must be
java.util.Collection
orjava.util.Set
.
After adding the CMR field abstract accessors and declaring the relationship, the relationship should be functional. The next section discusses the database mapping of the relationship.