Introduction

Part 1 of this article explained how to run Ant both inside WebSphere® Studio Application Developer (hereafter called Application Developer) and outside it ("headless"). This part will explain how you can use special Ant tasks for Application Developer production Ant builds of J2EE modules. Part 3 will explain how to create your own Ant tasks to provide specialized build functions.

Application Developer is an excellent tool for developing J2EE modules. During development, some of the deployment descriptor information is stored in ASCII XML files, but these files also contain some information in a format convenient for interactive testing and debugging. As part of the Application Developer functionality that creates (exports) standalone J2EE modules, this internally optimized deployment descriptor information is merged and changed into a standard format. This article includes a set of Application Developer Ant tasks to perform these build and export functions, using the "headless" operations described in Part 1 of this article.

Back to top

Download files

The two download files are not part of Application Developer V4 or V5 Early Availability (EA) and are not officially supported. However, Application Developer V5 General Availability (GA) includes these features in the product and they are fully supported. If you have suggestions or encounter problems with the older V4 or V5 EA features, please e-mail Barry Searle . V5 GA is supported via the normal IBM support channel.

Download now .

com.ibm.ant.extras_V4.zip

The Version 4 download file ( com.ibm.ant.extras_V4.zip ) has been tested with Application Developer 4.0.2 and 4.0.3 and works as described, but will not work with future versions of the product (V5 or later). This code includes the setDebugInfo task from the article Non-Debug compilations in WebSphere Studio Application Developer .

com.ibm.ant.extras_V5EA.zip

The Version 5 Early Availability download file ( com.ibm.ant.extras_V5EA.zip ) has been tested with Application Developer 5.0 Early Availability and works as described. It will not work with future versions of the product (V5 GA or later) and it will not work with Version 4.x. The download code changes from Version 4 (described in this article) to Version 5 are:

• HeadlessAntListener.java has been renamed to HeadlessAntLogger.java and now extends org.apache.tools.ant.DefaultLogger .
• HeadlessAntRunner.java no longer creates a new HeadlessAntLogger( ) . Instead, it calls addBuildLogger("HeadlessAntLogger") .
• HeadlessAntRunner.java no longer calls listener.setMessageOutputLevel(...) and super.processCommandLine(args) .

Important: If you download com.ibm.ant.extras_V5EA.zip , you must unzip it into your x:\Ws_installdir\ WSTOOLS\ECLIPSE \plugins directory, where it will create a com.ibm.ant.extras_5.0.0 subdirectory containing a runAnt.bat program and the various programs it requires. (The Version 4 code went into the x:\Ws_installdir\plugins directory.)

Application Developer V5 General Availability

Application Developer V5 GA contains the Headless Ant features and is fully supported. Do not use the V4 or V5 EA downloads. The RunAnt.bat file is now in the directory X:\WSAD5GA_INSTDIR\wstools\eclipse\plugins\com.ibm.etools.j2ee.ant_5.0.1 , and that directory also contains readme.htm . The Eclipse refresh task <eclipse.refreshLocal> has changed to <eclipse.refreshLocal resource="MyProject/MyFolder" depth="infinite"/> .

Back to top

J2EE modules and and reference reading

The WebSphere Developer Domain article J2EE class loading demystified describes how J2EE module build-time and run-time CLASSPATH dependencies are resolved in WebSphere Application Server. This article begins with a good overview of J2EE modules, which explains that the J2EE specification describes three types of modules and an overall package.

• Web module Web archives (WARs)
• Enterprise JavaBean^TM (EJB) module Java^TM archives (JARs)
• Application client module JARs
• Combined enterprise application archives (EARs)

When the application is deployed to a J2EE application server, one or more of each of the three J2EE modules are normally combined into a single J2EE application EAR.

Here are some useful reference materials about J2EE programming.

• WebSphere Studio Application Developer is an excellent J2EE development environment, and has extensive online documentation.
• For detailed EJB information, see the official Enterprise JavaBeans Specification, Version 1.1 .
• For a good programming guide, see Programming J2EE APIs with WebSphere Advanced .
• For a good introduction to J2EE, see the WebSphere Developer Domain article Developing and Testing a Complete "Hello World" J2EE Application with WebSphere Studio Application Developer .

Back to top

J2EE builds and Java utility JARs inside Application Developer

Application Developer has projects of different types, including one type for each of the J2EE module types, and for the overall enterprise application. It has several other project types, ranging from simple Java projects to Web Service projects and XML projects. For each of the J2EE projects, Application Developer has an Export function which creates a J2EE package for the code being developed. For example, if you are working on an EJB project, you can right-click on it and select Export EJB JAR, and the Export EJB JAR wizard will create the desired EJB JAR. Similarly, there is a WAR Export, EJB Export, Application Client Export, and EAR Export.

