Specifying Bean Relationships in the JBoss CMP Descriptor File
For each relationship defined in the EJB jar descriptor, the JBoss CMP descriptor must contain one <ejb-relation> child element in the <relationships> element. Each <ejb-relation> element can contain the following child elements:

• <ejb-relation-name> (required). Relationship name, which must correspond to a relationship name in the EJB jar descriptor.
• <foreign-key-mapping>. Indicator that foreign keys should be used to map the related entities. This element has no value and is required for one-to-many and many-to-one relationships.
• <relational-table-mapping>. Indicator that a join table should be used to map the related entities. This element is required for many-to-many relationships. The join table is specified with <table-name>.
• <ejb-relationship-role> (required). Defines a relationship role. One of these elements should be specified for each entity in the relationship.

Each <ejb-relationship-role> element contains:

• <ejb-relationship-role-name> (required). Role name, which must correspond to a role name in the EJB jar descriptor.
• <fk-constraint>. Indicator that a foreign key constraint should be added to the table.
• <read-ahead>. Indicator that read-ahead caching should be used.
• <key-fields> (required). Mapping of foreign key fields. This element contains one <key-field> element for each foreign key field. The field in the source entity is specified with <field-name>,and the column in the destination entity's table is specified with <column-name>. Also, this element must be empty for the child role.

JBlog's JBoss CMP descriptor contains one <ejb-relation> element for the relationship Author-Story.

 // The Author-Story relation element in JBoss CMP descriptor
<ejb-relation>
<ejb-relation-name>Author-Story</ejb-relation-name>
<foreign-key-mapping/>
<ejb-relationship-role>
<ejb-relationship-role-name>author-stories</ejb-relationship-role-name>
<key-fields>
<key-field>
<!-- Note: Field in Author. -->
<field-name>username</field-name>
<!-- Note: Column in Story table. -->
<column-name>username</column-name>
</key-field>
</key-fields>
</ejb-relationship-role>
<ejb-relationship-role>
<ejb-relationship-role-name>stories-author</ejb-relationship-role-name>
<key-fields/>
</ejb-relationship-role>
</ejb-relation>

As you can see from the code and configuration file sections listed in this article, entity beans that use CMP don't require much code; however, to achieve that code simplicity, bean configuration is extremely complex (far too complex, in my opinion). To compound the problem, because so much of the substance of a bean lies in the configuration files rather than the code, many errors are undetectable until deployment or runtime; therefore, you can lose many hours searching through the JBoss server log for clues to the cause of the errors. When developing your own entity beans using CMP and JBoss, keep in mind that everything depends on correct configuration.