J2EE EJB Configuration and Deployment

Date: Jun 1, 2001

Article is provided courtesy of Sams.

Java 2 platform, Enterprise Edition (J2EE) enterprise applications are comprised of one or more individual J2EE modules. J2EE modules have deployment descriptors specific to the module type, and J2EE enterprise applications have their own deployment descriptor format. In this article, author Paul Perrone introduces the EJB application module deployment descriptor and covers the basics of EJB deployment descriptors, deployed archives, and deployment procedures.

EJB Deployment Descriptor Top-Level Elements

Java 2 platform, Enterprise Edition (J2EE) enterprise applications are made up of one or more individual J2EE modules. J2EE modules have deployment descriptors specific to the module type, and J2EE enterprise applications also have their own deployment descriptor format.

J2EE EJB application module deployment descriptors are defined in XML files named ejb-jar.xml. Throughout this series of articles, I describe elements of the EJB deployment descriptor as they become relevant to the topic at hand. I thus carve out pieces of the XML EJB module and describe them as the elements they define become relevant. If you are new to XML and XML DTDs, I encourage you to review the basics of XML and DTD structure now. At the very least, I will provide examples of what XML files that adhere to the DTD schema specifications should look like.

The top-level elements of an EJB deployment descriptor, shown in Listing 1, are elements used to define EJB application metadata, EJB structure, assembly information, and the archive filename for any EJB client files. EJB application module deployment descriptors defined according to such a format must also include a standard DOCTYPE definition referencing the standard DTD. The basic top-level structure of an EJB deployment descriptor thus follows the sample form in Listing 1.

Listing 1 EJB DTD Top-Level Elements

<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//
[ic:ccc]DTD Enterprise JavaBeans 1.1//EN" 
[ic:ccc] "http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd">

<ejb-jar>
 <description> This is my BeeShirts.com EJB Application </description>
 <display-name> BeeShirts.com Application Service </display-name>
 <small-icon> beeshirtsSmall.jpg </small-icon>
 <large-icon> beeshirtsLarge.jpg </large-icon>
 <enterprise-beans>
  <session> ... </session>
  <session> ... </session>
  <entity> ... </entity>
  <entity> ... </entity>
   ...
 </enterprise-beans>
 <assembly-descriptor>
  ...
 </assembly-descriptor>
 <ejb-client-jar> beeshirtsClient.jar </ejb-client-jar>
</ejb-jar>

EJB JAR Files

An EJB JAR file represents the deployable JAR library that contains the server-side code and configuration of the EJB module. During deployment, the ejb-jar.xml file is placed in the META-INF directory of the EJB JAR file. Any entity and session beans defined within the ejb-jar.xml file must have the .class files for their implementations, home interfaces, and remote interfaces, as well as any dependent classes, archived inside the EJB JAR file. As you'll see later in this article and other articles, the ejb-jar.xml file can be used to define references to other EJBs in other EJB JAR files from EJBs defined in the current EJB JAR file. If the Class-Path attribute in the EJB JAR file's Manifest.mf file includes any auxiliary EJB JAR file library URLs, then the current EJB JAR file does not need to include any EJB client stubs or interfaces from any associated auxiliary EJBs on which its EJBs are dependent.

Any client stub and interface classes needed to access the EJBs in a particular EJB JAR file can be placed in a separate EJB client JAR file. The URL of this EJB client JAR file can then be specified in the ejb-jar.xml file's <ejb-client-jar> element. Any EJB clients of the EJBs in the associated server-side EJB JAR file can then automatically receive downloaded interface and stub classes as they are needed if the EJB client's class loader can reach the URL defined within the <ejb-client-jar> element. If no automatic class-downloading mechanism is supported or used by the client, the EJB client JAR libraries should be installed on the EJB client's machine.

EJB Deployment Procedures

The process for deploying J2EE applications involves establishing environment variables, configuring server properties, compiling Java code, creating XML-based deployment descriptors, packaging archive files, and deploying archives to a J2EE server environment. I focus on the deployment of J2EE-based EJB applications in this article, which might differ slightly between vendor-specific application server implementations. However, the general procedure for deploying J2EE-based EJB applications assumes the following general steps:

