Headless Ant builds in Rational Application Developer
Headless Ant builds provides a scriptable way of automating production builds of Eclipse based workspaces. These types of builds are performed from a command line, and are faster and more resource efficient.
The headless build feature in Rational Application Developer is based on Apache Ant. Supported by the Eclipse platform, it enables you to perform headless builds (compiling and packaging) of applications that you create in Rational Application Developer. Different versions of Apache Ant are supported in the following versions of Rational Application Developer:
- Apache Ant 1.7.1 for Rational Application Developer 8.0.x
- Apache Ant 1.7.0 for Rational Application Developer 7.5.x
- Apache Ant 1.6.5 for Rational Application Developer 7.0.0.x
The application developer tool provides a series of Ant tasks that you can use in headless mode through the build utility. They are similar to common operations performed by developers in an Eclipse workbench.
Headless build results are consistent with Rational Application Developer (Eclipse) build systems. By using the build utility, you can ensure that jobs you would normally run in the Rational Application Developer graphical interface are also run, such as indexing jobs or ensuring that various validators are configured with the projects.
The Rational build utility feature (the build utility) can be run exclusively from the command line. The Build Utility is the Rational Application Developer's headless build feature made into a stand-alone tool. You can install it through IBM Installation Manager on both Windows and Linux. See the documentation in the product information center for how to get and install the Rational Build Utility. A separate offering is also available for the IBM System z® platform; see Rational Build Utility z/OS offering documentation.
The code base for the build utility and the Rational Application Developer headless Ant builds are the same. Each Ant task contributed by the build utility can be directly mapped to a specific action or function in the application development workbench.
To run a headless build of a Rational Application Developer workspace, you must have the following items available:
- The workspace
- An Ant build script that defines the build, such as
build.xml - Either Rational Application Developer or the build utility installed on your build machine
You typically run headless builds from either a UNIX terminal or a Windows command prompt. The input is a single Eclipse workspace that contains projects and applications. The output depends on the type of work performed by the Ant build script, but it usually includes a compilation of the Eclipse workspace projects and the export files and packages of your applications.
A headless build is based on a single workspace and a new directory can usually be created to serve as the 'headless workspace'. It is also fundamental to have a workspace environment variable set up to point to the workspace directory before the headless build can run without errors.
Builds typically follow three distinct steps:
- Import projects
- Build projects
- Export application artifacts (EAR, WAR, JAR, SCA and OSGi archives for example)
Note that importing projects from the application development tool can either happen from a source control management system or directly from the local file system. The general scenario is to create projects in the application development tool, check them in to a source control system, and then use the build utility to import from the source control system for the headless build to proceed. For the introductory purposes of this article, we only cover how to import projects from a local file system.
You typically create the XML build script on your own. The script contains a combination of standard Apache Ant tasks as well as Ant tasks provided by Rational Application Developer. You can create the script in Rational Application Developer or your preferred editor.
The build utility includes the following Ant tasks for importing projects into a workspace, compiling projects, exporting build results as Java archives like WARs and EARs and many more:
projectImport- imports a project from the local file systemprojectBuild- builds (compiles) a single projectworkspaceBuild- performs a full build of the workspaceexportEAR- exports the project as an EAR file
For a detailed list of the Ant tasks as of version 8.0 see the product documentation. For more information about how to run the build utility see its documentation.
Integrate with Websphere Application Server, source control management systems, and more
As previously mentioned, a headless build can potentially import projects from any source control system. At the time of this writing, CVS is currently supported even though it is possible to extend this functionality in general to any other source control system. A possible workaround is to use the projectImporttask to import Eclipse projects from the local file system that you have checked out from a source control system.
You can integrate the build utility with IBM® WebSphere® Application Server. By default, the build utility packages the stub runtimes for different WebSphere Application Server versions, depending on the product version. The current version of the build utility is 8.0.3 and it provides the stubs for versions 6.0, 6.1, 7.0 and 8.0. The build utility and Rational Application Developer headless Ant builds can target the WebSphere Application Server stubs that come with it. The builds use a specific application server stub or runtime for compilation. Moreover, the build uses whatever runtime the projects created by the user in Rational Application Developer are pointing to, whether it is a stub runtime, a real application server runtime, or even a WebSphere test environment in the case of Rational Application Developer.
A third case that you can pursue is to include external libraries in a headless builds. For example, use ant-contrib.jar. This library provides you with a set of useful Ant tasks and XML control structures that you can use in the build script. For more information about this library, see the ant-contrib documentation.
New features in the build utility
You can install this version of the build utility through IBM Installation Manager on both the Linux and Windows platforms. The IBM System z offering still remains a compressed file format.
As of Rational Application Developer v8 (Headless Ant and the build utility), the Ant build tool includes numerous extra features and Ant tasks. The premier feature is support for building user projects that are targeted for a Websphere Application Server v8 runtime.
A series of new Ant tasks have also been included in the various v8.0.x fix pack releases. Some of the tasks were added to support importing, exporting, and compiling new artifact types in Rational Application Developer v8.0:
scaArchiveExport.This task allows SCA projects to be exported.- OSGi Enterprise tooling Ant tasks. A series of Ant tasks created to import, export and convert OSGi Enterprise artifacts.
prepareForDeploy.Just like in the workbench, this task will generate and compile the deployment code necessary for your application to run on a WebSphere Application Server.xmlCatalog.The task allows modification of the XML Catalog used by the product for a given workspace. The same operation may be performed within RAD via the workspace preferences. For more information, see the documentation.disableIndexer. This task allows disabling workspace indexers which usually make sense mainly in a graphical (UI) environment. Using this task should improve the performance of headless builds.- Server Control Ant tasks. A series of tasks that allow handling workspace server runtimes: creating a server, starting/stopping a server, publishing to a server.
A scenario for using the build utility
In this section, we will work through a sample scenario for using the build utility. It shows how you can use the utility to perform a headless build of an application that was created in Rational Application Developer. The SimpleCalculator application consists of a series of projects from Rational Application Developer that implement a simple mathematical calculator. There is an EAR project made up of an EJB module, an application client module and a web module.
The Ant script used to perform the headless build of the sample workspace will be examined (see the demoBuild.xml file), together with the output expected from its run by using the build utility (the expected output is also provided in the output.log file). The most significant part of this scenario is the example of how single Rational Application Developer Ant tasks in the build script can directly be mapped to functions inside the workbench. To see the sample and the files contained in it, get the DemoBuild.zip archive found at the end of this article.
Assuming that Windows is used to run the headless build of the sample, the following actions must be performed:
- Extract the sample files to a temporary location (use
C:\DemoBuild) - Open a command prompt and type: cd
RBU_HOME\bin(whereRBU_HOMEis the directory where the build utility is installed) - Set the workspace:
set workspace= C:\DemoBuild - Run the headless build:
runAnt.bat –f C:\DemoBuild\demoBuild.xml)
Then we must review the build script to understand what actions the headless build performs. See the demoBuild.xml file in the sample. Each of the following sections focuses on a particular Ant task from Rational Application Developer and used to perform one, or more, specific workbench operations:
- Initialize the workspace
- Import the projects into the workspace
- Build the projects
- Prepare the application server deployment code
- Export different types of artifacts
- Create a workspace server
- Start the server and add projects to it
- Remove projects from the server
- Stop and delete the the server
The following createWSRuntime Ant task is the first one run by the sample script:
<createWSRuntime targetId="was.v7.runtime" path="C:/IBM/SDP/802/20110227_1157/runtimes/base_v7" typeId="com.ibm.ws.ast.st.runtime.v70" /> |
The task creates a workspace runtime environment of a type specified by the mandatory typeId attribute. The path attribute is also a mandatory one. You must specify the location on the file system where the installation directory for the runtime environment is located. Finally, the targetId attribute represents the ID that is assigned to the new runtime and can later be used when creating a new workspace server with the createWSServer Ant task. The targetId attribute is optional. If a value is not provided, a default value will be set. The following related output is from the task:
[createWSRuntime] Creating a new server runtime. [createWSRuntime] ... subtask: Saving WebSphere Application Server v7.0 [createWSRuntime] Done creating a new server runtime. |
You can get a list of available runtimes that are created by the createWSRuntime task from the listRuntimeTypes Ant task. For more information, see the related documentation.
You can create a server runtime in the workbench through the Rational Application Developer preferences window. Select Windows > Preferences > Server > Runtime Environments and use the wizard to add a new runtime environment.
Figure 1. Create a new server runtime
Import the projects into the workspace
The following calls of the projectImport Ant task are responsible for importing the different projects from the sample workspace into the build utility workspace:
<projectImport projectName="SimpleCalculatorEJB21"
projectlocation="${basedir}/SimpleCalculatorEJB21" />
<projectImport projectName="SimpleCalculatorEJB21Client"
projectlocation="${basedir}/SimpleCalculatorEJB21Client" />
<projectImport projectName="SimpleCalculatorEJB21Web"
projectlocation="${basedir}/SimpleCalculatorEJB21Web"/>
<projectImport projectName="SimpleCalculatorEJB21EAR"
projectlocation="${basedir}/SimpleCalculatorEJB21EAR"/> |
If you were to do this same task in the graphical interface, you would select File > Import > General > Existing Project.
Figure 2. Import projects into the workspace
Each task call receives the two attribute parameters projectName and projectLocation. Only the first parameter is required. It specifies the name of the project to be imported. If a location is not specified, the default location<workspace>/<projectName>is used. If a location is specified, the project is imported from that location.
The following output represents the first invocation of the projectImport task in this sample:
[projectImport] projectName=SimpleCalculatorEJB21 projectLocation=C:\ArticleSample2/SimpleCalculatorEJB21 [projectImport] importing projectLocation=SimpleCalculatorEJB21 [projectImport] (Begin) [projectImport] project.create [projectImport] project.open [projectImport] ... subtask: Opening 'SimpleCalculatorEJB21'. Opening 'SimpleCalculatorEJB21'. [projectImport] ... subtask: Opening 'SimpleCalculatorEJB21'. Refreshing '/SimpleCalculatorEJB21'. [projectImport] (Done) |
Moreover, the import task ensures that extra operations, such as those that would normally run in the workbench after the import of a project are also run in headless mode.
Let's now take a look at the build operations. Here a single task is used, which performs the full workspace build.
<workspaceBuild buildtype="full"/> |
The previous call compiles the whole sample workspace to produce the following output:
[workspaceBuild] WorkspaceBuild (Begin) [workspaceBuild] (Begin) [workspaceBuild] ... subtask: Invoking 'Java Builder' on '/SimpleCalculatorEJB21Client'. [workspaceBuild] ... subtask: Preparing to build SimpleCalculatorEJB21Client [workspaceBuild] ... subtask: Cleaning output folder for SimpleCalculatorEJB21Client [workspaceBuild] ... subtask: Copying resources to the output folder [workspaceBuild] ... subtask: Cleaning output folder for SimpleCalculatorEJB21Client [workspaceBuild] ... subtask: Copying resources to the output folder [workspaceBuild] ... subtask: Analyzing sources [workspaceBuild] ... subtask: Compiling SimpleCalculatorEJB21Client/ejbModule/org/omg/stub/javax/ejb [workspaceBuild] ... subtask: Compiling SimpleCalculatorEJB21Client/ejbModule/org/omg/stub/java/lang [workspaceBuild] ... subtask: Compiling SimpleCalculatorEJB21Client/ejbModule/ejbs [workspaceBuild] ... subtask: Compiling SimpleCalculatorEJB21Client/ejbModule/com/ibm/websphere/csi |
This call is only part of the generated headless output. You can see all of the headless build output of the sample in the provided output.log file.
The workspaceBuild Ant task has the same effect as selecting Project > Build All from inside the workbench.
Figure 3. Performing a full workspace build from within the workbench
Building the whole workspace ensures the other required post build operations are also performed. These operations might include running workspace validators or indexers, as well as executing external tool builders that are configured within the projects. Some validation is run during the headless build of the simple calculator workspace, which is displayed in the following output:
[workspaceBuild] ... subtask: Invoking 'Faceted Project Validation Builder' on '/SimpleCalculatorEJB21Client'. [workspaceBuild] ... subtask: Invoking 'Validation' on '/SimpleCalculatorEJB21Client'. |
Prepare application server deployment code
The prepForDeploy task generates the application server deployment code of the project that is specified by the projectNameattribute. In the simple calculator sample, the task is invoked in correspondence to the EAR project. This action is generally required for EJB v2.x artifacts and for Web services deployment code. More modern artifacts will not require prepForDeploy to be invoked as the Websphere application server will generate their deployment code automatically. The same result can be obtained in the workbench by right clicking on the SimpleCalculatorEJB21EAR project and selecting the Java EE > Prepare for Deployment option.
Figure 4. Preparing for deployment in the workbench
Export Different types of artifacts
In the following example, there are three different export tasks that are being invoked: earExport, ejbExport and warExport. All three use a similar syntax, but the difference is the name of certain key attributes of the task. The generic "projectName" and "exportFile" attributes (earProjectName and earExportFile in the case of the earExport task for example) are the only two required attributes. They specify respectively the name of the project to export and which file the exported artifacts should be saved to.
<earExport EARProjectName="SimpleCalculatorEJB21EAR"
EARExportFile="${basedir}/simpleCalculatorEJB21EAR.ear" overwrite="true" />
<ejbExport ejbprojectname="SimpleCalculatorEJB21"
ejbexportfile="${basedir}/simpleCalculatorEJB21.jar" overwrite="true" />
<warExport warprojectname="SimpleCalculatorEJB21Web"
warexportfile="${basedir}/simpleCalculatorEJB21Web.war" overwrite="true" /> |
Note that we use the overwrite attribute. Since the value is set to "true" the operation ensures that any previously created EAR, JAR or WAR files are overwritten. The following output is a sample of the earExport tasks:
[earExport] Exporting project: SimpleCalculatorEJB21EAR (Begin) [earExport] (Begin) [earExport] ... subtask: Exporting archive 'simpleCalculatorEJB21EAR.ear'. Refreshing '/SimpleCalculatorEJB21EAR'. [earExport] (Done) [earExport] EARExport completed to C:\ArticleSample2/simpleCalculatorEJB21EAR.ear |
You can perform this same task in the workbench by right-clicking on the project and selecting the corresponding export action. For example, Export > EAR file:
Figure 5. Exporting an EAR file in the workbench
The following sample task creates a WebSphere Application Server v7 workspace based on the runtime which was created earlier on in the headless build by the createWSRuntime task and specified by the required attribute runtimeId of the workspace server creation task.
<createWSServer targetId="was7server" typeId="com.ibm.ws.ast.st.v7.server.base" runtimeId ="was.base.v7" /> |
The other required attribute is targetId, which is later used by the other contributed server control Ant tasks in order to use the server; start it up, add and remove projects to it, perform a publishing operation.
Finally, the typeIdattribute is an optional one. If it is not specified, the value defaults to the server name itself. You can get a list of all workspace servers that can be created by using the listServerTypes Ant task (see the related documentation).
When createWSServer is run it generates the following output:
[createWSServer] Creating a new server instance. [createWSServer] ... subtask: Saving WebSphere Application Server v7.0 @ localhost [createWSServer] Initializing the server... (Begin) [createWSServer] CWPKI0308I: Adding signer alias "CN=192.168.0.100, OU=Root Certi" to local [createWSServer] keystore "null" with the following SHA digest: [createWSServer] 59:6B:52:1D:8E:94:38:65:25:BF:D4:2B:F9:B8:4F:CC:06:77:0D:C5 [createWSServer] Initializing the server... (Done) [createWSServer] Done creating a new server instance. |
Creating a server in the workbench can be done from the Servers view. Click anywhere in the blank part of the view and select New > Server.
Figure 6. Creating a new server in the workbench
The wizard for creating a server is simple. Select the appropriate runtime that is required for the server. Just like in the Ant task (attribute runtimeId), you must provide the specific runtime in order to create the server instance.
Figure 7. Create a new server in the workbench
Start the server and add projects to it
You can start the server from the Servers view in the workbench. Right-click on the server entry itself and select Start.
Figure 8. Start a server from the workbench
To start the server in headless mode, use the serverId that was previously assigned to the newly create workspace server by the createWSServer Ant task.
<startWSServer serverId="was7server" /> |
The headless build runs for a while before it displays the following message:
[startWSServer] Synchronously starting the server instance 'WebSphere Application Server v7.0 @ localhost'. |
When the server has started, the headless build produces the following message:
[startWSServer] Done starting the server. |
In the workbench, the Console view opens with information about the server startup status. The same status is not displayed after the headless build.
You can add applications from the local workspace into a workspace application server in the "Add and Remove" window. Access this window from the Servers view by right-clicking on a specific server and choosing Add and Remove:
Figure 9. The Add and Remove window
In a headless environment, you can do this same task by using the addToWSServer Ant task:
<addToWSServer serverId="was7server"> <resource name="SimpleCalculatorEJB21EAR" type="ear"/> </addToWSServer> |
Notice the inner resource element. In this task, you can add several resources to the workspace server at one time, without having to run the addToWSServer task multiple times.
When you add the SimpleCalculatorEJB21EAR project to the server and click Finish in the Add and Remove window, the project is added to the server and automatically published. This latter operation is run in headless mode by the publishToWSServer Ant task:
<publishToWSServer serverId="was7server" type="incremental" /> |
The following output is for these two operations in the headless build tool:
[addToWSServer] Adding the following resources to the server: [SimpleCalculatorEJB21EAR,jst.ear]. [addToWSServer] ... subtask: Adding and/or removing resources. [addToWSServer] ... subtask: Saving WebSphere Application Server v7.0 @ localhost [addToWSServer] Done adding the application(s) to the server. [publishToWSServer] The server 'WebSphere Application Server v7.0 @ localhost' is not started. Attempting to start it in 'run' mode. [publishToWSServer] Synchronously starting the server instance 'WebSphere Application Server v7.0 @ localhost'. [publishToWSServer] Done starting the server. [publishToWSServer] Synchronously publishing to the server instance 'WebSphere Application Server v7.0 @ localhost' (type: incremental) [publishToWSServer] (Begin) [publishToWSServer] ... subtask: Preparing launch delegate... [publishToWSServer] ... subtask: Performing pre-launch check... [publishToWSServer] ... subtask: Building prerequisite project list [publishToWSServer] ... subtask: Performing final launch validation... [publishToWSServer] ... subtask: Initializing source locator... [publishToWSServer] (Done) [publishToWSServer] The publishing action may have failed due to the following reason: Source locator does not exist: com.ibm.debug.wsa.WSASourceLookupDirector [publishToWSServer] Done publishing to the server instance 'WebSphere Application Server v7.0 @ localhost'. |
Remove projects from the server
You can remove an application from the workspace server with the removeFromWSServer Ant task. Do this in the Add and Remove window for the server. Alternatively, the user can expand the server entry in the Servers view to see the resources that were added to it. Remove the resource by right-clicking on it and selecting Remove.
Figure 10. Remove projects from a server in the workbench
The call to the corresponding Ant task and its output is:
<removeFromWSServer serverId="was7server">
<resource name="SimpleCalculatorEJB21EAR" type="ear"/>
</removeFromWSServer>
[removeFromWSServer] Removing the following resources from the server:
[SimpleCalculatorEJB21EAR,jst.ear].
[removeFromWSServer] ... subtask: Adding and/or removing resources.
[removeFromWSServer] ... subtask: Saving WebSphere Application Server v7.0 @ localhost
[removeFromWSServer] Done removing the application(s) from the server. |
Just like in the addToWSServer task, multiple resources may be removed at one time from the workspace server by using multiple resource entries inside a single removeFromWSServer task invocation.
The following output is produced when the stopWSServer and deleteWSServer are called:
[stopWSServer] Synchronously stopping the server instance 'WebSphere Application Server v7.0 @ localhost'. [stopWSServer] Done stopping the server. [deleteWSServer] Deleting the server instance 'WebSphere Application Server v7.0 @ localhost'. [deleteWSServer] Done deleting the server instance 'WebSphere Application Server v7.0 @ localhost'. |
Then the following Ant tasks stop and delete the server:
<stopWSServer serverId="was7server" /> <deleteWSServer serverId="was7server" /> |
To perform this same task in the workbench, select the server in the Servers view and click Stop.
Figure 11. Stop a server in the workbench
You can delete the server by right-clicking on the server in the Servers view and selecting Delete.
Figure 12. Delete a server in the workbench
Most Ant tasks in Rational Application Developer provide the failOnError attribute. Use this attribute to decide what to do in cases where errors occur during a headless build. The value of the attribute can either be "false" or "true" with the default value being "true" in most cases and when the attribute is not specified. The effect of having the failOnError attribute set to "true" is that the headless build will exit immediately as soon as an error is found. On the contrary, if the attribute is set to "false" the build will continue running through the script beyond the point where an error was found and ignore the errors.
The build utility also provides some other error detection Ant tasks for build operations. These are the workspaceGetErrors and the projectGetErrors tasks. They are respectively subsets of the workspaceBuild and projectBuild Ant tasks but they do not perform build operations. Both tasks are used to detect the errors independently of how they were generated and display them to the user. For more information on these two tasks, see the related documentation.
| Description | Name | Size | Download method |
|---|---|---|---|
| Archive file for article | DemoBuild.zip | 708KB | HTTP |
Information about download methods
Learn
- Find out more about Rational Application Developer:
- Browse the Rational Application Developer for WebSphere Software page on developerWorks for links to technical articles and many related resources.
- Explore the Information Center.
- For more information about Apache Ant, visit the Apache Ant website
- To get started with the Rational build utility and Rational Application Developer Headless build function, see the product documentation.
- Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
- Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
- Attend a free developerWorks Live! briefing to get up-to-speed quickly on IBM products and tools, as well as IT industry trends.
- Watch developerWorks on-demand demos, ranging from product installation and setup demos for beginners to advanced functionality for experienced developers.
- Improve your skills. Check the Rational training and certification catalog, which includes many types of courses on a wide range of topics. You can take some of them anywhere, any time, and many of the "Getting Started" ones are free.
Get products and technologies
- Try Rational Application Developer for WebSphere Software, free.
- Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.
Discuss
- Check Rational Application Developer wiki to keep up with news and to contribute.
- Join the Development Tools forum to ask questions and participate in discussions.
- Rate or review Rational software. It's quick and easy. Really.
- Share your knowledge and help others who use Rational software by writing a developerWorks article. You'll get worldwide exposure, RSS syndication, a byline and a bio, and the benefit of professional editing and production on the developerWorks Rational website. Find out what makes a good developerWorks article and how to proceed.
- Follow Rational software on Facebook and Twitter (@ibmrational), and add your comments and requests.
- Ask and answer questions and increase your expertise when you get involved in the Rational forums, cafés, and wikis.
- Connect with others who share your interests by joining the developerWorks community and responding to the developer-driven blogs.





