Class Tar

java.lang.Object

org.apache.tools.ant.ProjectComponent

org.apache.tools.ant.Task

org.apache.tools.ant.taskdefs.MatchingTask

org.apache.tools.ant.taskdefs.Tar

All Implemented Interfaces:

Cloneable, SelectorContainer

public class Tar
extends MatchingTask

Creates a tar archive.

Since:

Ant 1.1

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	Tar.TarCompressionMethod	Valid Modes for Compression attribute to Tar Task
static class	Tar.TarFileSet	This is a FileSet with the option to specify permissions and other attributes.
static class	Tar.TarLongFileMode	Set of options for long file handling in the task.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	FAIL	Deprecated. since 1.5.x.
static final String	GNU	Deprecated. since 1.5.x.
static final String	OMIT	Deprecated. since 1.5.x.
static final String	TRUNCATE	Deprecated. since 1.5.x.
static final String	WARN	Deprecated. since 1.5.x.

Fields inherited from class MatchingTask

fileset

Modifier and Type	Field	Description
protected FileSet	fileset

Fields inherited from class Task

target, taskName, taskType, wrapper

Modifier and Type	Field	Description
protected Target	target	Deprecated. since 1.6.x.
protected String	taskName	Deprecated. since 1.6.x.
protected String	taskType	Deprecated. since 1.6.x.
protected RuntimeConfigurable	wrapper	Deprecated. since 1.6.x.

Fields inherited from class ProjectComponent

description, location, project

Modifier and Type	Field	Description
protected String	description	Deprecated. since 1.6.x.
protected Location	location	Deprecated. since 1.6.x.
protected Project	project	Deprecated. since 1.6.x.

Constructor Summary

Constructors

Constructor	Description
Tar()

Method Summary

Modifier and Type	Method	Description
void	add(ResourceCollection res)	Add a collection of resources to archive.
protected boolean	archiveIsUpToDate(String[] files)	Deprecated. since 1.5.x.
protected boolean	archiveIsUpToDate(String[] files, File dir)	Is the archive up to date in relationship to a list of files.
protected boolean	archiveIsUpToDate(Resource r)	Is the archive up to date in relationship to a list of files.
protected Tar.TarFileSet	asTarFileSet(ArchiveFileSet archiveFileSet)	Copies fullpath, prefix and permission attributes from the ArchiveFileSet to a new TarFileSet (or returns it unchanged if it already is a TarFileSet).
protected boolean	check(File basedir, String[] files)	Checks whether the archive is out-of-date with respect to the given files, ensures that the archive won't contain itself.
protected boolean	check(File basedir, Collection<String> files)	Checks whether the archive is out-of-date with respect to the given files, ensures that the archive won't contain itself.
protected boolean	check(ResourceCollection rc)	Checks whether the archive is out-of-date with respect to the resources of the given collection.
Tar.TarFileSet	createTarFileSet()	Add a new fileset with the option to specify permissions
void	execute()	do the business
protected static String[]	getFileNames(FileSet fs)	Grabs all included files and directors from the FileSet and returns them as an array of (relative) file names.
protected static boolean	isFileFileSet(ResourceCollection rc)	whether the given resource collection is a (subclass of) FileSet that only contains file system resources.
void	setBasedir(File baseDir)	This is the base directory to look in for things to tar.
void	setCompression(Tar.TarCompressionMethod mode)	Set compression method.
void	setDestFile(File destFile)	Set is the name/location of where to create the tar file.
void	setEncoding(String encoding)	Encoding to use for filenames, defaults to the platform's default encoding.
void	setLongfile(String mode)	Deprecated. since 1.5.x.
void	setLongfile(Tar.TarLongFileMode mode)	Set how to handle long files, those with a path>100 chars.
void	setTarfile(File tarFile)	Deprecated. since 1.5.x.
protected boolean	supportsNonFileResources()	Whether this task can deal with non-file resources.
protected void	tar(ResourceCollection rc, TarOutputStream tOut)	Adds the resources contained in this collection to the archive.
protected void	tarFile(File file, TarOutputStream tOut, String vPath, Tar.TarFileSet tarFileSet)	tar a file
protected void	tarResource(Resource r, TarOutputStream tOut, String vPath, Tar.TarFileSet tarFileSet)	tar a resource

Methods inherited from class 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

