Section 3.6. Creating JAR Files

3.6. Creating JAR Files

The jar task JARs files for you. Example 3-4 is a fairly complex example, which creates a new JAR file with an included manifest, MANIFEST.MF, that contains several attributes.

Example 3-4. Using the jar task (ch03/jar/build.xml)

<?xml version="1.0" ?> <project default="main">     <property name="message" value="Building the .jar file." />     <property name="src" location="source" />     <property name="output" location="bin" />     <target name="main" depends="init, compile, compress">         <echo>             ${message}         </echo>     </target>        <target name="init">         <mkdir dir="${output}" />     </target>        <target name="compile">         <javac srcdir="${src}" destdir="${output}" />     </target>        <target name="compress">         <jar destfile="${output}/Project.jar" basedir="${output}"              includes="*.class" >             <manifest>                 <attribute name="Author" value="${user.name}"/>                 <section name="Shared">                     <attribute name="Title" value="Example"/>                     <attribute name="Vendor" value="MegaAntCo"/>                 </section>                 <section name="Copyright">                     <attribute name="Copy" value="(C) MegaAntCo 2005"/>                 </section>             </manifest>         </jar>     </target> </project>

The created JAR file contains Project.class and MANIFEST.MF; this latter file contains these contents:

Manifest-Version: 1.0 Ant-Version: Apache Ant 1.6.1 Created-By: 1.4.2_03-b02 (Sun Microsystems Inc.) Author: Steven Holzner Name: Shared Title: Example Vendor: MegaAntCo Name: Copyright Copy: (C) MegaAntCo 2005

Want to sign your JAR file for distribution? Use the jarsign task like this:

<signjar jar="jarfile.jar" alias="development"           keystore="local.keystore"            storepass="secret"/>

The attributes of the jar task are listed in Table 3-10. For more on creating manifests, take a look at the Section 3.6.2.

Table 3-10. The jar task's attributes

Attribute	Description	Required	Default
basedir	Specifies the directory where the task should find files to JAR.	No
compress	Specifies you want to compress data besides storing it.	No	true
defaultexcludes	Specifies whether you want to use default excludes or not (set to yes or no).	No	yes
destfile	Specifies the new JAR file to create.	Yes
duplicate	Specifies what you want to do when a duplicate file is found. Possible values are add, preserve, and fail.	No	add
encoding	Specifies the character encoding to use for file-names in the JAR file.	No	UTF-8
excludes	Specifies files to exclude. Give as a comma- or space-separated list.	No	No files (except default excludes) are excluded.
excludesfile	Specifies the name of a file containing exclude patterns, one to a line.	No
filesetmanifest	Specifies what you want the task to do when a manifest is found in a zipfileset or a zipgroupfileset file is found. Valid values are skip, merge, and mergewithoutmain.	No	skip
filesonly	Specifies you want to store only files in the JAR file.	No	false
includes	Specifies files to include. Give as a comma- or space-separated list of patterns.	No
includesfile	Specifies the name of a file containing include patterns, one to a line.	No
index	Specifies whether to create an index. This can aid when loading classes.	No	false
keepcompression	Specifies what you want to do with items from existing archives (as with nested JAR files). Available since Ant 1.6.	No	false
manifest	Specifies the manifest file to use. Set to the location of a manifest, or the name of a JAR added through a fileset. If you're using the name of an added JAR file, the task expects the manifest to be in the JAR at META-INF/MANIFEST.MF.	No
manifestencoding	Specifies the encoding used to read the JAR manifest.	No .	The platform encoding.
update	Specifies whether if you want to update or overwrite the output file in case it exists.	No	false
whenempty	Specifies what this task should do when when no files match. Possible values are fail, skip, and create.	No	skip

You can refine the set of files to JAR with the includes, includesfile, excludes, excludesfile, and defaultexcludes attributes. The jar task forms an implicit FileSet and supports all attributes of fileset (though dir becomes basedir) as well as the nested include, exclude and patternset elements. You can use nested file sets for more flexibility, and specify multiple ones to merge together different trees of files into one JAR.

The update parameter controls what happens if the .jar file exists. When set to

yes

, the .jar file is updated with the files specified. When set to

no

(the default), the .jar file is overwritten.

Besides nested include, exclude and patternset elements, you can nest metainf and manifest elements in the jar task.

3.6.1. Working with the META-INF Directory

The nested metainf element specifies a FileSet. All files included in this fileset will end up in the META-INF directory of the JAR file. If this fileset includes a file named MANIFEST.MF, the file is ignored (but you'll get a warning telling you what's going on).

3.6.2. Creating Manifest Files

You use this task to write data into a JAR manifest file. The manifest task supports two nested elements: attribute, which you can use to set attributes in a manifest file, and section, which can create a section in a manifest file. The attribute element has two attributes: name (the name of the attribute) and value (the value of the attribute). The section element has one attribute, name (the name of the new section). Here's an example, which creates a manifest with attributes and sections:

  <target name="compress">         <jar destfile="${output}/Project.jar" basedir="${output}"              includes="*.class" >             <manifest>                 <section name="Credits">                     <attribute name="Author" value="Steve"/>                 </section>                 <section name="Title">                     <attribute name="Title" value="Profits"/>                     <attribute name="Company" value="YourCoInc"/>                 </section>             </manifest>      </jar>   </target>

For a more substantial example, see Example 3-5 coming up in this chapter. You can see the attributes of this task in Table 3-11.

Table 3-11. The manifest attributes

Attribute	Description	Required	Default
file	Specifies the name of the manifest file to create.	Yes
mode	Specifies what you want to do with the manifiest file. Possible values are update or replace.	No	replace
encoding	Specifies the encoding you want to use when reading a manifest to update.	No	UTF-8 encoding

There's more you can put into JAR manifests as well, such as an automatically incremented build number and a time stamp, both coming up next.

Need to un-JAR a JAR file? Use Ant's unjar task. Just set the src attribute to the JAR file to un-jar and set the dest attribute to the directory where you want the output.