Set J2EE server environment variables—Environment variables must be set for running a J2EE server environment and vary per vendor implementation and operating-system platform.
Configure J2EE server properties—Configuration properties for most J2EE server implementations can be set to suit your particular network and operating environment.
Compile J2EE EJB application code—All J2EE EJB implementation, home, remote, and dependent utility code must be compiled using a standard Java compiler.
Create a J2EE EJB application deployment descriptor—An XML-based deployment descriptor is created according to the EJB application DTD. Some vendor products can create this file for you from a GUI-based configuration tool.
Create vendor-specific deployment descriptors—Because no standard means exists to bind J2EE standard EJB reference names to a J2EE server's JNDI-based naming service, a vendor-specific deployment descriptor mechanism is required to perform this mapping. This deployment descriptor must map EJB reference names used by J2EE components to the actual JNDI names associated with EJB home interfaces. Other vendor-specific properties may also be set for customizing both session and entity beans. Vendors may provide a GUI-based means to configure these files.
Package J2EE EJB application code—The EJB deployment descriptors, all compiled J2EE EJB implementation classes, all compiled J2EE EJB implementation interfaces, and all other compiled classes dependent on your EJBs need to be packaged into an EJB JAR file with a .jar extension. J2EE-based products might supply command-line or GUI-based utilities for this purpose.
Start the J2EE server—The J2EE-compliant server must generally be started at this stage. The exact mechanism for starting a server is often vendor-dependent but can be as simple as invoking a single startup command from the command line.
Create a J2EE application deployment descriptor—A J2EE application deployment descriptor must be created to collect one or more Web, EJB, and application client modules into a cohesive J2EE application. Many products will create this file for you automatically or via a GUI-based configuration tool.
Package J2EE application code—The application and JNDI mapping deployment descriptor, Web applications, EJB applications, and application clients need to be packaged into an enterprise archive (EAR) file with an extension of .ear. Many products also create this archive for you automatically or via GUI-based development tools.
Deploy the J2EE enterprise application code—Finally, the integrated J2EE application is deployed to the J2EE server environment for access by enterprise application clients. This step is also often automated via GUI tools.

Example BEA WebLogic Server Startup and Deployment

I will now briefly discuss deployment via the BEA WebLogic Server exemplifying an enterprise class server capable of deploying J2EE-based EJB applications. Generally, you first want to compile all server Java classes and then copy any EJB ejb-jar.xml files under a META-INF directory created below a special temporary WebLogic build directory. Special WebLogic-specific configuration and deployment parameters are defined in a weblogic-ejb-jar.xml file for all beans and a weblogic-cmp-rdbms-jar.xml file for entity beans. These descriptor files are also copied to the META-INF directory.

You then must create a standard JAR file out of all compiled classes and XML deployment descriptor files, and subsequently call a special WebLogic Server weblogic.ejbc program to create the EJB JAR file. The weblogic.ejbc program is a Java program that creates all necessary client- and server-side stubs, skeletons, and delegates for the EJB classes. The basic format of weblogic.ejbc used is shown here:

[JAVA_HOME]\bin\java -classpath [CLASSPATH]
           -Dweblogic.home=[WEBLOGIC_HOME]
           weblogic.ejbc
           -compiler javac
           [build_directory]\standardJarFileName.jar
           [WEBLOGIC_HOME]\myserver\EJBJarFileName.jar

The [CLASSPATH] value after the -classpath flag specifies those class files and libraries to use during compilation with the Java compiler defined after the -compiler flag. The location and filename of the standard JAR file previously built with your compiled EJB classes and interfaces must also be provided on the command line (that is, [build_directory]\standardJarFileName.jar), along with the desired location and filename for the EJB JAR file to be created by weblogic.ejbc (that is, [WEBLOGIC_HOME]\myserver\EJBJarFileName.jar).

Before deploying the EJBs, each EJB JAR file location and name must also be added to the weblogic.properties file's weblogic.ejb.deploy property. The weblogic.properties file is a special Java property file contained in the WEBLOGIC_HOME directory to define instance-specific configuration parameters for the WebLogic Server. The BEA WebLogic Server can then be started using a special command script, a starter script for which comes equipped with the WebLogic Server in the WEBLOGIC_HOME directory.

Conclusions

This article examined the top-level structure of an EJB deployment descriptor. It also looked at the basic means for creating EJB JAR files. Such constructs, along with a generic description of EJB deployment procedures and an example discussion, offer a sense for what is involved when actually deploying EJBs. As you might surmise from this article, slightly more effort can be involved with deploying an EJB than is involved with a regular Java class. Subsequent articles in this series delve into more specific procedures for deploying particular types of EJBs.