Creating an EJB Archive File

The first step, creating an EJB archive file, is well documented in other EJB references and should be familiar to you. To review the process: EJB components are developed as separate Java source files defining the implementation, interfaces, and home interfaces. As shown in Figure 8.2, these individual files must be compiled using the standard Java compiler, combined with XML descriptors defining key bean attributes and behaviors, and processed through the WebLogic Server EJB compiler to create the archive file.

Figure 8.2:  EJB archive created using Java and EJB compilers.

This book is not intended to be a primer, introduction, or reference for general EJB topics, so we will not spend time reviewing the details of the standard EJB descriptor files or the EJB compilation process. If you are unfamiliar with the basics of EJB, we suggest you consult one of the EJB references listed at the beginning of Chapter 6.

Let s pause for a moment and discuss the directory structure used in the working area for bigrez.com . It will be much easier to follow the build process if you understand the directories and related property definitions in the build.xml file.

Figure 8.3 presents the important directories in the work area for the application.

Figure 8.3:  Summary of work directory structure.

These directories are defined in key properties in the build.xml file:

 <project basedir=. default=all name=Mastering WebLogic> ... <property name=src value=${basedir}/src/> <property name=build value=${basedir}/build/> <property name=dd value=${basedir}/dd/> <property name=srcjava value=${src}/java/> <property name=webuser value=${src}/web-user/> <property name=webadmin value=${src}/web-admin/> 

Note that we have chosen to consolidate all Java code in a single source code hierarchy beginning with src/java , rather than adopting a split directory approach in which source code is segregated into separate areas for EJB classes, support classes (value objects, utility classes, and so on), and Web application classes. In a split directory approach, all Web application classes for the user site would be located in a directory structure beneath the Web application itself, perhaps in src/web-user/_WEB-INF/src/com/bigrez/... , and the admin site s classes would be in a similar location in src/web-admin . EJB classes would be in a separate hierarchy such as src/ejb/com/bigrez/ejb/... , and value objects would be in yet another location. A split directory approach simplifies some of the EJB compilation and packaging steps by providing a clearly defined directory structure for inclusion in the EJB archive. The consolidated approach keeps things simple in terms of source-code organization, although it does require some additional work up front to create the proper build scripts. Either option will work; we ve chosen the consolidated approach for bigrez.com to be more in line with typical organization strategies.

Figure 8.4 presents a high-level view of the main targets in the bigrez.com build script and their dependencies. Use this figure as a reference as we walk through various portions of the script throughout this chapter.

Figure 8.4:  BigRez.com primary build file targets.

Creating EJB Source Code and Descriptor Files

The first step in the creation of an EJB archive file is the creation of Java source files and appropriate EJB descriptors for the EJB components. We assume you are familiar with the basics of this process.

WebLogic Server supplements the standard EJB descriptor file, ejb-jar.xml , with two WebLogic-specific descriptor files required to supply all necessary configuration information for the EJB components:

• The weblogic-ejb-jar.xml descriptor defines configuration parameters related to pooling, caching, JNDI names , the mapping of logical references in ejb-jar.xml to actual resources and beans, and various miscellaneous features.

• The weblogic-cmp-rdbms-jar.xml descriptor defines container-managed persistence (CMP) parameters for entity beans. It maps beans to database tables, defines the storage mechanism for container-manager relationships, modifies standard finder and ejbSelect methods to employ WebLogic Server-specific features and optimizations, and configures many of the new WebLogic Server caching and optimization capabilities.

A complete discussion of these descriptor files and their contents is beyond the scope of this book. The WebLogic Server online documentation is your best reference source for this information. Note that Chapter 6 also presented examples of many WebLogic Server-specific EJB features along with the corresponding descriptor elements.

The good news is that you may never have to learn the details of these descriptors, or the ejb-jar.xml descriptor for that matter, because tools such as EJBGen create these files for you. As described in Chapter 7, EJBGen uses Javadoc tags placed in the bean class file to generate all related Java files and descriptor files. Figure 8.5 illustrates the EJB archive-creation process using EJBGen.

Figure 8.5:  EJB archive creation process using EJBGen.

The bigrez.com application uses EJBGen in all EJB components, eliminating all hand-editing of the EJB descriptor files. The Ant build script includes a target to execute EJBGen and build the Java and descriptor files:

 <property name="ejbgen.jar.filename"           value="${WEBLOGIC_HOME}/server/lib/weblogic.jar"/> <property name="ejbgen.class.path"           value="${WEBLOGIC_HOME}/server/lib/weblogic.jar;                  ${basedir}/lib/log4j.jar;${build}"/>  ... <target name="  ejbgen  ">   <delete>     <fileset dir="${srcjava}/com/bigrez/ejb"               includes="*Local.java, *Remote.java"/>   </delete>   <exec dir="${srcjava}" executable="javadoc">     <arg line="-classpath ${ejbgen.class.path}                 -docletpath ${ejbgen.jar.filename}                 -doclet weblogic.tools.ejbgen.EJBGen -wls81                 -noValueClasses -remoteSuffix Remote                 -remoteHomeSuffix HomeRemote                 -localSuffix Local -localHomeSuffix HomeLocal                 -sourcepath ${srcjava}"/>      <arg value="com.bigrez.ejb"/>   </exec>   <move todir="${dd}">     <fileset dir="${srcjava}" includes="*-jar.xml"/>   </move> </target> 

