644 WebSphere Studio Application Developer Version 5 Programming Guide Forced build To generate a complete build, select the clean target as the first target and the dist target as the second target to run. You have to de-select dist, select clean, and then select dist again to get the execution order right (Figure 19-9). Figure 19-9 Launching Ant to generate complete build Classpath problem The classpath specified in the Java build path for the project is, unfortunately, not available to the Ant process. If you are building a project that references another project, the classpath for the javac compiler must be set up in the following way: <javac srcdir="${source}" destdir="${build}" includes="**/*.java"> <classpath> <pathelement location=" /MyOtherProject"/> <pathelement location=" /MyThirdProject"/> </classpath> </javac> Building J2EE applications As we have just shown, building a simple Java application using Ant is quite easy. Now we will also show you how to use Ant to build your J2EE projects. EAR, WAR, and EJB JAR files all contain a number of deployment descriptors that control how the artifacts of the application are to be deployed onto an Chapter 19. Building applications with Ant 645 application server. These deployment descriptors are mostly XML files and are standardized in the J2EE specification. While working in Application Developer, some of the information in the deployment descriptors is stored in XML files, but these files also contain information in a format convenient for interactive testing and debugging. That is part of the reason it is so quick and easy to test J2EE applications in the internal WebSphere Application Server included with Application Developer. The actual EAR being tested, and its WAR, EJB, and client application JARs, are not actually created as a standalone file. Instead, a special EAR is used that simply points to the build contents of the various J2EE projects. Because these 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. Therefore, during the export operation, all absolute paths are changed into self-contained relative references within that EAR, and the internally optimized deployment descriptor information is merged and changed into a standard format. To create a J2EE compliant WAR or EAR, we therefore have to use Application Developer’s export function. Using or importing a J2EE project In this example we use the ItsoProGuide enterprise application we developed in the previous chapters. This application consists of one EJB module, several Web modules, a J2EE client application, and a utility JAR file (from a Java project). You can use the ItsoProGuide enterprise application that you have in your workspace, or you can import our sample application as described in “Installing the ItsoProGuide.ear file” on page 812. Ant J2EE build script To build the ItsoProGuide enterprise application, we wrote a new Ant build script that utilizes the Application Developer’s J2EE Ant tasks. Because this build script is not really tied to either Web projects or the EJB project, we chose to put it in the enterprise application project’s META-INF directory. To add this script, do the following: Make sure the J2EE perspective is shown and that the J2EE Navigator view is selected. Expand the ItsoProguide project, select the META-INF directory and New -> Other (context), then select Simple -> File and click Next. 646 WebSphere Studio Application Developer Version 5 Programming Guide Enter build.xml as the file name and make sure that the folder says ItsoProGuide/META-INF. Then click Finish. Switch to the Source tab and paste the code in Example 19-1 into the build.xml file. The source code is available in: \sg246957\sampcode\deploy-ant\j2ee\build.xml Example 19-1 J2EE Ant script <?xml version="1.0" encoding="UTF-8"?> <project name="ITSO Pro Guide Ant" default="Total" basedir="."> <! Set global properties > <property name="work.dir" value="c:/ItsoProGuideTest" /> <property name="dist" value="${work.dir}/dist" /> <property name="project.ear" value="ItsoProGuide" /> <property name="project.ejb" value="ItsoProGuideEJB" /> <property name="project.war.1" value="ItsoProGuideBasicWeb" /> <property name="project.war.2" value="ItsoProGuideStrutsWeb" /> <property name="project.util" value="ItsoProGuideJava" /> <property name="project.client" value="ItsoProGuideJavaClient" /> <property name="type" value="incremental" /> <==== or full <property name="debug" value="false" /> <property name="source" value="false" /> <property name="meta" value="false" /> <property name="noValidate" value="false" /> <target name="init"> <! Create the time stamp > <tstamp /> <! Create the dist directory where the output files are placed > <mkdir dir="${dist}" /> </target> <target name="info"> <! Displays the properties for this run > <echo message="debug=${debug}" /> <echo message="type=${type}" /> <echo message="source=${source}" /> <echo message="meta=${meta}" /> <echo message="noValidate=${noValidate}" /> <echo message="Output directory=${dist}" /> <echo message="project.ear=${project.ear}" /> <echo message="project.ejb=${project.ejb}" /> <echo message="project.war.1=${project.war.1}" /> <echo message="project.war.2=${project.war.2}" /> <echo message="project.util=${project.util}" /> <echo message="project.client=${project.client}" /> </target> Chapter 19. Building applications with Ant 647 <target name="deployEjb"> <! Generates deployed code for the EJBs > <ejbDeploy EJBProject="${project.ejb}" NoValidate="${noValidate}" /> </target> <target name="buildEjb" depends="deployEjb"> <! Builds the EJB project > <projectBuild ProjectName="${project.ejb}" BuildType="${type}" DebugCompilation="${debug}" /> </target> <target name="buildWar1"> <! Builds the WAR project > <projectBuild ProjectName="${project.war.1}" BuildType="${type}" DebugCompilation="${debug}" /> </target> <target name="buildWar2"> <! Builds the WAR project > <projectBuild ProjectName="${project.war.2}" BuildType="${type}" DebugCompilation="${debug}" /> </target> <target name="buildUtil"> <! Builds the utility project > <projectBuild ProjectName="${project.util}" BuildType="${type}" DebugCompilation="${debug}" /> </target> <target name="buildClient"> <! Builds the application client project > <projectBuild ProjectName="${project.client}" BuildType="${type}" DebugCompilation="${debug}" /> </target> <target name="buildEar"> <! Builds the EAR project > <projectBuild ProjectName="${project.ear}" BuildType="${type}" DebugCompilation="${debug}" /> </target> <target name="exportEjb" depends="init"> <! Exports the EJB JAR > <ejbExport EJBProjectName="${project.ejb}" EJBExportFile="${dist}/${project.ejb}.jar" ExportSource="${source}" overwrite="true" /> </target> 648 WebSphere Studio Application Developer Version 5 Programming Guide <target name="exportWar1" depends="init"> <! Exports the WAR file > <warExport WARProjectName="${project.war.1}" WARExportFile="${dist}/${project.war.1}.war" ExportSource="${source}" overwrite="true" /> </target> <target name="exportWar2" depends="init"> <! Exports the WAR file > <warExport WARProjectName="${project.war.2}" WARExportFile="${dist}/${project.war.2}.war" ExportSource="${source}" overwrite="true" /> </target> <target name="exportClient" depends="init"> <! Exports the application client JAR file > <appClientExport AppClientProjectName="${project.client}" AppClientExportFile="${dist}/${project.client}.jar" ExportSource="${source}" overwrite="true" /> </target> <target name="exportEar" depends="init"> <! Exports the EAR file > <earExport EARProjectName="${project.ear}" EARExportFile="${dist}/${project.ear}.ear" ExportSource="${source}" IncludeProjectMetaFiles="${meta}" overwrite="true" /> </target> <target name="buildAll" depends="buildEjb,buildWar1,buildWar2,buildClient,buildUtil,buildEar"> <! Builds all projects > <echo message="Built all projects" /> </target> <target name="exportAll" depends="exportEjb,exportWar1,exportWar2,exportClient,exportEar"> <! Exports all files > <echo message="Exported all files" /> </target> <target name="Total" depends="buildAll,exportAll"> <! Buidl all projects and exports all files > <echo message="Total finished" /> </target> <target name="clean"> <! Delete the output files > <delete file="${dist}/${project.ejb}.jar" failOnError="false" /> <delete file="${dist}/${project.war.1}.war" failOnError="false" /> Chapter 19. Building applications with Ant 649 <delete file="${dist}/${project.war.2}.war" failOnError="false" /> <delete file="${dist}/${project.client}.jar" failOnError="false" /> <delete file="${dist}/${project.ear}.ear" failOnError="false" /> </target> </project> This script provides you with a selection of useful J2EE operations you can combine to produce the desired results. We will not go through all the different Application Developer Ant tasks that we use because their names describe their purpose. We have included some dependencies between the targets: Building the EJB project relies on generating the deployed code Build all executes all the build targets Export all executes all the export targets A total target executes build all and export all In the global properties for this script we define a number of useful variables, such as the project names and the target directory. We also define a number of properties that we pass on to the Application Developer Ant tasks. These properties allow us to control whether the build process should perform a full or incremental build, if debug statements should be included in the generated class files, and if Application Developer’s metadata information should be included when exporting the project. When launching this Ant script, we can also override these properties by specifying other values in the arguments field, allowing us to perform different kinds of builds with the same script. We only included two of the Web projects for separate build and export. The script could be expanded to include all the Web projects of the enterprise application. Note: Documentation for the Application Developer Ant tasks can be found in: <wsad>\wstools\eclipse\plugins\com.ibm.etools.j2ee.ant_5.0.1\doc\index.htm There are also tasks for regenerating EJB Access Beans and some other utility tasks. 650 WebSphere Studio Application Developer Version 5 Programming Guide Running Ant for J2EE When launching the build.xml script, we can select which targets to run and the execution order. As an example we export some of the projects with their source code by calling the following targets (in the order as shown below): info Shows the properties that will be used clean Removes old output files, if they exist init Creates the output directory buildWar1 Builds one Web project exportWar1 Exports one Web project exportEjb Exports the EJBs exportEar Exports the EAR project Select the build.xml file in the J2EE Navigator view and Run Ant (context). Select the targets in the correct sequence and enter arguments to build the class files with debugging information, include the source code, and include Application Developer metadata in the generated EAR file: -DDebug=true -Dsource=true -Dmeta=true . The output EAR file is placed in the directory: c:\ItsoProGuideTest\dist Figure 19-10 shows the target selection dialog with the argument. On the right-hand side, the Log Console view shows the operations performed and their results. At the very beginning, the properties used in the script are displayed. Chapter 19. Building applications with Ant 651 Figure 19-10 Launch Ant to build and export a J2EE project To build a production-ready EAR file, you would have to execute the total target with an argument of -Dtype=full so that all the classes are recompiled without debugging information. We have now shown you two examples of using Ant within Application Developer. These are basic operations that you could perform using the Application Developer GUI. With Ant you can also automate more complex tasks, for example, to perform a complete build of a project, export the resulting EAR file, deploy it to a WebSphere Application Server, start it, run regression tests using JUnit, and send you an e-mail with the results. This is outside the scope of this book. Building Javadoc with Ant See “Using Ant to generate Javadoc” on page 136 for an Ant build script to generate Javadoc. 652 WebSphere Studio Application Developer Version 5 Programming Guide Running Ant outside of Application Developer To automate the build process even further, you may want to run Ant outside of Application Developer by running Ant in a so called headless mode for this purpose. Preparation of the command file Application Developer provides a runAnt.bat file in: <wsad>\wstools\eclipse\plugins\com.ibm.etools.j2ee.ant_5.0.1 This command file invokes Ant in headless mode and passes the parameters that you specify. The file must be tailored with the workspace location. To build our J2EE project, we copied the runAnt.bat file to a new file called itsoRunAnt.bat and changed it as shown in Figure 19-11. Figure 19-11 Modified runAnt.bat file We updated the WSAD variable to point to the directory where Application Developer is installed (also include the \eclipse subdirectory) and the WORKSPACE variable to point to our workspace directory. We provide the modified file in: \sg246957\sampcode\deploy-ant Note that you have to tailor the file with correct directory locations. echo off setlocal REM The root directory of your WSAD installation set WSAD=D:\WSAD5\eclipse REM ************* The location of your workspace ***************** set WORKSPACE=E:\WSAD5sg246957 REM ************* The location of your workspace ***************** if not exist %WORKSPACE% echo ERROR: incorrect workspace=%WORKSPACE%, edit this runAnt.bat and correct the WORKSPACE envar if not exist %WORKSPACE% goto done :run @echo on %WSAD%\jre\bin\java -cp %WSAD%\startup.jar org.eclipse.core.launcher.Main -consolelog -application com.ibm.etools.j2ee.ant.RunAnt -data %WORKSPACE% %* :done Chapter 19. Building applications with Ant 653 Running the command file To run the command file, start a Windows command prompt and change to the directory where the itsoRunAnt.bat file is located. Then execute the following command: itsoRunAnt -buildfile c:\WSAD5sg246957\ItsoProGuide\META-INF\build.xml clean exportWar1 -Dsource=true -Dmeta=true The -buildfile parameter should specify the fully qualified path of the build.xml script file. We can pass the targets to run as parameters to itsoRunAnt and we can also pass Java environment variables by using the -D switch. In this example we chose to run the clean and exportWar1 targets and we chose to include the Java source and metadata files in the resulting EAR file. The output from the script is shown in Example 19-2. Example 19-2 Ant headless output Headless RunAnt started RunAnt.run antArgs.length=11 RunAnt.run about to null HeadlessWorkspaceSettings RunAnt.run about to create new HeadlessWorkspaceSettings RunAnt.run DONE create new HeadlessWorkspaceSettings RunAnt.runAntCommands args=[Ljava.lang.String;@1b3f0c97 RunAnt.runAntCommands about to create new AntRunner RunAnt.runAntCommands DONE create new AntRunner RunAnt.runAntCommands args=[Ljava.lang.String;@1b3f0c97 clean: init: exportWar1: [warExport] Exporting: ItsoProGuideBasicWeb [warExport] Exporting: ItsoProGuideBasicWeb Building: /ItsoProGuideBasicWeb. Invoking Java Builder on /ItsoProGuideBasicWeb [warExport] Exporting: ItsoProGuideBasicWeb Building: /ItsoProGuideBasicWeb. Reading saved built state for project ItsoProGuideBasicWeb [warExport] Exporting: ItsoProGuideBasicWeb Building: /ItsoProGuideBasicWeb. Preparing for build Note: When running Ant in headless mode, Application Developer must not be started. If Application Developer is started on the machine where runAnt.bat is invoked, it does not do anything. . an Ant build script to generate Javadoc. 652 WebSphere Studio Application Developer Version 5 Programming Guide Running Ant outside of Application Developer To automate the build process even. for regenerating EJB Access Beans and some other utility tasks. 650 WebSphere Studio Application Developer Version 5 Programming Guide Running Ant for J2EE When launching the build.xml script,. File and click Next. 646 WebSphere Studio Application Developer Version 5 Programming Guide Enter build.xml as the file name and make sure that the folder says ItsoProGuide/META-INF. Then click