Configuring a CMP Entity Bean

As you now appreciate, a substantial part of the implementation effort for CMP Entity beans is simply completing the deployment descriptor correctly.

This will always involve completing the entity element of the deployment descriptor, either manually or using a GUI tool such as deploytool. If the CMP Entity has container-managed relationships, these too must be specified under the relationships element of the deployment descriptor.

The entity Element

To remind you, the structure of the deployment descriptor is as follows:

<!ELEMENT ejb-jar (description?, display-name?, small-icon?, large-icon?,
enterprise-beans, relationships?, assembly-descriptor?, ejb-client-jar?)>

Here you can see the relationships element, with

<!ELEMENT enterprise-beans (session | entity | message-driven)+>

and the entity element defined as

<!ELEMENT entity (description?, display-name?, small-icon?, large-icon?,
ejb-name, home?, remote?, local-home?, local?, ejb-class,
persistence-type,
prim-key-class,
reentrant,
cmp-version?, abstract-schema-name?,
cmp-field*, primkey-field?,
env-entry*,
ejb-ref*, ejb-local-ref*,
security-role-ref*, security-identity?,
resource-ref*,
resource-env-ref*,
query*)>

Looking first at the entity element, much of it will be unchanged. What needs to be specified for a CMP entity are

• cmp-version Always set to 2.0. The value 1.1 is supported only for legacy CMP Entity beans written to the EJB 1.1 specification.

• abstract-schema-name Any unique name, this defines the name used to identify the bean in EJB QL queries. It makes sense to base this on the name of the bean. In the case study, the JobBean bean has a schema with the name of Job.

• cmp-field One for each cmp-field (but not cmr-fields). In the Job bean, the cmp-fields are ref, customer, and description. The location and skills fields are cmr-fields representing relations to the Location and Skill beans respectively, and so do not appear.

• primkey-field This optional field is used when the primkey-class element does not identify a custom primary key class. It is not specified for the Job bean, but for the Location bean, for example, it is specified and is set to name.

• query Defines an EJB QL query, associating it with a finder or select method.

Listing 7.12 shows the entity element for the Job bean.

Listing 7.12. Job Bean's entity Element

 1: <entity>
 2:   <display-name>JobBean</display-name>
 3:   <ejb-name>JobBean</ejb-name>
 4:   <local-home>data.JobLocalHome</local-home>
 5:   <local>data.JobLocal</local>
 6:   <ejb-class>data.JobBean</ejb-class>
 7:   <persistence-type>Container</persistence-type>
 8:   <prim-key-class>data.JobPK</prim-key-class>
 9:   <reentrant>False</reentrant>
10:   <cmp-version>2.x</cmp-version>
11:   <abstract-schema-name>Job</abstract-schema-name>
12:   <cmp-field>
13:     <description>no description</description>
14:     <field-name>ref</field-name>
15:   </cmp-field>
16:   <cmp-field>
17:     <description>no description</description>
18:     <field-name>description</field-name>
19:   </cmp-field>
20:   <cmp-field>
21:     <description>no description</description>
22:     <field-name>customer</field-name>
23:   </cmp-field>
24:   <ejb-local-ref>
25:     <ejb-ref-name>ejb/CustomerLocal</ejb-ref-name>
26:     <ejb-ref-type>Entity</ejb-ref-type>
27:     <local-home>CustomerLocalHome</local-home>
28:     <local>CustomerLocal</local>
29:     <ejb-link>data_entity_ejbs.jar#CustomerBean</ejb-link>
30:   </ejb-local-ref>
31:   <!-- shouldn't be needed, but ctx.getEJBHome() returns null in J2EE RI -->
32:   <ejb-local-ref>
33:     <ejb-ref-name>ejb/JobLocal</ejb-ref-name>
34:     <ejb-ref-type>Entity</ejb-ref-type>
35:     <local-home>JobLocalHome</local-home>
36:     <local>JobLocal</local>
37:     <ejb-link>data_entity_ejbs.jar#JobBean</ejb-link>
38:   </ejb-local-ref>
39:   <security-identity>
40:     <description></description>
41:     <use-caller-identity></use-caller-identity>
42:   </security-identity>
43:   <query>
44:     <description></description>
45:     <query-method>
46:       <method-name>findByCustomer</method-name>
47:       <method-params>
48:         <method-param>java.lang.String</method-param>
49:       </method-params>
50:     </query-method>
51:     <ejb-ql>SELECT OBJECT(j)
52: FROM Job AS j
53: WHERE j.customer = ?1</ejb-ql>
54:   </query>
55:   <query>
56:     <description></description>
57:     <query-method>
58:       <method-name>findByLocation</method-name>
59:       <method-params>
60:         <method-param>java.lang.String</method-param>
61:       </method-params>
62:     </query-method>
63:     <ejb-ql>SELECT OBJECT(o)
64: FROM Job o
65: WHERE o.location.name = ?1</ejb-ql>
66:   </query>
67: </entity>
						

