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

# Class Expand

java.lang.Object
org.apache.tools.ant.ProjectComponent
org.apache.tools.ant.Task
org.apache.tools.ant.taskdefs.Expand

All Implemented Interfaces:
  `Cloneable`

Direct Known Subclasses:
  `Untar`

public class Expand extends Task
Unzip a file.

Since:
  Ant 1.1

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `ERROR_MULTIPLE_MAPPERS`
  Error message when more that one mapper is defined
  `static final String`
  `NATIVE_ENCODING`

  ### 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
  Modifier
  Constructor
  Description
  ``
  `Expand()`
  Creates an Expand instance and sets encoding to UTF-8.
  `protected`
  `Expand(String encoding)`
  Creates an Expand instance and sets the given encoding.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(ResourceCollection rc)`
  Add a resource collection.
  `void`
  `add(FileNameMapper fileNameMapper)`
  A nested filenamemapper
  `void`
  `addFileset(FileSet set)`
  Add a fileset
  `void`
  `addPatternset(PatternSet set)`
  Add a patternset.
  `Mapper`
  `createMapper()`
  Defines the mapper to map source entries to destination files.
  `void`
  `execute()`
  Do the work.
  `protected void`
  `expandFile(FileUtils fileUtils, File srcF, File dir)`
  This method is to be overridden by extending unarchival tasks.
  `protected void`
  `expandResource(Resource srcR, File dir)`
  This method is to be overridden by extending unarchival tasks.
  `protected void`
  `extractFile(FileUtils fileUtils, File srcF, File dir, InputStream compressedInputStream, String entryName, Date entryDate, boolean isDirectory, FileNameMapper mapper)`
  extract a file to a directory
  `Boolean`
  `getAllowFilesToEscapeDest()`
  Whether to allow the extracted file or directory to be outside of the dest directory.
  `String`
  `getEncoding()`
  `boolean`
  `getFailOnEmptyArchive()`
  Whether try ing to expand an empty archive would be an error.
  `protected FileNameMapper`
  `getMapper()`
  get a mapper for a file
  `boolean`
  `getScanForUnicodeExtraFields()`
  `protected void`
  `internalSetEncoding(String encoding)`
  Supports grand-children that want to support the attribute where the child-class doesn't (i.e.
  `protected void`
  `internalSetScanForUnicodeExtraFields(boolean b)`
  Supports grand-children that want to support the attribute where the child-class doesn't (i.e.
  `void`
  `setAllowFilesToEscapeDest(boolean b)`
  Whether to allow the extracted file or directory to be outside of the dest directory.
  `void`
  `setDest(File d)`
  Set the destination directory.
  `void`
  `setEncoding(String encoding)`
  Sets the encoding to assume for file names and comments.
  `void`
  `setFailOnEmptyArchive(boolean b)`
  Whether try ing to expand an empty archive would be an error.
  `void`
  `setOverwrite(boolean b)`
  Should we overwrite files in dest, even if they are newer than the corresponding entries in the archive?
  `void`
  `setScanForUnicodeExtraFields(boolean b)`
  Whether unicode extra fields will be used if present.
  `void`
  `setSrc(File s)`
  Set the path to zip-file.
  `void`
  `setStripAbsolutePathSpec(boolean b)`
  Whether leading path separators should be stripped.

  ### 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, setProject`
  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.
  `void`
  `setProject(Project project)`
  Sets the project object of this component.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### NATIVE_ENCODING

    public static final String NATIVE_ENCODING
    See Also:
      - Constant Field Values

  - ### ERROR_MULTIPLE_MAPPERS

    public static final String ERROR_MULTIPLE_MAPPERS
    Error message when more that one mapper is defined
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### Expand

    public Expand()
    Creates an Expand instance and sets encoding to UTF-8.

  - ### Expand

    protected Expand(String encoding)
    Creates an Expand instance and sets the given encoding.
    Parameters:
      `encoding` - String
    Since:
      Ant 1.9.5

