Tar (Apache Ant API)
Description: declaration: package: org.apache.tools.ant.taskdefs, class: Tar

# 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