Although Java utility JARs are not part of the J2EE packaging, they are very common, and the WebSphere Developer Domain article Developing J2EE utility JARs explains how to use them in Application Developer. It has downloadable code for a plug-in that automates utility JAR creation and use in an EAR. This functionality is being considered for inclusion in subsequent releases of WebSphere Studio Application Developer. However, no decision has been made and IBM reserves the right not to include such functionality.

One aspect that is different for EJB projects is that there is a project function to generate deploy and RMIC code. The resulting wizard enables you to select EJBs in that project, will generate deploy code and RMIC code for those beans, and will compile that code.

Thus, an EJB JAR may be deployable, meaning it needs to have deploy code generated as part of the server deployment, or it may be deployed, meaning that the deploy and RMIC code has already been generated and compiled.

Back to top

J2EE deployment descriptors inside Application Developer

As mentioned in the introduction, the J2EE deployment descriptor information in Application Developer is stored in ASCII XML files, but these files contain some information in a format convenient for interactive testing and debugging. That is partly why it is convenient and quick to test J2EE applications on the internal WebSphere Application Server included with Application Developer. The actual EAR being tested, and its WAR, EJB, and ClientApplication JARs, are not actually created as a standalone JAR file. Instead, a special EAR is used that simply points to the build contents of the various J2EE projects. Since these various individual projects can be anywhere on the development machine, absolute path references are used.

When an Enterprise Application project is exported, a true standalone EAR is created, including all the module WARs, EJB JARs, and Java utility JARs it contains. Hence, during the export operation, all absolute paths are changed into self-contained relative references within that EAR.

Back to top

Ant J2EE builds outside Application Developer ("headless" operation)

As described above, the Application Developer functions that create (export) standalone J2EE modules merge and change the internal deployment descriptor information into standard format. So what happens if you are running a production Ant build, and want to create one or more of these exported standalone J2EE modules? You cannot just create JAR files from the applicable Application Developer files, because they are in an internally optimized format containing absolute references.

What you need is a set of Application Developer Ant tasks to perform these build and export functions, using the "headless" operations described in Part 1 . The attached code for this article contains these Ant tasks. In addition to the Ant tasks for the various J2EE export operations, it also includes Ant tasks to perform an EJB Deploy and to build Java utility JARs and include them within Ant builds of EARs (equivalent to the downloadable Application Developer plug-in described above). Specifically, these new Ant tasks are:

• ejbDeploy - generates deployment code and RMIC code for an EJB Project.
• ejbExport - exports an EJB project to an EJB JAR file.
• warExport - exports a Web project to a WAR file.
• appClientExport - exports an application client project to an application client JAR file.
• utilJar - JARs up a Java project into a JAR file within an enterprise application project.
• earExport - exports an enterprise application project to an EAR file.

What does an Ant script to perform an EJB Export look like?

<ejbExport EJBProjectName="MyEJBProject"
   EJBExportFile="X:\SOMEPLACE\MyEJBProject.jar"
   ExportSource="false" />

You must specify the input EJBProjectName and the output EJBExportFile parameters. The other parameters are optional. Each of the Ant tasks has a few required parameters and various optional parameters. The attached download code includes documentation of each operation. What if you want to perform an EJB Deploy first, followed by creating a utility JAR, followed by an EAR Export of the result?

<ejbDeploy EJBProject="MyEJBProject"/>
<utilJar JavaProjectName="MyJavaProject"
   EARProjectName="MyEARProject"
   Jar="JarName.jar"
   IncludeBinary="true" />
<earExport EARProjectName="MyEARProject"
   EARExportFile="X:\SOMEPLACE\MyEARProject.ear" />

Given these J2EE Ant tasks for Application Developer, you can now create complete Ant build scripts for your application. In particular, you can run them outside Application Developer using the "headless" workbench facility described in Part 1 . This facility is also included in the download code below .

Now you are all set to create your production Ant builds of J2EE applications.

Back to top

Scripted modification of J2EE deployment descriptors

In many Web application environments, the J2EE deployment descriptors need to be modified to fit the particular Web server they are being deployed on. Typical examples are changing the jdniName(s), securityRole(s), etc. One approach is to enhance the J2EE Ant build to produce multiple EARs, each EAR specifically created for a specific Web server. You can do this by using simple Ant Replace commands to perform simple text substitutions.

