Release Packaging

Once you have constructed your Release Build, you can package it for deployment. The actual format of the Release Package that is created during the packaging stage, as I stated in Chapter 10, depends on the environment you are deploying to. This section describes the following common scenarios for the creation of Java-based Release Packages:

• The creation of Java manifest files

• The creation of a simple Java archive (.jar)

• The creation of Web archives (.war files) for deployment to a Web server

• The creation of enterprise archives (.ear files) for deployment to an application server

There are potentially many other different scenarios for packaging applications ready for deployment, but these are the most common for typical Java development environments.

Creating Manifest Files

A manifest file is usually generated as part of the build process. It contains content about an archive, such as the archive's author, the version, CLASSPATH settings, whether the archive should be signed, and so on. Here archive can simply be seen as another term for our Release Package. Manifest files are required for any .jar, .war, or .ear archive you create. If you do not explicitly create a manifest file, the relevant Ant tasks create a cut-down version for you. However, the creation of the manifest file is an ideal opportunity to embed versioning information into the distribution archive, as in the following example:

Manifest-Version: 1.0 Ant-Version: Apache Ant 1.6.5 Created-By: 1.4.2 (IBM Corporation) Built-By: Dale King Main-Class: com.ratlbank.main.BankMain Name: com/ratlbank/ Specification-Title: "Rational Bank Classes" Specification-Version: "1.0" Specification-Vendor: "IBM Corporation". Implementation-Title: "com.ratlbank" Implementation-Version: "RATLBANK_02_REL" Implementation-Vendor: "IBM Corporation"

To create this manifest file, you would create an Ant target called make-manifest, similar to the following:

<target name="make-manifest" depends="init"     description="create the jar manifest file">     <manifest file="${dir.build}/manifest.mf">         <attribute name="Built-By" value="${user.name}" />         <attribute name="Main-Class" value="${name.main.class}"/>         <section name="com.ratlbank">             <attribute name="Specification-Title" value="Example"/>             <attribute name="Specification-Version" value="${value.spec.version}"/>             <attribute name="Specification-Vendor" value="IBM Corporation"/>             <attribute name="Implementation-Title" value="com.ratlbank"/>             <attribute name="Implementation-Version" value="="${label}"/>             <attribute name="Implementation-Vendor" value="IBM Corporation"/>         </section>     </manifest> </target>

In this example a manifest file called manifest.mf is created in the dir.build directory. Each entry in this file is created via the attribute element and should be self-explanatory. Note that the automatically generated Release Build label or baseline is placed in the Implementation-Version attribute. For more information on manifest files, see the JAR file specification at http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html.

Creating Java Archives

Ant has a number of ways to create archives. The exact task to use depends on whether you want to create a standard Java .jar archive, a .zip file, a Web .war file, or a J2EE .ear file. The .jar (Java archive) format is a standard mechanism that is used for distributing Java client applications. It uses the same compression format as .zip files (hence, you can open and extract them with a standard tool such as WinZip). The main difference is that you can additionally include a manifest file. To create a .jar file, you use the Ant <jar> task:

<jar destfile="${dir.dist}/${ant.project.name}.jar"      basedir="${dir.build}"      manifest="${dir.build}/manifest.mf"      includes="**/*.class"      excludes="**/Test*.class"/>

This example creates a jar file in the ${dir.dist} directory, such as dist/ratlbankmodel.jar, which contains all the built Java .class files (excluding the test classes). It additionally includes the manifest file that was created in the preceding section.

Creating Java Web and Enterprise Archives

The creation of .war and .ear files is slightly different. Essentially both of these files are expected to have a specific format and also include extra deployment descriptor files. The deployment descriptors define settings for the application and where to locate files in the archive relative to each other. For a .war file, the deployment descriptor is usually a single file called WEB-INF/web.xml. For the .ear file, this is usually a file called WEB-INF/application.xml plus any vendor-specific configuration files. The .war and .ear files can be created by the Ant <war> and <ear> tasks, respectively. Here's an example of a <war> task:

<war warfile="${dir.dist}/${ant.project.name}.war"     webxml="WebContent/WEB-INF/web.xml"     manifest="${dir.build}/manifest.mf">     <fileset dir="WebContent">         <exclude name="web.xml"/>     </fileset>     <classes dir="${dir.build}">         <include name="com/ratlbank/**/*.class"/>     </classes> </war>

In this example, a .war file is created using the deployment descriptor web.xml in the directory WebContent/WEB-INF, and a manifest file manifest.mf is created in the dir.build directory (I will discuss manifest files in more detail later). It also includes the content of the WebContent directory, except for the web.xml file (because it has already been consumed as the deployment descriptor). The WebContent directory typically contains HTML files, images, and JSP files. Finally, any supporting Java classes, such as servlets, that have been built in the dir.build directory are also included in the archive.

