org.apache.tools.ant.taskdefs
Class Jar

java.lang.Object
  org.apache.tools.ant.ProjectComponent
      org.apache.tools.ant.Task
          org.apache.tools.ant.taskdefs.MatchingTask
              org.apache.tools.ant.taskdefs.Zip
                  org.apache.tools.ant.taskdefs.Jar

All Implemented Interfaces:

java.lang.Cloneable, SelectorContainer

Direct Known Subclasses:

Ear, War

public class Jar
extends Zip

Creates a JAR archive.

Since:

Ant 1.1

Nested Class Summary

static class	Jar.FilesetManifestConfig The manifest config enumerated type.
static class	Jar.StrictMode The strict enumerated type.

Nested classes/interfaces inherited from class org.apache.tools.ant.taskdefs.Zip

Zip.ArchiveState, Zip.Duplicate, Zip.UnicodeExtraField, Zip.WhenEmpty

Field Summary

Fields inherited from class org.apache.tools.ant.taskdefs.Zip

addedDirs, archiveType, doubleFilePass, duplicate, emptyBehavior, entries, skipWriting, zipFile

Fields inherited from class org.apache.tools.ant.taskdefs.MatchingTask

fileset

Fields inherited from class org.apache.tools.ant.Task

target, taskName, taskType, wrapper

Fields inherited from class org.apache.tools.ant.ProjectComponent

description, location, project

Constructor Summary

Jar()
constructor

Method Summary

