Published on ONJava.com (http://www.onjava.com/)
 See this if you're having trouble printing code examples

Using Ant and WebLogic EJBs

by Jesse E. Tilly

EJBs are complex in both design and implementation. The steps required just to deploy them for the numerous application servers make matters worse. However, for developers using BEA's WebLogic family of application servers, life is made easier thanks to Ant.

Ant is an open-source tool for building Java-based applications and is a part of the Apache Jakarta project. Using XML as a build description language, Ant groups build results into targets with finite resolution states; a target fails or succeeds. We, the developer or build manager, define the build properties, the tasks needed to build targets, and the dependencies between those targets in the antfile. For more information, an overview of Ant, written by David Thomson, is available on the ONJava.com site.

The developers of Ant provide a set of tasks that can build deployable EJBs that are useable in WebLogic 4.5, 5.1, and 6.0, and can also create generic EJB bundles for processing in other application servers. When properly set up, a project's antfile, using the <ejbjar> task and <weblogic> element, can build hundreds of EJBs, defined by the same five to eight lines of XML.

This article covers builds of EJBs for WebLogic 5.1. However, developers and build managers working with other application servers can take heart that the design used to create these EJB and WebLogic tasks is extensible. These users should remain alert for the next Ant release (1.4), which will include supported EJB tasks for iPlanet, Borland Application Server and jBoss. Unsupported forms of these are available either in some nightly builds of Ant's optional tasks or from other developers. Curious users are encouraged to search the Ant-user mailing lists for messages pertaining to EJBs and iPlanet, etc. From there, they can find the module that meets their needs.

This article is divided into four parts. The first part describes how to configure a project for use with the <ejbjar> task and <weblogic> element. The second part shows an example of how to build series of EJBs for a project. The third part teaches you how to write a target that builds only one EJB. Finally, the fourth part covers some of the more useful optional functions, as well as some tips and tricks.

O'Reilly Open Source Convention

Learn more about Java open source projects during the Java sesssions at the O'Reilly Open Source Convention in San Diego, CA, July 23-27, 2001. Rub elbows with open source leaders while relaxing on the beautiful Sheraton San Diego Hotel and Marina waterfront. For more information, visit our conference home page.


Comment on this articleWhat are your experiences with Ant and WebLogic Application Server EJBs?
Post your comments

Ant's requirements cause conflicts with other EJB toolsets, since they may have naming conventions of their own. This article provides solutions to some of the known conflicts. However, the more of these tools a development shop uses, the higher the likelihood of having an unresolved conflict. Read the Ant documentation for more details of how Ant works with IDEs.

Naming Schemes

WebLogic EJB developers that want to use Ant need to jump through a few hoops to get the full power of the <ejbjar> task. The actual amount of antfile code involved is small, maybe about seven or eight lines (not including property configurations, etc.). Developers just beginning their projects will have the easiest time; those developers who are months, or even years, into a project may find incorporating Ant to be a more daunting task. For the latter unlucky folks, this article is meant to be enlightening enough to have them reconsider their project configurations and possibly refactor them. Even if it their project will not be using Ant, a well designed project configuration helps everyone in the long run.

Due to the precedent set by EJB examples and books (notably Monson-Haefel's EJB books), it is fairly common for developers to use the following convention when naming classes and Java modules:

Because of these same examples, it is not common to find the deployment descriptors following any naming convention or proper organization. Partly, this is because of the constraints that the containers place on descriptor names, but this can be solved with scripts or smart EJB building programs. Ant's EJB tasks require some good organizational guidelines for all of the EJB files. Without some standard organization, EJB projects become troublesome to maintain as, over time, descriptors become scattered throughout the file system. Ant's scheme provides structure to the typically structureless aspect of many Java projects.

To begin, here is the set of project organization rules <ejbjar> uses:

All EJB classes should follow the de-facto class naming standard, using the bean name prefix.
While technically possible with the flexibility of the descriptor files, the EJB implementation class, for example, should not be named IThumbMyNoseAtNamingConventions.java. <Bean Name>Bean.java, while boring, works best.

All EJB descriptors should follow the class naming convention, using the bean name prefix before the descriptor type.
This descriptor convention is not as demanding as it may sound. All descriptors start with the <Bean Name> (e.g. Account-ejb-jar.xml). In the WebLogic deployment descriptor, the CMP descriptor is explicitly named. This does not need to be changed. Only the filename on the file system must follow the convention. We visit the potential conflicts of such a naming convention in the "work-around' section.

Descriptors get their own directory, per bean, using the bean name.
This rule is not as much of a requirement as the first two, but it makes life easier over the long haul.

These rules are not requirements.
Large and complex applications may have special needs unsatisfied by the task's current level of functionality or other needs that are satisfied but not covered in this article. For these projects, the naming schemes and project layout may not apply. Any project can be built using <ejbjar> with enough effort; using the rules makes <ejbjar> easier.

The Layout

Project layout is important for effective code and build management. Creating modular file-system organizations makes for easy bundling or removal of code. Java's packaging system is an example of this design concept. Concept diagrams during project whiteboarding sessions benefit from good layout. Managing the code in CVS or any other version control system is made easier.

External benefits aside, without conventions, the <ejbjar> task becomes like any other Ant task. The projects that closely follow the rules require the least amount of antfile code. Straying from the rules, the antfile writer may have to describe and define how to build each EJB. With conventions applied, the <ejbjar> task becomes quite powerful, with only little work.

The following is an example project layout:


The project structure follows all the rules mentioned. The Account EJB code modules are named appropriately. The descriptor files are in their own directory, and they too share the code-module naming scheme.

Building all EJBs

This is what the project's <ejbjar> task would look like, assuming ${weblogic.classpath} includes the service packs, jars and class directories needed by WebLogic:

<ejbjar srcdir="build"
                <weblogic destdir="build/deploy"
                <include name="**/*-ejb-jar.xml"/>
                <exclude name="**/*weblogic*.xml"/>

Eight formatted lines efficiently compile any number of EJBs. (In a "real-world" antfile, most of the attribute values would be properties, making the number of total lines needed a bit larger. To avoid wasting space, this article has explicitly defined the attributes.) The operation consists of two main tasks, <ejbjar> and <weblogic>. The documentation lists many more attributes and nested elements, but those above are the only ones needed for this example. <ejbjar> builds the "generic" EJB, ready for container-specific compiling and deployment. <weblogic> runs weblogic.ejbc on the "generic" EJB, preparing it for deployment to a WebLogic container. There are no class-specific or module-specific attributes. For a great performance boost, the compiler attribute can be replaced with Jikes like so:

compiler="jikes -nowarn"
The 'no-warn' argument is for weblogic.ejbc, since it interprets some warnings from Jikes as errors and would "fail" to build an otherwise good EJB.

With this, building 100 EJBs will not make it seem like the computer is rendering dust for a Pixar movie. Experience has shown that the building of the EJBs takes the most time in builds; performance in this part of a build means a great deal. As an example, a project using roughly 700 classes and 70 EJBs can be compiled in under 10 minutes (on a Pentium III 800 with 512MB of RAM). The same project compiled with the javac compiler takes 30 to 40 minutes to complete. In both instances, the classes alone compile in under 30 seconds (the jikes version taking slightly less time).

Just One Bean

By using some command-line/property-file specified attributes, a user can specify that a specific EJB be built.

<ejbjar srcdir="build" descriptordir="descriptor/${bean.name}"> <weblogic destdir="build/${bean.name}/${bean.name}.jar" classpath="${weblogic.classpath}:build" keepgenerated="true" compiler="javac"/> <include name="**/*-ejb-jar.xml"/> <exclude name="**/*weblogic*xml"/> </ejbjar>

The previous code fragment tells <ejbjar> and <weblogic> to create, compile and place an EJB in the ${bean.name} deployment directory -- the same location it would be found in a global compile. This snippet is handy for the developers who do not want to rebuild the entire system every time. It should be noted that static dependencies and the like are not taken into consideration during dependency checks. A complete rebuild is not without merit.

Quirks, Tips and Optional Features

Descriptor discrepancies

Some containers, WebLogic's included, expect the descriptors to follow a different naming convention than the one Ant's tasks require. The <ejbjar> task takes care of this internally, renaming the files prior to packaging them within the jar. However, this means that the descriptors on the file system are in a naming scheme that may break other deployment programs and programming IDEs.

There are a couple of ways to handle this. In systems with symbolic-link capable file systems, it is easy to maintain two sets of filenames: one for the IDE, one for Ant. Links would need to be recreated during version-control updates. Scripts and Ant both have features capable of solving this issue. In a non-linking file system (such as Windows), it will be necessary to maintain either two sets of files, or have Ant or a script rename everything prior to building the application.

CMP descriptors are particularly vulnerable to this naming scheme. Following the scheme, a developer loses the ability to build EJBs by hand, since the CMP descriptor name is also specified in the WebLogic descriptor. As of Ant 1.3, it is possible for the user to allow Ant to discover the container-managed descriptors from the WebLogic descriptor. This is a benefit for those with multiple CMP descriptors, as well. Those using Ant 1.2 can patch the EJB modules with the latest code to get this functionality. To turn this on, add the newCMP attribute to the <weblogic> element. For example:

<ejbjar srcdir="build"
                           <weblogic destdir="build/deploy"
           <include name="**/*-ejb-jar.xml"/>
           <exclude name="**/*weblogic*Xml"/>

Generic EJBs for Dynamic Deployment Containers

jBoss and WebLogic 6.0, for example, perform dynamic compiling and deployment. For these servers, "generic" EJBs can be created by omitting the nested WebLogic task. Ant will create a jar with the proper classes and the EJB descriptor, leaving it up to the user or application server to compile and create a fully deployable bean from this jar file.

Here's a simple example:

<ejbjar srcdir="build"
     <include name="**/*-ejb-jar.xml"/>
     <exclude name="**/*weblogic*Xml"/>

DTD Location

Typically, DTD URLs are found in the headers of the deployment descriptors. WebLogic's compiler knows these DTDs can exist in the classpath. If the WebLogic classes are in the classpath for the Ant JVM (not just the <weblogic> task's classpath), these DTDs are found. If not, they are located via standard net communications. If the network is latent or nonexistent, the requests can fail, causing a compile and build error. Beginning with Ant 1.3's EJB tasks, DTDs can be specified as a nested element. For example (assuming ${weblogic.home} is the root location for a WebLogic installation):

<ejbjar srcdir="build"
 <weblogic destdir="build/deploy"
 <include name="**/*-ejb-jar.xml"/>
<exclude name="**/*weblogic*xml"/>
<dtd publicId="-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN"
<dtd publicId="-//BEA Systems, Inc.//DTD WebLogic 5.1.0 EJB//EN"

Jesse E. Tilly is a developer with HotelTools, Inc. in Atlanta, GA. He has been working exclusively with BEA WebLogic developing and managing hospitality applications over the Internet.

Return to ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.