Modifier and Type	Method	Description
void	add(FileSelector selector)	add an arbitrary selector
void	addAnd(AndSelector selector)	add an "And" selector entry on the selector list
void	addContains(ContainsSelector selector)	add a contains selector entry on the selector list
void	addContainsRegexp(ContainsRegexpSelector selector)	add a regular expression selector entry on the selector list
void	addCustom(ExtendSelector selector)	add an extended selector entry on the selector list
void	addDate(DateSelector selector)	add a selector date entry on the selector list
void	addDepend(DependSelector selector)	add a depends selector entry on the selector list
void	addDepth(DepthSelector selector)	add a depth selector entry on the selector list
void	addDifferent(DifferentSelector selector)	add a type selector entry on the type list
void	addFilename(FilenameSelector selector)	add a selector filename entry on the selector list
void	addMajority(MajoritySelector selector)	add a majority selector entry on the selector list
void	addModified(ModifiedSelector selector)	add the modified selector
void	addNone(NoneSelector selector)	add a "None" selector entry on the selector list
void	addNot(NotSelector selector)	add a "Not" selector entry on the selector list
void	addOr(OrSelector selector)	add an "Or" selector entry on the selector list
void	addPresent(PresentSelector selector)	add a present selector entry on the selector list
void	addSelector(SelectSelector selector)	add a "Select" selector entry on the selector list
void	addSize(SizeSelector selector)	add a selector size entry on the selector list
void	addType(TypeSelector selector)	add a type selector entry on the type list
void	appendSelector(FileSelector selector)	Add a new selector into this container.
PatternSet.NameEntry	createExclude()	add a name entry on the exclude list
PatternSet.NameEntry	createExcludesFile()	add a name entry on the include files list
PatternSet.NameEntry	createInclude()	add a name entry on the include list
PatternSet.NameEntry	createIncludesFile()	add a name entry on the include files list
PatternSet	createPatternSet()	add a set of patterns
protected DirectoryScanner	getDirectoryScanner(File baseDir)	Returns the directory scanner needed to access the files to process.
protected final FileSet	getImplicitFileSet()	Accessor for the implicit fileset.
FileSelector[]	getSelectors(Project p)	Returns the set of selectors as an array.
boolean	hasSelectors()	Indicates whether there are any selectors here.
int	selectorCount()	Gives the count of the number of selectors in this container
Enumeration<FileSelector>	selectorElements()	Returns an enumerator for accessing the set of selectors.
void	setCaseSensitive(boolean isCaseSensitive)	Sets case sensitivity of the file system
void	setDefaultexcludes(boolean useDefaultExcludes)	Sets whether default exclusions should be used or not.
void	setExcludes(String excludes)	Sets the set of exclude patterns.
void	setExcludesfile(File excludesfile)	Sets the name of the file containing the includes patterns.
void	setFollowSymlinks(boolean followSymlinks)	Sets whether or not symbolic links or Windows junctions should be followed.
void	setIncludes(String includes)	Sets the set of include patterns.
void	setIncludesfile(File includesfile)	Sets the name of the file containing the includes patterns.
void	setProject(Project project)	Sets the project object of this component.
void	XsetIgnore(String ignoreString)	List of filenames and directory names to not include.
void	XsetItems(String itemString)	Set this to be the items in the base directory that you want to be included.

Methods inherited from class 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

Modifier and Type	Method	Description
final void	bindToOwner(Task owner)	Bind a task to another; use this when configuring a newly created task to do work on behalf of another.
Target	getOwningTarget()	Returns the container target of this task.
RuntimeConfigurable	getRuntimeConfigurableWrapper()	Returns the wrapper used for runtime configuration.
String	getTaskName()	Returns the name to use in logging messages.
String	getTaskType()	Return the type of task.
protected RuntimeConfigurable	getWrapper()	Return the runtime configurable structure for this task.
protected void	handleErrorFlush(String output)	Handles an error line by logging it with the WARN priority.
protected void	handleErrorOutput(String output)	Handles an error output by logging it with the WARN priority.
protected void	handleFlush(String output)	Handles output by logging it with the INFO priority.
protected int	handleInput(byte[] buffer, int offset, int length)	Handle an input request by this task.
protected void	handleOutput(String output)	Handles output by logging it with the INFO priority.
void	init()	Called by the project to let the task initialize properly.
protected final boolean	isInvalid()	Has this task been marked invalid?
void	log(String msg)	Logs a message with the default (INFO) priority.
void	log(String msg, int msgLevel)	Logs a message with the given priority.
void	log(String msg, Throwable t, int msgLevel)	Logs a message with the given priority.
void	log(Throwable t, int msgLevel)	Logs a message with the given priority.
void	maybeConfigure()	Configures this task - if it hasn't been done already.
final void	perform()	Performs this task if it's still valid, or gets a replacement version and performs that otherwise.
void	reconfigure()	Force the task to be reconfigured from its RuntimeConfigurable.
void	setOwningTarget(Target target)	Sets the target container of this task.
void	setRuntimeConfigurableWrapper(RuntimeConfigurable wrapper)	Sets the wrapper to be used for runtime configuration.
void	setTaskName(String name)	Sets the name to use in logging messages.
void	setTaskType(String type)	Sets the name with which the task has been invoked.