The definition of the query element is as follows:

<!ELEMENT query (description?, query-method, result-type-mapping?, ejb-ql)>

You can see from the listing that the query-method element just identifies the name of the finder or select method. Note that if a finder method is being identified, it is the name appearing in the local-home (or home) interface; that is, without the ejb prefix. On the other hand, if a select method is being identified, there will be an ejb prefix, because select methods never appear in the interfaces of the bean.

The result-type-mapping element applies only if the method identified by query-method has identified a select method, and only then if the EJB QL string returns Entity bean references (that is, if the SELECT [DISTINCT] OBJECT(x) style of select_clause has been used). The allowable values are Local and Remote, indicating whether the clause should return references through the local or remote interfaces. Obviously, if specified, the bean must provide an interface of the appropriate type; if not specified, the bean must provide a local interface, because this is the implied value for the result-type-mapping element.

Of course, all of this deployment information can be entered graphically using the deploytool. Figure 7.8 shows some of the equivalent information for Listing 7.12.

The relationships Element

The relationships element is defined in the EJB 2.0 DTD as follows:

<!ELEMENT relationships (description?, ejb-relation+)>

That is, it consists of one or more ejb-relation elements. These in turn are defined as

<!ELEMENT ejb-relation (description?, ejb-relation-name?,
ejb-relationship-role, ejb-relationship-role)>

which is a somewhat curious definition: an optional description, an optional name, and then precisely two ejb-relationship-role elements. Each of these identifies the role that some bean is playing with respect to the relationship.

The ejb-relationship-role element is defined as follows:

<!ELEMENT ejb-relationship-role (description?, ejb-relationship-role-name?,
multiplicity, cascade-delete?, relationship-role-source, cmr-field?)>

with

<!ELEMENT relationship-role-source (description?, ejb-name)>

You can see that the relationship-role-source element merely identifies an Entity bean by name. This element's name is perhaps somewhat misleading, because it is neither a “source” nor (for that matter) a target within the relationship. The navigability of the relationship comes from the presence (or not) of the cmr-field element. Of course, at least one of the ejb-relationship-role elements must have a cmr-field specified, and if both do, the relationship is bi-directional.

The choices for the multiplicity element are either One or Many. There will be two such elements in the complete ejb-relation element, so this is what gives one-to-one, one-to-many, many-to-one, or many-to-many.

There is also an optional cascade-delete element. Perhaps non-intuitively, this is placed on the “child” (multiplicity = many) side of a relationship.

Finally, the cmr-field is defined as follows:

<!ELEMENT cmr-field (description?, cmr-field-name, cmr-field-type?)>

The cmr-field-name element just names the cmr-field (for example, skills or location for the Job bean). The cmr-field-type element is needed only for multi-valued cmr-fields (for example, skills for the Job bean) and indicates whether the return type is a java.util.Collection or java.util.Set.

Okay! Time for an example or two from the case study to see if all that theory makes sense.

Listing 7.13 shows the ejb-relation element defining the one-to-many relationship between the Location bean and the Job bean.

Listing 7.13. The Location/Job Relationship

 1: <ejb-relation>
 2:     <ejb-relation-name></ejb-relation-name>
 3:     <ejb-relationship-role>
 4:         <ejb-relationship-role-name>JobBean</ejb-relationship-role-name>
 5:         <multiplicity>Many</multiplicity>
 6:         <relationship-role-source>
 7:             <ejb-name>JobBean</ejb-name>
 8:         </relationship-role-source>
 9:         <cmr-field>
