- Overview
- The javax.ejb Package for Entity Beans
- Entity Bean Types
- Remote Versus Local Interfaces
- BMP Entity Bean Lifecycle
- Specifying a BMP Entity Bean
- Implementing a BMP Entity Bean
- Configuring and Deploying a BMP Entity Bean
- Client's View
- Session Beans Revisited
- Patterns and Idioms
- Gotchas
- Summary
- Q&A
- Exercises
This chapter is from the book
This chapter is from the book
This chapter is from the book
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 (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. There's more on this topic on Day 8, as part of the coverage of transactions.
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
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>Bean</persistence-type> 8: <prim-key-class>data.JobPK</prim-key-class> 9: <reentrant>False</reentrant> 10: <ejb-local-ref> 11: <ejb-ref-name>ejb/SkillLocal</ejb-ref-name> 12: <ejb-ref-type>Entity</ejb-ref-type> 13: <local-home>data.SkillLocalHome</local-home> x <local>data.SkillLocal</local> 15: <ejb-link>data_entity_ejbs.jar#SkillBean</ejb-link> 16: </ejb-local-ref> 17: <ejb-local-ref> 18: <ejb-ref-name>ejb/LocationLocal</ejb-ref-name> 19: <ejb-ref-type>Entity</ejb-ref-type> 20: <local-home>data.LocationLocalHome</local-home> 21: <local>data.LocationLocal</local> 22: <ejb-link>data_entity_ejbs.jar#LocationBean</ejb-link> 23: </ejb-local-ref> 24: <ejb-local-ref> 25: <ejb-ref-name>ejb/CustomerLocal</ejb-ref-name> 26: <ejb-ref-type>Entity</ejb-ref-type> 27: <local-home>data.CustomerLocalHome</local-home> 28: <local>data.CustomerLocal</local> 29: <ejb-link>data_entity_ejbs.jar#CustomerBean</ejb-link> 30: </ejb-local-ref> 31: <security-identity> 32: <description></description> 33: <use-caller-identity></use-caller-identity> 34: </security-identity> 35: <resource-ref> 36: <res-ref-name>jdbc/Agency</res-ref-name> 37: <res-type>javax.sql.DataSource</res-type> xx <res-auth>Container</res-auth> 39: <res-sharing-scope>Shareable</res-sharing-scope> 40: </resource-ref> 41: </entity>
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 LocationBean. 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.
){kind=link}
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 day06\agency, the directory structure has been reorganized into a number of subdirectories, as shown in Table 6.2.
Table 6.2—Directory Structure under day06\agency.
|
Subdirectory |
Contents |
|
build |
a) buildAll, which calls most of the other scripts in this directory, except b) deploy, which deploys the enterprise application. |
|
src |
Java source for the client, agency, and data packages. |
|
dd |
Standard XML deployment descriptors for the EJBs, for the enterprise application, and for the application clients. This directory also contains auxiliary deployment descriptors used by the J2EE RI to map the logical references in the standard deployment descriptors to the physical runtime environment managed by the J2EE RI container. |
|
classes |
Compiled Java classes. The various compile* scripts in the build directory compile into this directory. |
|
jar |
ejb-jar and ear (Enterprise Application) archives. Generated by the various build* scripts in the build directory. |
|
run |
The scripts to run the various clients. |
To deploy the enterprise application, start Cloudscape and the J2EE RI, and then type
> cd day06\agency\build > 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.