- ## Method Details

  - ### setFailOnEmptyArchive

    public void setFailOnEmptyArchive(boolean b)
    Whether try ing to expand an empty archive would be an error.
    Parameters:
      `b` - boolean
    Since:
      Ant 1.8.0

  - ### getFailOnEmptyArchive

    public boolean getFailOnEmptyArchive()
    Whether try ing to expand an empty archive would be an error.
    Returns:
      boolean
    Since:
      Ant 1.8.0

  - ### execute

    public void execute() throws BuildException
    Do the work.
    Overrides:
      `execute` in class `Task`
    Throws:
      `BuildException` - Thrown in unrecoverable error.

  - ### expandFile

    protected void expandFile(FileUtils fileUtils, File srcF, File dir)
    This method is to be overridden by extending unarchival tasks.
    Parameters:
      `fileUtils` - the fileUtils
      `srcF` - the source file
      `dir` - the destination directory

  - ### expandResource

    protected void expandResource(Resource srcR, File dir)
    This method is to be overridden by extending unarchival tasks.
    Parameters:
      `srcR` - the source resource
      `dir` - the destination directory

  - ### getMapper

    protected FileNameMapper getMapper()
    get a mapper for a file
    Returns:
      a filenamemapper for a file

  - ### extractFile

    protected void extractFile(FileUtils fileUtils, File srcF, File dir, InputStream compressedInputStream, String entryName, Date entryDate, boolean isDirectory, FileNameMapper mapper) throws IOException
    extract a file to a directory
    Parameters:
      `fileUtils` - a fileUtils object
      `srcF` - the source file
      `dir` - the destination directory
      `compressedInputStream` - the input stream
      `entryName` - the name of the entry
      `entryDate` - the date of the entry
      `isDirectory` - if this is true the entry is a directory
      `mapper` - the filename mapper to use
    Throws:
      `IOException` - on error

  - ### setDest

    public void setDest(File d)
    Set the destination directory. File will be unzipped into the destination directory.
    Parameters:
      `d` - Path to the directory.

  - ### setSrc

    public void setSrc(File s)
    Set the path to zip-file.
    Parameters:
      `s` - Path to zip-file.

  - ### setOverwrite

    public void setOverwrite(boolean b)
    Should we overwrite files in dest, even if they are newer than the corresponding entries in the archive?
    Parameters:
      `b` - a `boolean` value

  - ### addPatternset

    public void addPatternset(PatternSet set)
    Add a patternset.
    Parameters:
      `set` - a pattern set

  - ### addFileset

    public void addFileset(FileSet set)
    Add a fileset
    Parameters:
      `set` - a file set

  - ### add

    public void add(ResourceCollection rc)
    Add a resource collection.
    Parameters:
      `rc` - a resource collection.
    Since:
      Ant 1.7

  - ### createMapper

    public Mapper createMapper() throws BuildException
    Defines the mapper to map source entries to destination files.
    Returns:
      a mapper to be configured
    Throws:
      `BuildException` - if more than one mapper is defined
    Since:
      Ant1.7

  - ### add

    public void add(FileNameMapper fileNameMapper)
    A nested filenamemapper
    Parameters:
      `fileNameMapper` - the mapper to add
    Since:
      Ant 1.6.3

  - ### setEncoding

    public void setEncoding(String encoding)
    Sets the encoding to assume for file names and comments.

    Set to `native-encoding` if you want your platform's native encoding, defaults to UTF8.

    Parameters:
      `encoding` - the name of the character encoding
    Since:
      Ant 1.6

  - ### internalSetEncoding

    protected void internalSetEncoding(String encoding)
    Supports grand-children that want to support the attribute where the child-class doesn't (i.e. Unzip in the compress Antlib).
    Parameters:
      `encoding` - String
    Since:
      Ant 1.8.0

  - ### getEncoding

    public String getEncoding()
    Returns:
      String
    Since:
      Ant 1.8.0

  - ### setStripAbsolutePathSpec

    public void setStripAbsolutePathSpec(boolean b)
    Whether leading path separators should be stripped.
    Parameters:
      `b` - boolean
    Since:
      Ant 1.8.0

  - ### setScanForUnicodeExtraFields

    public void setScanForUnicodeExtraFields(boolean b)
    Whether unicode extra fields will be used if present.
    Parameters:
      `b` - boolean
    Since:
      Ant 1.8.0

  - ### internalSetScanForUnicodeExtraFields

    protected void internalSetScanForUnicodeExtraFields(boolean b)
    Supports grand-children that want to support the attribute where the child-class doesn't (i.e. Unzip in the compress Antlib).
    Parameters:
      `b` - boolean
    Since:
      Ant 1.8.0

  - ### getScanForUnicodeExtraFields

    public boolean getScanForUnicodeExtraFields()
    Returns:
      boolean
    Since:
      Ant 1.8.0

  - ### setAllowFilesToEscapeDest

    public void setAllowFilesToEscapeDest(boolean b)
    Whether to allow the extracted file or directory to be outside of the dest directory.
    Parameters:
      `b` - the flag
    Since:
      Ant 1.10.4

  - ### getAllowFilesToEscapeDest

    public Boolean getAllowFilesToEscapeDest()
    Whether to allow the extracted file or directory to be outside of the dest directory.
    Returns:
      `null` if the flag hasn't been set explicitly, otherwise the value set by the user.
    Since:
      Ant 1.10.4