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.

The EJB-JAR File

All of the EJB classes and the deployment descriptor should be bundled up in a JAR file. The deployment descriptor is stored in a META-INF directory (the same location as the JAR manifest file) and must be named ejb-jar.xml. If there are multiple EJBs packaged in the same JAR file, the deployment descriptor will have multiple EJB definitions in it. The JAR file is then termed an EJB-JAR file to denote its payload. The JAR file itself can be called anything (but obviously a name appropriate to the application makes most sense) and conventionally has a .jar file extension.

The EJB-JAR file can also contain any extra resources required by the EJB, such as platform-specific configuration information that does not fit in the standard deployment descriptor.

Typical contents of a platform specific deployment descriptor are

• The JNDI name the EJB must be deployed under

• Mappings between resources referenced in the J2EE components such as EJBs and the actual resources within the J2EE server

An EJB-JAR file can store more than one platform-specific deployment descriptor file, enabling it to be used with different J2EE implementations. Although the EJB-JAR file is now complete, it must form part of an application to serve a useful purpose. J2EE defines that enterprise applications can be built from components (Web, EJB, and Client Application components). Therefore, a second JAR file is used to bundle these J2EE components into a complete J2EE Application, this is called the Enterprise Archive file.

The Enterprise Archive File

The Enterprise Archive (EAR) file contains a number of J2EE components comprising an application and yet another deployment descriptor. This descriptor includes a description of the application, which components it uses, how those components relate to each other, and which specific resources they use. This is the information provided by the Application Assembler and Deployer.

The application deployment descriptor is also an XML document, called application.xml, and it is stored in the META-INF directory of the Enterprise Archive (which although a JAR file the Enterprise Archive typically has a filename extension of .ear not .jar). Listing 4.6 shows the application.xml descriptor for the Agency application.

Listing 4.6. Agency Bean EJB Deployment Descriptor

<?xml version="1.0" encoding="UTF-8"?>
<application version="1.4" 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
/application_1_4.xsd">
  <description>Application description</description>
  <display-name>agency</display-name>
  <module>
    <ejb>agency-session-ejb.jar</ejb>
  </module>
  <module>
    <web>
      <web-uri>webagency.war</web-uri>
      <context-root>/webagency</context-root>
    </web>
  </module>
</application>

The application.xml file just lists the modules that form the enterprise application, in this case the single Agency EJB contained in agency-session-ejb.jar.

An EAR file may also contain one or more platform-specific deployment descriptors for the application enabling it to be used with different J2EE implementations.