void	addConfiguredIndexJars(Path p) Add a path to index jars.
void	addConfiguredManifest(Manifest newManifest) Allows the manifest for the archive file to be provided inline in the build file rather than in an external file.
void	addConfiguredService(Service service) A nested SPI service element.
void	addMetainf(ZipFileSet fs) Adds a zipfileset to include in the META-INF directory.
protected void	cleanUp() Make sure we don't think we already have a MANIFEST next time this task gets executed.
protected boolean	createEmptyZip(java.io.File zipFile) Create an empty jar file.
protected void	finalizeZipOutputStream(ZipOutputStream zOut) Finalize the zip output stream.
protected static java.lang.String	findJarName(java.lang.String fileName, java.lang.String[] classpath) try to guess the name of the given file.
protected Zip.ArchiveState	getResourcesToAdd(ResourceCollection[] rcs, java.io.File zipFile, boolean needsUpdate) Collect the resources that are newer than the corresponding entries (or missing) in the original archive.
protected static void	grabFilesAndDirs(java.lang.String file, java.util.List dirs, java.util.List files) Grab lists of all root-level files and all directories contained in the given archive.
protected void	initZipOutputStream(ZipOutputStream zOut) Initialize the zip output stream.
void	reset() reset to default values.
void	setFilesetmanifest(Jar.FilesetManifestConfig config) Behavior when a Manifest is found in a zipfileset or zipgroupfileset file.
void	setFlattenAttributes(boolean b) Whether to flatten multi-valued attributes (i.e.
void	setIndex(boolean flag) Set whether or not to create an index list for classes.
void	setIndexMetaInf(boolean flag) Set whether or not to add META-INF and its children to the index.
void	setJarfile(java.io.File jarFile) Deprecated. since 1.5.x. Use setDestFile(File) instead.
void	setManifest(java.io.File manifestFile) The manifest file to use.
void	setManifestEncoding(java.lang.String manifestEncoding) The character encoding to use in the manifest file.
void	setMergeClassPathAttributes(boolean b) Whether to merge Class-Path attributes.
void	setStrict(Jar.StrictMode strict) Activate the strict mode.
void	setWhenempty(Zip.WhenEmpty we) Not used for jar files.
void	setWhenmanifestonly(Zip.WhenEmpty we) Indicates if a jar file should be created when it would only contain a manifest file.
protected void	writeIndexLikeList(java.util.List dirs, java.util.List files, java.io.PrintWriter writer) Writes the directory entries from the first and the filenames from the second list to the given writer, one entry per line.
protected void	zipFile(java.io.InputStream is, ZipOutputStream zOut, java.lang.String vPath, long lastModified, java.io.File fromArchive, int mode) Overridden from Zip class to deal with manifests and index lists.

Methods inherited from class org.apache.tools.ant.taskdefs.Zip

add, addFileset, addParentDirs, addResources, addResources, addZipfileset, addZipGroupFileset, execute, executeMain, getComment, getCreateUnicodeExtraFields, getCurrentExtraFields, getDestFile, getEncoding, getFallBackToUTF8, getLevel, getNonFileSetResourcesToAdd, getPreserve0Permissions, getResourcesToAdd, getUseLanguageEnodingFlag, grabNonFileSetResources, grabResources, hasUpdatedFile, isAddingNewFiles, isCompress, isEmpty, isFirstPass, isInUpdateMode, logWhenWriting, selectDirectoryResources, selectFileResources, selectResources, setBasedir, setComment, setCompress, setCreateUnicodeExtraFields, setCurrentExtraFields, setDestFile, setDuplicate, setEncoding, setFallBackToUTF8, setFile, setFilesonly, setKeepCompression, setLevel, setPreserve0Permissions, setRoundUp, setUpdate, setUseLanguageEncodingFlag, setZipfile, zipDir, zipDir, zipDir, zipFile, zipFile

Methods inherited from class org.apache.tools.ant.taskdefs.MatchingTask

add, addAnd, addContains, addContainsRegexp, addCustom, addDate, addDepend, addDepth, addDifferent, addFilename, addMajority, addModified, addNone, addNot, addOr, addPresent, addSelector, addSize, addType, appendSelector, createExclude, createExcludesFile, createInclude, createIncludesFile, createPatternSet, getDirectoryScanner, getImplicitFileSet, getSelectors, hasSelectors, selectorCount, selectorElements, setCaseSensitive, setDefaultexcludes, setExcludes, setExcludesfile, setFollowSymlinks, setIncludes, setIncludesfile, setProject, XsetIgnore, XsetItems

Methods inherited from class org.apache.tools.ant.Task

bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType

Methods inherited from class org.apache.tools.ant.ProjectComponent

clone, getDescription, getLocation, getProject, setDescription, setLocation

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Jar

public Jar()

constructor

Method Detail

setWhenempty

public void setWhenempty(Zip.WhenEmpty we)

Not used for jar files.

Overrides:

setWhenempty in class Zip

Parameters:

we - not used

setWhenmanifestonly

public void setWhenmanifestonly(Zip.WhenEmpty we)

Indicates if a jar file should be created when it would only contain a manifest file. Possible values are: fail (throw an exception and halt the build); skip (do not create any archive, but issue a warning); create (make an archive with only a manifest file). Default is create;

Parameters:

we - a WhenEmpty enumerated value

setStrict

public void setStrict(Jar.StrictMode strict)

Activate the strict mode. When set to true a BuildException will be thrown if the Jar-Packaging specification was broken.

Parameters:

strict - New value of the strict mode.

Since:

Ant 1.7.1

setJarfile

public void setJarfile(java.io.File jarFile)

Deprecated. since 1.5.x. Use setDestFile(File) instead.

Set the destination file.

Parameters:

jarFile - the destination file

setIndex

public void setIndex(boolean flag)

Set whether or not to create an index list for classes. This may speed up classloading in some cases.

Parameters:

flag - a boolean value

setIndexMetaInf

public void setIndexMetaInf(boolean flag)

Set whether or not to add META-INF and its children to the index.

Doesn't have any effect if index is false.

Sun's jar implementation used to skip the META-INF directory and Ant followed that example. The behavior has been changed with Java 5. In order to avoid problems with Ant generated jars on Java 1.4 or earlier Ant will not include META-INF unless explicitly asked to.

Parameters:

flag - a boolean value, defaults to false

Since:

Ant 1.8.0

See Also:

jar -i omits service providers in index.list

setManifestEncoding

public void setManifestEncoding(java.lang.String manifestEncoding)

The character encoding to use in the manifest file.

Parameters:

manifestEncoding - the character encoding

addConfiguredManifest

public void addConfiguredManifest(Manifest newManifest)
                           throws ManifestException

Allows the manifest for the archive file to be provided inline in the build file rather than in an external file.

Parameters:

newManifest - an embedded manifest element

Throws:

ManifestException - on error

setManifest

public void setManifest(java.io.File manifestFile)

The manifest file to use. This can be either the location of a manifest, or the name of a jar added through a fileset. If its the name of an added jar, the task expects the manifest to be in the jar at META-INF/MANIFEST.MF.

Parameters:

manifestFile - the manifest file to use.

setFilesetmanifest

public void setFilesetmanifest(Jar.FilesetManifestConfig config)

Behavior when a Manifest is found in a zipfileset or zipgroupfileset file. Valid values are "skip", "merge", and "mergewithoutmain". "merge" will merge all of manifests together, and merge this into any other specified manifests. "mergewithoutmain" merges everything but the Main section of the manifests. Default value is "skip". Note: if this attribute's value is not "skip", the created jar will not be readable by using java.util.jar.JarInputStream

Parameters:

config - setting for found manifest behavior.

addMetainf

public void addMetainf(ZipFileSet fs)

Adds a zipfileset to include in the META-INF directory.

Parameters:

fs - zipfileset to add

addConfiguredIndexJars

public void addConfiguredIndexJars(Path p)

Add a path to index jars.

Parameters:

p - a path

Since:

Ant 1.6.2

addConfiguredService

public void addConfiguredService(Service service)

A nested SPI service element.

Parameters:

service - the nested element.

Since:

Ant 1.7

setMergeClassPathAttributes

public void setMergeClassPathAttributes(boolean b)

Whether to merge Class-Path attributes.

Since:

Ant 1.8.0

setFlattenAttributes

public void setFlattenAttributes(boolean b)

Whether to flatten multi-valued attributes (i.e. Class-Path) into a single one.

Since:

Ant 1.8.0

initZipOutputStream

protected void initZipOutputStream(ZipOutputStream zOut)
                            throws java.io.IOException,
                                   BuildException

Initialize the zip output stream.

Overrides:

initZipOutputStream in class Zip

Parameters:

zOut - the zip output stream

Throws:

java.io.IOException - on I/O errors

BuildException - on other errors

finalizeZipOutputStream

protected void finalizeZipOutputStream(ZipOutputStream zOut)
                                throws java.io.IOException,
                                       BuildException

Finalize the zip output stream. This creates an index list if the index attribute is true.

Overrides:

finalizeZipOutputStream in class Zip

Parameters:

zOut - the zip output stream

Throws:

java.io.IOException - on I/O errors

BuildException - on other errors

zipFile

protected void zipFile(java.io.InputStream is,
                       ZipOutputStream zOut,
                       java.lang.String vPath,
                       long lastModified,
                       java.io.File fromArchive,
                       int mode)
                throws java.io.IOException

Overridden from Zip class to deal with manifests and index lists.

Overrides:

zipFile in class Zip

Parameters:

is - the stream to read data for the entry from. The caller of the method is responsible for closing the stream.

zOut - the zip output stream

vPath - the name this entry shall have in the archive

lastModified - last modification time for the entry.

fromArchive - the original archive we are copying this entry from, will be null if we are not copying from an archive.

mode - the Unix permissions to set.

Throws:

java.io.IOException - on error

getResourcesToAdd

protected Zip.ArchiveState getResourcesToAdd(ResourceCollection[] rcs,
                                             java.io.File zipFile,
                                             boolean needsUpdate)
                                      throws BuildException

Collect the resources that are newer than the corresponding entries (or missing) in the original archive.

If we are going to recreate the archive instead of updating it, all resources should be considered as new, if a single one is. Because of this, subclasses overriding this method must call super.getResourcesToAdd and indicate with the third arg if they already know that the archive is out-of-date.

Overrides:

getResourcesToAdd in class Zip

Parameters:

rcs - The resource collections to grab resources from

zipFile - intended archive file (may or may not exist)

needsUpdate - whether we already know that the archive is out-of-date. Subclasses overriding this method are supposed to set this value correctly in their call to super.getResourcesToAdd.

Returns:

an array of resources to add for each fileset passed in as well as a flag that indicates whether the archive is uptodate.

Throws:

BuildException - if it likes

createEmptyZip

protected boolean createEmptyZip(java.io.File zipFile)
                          throws BuildException

Create an empty jar file.

Overrides:

createEmptyZip in class Zip

Parameters:

zipFile - the file to create

Returns:

true for historic reasons

Throws:

BuildException - on error

cleanUp

protected void cleanUp()

Make sure we don't think we already have a MANIFEST next time this task gets executed.

Overrides:

cleanUp in class Zip

See Also:

Zip.cleanUp()

reset

public void reset()

reset to default values.

Overrides:

reset in class Zip

Since:

1.44, Ant 1.5

See Also:

Zip.reset()

writeIndexLikeList

protected final void writeIndexLikeList(java.util.List dirs,
                                        java.util.List files,
                                        java.io.PrintWriter writer)
                                 throws java.io.IOException

Writes the directory entries from the first and the filenames from the second list to the given writer, one entry per line.

Parameters:

dirs - a list of directories

files - a list of files

writer - the writer to write to

Throws:

java.io.IOException - on error

Since:

Ant 1.6.2

findJarName

protected static java.lang.String findJarName(java.lang.String fileName,
                                              java.lang.String[] classpath)

try to guess the name of the given file.

If this jar has a classpath attribute in its manifest, we can assume that it will only require an index of jars listed there. try to find which classpath entry is most likely the one the given file name points to.

In the absence of a classpath attribute, assume the other files will be placed inside the same directory as this jar and use their basename.

if there is a classpath and the given file doesn't match any of its entries, return null.

Parameters:

fileName - the name to look for

classpath - the classpath to look in (may be null)

Returns:

the matching entry, or null if the file is not found

Since:

Ant 1.6.2

grabFilesAndDirs

protected static void grabFilesAndDirs(java.lang.String file,
                                       java.util.List dirs,
                                       java.util.List files)
                                throws java.io.IOException

Grab lists of all root-level files and all directories contained in the given archive.

Parameters:

file - the zip file to examine

dirs - where to place the directories found

files - where to place the files found

Throws:

java.io.IOException - on error

Since:

Ant 1.7