The EJBGen process executes in the /src/java directory (defined by the srcjava property) and will examine and process all files located in the com.bigrez.ejb package. We were careful to place only EJB class files in this package to avoid EJBGen errors. The generated Java code and descriptors will be created in the /src/java directory structure by ejbgen , and the final move task places the descriptors in the /dd directory in preparation for the next step in the process.

Compiling EJB Components

After you have all of the required EJB source files and descriptors, the source files must be compiled using the standard Java compiler in preparation for the EJB compilation step. The build.xml file for bigrez.com defines a classpath for compilation and a compile target to perform the call to the Java compiler:

 <!-- Set up the development classpath --> <path id="dev.classpath">   <pathelement location="${JAVA_HOME}/lib/tools.jar"/>   <pathelement location="${WEBLOGIC_HOME}/server/lib/weblogic.jar"/>   <pathelement location="./lib/struts.jar"/>   <pathelement location="./lib/log4j.jar"/>   <pathelement location="./lib/junit.jar"/>   <pathelement location="./lib/httpunit.jar"/>   <pathelement location="${build}"/> </path> ... <target name="  compile  ">   <javac classpathref="dev.classpath" destdir="${build}"          srcdir="${srcjava}">     <include name="com/**/*.java"/>   </javac> </target> 

All Java classes are compiled to the build directory, a staging area for the construction of the EJB archive file and for the classes intended for inclusion in one or more deployed Web applications.

Executing the EJB Compiler

Once the EJB source files are compiled to Java classes the EJB compiler is invoked to combine the classes and descriptors and create the EJB archive. The EJB compiler validates the files and descriptors, creates the required stubs, skeletons, proxies, and concrete implementation classes, and produces a single .jar archive file containing everything.

There are a number of ways to invoke the EJB compiler and integrate this step in your build process.

Invoking the EJB Compiler Directly

The EJB compiler may be invoked directly as a command-line utility by first creating a .jar archive containing all of the descriptors and compiled Java classes and then using a command similar to the following:

 java weblogic.ejbc build.jar ejbarchive.jar 

The ejbarchive.jar file will contain all of the weblogic.ejbc -generated container classes along with the original classes and descriptors. Note that the classpath must include files such as weblogic.jar either through the CLASSPATH environment variable or by using the -classpath option in the command line.

This command-line technique can be difficult to integrate in your overall build script. You must manually assemble the build.jar file by creating and populating a temporary directory and invoking the jar utility prior to executing the weblogic_.ejbc command using a java task.

Using the WebLogic Application Compiler

WebLogic Server 8.1 deprecates the weblogic.ejbc utility and replaces it with weblogic.appc , a new utility combining the capabilities of weblogic.ejbc and weblogic.jspc , the JSP compiler, in a single program. The new weblogic. appc utility provides the same ability to process a prepackaged .jar file to create a complete EJB archive, if desired, but adds the ability to process Web application archive ( .war ) and complete enterprise application archive ( .ear ) files as well. In addition, weblogic.appc can operate on an exploded version of any of the supported file types, providing one useful technique for avoiding unnecessary jar steps during the build process. The exploded directory structure must mirror the contents of the associated archive file for proper operation.

The weblogic.appc utility may be invoked through a normal java task:

 <java classname=weblogic.appc fork=yes        failonerror=yes classpathref=ejbjar.classpath>   <arg value=${myejbdirectory}/> </java> 

The new wlappc Ant task provided in WebLogic Server 8.1 may also be used to invoke the utility:

 <wlappc source="${myejbdirectory}"          classpathref="ejbjar.classpath" verbose="true" /> 

To use the wlappc task, you need to first define it:

 <taskdef name=wlappc classname=weblogic.ant.taskdefs.j2ee.Appc/> 

To operate as an EJB compiler, the weblogic.appc utility requires a directory structure or archive file populated with the correct EJB classes and deployment descriptors. We have two choices in bigrez.com : copy everything required for EJB compilation to a separate staging area before invoking weblogic.appc or use the build directory as the staging area for EJB compilation. The first option is very common and simple enough to implement, requiring only a temporary directory and appropriate copy tasks prior to invoking the EJB compiler. The second option is more promising because it avoids the creation of a temporary directory and makes better use of the in-place compilation capabilities of weblogic.appc .

To execute the EJB compiler using the build directory as the staging area, the build directory must contain the deployment descriptors for the EJB archive. The ejbjar target therefore copies the descriptors from the dd directory, preserving timestamps, before invoking the weblogic.appc utility using the wlappc Ant task:

 <target name=ejbjar depends=compile>   <mkdir dir=${build}/META-INF/>   <copy todir=${build}/META-INF preservelastmodified=true>     <fileset dir=${dd} includes=*-jar.xml/>   </copy>   <wlappc source=${build}           classpathref=ejbjar.classpath verbose=true /> 