10:             <cmr-field-name>location</cmr-field-name>
11:         </cmr-field>
12:     </ejb-relationship-role>
13:     <ejb-relationship-role>
14:         <ejb-relationship-role-name> LocationBean  </ejb-relationship-role-name>
15:         <multiplicity>One</multiplicity>
16:         <relationship-role-source>
17:             <ejb-name>LocationBean</ejb-name>
18:         </relationship-role-source>
19:         <cmr-field>
20:             <cmr-field-name>jobs</cmr-field-name>
21:             <cmr-field-type>java.util.Collection</cmr-field-type>
22:         </cmr-field>
23:     </ejb-relationship-role>
24: </ejb-relation>

Figure 7.9 shows this relationship overlaid onto the implied abstract schema.

Another example; Listing 7.14 shows the ejb-relation element defining the many-to-many relationship between the Job bean and the Skill bean.

Listing 7.14. The Job/Skill Relationship

 1: <ejb-relation>
 2:     <ejb-relation-name></ejb-relation-name>
 3:     <ejb-relationship-role>
 4:         <ejb-relationship-role-name>JobBean</ejb-relationship-role-name>
 5:         <multiplicity>Many</multiplicity>
 6:         <relationship-role-source>
 7:             <ejb-name>JobBean</ejb-name>
 8:         </relationship-role-source>
 9:         <cmr-field>
10:             <cmr-field-name>skills</cmr-field-name>
11:             <cmr-field-type>java.util.Collection</cmr-field-type>
12:         </cmr-field>
13:     </ejb-relationship-role>
14:     <ejb-relationship-role>
15:         <ejb-relationship-role-name> SkillBean </ejb-relationship-role-name>
16:         <multiplicity>Many</multiplicity>
17:         <relationship-role-source>
18:             <ejb-name>SkillBean</ejb-name>
19:         </relationship-role-source>
20:         <cmr-field>
21:             <cmr-field-name>jobs</cmr-field-name>
22:             <cmr-field-type>java.util.Collection</cmr-field-type>
23:         </cmr-field>
24:     </ejb-relationship-role>
25: </ejb-relation>

Figure 7.10 shows these elements overlaid onto the abstract schema.

As always, configuring these deployment descriptor elements can be done either by editing the deployment descriptors directly or by using the deploytool. Figure 7.11 shows the deploytool for the Job/Skill relationship.

To actually deploy the enterprise application, use the buildAll and deploy batch scripts in the day07uild directory, or use buildAll to assemble the enterprise application and deploy from deploytool.

Over the last three days, you have seen Session beans, BMP Entity beans and CMP Entity beans deployed using both the graphical deploytool and then using batch scripts. Clearly, the information held in those deployment descriptors is valuable and should be under source code control. Moreover, the mechanism for building and deploying enterprise applications should be able to use that information rather than recreate it from scratch. This suggests that, for the production environment, the graphical deploytool should be used only for deploying enterprise applications and for configuring J2EE RI servers.

On the other hand, in the development environment, it can be an error-prone task to attempt to write XML deployment descriptors from scratch. If a valid deployment descriptor already exists, modifying it (to add a new ejb-ref element or something similar) can often be accomplished, but larger changes (such as adding a completely new bean) will be more difficult without much practice. Here, deploytool comes into its own to modify the enterprise application as required (or indeed, to create an enterprise application from scratch).

When you are happy that the beans and clients in your enterprise application are correctly configured, deploytool allows the XML deployment descriptor to be saved, for checking into source code control. This is shown in Figure 7.12.

The Tools, Descriptor Viewer menu option brings up a dialog box displaying the XML deployment descriptor; from there, the data can be saved as a file. This menu option is context sensitive, so what it shows will depend on the node selected in the explorer on the left pane in the GUI. The descriptor viewer dialog should be brought up for each node under the enterprise application node, and for the enterprise application node itself. In the case study, this means for each of the clients, for the data Entity EJBs, for the agency Session EJBs, and for the agency application node.