Verifying an EJB - Java

One of the problems most developers come across when writing EJBs is making sure the bean implementation provides the requisite functionality in the remote and home interfaces. Because your bean does not implement the remote interface (or the home interface), you must manually check that you have defined all the business methods in the bean implementation and that every create() method in the home interface has a corresponding ejbCreate() method in the implementation.

There are two ways of solving this problem:

• Generate a template bean implementation class from the home and remote interfaces.

• Use a tool that checks the bean implementation against the home and remote interfaces.

The drawback to the first approach is that changes to the home or remote interfaces necessitate regenerating the template class and copying existing functionality into the newly generated template. The process of manually copying existing code into the new template could lead to errors and is best avoided.

Use of a separate verification utility is more common, as this can be used any time changes are made to the interfaces or the implementation. The J2EE RI comes with the verifier tool, which validates the contents of an enterprise application and generates a comprehensive list of any errors encountered. The verifier is discussed in more detail in the section "Verifying the Case Study Application."

You are now nearing the conclusion of this whistle-stop tour of the structure of an EJB. After you have examined how an EJB is created and packaged, you will be ready to deploy and use one.

How Do I Create an EJB?

First you have to design and write your EJB classes. After that small task, all that remains is to wrap the class files up as a deployable unit with the deployment descriptor. In reality, not all of the deployment information is defined in the EJB specification. A certain amount of EJB information will, of necessity, be J2EE implementation specific. Consequently there will typically be at least two deployment descriptors in an EJB. Before looking at the deployment descriptors, there are certain caveats you should bear in mind while creating your bean.

Caveats on EJBs

Due to the managed nature of the bean lifecycle, the EJB container imposes certain restrictions on the bean including

• EJBs cannot perform file I/O. If you need to log messages or access files, you must find an alternative mechanism.

• EJBs are not allowed to start threads. The container controls all threading and ensures that the EJB is always multi-thread safe by only allowing a single thread of execution for each EJB.

• EJBs cannot call native methods.

• EJBs cannot use static member variables.

• There is no GUI available to an EJB, so it must not attempt to use AWT or JFC components.

• An EJB cannot act as a network server, listening for inbound connections.

• An EJB should not attempt to create class loaders or change factories for artifacts, such as sockets.

• An EJB should not return this from a method. Although not strictly a restriction (the container will not prevent you from doing it), it is identified as being a very bad practice as it would potentially give a client a direct remote reference to the bean rather than the EJB Object. Instead, the bean should query its EJB context for a reference to its associated EJB Object and return that to the caller in place of the this variable.

For a full list of restrictions, see the EJB specification available online at http://java.sun.com/products/ejb/docs.html.

The EJB Deployment Descriptor

The EJB specification defines a standard format for the XML deployment descriptor document that stores EJB meta data. The exact format of a deployment descriptor is usually hidden behind tools (such as the J2EE RI deploytool) that manipulates it on your behalf. However, it is worth examining some of the contents of a deployment descriptor to see how the EJB fits together and how extra information and meta data is provided.

Listing 4.5 shows the deployment descriptor for the example Agency EJB.

Listing 4.5 Agency Bean EJB Deployment Descriptor

<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar version="2.1" xmlns="http://java.sun.com/xml/ns/j2ee"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
 http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd">
 <display-name>Simple</display-name>
 <enterprise-beans>
  <session>
   <ejb-name>AgencyBean</ejb-name>
   <home>agency.AgencyHome</home>
   <remote>agency.Agency</remote>
   <ejb-class>agency.AgencyBean</ejb-class>
   <session-type>Stateless</session-type>
   <transaction-type>Bean</transaction-type>
   <env-entry>
    <env-entry-name>AgencyName</env-entry-name>
    <env-entry-type>java.lang.String</env-entry-type>
    <env-entry-value>J2EE in 21 Days Job Agency</env-entry-value>
   </env-entry>
   <security-identity>
    <use-caller-identity/>
   </security-identity>
   <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>
  </session>
 </enterprise-beans>
</ejb-jar>

The essential parts of the deployment descriptor in Listing 4.5 are

• The <session> tag delimits the definition of the Agency EJB and indicates that it is a Session EJB.

• The <ejb-name> tag defines the name of the EJB, in this case Agency.

• The home and remote interface types (as defined by their fully-qualified class filenames) are specified by the <home> and <remote> tags, respectively. The type of the bean itself is defined by the <ejb-class> tag.

In addition, two other parts are of particular note at this point in time:

• An environment entry is defined using the <env-entry> tag. This indicates that a String property called AgencyName should be made available to the bean. The value of the property is J2EE in 21 Days Job Agency. The environment defined in the deployment descriptor is made available through JNDI under java:comp/env. In this case, the agency name can be retrieved by looking up the name java:comp/env/AgencyName. This lookup can be seen in the ejbCreate() method of Listing 4.4.

• An external resource is defined using the <resource-ref> tag. This defines that a DataSource should be made available to this EJB under the name jdbc/Agency. As with the environment entry for the agency name, this resource is made available through JNDI under java:comp/env, so the EJB can retrieve the DataSource by looking up the name java:comp/env/jdbc/Agency. Again, this lookup can be seen in the ejbCreate() method of Listing 4.4.