The weblogic.appc utility will create all of the necessary container classes in the build directory, leaving it ready for packaging as an archive file. Subsequent calls to weblogic.appc may not require a full recompilation of the entire set of EJB classes. It depends on the components and files that have changed since the last invocation. This can be very important on projects with many EJB components.

Because we are using consolidation of all source code in one directory structure, the build directory also contains Web application classes that must be omitted from the EJB archive. To accomplish this selectivity, the jar task in the ejbjar target explicitly defines the files to include in the archive:

 <jar destfile="${ejb.jar.filename}">     <fileset dir="${build}" includes="com/bigrez/ejb/**/*.class,                                       com/bigrez/utils/**/*.class,                                       com/bigrez/val/**/*.class,                                       META-INF/*-jar.xml"     />     <manifest>       <attribute name="Class-Path" value="lib/log4j.jar"/>     </manifest>   </jar> </target> 

Note that the jar task also creates a manifest Class-Path entry referencing a required logging utility archive file, log4j.jar . This Class-Path entry in the manifest causes the container to load additional utility classes in the top-level application classloader, making them available to EJB components and Web components. We ll discuss this manifest Class-Path technique, along with a new alternative technique using the APP-INF/lib and APP-INF/classes directories, in a later section when we describe the packaging of enterprise applications.

Properties required by the ejbjar target are defined earlier in the build.xml file:

 <property name=ejb.jar.filename value=bigrezejb.jar /> ... <path id=ejbjar.classpath>   <pathelement location=${JAVA_HOME}/lib/tools.jar/>   <pathelement location=${WEBLOGIC_HOME}/server/lib/weblogic.jar/>   <pathelement location=./lib/log4j.jar/>   <pathelement location=${build}/> </path> 

The EJB archive file is now ready for deployment. It contains all of the EJB class files, supporting value-object and utility classes, descriptors, and weblogic.appc -created container classes for the EJB components defined in the archive.

Best Practice  

The weblogic.appc compiler is the recommended approach for EJB compilation in WebLogic Server 8.1. The wlappc Ant task provides a convenient mechanism for integrating this step in your build script.

Using the ejbjar Optional Ant Task

One alternative option for invoking the EJB compiler involves the use of an optional task that comes with Ant, ejbjar , to create the EJB archive and perform the compilation:

 <target name="ejbjar" depends="compile">   <ejbjar srcdir="${build}"           descriptordir="${dd}"           basejarname="${ejb.jar.basename}">     <include name="ejb-jar.xml"/>     <classpath refid="ejbjar.classpath" />     <weblogic destdir="${basedir}" rebuild="false"/>     <support dir="${build}">       <include name="**/ejb/**/*.class"/>       <include name="**/utils/**/*.class"/>       <include name="**/val/**/*.class"/>     </support>   </ejbjar>   <jar destfile="${ejb.jar.filename}" update="true">     <manifest>       <attribute name="Class-Path" value="lib/log4j.jar"/>     </manifest>   </jar> </target> 

The attributes of the ejbjar task define the location of the compiled classes and EJB descriptors and the name to use for the EJB archive file. The ejbjar task also makes it easy to specify the additional support classes (value objects, utility classes, etc.) to be placed in the EJB archive using support elements. The rebuild attribute is also useful; setting it to false causes ejbjar to skip a full recompilation of all container classes whenever possible.

Note that the ejbjar.classpath definition includes the build directory, making all compiled Java classes available during the weblogic.ejbc processing step in the ejbjar task. The presence of the EJB classes in the classpath causes a few warnings similar to the following during the weblogic.ejbc process:

 [ejbc] <Apr 6, 2003 5:53:38 PM CDT> <Warning> <EJB> <BEA-010054>  <EJB Deployment: ReservationSessionEJB has a class com.bigrez.ejb. ReservationSessionBean that is in the classpath. This class should  only be located in the ejb-jar file.> 

These warnings can be safely ignored, and they can be suppressed in WebLogic Server 8.1 by including a disable-warning element in the weblogic-ejb-jar.xml file:

 <disable-warning>BEA-010054</disable-warning> 

The final step in the overall ejbjar target involves updating the generated bigrezejb.jar archive file to include the Class-Path manifest entry described in the previous section. The EJB archive file is now complete and ready for deployment.

Best Practice  

Consider using the ejbjar optional Ant task with earlier versions of WebLogic Server in place of a direct invocation of weblogic.ejbc . The built-in support element is a useful way to package supporting classes in the EJB archive.

We ve considered three approaches for creating the EJB archive file: direct invocation of the EJB compiler, the use of weblogic.appc through a java task or the new wlappc task, and the ejbjar optional Ant task. The build process for bigrez.com uses the wlappc task because it provides the best integration with the build process and utilizes the new standard mechanism for EJB compilation in WebLogic Server 8.1, weblogic.appc .

At this point in the build process the EJB archive file is located in our work root directory awaiting deployment. Choosing the final destination for this file is the subject of the next section.