Rational Application Developer and Headless Ant Builds

If you are using WebSphere Studio or Rational Application Developer, you can use the version of Ant that is supplied with these products and run it in "headless" mode. "Headless" means running builds from the WebSphere Studio or Rational Application Developer workspace but without starting up the GUI. This allows you to take advantage of a number of built-in capabilities for creating and deploying Release Packages. However, the main disadvantage is that your build process is then tied to your IDE and the particular workspace that you set up for building in. For more information on this capability, see the online help or http://www-128.ibm.com/developerworks/websphere/library/techarticles/0505_weisz/0505_weisz.html.

Similarly, an example of an <ear> task is as follows:

<!-- define a patternset for distribution sources --> <patternset >     <include name="**/*.jar"/>     <include name="**/*.war"/>     <include name="**/*.ear"/> </patternset> <ear destfile="${dir.dist}/RationalBank.ear"     appxml="META-INF\application.xml">     <fileset dir="${dir.dist}">         <patternset ref/>             <exclude name="**/*.ear"/>     </fileset> </ear>

In this example, an .ear file is created using the previously built .war file as well as the file META-INF/application.xml, which is the deployment descriptor for the complete application. For a more complete enterprise application, you might also include EJB and application client projects, as well as additional deployment information files for different vendors' application servers. For more information on creating .war and .ear archives, refer to Hatcher [Hatcher02] or Hightower et al. [Hightower04].

Release Packaging with IBM Tivoli Configuration Manager

IBM Tivoli Configuration Manager is a comprehensive enterprise tool for capturing and automating software distribution best practices. Rather than just allowing you to define packages, Tivoli Configuration Manager is also a complete infrastructure for deployment. It includes software distribution and inventory components so that you can deploy applications to multiple locations from a central point, ensuring that the endpoints are compliant with appropriate hardware, software, and patch levels.

Tivoli Configuration Manager includes a Software Package Editor tool, as shown in Figure 11.1. If you are familiar with InstallShield or MSI packaging on Windows, or RPM packages on Linux, the concept is the same. Basically, you define a package in terms of the files and directories that are to be installed on the target. Then you include other settings, such as Registry entries, installation of services, creation of program groups, and so on. The Software Package Editor can be "dropped" onto a developer's desktop so that he or she can create the package definition files that are to be used as part of the build process. Packages can also be versioned and sealed so that you can ensure consistency between teams. For more information on using ClearCase with Tivoli Configuration Manager, see the paper "Using Tivoli software distribution with Rational ClearCase UCM," located at http://www-128.ibm.com/developerworks/rational/library/5447.html.

Figure 11.1. Tivoli Software Package Editor

A Complete Package Target

Now that you understand how to create a distribution archive and Release Package, you can put together a complete Ant example to create Release Packages and stage them, as illustrated in Listing 11.1.

Listing 11.1. Release Target with Packaging

<?xml version="1.0"?> <project name="RatlBankWeb" default="help" basedir="."     xmlns:ca="antlib:net.sourceforge.clearantlib">     <property name="dir.dist"  value="dist"/> ... <target name="dist" description="create release package">     depends="junit-all,make-manifest">     <war warfile="${dir.dist}/${ant.project.name}.war"      webxml="WebContent/WEB-INF/web.xml"      manifest="${dir.build}/manifest.mf">         <fileset dir="WebContent">             <exclude name="web.xml"/>         </fileset>         <classes dir="${dir.build}">             <include name="com/ratlbank/**/*.class"/>         </classes>     </war>     <!-- create checksum -->     <checksum file="${dir.dist}/${ant.project.name}.war" /> </target> <!-- Release Build --> <target name="release" description="execute Release Build">     depends="compile, junit-all, javadoc, update-buildinfo, dist">     <ca:ccstage todir="${dir.stage}" outfile="ccstage.xml">         <fileset dir="${dir.dist}">             <include name="**/*.war"/>             <include name="**/*.MD5"/>             <include name="**/*.html"/>         </fileset>     </ca:ccstage>     ... </target>

This example works by first executing the Release Build as in Chapter 10, compiling and unit-testing the Java classes. It then creates a Release Package for the application using the Ant <war> task; it also creates a checksum of this archive. Finally, as part of the release target, the Release Package along with its supporting files (checksum and baseline report) are staged using the process described in Chapter 10. With this target in place, to both execute your Release Build and create and stage a Release Package, you would simply enter the following:

>ant release

As I mentioned earlier, the output of your Release Packaging stage might not be a single archive, as in this example. However, whatever the output, after the Release Packaging phase, you should be in a position to create a Deployment Unit that describes the set of Release Packages you want to deploy. I will discuss some of the mechanisms to achieve this next.