Methods inherited from class ProjectComponent

clone, getDescription, getLocation, getProject, setDescription, setLocation

Modifier and Type	Method	Description
Object	clone()
String	getDescription()	Returns the description of the current action.
Location	getLocation()	Returns the file/location where this task was defined.
Project	getProject()	Returns the project to which this component belongs.
void	setDescription(String desc)	Sets a description of the current action.
void	setLocation(Location location)	Sets the file/location where this task was defined.

Methods inherited from class Object

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

Field Details

WARN

@Deprecated
public static final String WARN

Deprecated.

since 1.5.x. Tar.WARN is deprecated and is replaced with Tar.TarLongFileMode.WARN

See Also:

• Constant Field Values

FAIL

@Deprecated
public static final String FAIL

Deprecated.

since 1.5.x. Tar.FAIL is deprecated and is replaced with Tar.TarLongFileMode.FAIL

See Also:

• Constant Field Values

TRUNCATE

@Deprecated
public static final String TRUNCATE

Deprecated.

since 1.5.x. Tar.TRUNCATE is deprecated and is replaced with Tar.TarLongFileMode.TRUNCATE

See Also:

• Constant Field Values

GNU

@Deprecated
public static final String GNU

Deprecated.

since 1.5.x. Tar.GNU is deprecated and is replaced with Tar.TarLongFileMode.GNU

See Also:

• Constant Field Values

OMIT

@Deprecated
public static final String OMIT

Deprecated.

since 1.5.x. Tar.OMIT is deprecated and is replaced with Tar.TarLongFileMode.OMIT

See Also:

• Constant Field Values

Constructor Details

Tar

public Tar()

Method Details

createTarFileSet

public Tar.TarFileSet createTarFileSet()

Add a new fileset with the option to specify permissions

Returns:

the tar fileset to be used as the nested element.

add

public void add(ResourceCollection res)

Add a collection of resources to archive.

Parameters:

res - a resource collection to archive.

Since:

Ant 1.7

setTarfile

@Deprecated
public void setTarfile(File tarFile)

Deprecated.

since 1.5.x. For consistency with other tasks, please use setDestFile().

Set is the name/location of where to create the tar file.

Parameters:

tarFile - the location of the tar file.

setDestFile

public void setDestFile(File destFile)

Set is the name/location of where to create the tar file.

Parameters:

destFile - The output of the tar

Since:

Ant 1.5

setBasedir

public void setBasedir(File baseDir)

This is the base directory to look in for things to tar.

Parameters:

baseDir - the base directory.

setLongfile

@Deprecated
public void setLongfile(String mode)

Deprecated.

since 1.5.x. setLongFile(String) is deprecated and is replaced with setLongFile(Tar.TarLongFileMode) to make Ant's Introspection mechanism do the work and also to encapsulate operations on the mode in its own class.

Set how to handle long files, those with a path>100 chars. Optional, default=warn.

Allowable values are

• truncate - paths are truncated to the maximum length
• fail - paths greater than the maximum cause a build exception
• warn - paths greater than the maximum cause a warning and GNU is used
• gnu - GNU extensions are used for any paths greater than the maximum.
• omit - paths greater than the maximum are omitted from the archive

Parameters:

mode - the mode string to handle long files.

setLongfile

public void setLongfile(Tar.TarLongFileMode mode)

Set how to handle long files, those with a path>100 chars. Optional, default=warn.

Allowable values are

• truncate - paths are truncated to the maximum length
• fail - paths greater than the maximum cause a build exception
• warn - paths greater than the maximum cause a warning and GNU is used
• gnu - extensions used by older versions of GNU tar are used for any paths greater than the maximum.
• posix - use POSIX PAX extension headers for any paths greater than the maximum. Supported by all modern tar implementations.
• omit - paths greater than the maximum are omitted from the archive

Parameters:

mode - the mode to handle long file names.

setCompression

public void setCompression(Tar.TarCompressionMethod mode)

Set compression method. Allowable values are

• none - no compression
• gzip - Gzip compression
• bzip2 - Bzip2 compression
• xz - XZ compression, requires XZ for Java

