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, and with appropriate entries in the deployment descriptor. This same deployment descriptor is used for both Session and Entity beans. Session beans and Entity beans can be placed in the same ejb-jar if required.

Entity Element

Most of the deployment descriptor elements referred by the entity element are also used by the session element and were discussed yesterday. Using the deploytool GUI interface to define an Entity Bean follows the same dialog screens as for a Session bean. Figure 6.9 shows the screen for defining the Local Home Interface and Local Interface class names when defining an Entity bean.

Figure 6.9. Defining an Entity bean with deploytool.

[View full size image]

The only additional deploytool dialogue screen used when defining an Entity bean is for determining the persistence management. Figure 6.10 shows the persistence dialogue for selecting BMP.

Figure 6.10. Selecting Bean Managed Persistence (BMP) using deploytool.

[View full size image]

The dialogue screen in Figure 6.10 shows that the a BMP Entity bean requires the Primary Key Class name (in this case data.JobPK). Remember to include the full package name along with the class name.

Defining the Job Entity bean has added the following entry to the ejb-jar.xml DD file:

<ejb-jar>
  <enterprise-beans>
...
    <entity>
							<ejb-name>JobBean</ejb-name>
							<local-home>data.JobLocalHome</local-home>
							<local>data.JobLocal</local>
							<ejb-class>data.JobBean</ejb-class>
							<persistence-type>Bean</persistence-type>
							<prim-key-class>data.JobPK</prim-key-class>
							<reentrant>false</reentrant>
...
    </entity>
  </enterprise-beans>
...
</ejb-jar>

The Job Entity bean requires a resource reference for the jdbc/Agency datasource and is defined in the same way as the Agency Session bean resource reference shown yesterday. The resource reference added to the deployment descriptor is

<ejb-jar>
  <enterprise-beans>
...
    <entity>
      <ejb-name>JobBean</ejb-name>
...
      <resource-ref>
							<res-ref-name>jdbc/Agency</res-ref-name>
							<res-type>javax.sql.DataSource</res-type>
							<res-auth>Container</res-auth>
							<res-sharing-scope>Shareable</res-sharing-scope>
							</resource-ref>
    </entity>
  </enterprise-beans>
...
</ejb-jar>

The corresponding entry in the Sun-specific sun-ejb-jar.xml deployment descriptor is

<sun-ejb-jar>
  <enterprise-beans>
    <name>Entity</name>
...
    <ejb>
							<ejb-name>JobBean</ejb-name>
							<jndi-name>ejb/JobLocal</jndi-name>
							<resource-ref>
							<res-ref-name>jdbc/Agency</res-ref-name>
							<jndi-name>jdbc/Agency</jndi-name>
							<default-resource-principal>
							<name>pbPublic</name>
							<password>pbPublic</password>
							</default-resource-principal>
							</resource-ref>
							</ejb>
...
  </enterprise-beans>
</sun-ejb-jar>

To complete the definition for the Job Entity bean, it requires EJB references to the local interfaces of the Customer, Location and Skill Entity beans. Local EJB references are defined using the EJB Refs dialog page, as shown in Figure 6.11.

Figure 6.11. Defining local EJB References using deploytool.

[View full size image]

Local EJB references require the coded name, a local-home and a local interface definition in the same way that remote EJB references require a coded name, a home and a remote interface definition. The difference between remote and local references occurs in how to map the EJB reference onto the real EJB, as shown in the deploytool Sun-specific settings at the bottom of Figure 6.11. A local EJB reference defines the target JAR and bean name of the EJB rather than its JNDI name, and this value is stored in the deployment descriptor (shown below). There is no platform-specific deployment descriptor entry for mapping a local EJB Reference because all the information is in the portable deployment descriptor.

The entry for the Customer local EJB reference in the DD file is

<ejb-jar>
  <enterprise-beans>
...
    <entity>
      <ejb-name>JobBean</ejb-name>
      <resource-ref>
        <res-ref-name>jdbc/Agency</res-ref-name>
...
      <ejb-local-ref>
        <ejb-ref-name>ejb/CustomerLocal</ejb-ref-name>
        <ejb-ref-type>Entity</ejb-ref-type>
        <local-home>data.CustomerLocalHome</local-home>
        <local>data.CustomerLocal</local>
        <ejb-link>data-entity-ejb.jar#CustomerBean</ejb-link>
      </ejb-local-ref>
...
    </entity>
  </enterprise-beans>
...
</ejb-jar>

Both deployment descriptors for the case study Entity beans can be found in the directory Day06/agency/dd/agency/entity in the case study on the accompany Web site.

Additionally, you will need to add transaction semantics (see Day 8) to the <assembly-descriptor> section of the DD. This is done using the deploytool Transaction dialogue screen as discussed yesterday or, if you are manually editing the ejb-jar.xml file, you can add an entry similar to the following:

<ejb-jar>
...
  </assembly-descriptor>
    <container-transaction>
      <method>
        <ejb-name>JobBean</ejb-name>
        <method-name>*</method-name>
      </method>
      <trans-attribute>Required</trans-attribute>
    </container-transaction>
  </assembly-descriptor>
</ejb-jar>

If you look in Day06/agency directory on the Web site, you can see that the case study seperates out the Session beans and the Entity beans into two different deployment JARs.

The Agency 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 JAR has the new BMP Entity beans. How you choose to organize your enterprise application is up to you.

You can verify and deploy this example using the asant build files with the command:

asant build verify deploy

You can test the new version using the GUI client application shown yesterday using the command:

asant run

Adding Entity beans into the case study example has not required any changes to the client application. This shows one of the benefits of employing an n-tier architecture. It is possible to change the implementation details of one tier (introducing Entity beans behind a Session bean façade) without affecting the other tiers (no changes to the client application or the database schema).