Configuring and Deploying a BMP Entity Bean
Yesterday, you learned how to deploy Session beans by creating ejb-jar files with their own deployment descriptor and including the ejb-jar into an enterprise application. Deploying Entity beans is done in precisely the same way, by creating ejb-jar files that contain the Entity bean classes, with appropriate entries in the deployment descriptor. This deployment descriptor is the same deployment descriptor as for Session beans. As you saw yesterday, the root element of this deployment descriptor is the ejb-jar element:
<!ELEMENT ejb-jar (description?, display-name?, small-icon?, large-icon?, enterprise-beans, relationships?, assembly-descriptor?, ejb-client-jar?)>
Looking at the enterprise-beans element, this is defined as follows:
<!ELEMENT enterprise-beans (session | entity | message-driven)+>
The deployment descriptor can contain Session, Entity, and/or Message-driven beans. Or put another way, Session beans and Entity beans can be placed in the same ejb-jar if required.
Entity Element
The entity element of the DTD is defined as follows:
<!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*)>
Many of the elements referred by the entity element are also used by the session element, and were discussed yesterday:
Presentational elements— description, display-name, small-icon, and large-icon.
Elements describing the components of the bean— ejb-name, home, remote, local-home, local, and ejb-class elements. The local-home and local elements just name the interfaces that extend javax.ejb.EJBLocalHome and javax.ejb.EJBLocal, respectively.
Elements referring to the environment and other resources— env-entry, ejb-ref, ejb-local-ref, resource-ref, and resource-env-ref.
The remaining elements are specific to Entity beans:
persistence-type Set to Bean for bean-managed persistence or Container for container-managed persistence. For the purposes of today, this will be set to Bean.
prim-key-class This mandatory element indicates the name of the primary key class. This will be a custom developed class for beans that have primary keys (JobPK for Job bean) but may be a regular class (java.lang.String) for others (for example, the Location bean).
cmp-version, abstract-schema-name, cmp-field, prim-key-field, query These are used only for CMP beans and are covered tomorrow.
reentrant Set to true for reentrant Entity beans, or false for non reentrant beans. It's safer to mark Entity beans as non reentrant.
security-role-ref, security-identity You will learn more about security on Day 15.
Listing 6.12 shows the deployment descriptor for the Job bean.
Listing 6.12. entity Element Descriptor for the Job Bean
Note the resource-ref dependency on jdbc/Agency, just as you saw for Session beans that make JDBC calls. The res-ref-name is the coded name jdbc/Agency that appears in the setEntityContext() method of JobBean. This logical reference is mapped to the physical resource through the auxiliary deployment descriptor agency_ea-sun-j2ee-ri.xml. There are also ejb-ref dependencies on various other beans; these are ultimately used to manage the relationships with the Location, Skill, and Customer beans.
All of this information can be seen through the J2EE RI deploytool GUI, as shown in Figure 6.9.
Figure 6.9. The deploytool GUI displays deployment descriptor information graphically.
Good though the deploytool GUI is, sometimes a command-line interface is required. For example, you might want to automatically compile and then re-deploy your enterprise application in a project as part of a nightly build. Luckily, the deploytool also provides a command-line interface, so today you will deploy the Entity beans using this mechanism.
Under day06agency, the directory structure has been organized into a number of subdirectories, as shown in Table 6.2.
To deploy the enterprise application, start Cloudscape and the J2EE RI, and then type
> cd day06agencyuild > buildAll > deploy
It's as simple as that!
One of the benefits of this approach is that bean developers, application assemblers and deployers who are familiar with the standard EJB deployment descriptors can modify the bean's deployment configuration by simply editing the XML deployment descriptors directly—without having to get to grips with the J2EE RI GUI. Moreover, some of the names automatically assigned by the deploytool GUI, such as the names of the ejb-jar files themselves, can be given more descriptive names. Consequently, the ejb-jar that contains the Entity beans is called data_entity_ejbs.jar and its deployment descriptor is called data_entity_ejbs_ejb-jar.xml.
If you look in the dd directory (or in the deploytool GUI as shown in Figure 6.9), you can see that the case study separates out the Session beans and the Entity beans into two different ejb-jars. The Agency ejb-jar contains the same set of Session beans that you saw yesterday (although their implementation is different as you shall see shortly, they now delegate to the Entity beans), while the Data ejb-jar has the new BMP Entity beans. How you choose to organize your enterprise application is up to you.