Parameters:

mode - the compression method.

setEncoding

public void setEncoding(String encoding)

Encoding to use for filenames, defaults to the platform's default encoding.

For a list of possible values see https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html.

Parameters:

encoding - the encoding name

Since:

Ant 1.9.5

execute

public void execute()
             throws BuildException

do the business

Overrides:

execute in class Task

Throws:

BuildException - on error

tarFile

protected void tarFile(File file,
 TarOutputStream tOut,
 String vPath,
 Tar.TarFileSet tarFileSet)
                throws IOException

tar a file

Parameters:

file - the file to tar

tOut - the output stream

vPath - the path name of the file to tar

tarFileSet - the fileset that the file came from.

Throws:

IOException - on error

tarResource

protected void tarResource(Resource r,
 TarOutputStream tOut,
 String vPath,
 Tar.TarFileSet tarFileSet)
                    throws IOException

tar a resource

Parameters:

r - the resource to tar

tOut - the output stream

vPath - the path name of the file to tar

tarFileSet - the fileset that the file came from, may be null.

Throws:

IOException - on error

Since:

Ant 1.7

archiveIsUpToDate

@Deprecated
protected boolean archiveIsUpToDate(String[] files)

Deprecated.

since 1.5.x. use the two-arg version instead.

Is the archive up to date in relationship to a list of files.

Parameters:

files - the files to check

Returns:

true if the archive is up to date.

archiveIsUpToDate

protected boolean archiveIsUpToDate(String[] files,
 File dir)

Is the archive up to date in relationship to a list of files.

Parameters:

files - the files to check

dir - the base directory for the files.

Returns:

true if the archive is up to date.

Since:

Ant 1.5.2

archiveIsUpToDate

protected boolean archiveIsUpToDate(Resource r)

Is the archive up to date in relationship to a list of files.

Parameters:

r - the files to check

Returns:

true if the archive is up to date.

Since:

Ant 1.7

supportsNonFileResources

protected boolean supportsNonFileResources()

Whether this task can deal with non-file resources.

This implementation returns true only if this task is <tar>. Any subclass of this class that also wants to support non-file resources needs to override this method. We need to do so for backwards compatibility reasons since we can't expect subclasses to support resources.

Returns:

true for this task.

Since:

Ant 1.7

check

protected boolean check(ResourceCollection rc)

Checks whether the archive is out-of-date with respect to the resources of the given collection.

Also checks that either all collections only contain file resources or this class supports non-file collections.

And - in case of file-collections - ensures that the archive won't contain itself.

Parameters:

rc - the resource collection to check

Returns:

whether the archive is up-to-date

Since:

Ant 1.7

check

protected boolean check(File basedir,
 String[] files)

Checks whether the archive is out-of-date with respect to the given files, ensures that the archive won't contain itself.

Parameters:

basedir - base directory for file names

files - array of relative file names

Returns:

whether the archive is up-to-date

Since:

Ant 1.7

check

protected boolean check(File basedir,
 Collection<String> files)

Checks whether the archive is out-of-date with respect to the given files, ensures that the archive won't contain itself.

Parameters:

basedir - base directory for file names

files - array of relative file names

Returns:

whether the archive is up-to-date

Since:

Ant 1.9.5

See Also:

• check(File, String[])

tar

protected void tar(ResourceCollection rc,
 TarOutputStream tOut)
            throws IOException

Adds the resources contained in this collection to the archive.

Uses the file based methods for file resources for backwards compatibility.

Parameters:

rc - the collection containing resources to add

tOut - stream writing to the archive.

Throws:

IOException - on error.

Since:

Ant 1.7

isFileFileSet

protected static boolean isFileFileSet(ResourceCollection rc)

whether the given resource collection is a (subclass of) FileSet that only contains file system resources.

Parameters:

rc - the resource collection to check.

Returns:

true if the collection is a fileset.

Since:

Ant 1.7

getFileNames

protected static String[] getFileNames(FileSet fs)

Grabs all included files and directors from the FileSet and returns them as an array of (relative) file names.

Parameters:

fs - the fileset to operate on.

Returns:

a list of the filenames.

Since:

Ant 1.7

asTarFileSet

protected Tar.TarFileSet asTarFileSet(ArchiveFileSet archiveFileSet)

Copies fullpath, prefix and permission attributes from the ArchiveFileSet to a new TarFileSet (or returns it unchanged if it already is a TarFileSet).

Parameters:

archiveFileSet - fileset to copy attributes from, may be null

Returns:

a new TarFileSet.

Since:

Ant 1.7