Building Java Enterprise Applications

Deploying the Bean

At this point, you’ve completed the code for your entity bean, and now you need to deploy the bean. This involves creating a deployment descriptor for the bean and then wrapping the entire bean into a deployable unit. I’ll cover each of these steps in the following sections.

Deployment Descriptors

To wrap all these classes into a coherent unit, you must create an XML deployment descriptor. These descriptors replace the horrible serialized deployment descriptors from EJB 1.0. XML deployment descriptors eliminate one vendor-dependent detail: the descriptor is standardized across all application servers. Notice that the document type definition (DTD) referred to in the DOCTYPE declaration refers to a Sun file, ensuring that no vendors add their own tags or extensions to the descriptor. If your server requires you to use a different DTD, you may have a serious problem on your hands; you may want to consider switching to a standards-based application server immediately. And if DTDs, elements, tags, and these other XML terms are Greek to you, pick up Java and XML(O’Reilly), by yours truly, to get answers to your XML-related questions.

Example 4-7, the deployment descriptor for the office entity bean, contains entries only for that bean, detailing its home, remote, implementation, and primary key classes. These are all required elements for an entity bean, as is specifying that the bean is not reentrant and specifying the persistence type, which in our case is container-managed. Later on, we’ll add entries for numerous other entity beans that we will code and add to the application. Because we are deploying a CMP bean, the fields that must be handled by the container are listed; in this case, these are all the fields in the OfficeBean class. We also give the bean a name to be used, OfficeBean.

If you are familiar with EJB deployment descriptors, you might notice that I have left out the assembly-descriptor element and related subelements that allow permission specification for beans and their methods. That’s so you can focus on the bean right now, and deal with security later. Don’t worry, though; I’ll get to all of this before we’re done with our application. Leaving it out for now will allow the container to generate default permissions.

Example 4-7. The Office Entity Bean Deployment Descriptor

<?xml version="1.0"?>

<!DOCTYPE ejb-jar 
    PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN"
    "http://java.sun.com/dtd/ejb-jar_2_0.dtd">

<ejb-jar>
  <enterprise-beans>
    <entity>
      <description>
        This Office bean represents a Forethought office, 
          including its location.
      </description>
      <display-name>OfficeBean</display-name>
      <ejb-name>OfficeBean</ejb-name>
      <home>com.forethought.ejb.office.OfficeHome</home>
      <remote>com.forethought.ejb.office.Office</remote>
      <local-home>com.forethought.ejb.office.OfficeLocalHome</local-home>
      <local>com.forethought.ejb.office.OfficeLocal</local>
      <ejb-class>com.forethought.ejb.office.OfficeBean</ejb-class>
      <persistence-type>Container</persistence-type>
      <prim-key-class>java.lang.Integer</prim-key-class>
      <reentrant>False</reentrant>

      <abstract-schema-name>OFFICES</abstract-schema-name>
      <cmp-field><field-name>id</field-name></cmp-field>
      <cmp-field><field-name>city</field-name></cmp-field>
      <cmp-field><field-name>state</field-name></cmp-field>
      <primkey-field>id</primkey-field>
    </entity>
  </enterprise-beans>
</ejb-jar>

Warning

A word to the wise here: it might seem that the XML would be clearer with some reorganization. For example, the prim-key-class element might be easier to find if it were right below the other class entries (home, remote, and ejb-class). However, moving it will cause an error in deployment! The ejb-jar_2_0.dtd file specifies the order of elements, and is completely inflexible in this respect. This is a typical limitation of DTDs, as opposed to other constraint representations in XML such as XML Schemas. If these elements not in the correct order shown in the example, you will encounter errors in deployment.

Wrapping It Up

The process of creating the Office entity bean is finally complete (at least in its current form). You now need to create a deployable JAR file, and then create the container classes to add implementation details to your bean, such as SQL and JDBC code. First, ensure that your directory structure is set up correctly. The Java source files can all be in a top-level directory. You should then create a directory called META-INF/, and place the ejb-jar.xml deployment descriptor inside it. Next, compile your source files:

galadriel:/dev/javaentI $ javac -d build \
                          ch04/src/java/com/forethought/ejb/util/*.java \
                          ch04/src/java/com/forethought/ejb/office/*.java

Tip

Setting up your classpath for these compilations can be either really simple or really difficult. Many application servers provide a script that can be run to set up all the environment variables. Running this script takes care of all the classpath issues for you, and your compilations will be a piece of cake (refer to Appendix D and Appendix E for these details for the Sun J2EE reference implementation). Or, you may have to manually add the entries needed to your classpath. You should consider creating your own script in these cases, and then bothering your server vendor until they provide you with a prebuilt script. Unfortunately, the libraries are packaged differently with every server (for example, in Weblogic there is one giant JAR, and in jBoss there are individual JARs for each API), so I can’t tell you exactly what to type. Just look for a script; it’s almost always there.

Correct any errors you receive by referring to the text. Once you’ve compiled the source, you should have the directory structure shown in Figure 4-2. Notice that I have build/ and deploy/ directories in place before compilation and deployment to segregate my files. You should create these as well (or use your own structure, of course).

Figure 4-2. Directory structure for office entity bean

Next, you need to create a JAR file of these classes and the deployment descriptor. Create it with the name forethoughtEntities.jar, as shown:

galadriel:/dev/javaentI $ cd build

galadriel:/dev/javaentI/build $ jar cvf ../deploy/forethoughtEntities.jar com \
                                    META-INF/ejb-jar.xml
added manifest
adding: com/(in = 0) (out= 0)(stored 0%)
adding: com/forethought/(in = 0) (out= 0)(stored 0%)
adding: com/forethought/ejb/(in = 0) (out= 0)(stored 0%)
adding: com/forethought/ejb/office/(in = 0) (out= 0)(stored 0%)
adding: com/forethought/ejb/office/Office.class(in = 439) (out= 280)(deflated 
36%)
adding: com/forethought/ejb/office/OfficeBean.class(in = 805) (out= 445)
(deflated 44%)
adding: com/forethought/ejb/office/OfficeHome.class(in = 480) (out= 260)
(deflated 45%)
adding: com/forethought/ejb/util/(in = 0) (out= 0)(stored 0%)
adding: com/forethought/ejb/util/EntityAdapter.class(in = 831) (out= 388)
(deflated 53%)
adding: META-INF/ejb-jar.xml(in = 1038) (out= 430)(deflated 58%)

With this archive ready for use, you can refer to Appendix D for instructions on taking the JAR from its current state to a deployable, CMP entity bean and descriptor.