<target name="EjbExport" >
   <copy file="ejbModule/META-INF/ibm-ejb-jar-bnd.xmi"
      tofile="ejbModule/META-INF/ibm-ejb-jar-bnd.BACKUP"
      overwrite="yes" preservelastmodified="yes" />
   <replace file="ejbModule/META-INF/ibm-ejb-jar-bnd.xmi"
      token='"MyTarget_Bnd" jndiName="com/MyCompany/MyJdniName"'
      value='"MyTarget_Bnd" jndiName="com/MyCompany/MyJdniNameNEW"' />
   <ejbExport EJBProjectName="MyEJBProject"
      EJBExportFile="X:\SOMEPLACE\MyEjbExport.jar" ExportSource="false" />
   <copy file="ejbModule/META-INF/ibm-ejb-jar-bnd.BACKUP"
      tofile="ejbModule/META-INF/ibm-ejb-jar-bnd.xmi"
      overwrite="yes" preservelastmodified="yes" />
</target>

If simple text substitution is not enough, your Ant script could shell out to invoke a complex script edit (perhaps using awk or some other scripting tool):

<target name="WarExport" >
   <copy file="webApplication/WEB-INF/ibm-web-bnd.xmi"
      tofile="webApplication/WEB-INF/ibm-web-bnd.BACKUP"
      overwrite="yes" preservelastmodified="yes" />
   <exec dir="webApplication/WEB-INF/"
      executable="cmd.exe" os="Windows 2000" output="modify.log">
      arg line="/c awk MyScript.awk MyTargetText MyNewText" />
   </exec>
   <warExport WARProjectName="MyWebProject"
      WARexportFile="X:\SOMEPLACE\MyWarExport.war"
      ExportSource="false" />
   <copy file="webApplication/WEB-INF/ibm-web-bnd.BACKUP"
      tofile="webApplication/WEB-INF/ibm-web-bnd.xmi"
      overwrite="yes" preservelastmodified="yes" />
</target>

Both of the above techniques are somewhat simplistic, inflexible, and error-prone. We are considering creating a new Ant task called modifyDeploymentInformation that would be specialized for these operations. If you have suggestions to improve the above techniques, or a suggested enhancement or change to any of these new J2EE Ant tasks, e-mail them to Barry Searle. We are want to ensure that developers have the Ant tasks they need for effective production builds, so your suggestions will be received with great interest.

The IBM Predeploy Tool for J2EE Applications prepares J2EE application files for installation into WebSphere Application Server, Version 4.0. It generates WebSphere application bindings, and can operate on all EJBs in the application. If you need this functionality, you can register and download the tool. You can find out more about it in the IBM developerWorks Newsletter, which describes a technical preview of the Predeploy Tool for J2EE Applications.

Back to top

Overview of Part 3 -- Creating new Ant tasks

With Part 1 and Part 2 of this article, you have a good set of production Ant build capabilities. However, there may be one or two special things that your build has to do. The "Why use Ant" section of Part 1 explained that one reason to use Ant is that it is written in Java and you can therefore write new Ant tasks in Java to extend the build capabilities. Part 3 of this article explains how to write new Java Ant tasks to provide specialized build functions you may need (just like the J2EE Ant tasks described in this article).

Back to top

Summary

This article explained why J2EE deployment descriptors are optimized within Application Developer for quick and easy testing on its internal WebSphere Application Server, and how the various J2EE export operations merge and modify this information whenever standard J2EE modules are exported. The article then described a set of new Ant tasks that can be used to perform the same J2EE deploy or export operations during builds, including during production Ant builds run outside a "headless" Application Developer. It also described how to modify deployment descriptors as part of building and deploying to different target Web servers. Thus, this article described how a production build of J2EE products can be achieved, and included download code containing the new J2EE Ant tasks (along with simple HTML documentation).

Back to top

Downloads

Name	Size	Download method
com.ibm.ant.extras_V4.zip	0.1 MB	FTP|HTTP
com.ibm.ant.extras_V5EA.zip	0.1 MB	FTP|HTTP

Information about download methods

About the authors

Barry Searle is the Migration Team Leader for WebSphere Studio Application Developer. He is a professional engineer who has worked at the IBM Toronto Lab for over ten years on various application development tools. Prior to that he had many years of industry experience developing command and control systems and leading complex communications development projects. You can reach Barry at searle@ca.ibm.com.

Ellen McKay is an Information Developer for IBM Toronto Lab. She writes online help and publications for WebSphere Studio Application Developer. You can reach Ellen at ecmckay@ca.ibm.com .

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Download files
• J2EE modules and and reference reading
• J2EE builds and Java utility JARs inside Application Developer
• J2EE deployment descriptors inside Application Developer
• Ant J2EE builds outside Application Developer ("headless" operation)
• Scripted modification of J2EE deployment descriptors
• Overview of Part 3 -- Creating new Ant tasks
• Summary
• Downloads
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Webcast: Using Rational Application Developer with WebSphere Application Server to increase productivity
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers