Expand (Apache Ant API)

Package org.apache.tools.ant.taskdefs

## Class Expand

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

- All Implemented Interfaces:
    `java.lang.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 java.lang.String` | `ERROR_MULTIPLE_MAPPERS` | Error message when more that one mapper is defined
    `static java.lang.String` | `NATIVE_ENCODING` |

    - ### 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

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `` | `Expand()` | Creates an Expand instance and sets encoding to UTF-8.
    `protected` | `Expand​(java.lang.String encoding)` | Creates an Expand instance and sets the given encoding.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    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, java.io.File srcF, java.io.File dir)` | This method is to be overridden by extending unarchival tasks.
    `protected void` | `expandResource​(Resource srcR, java.io.File dir)` | This method is to be overridden by extending unarchival tasks.
    `protected void` | `extractFile​(FileUtils fileUtils, java.io.File srcF, java.io.File dir, java.io.InputStream compressedInputStream, java.lang.String entryName, java.util.Date entryDate, boolean isDirectory, FileNameMapper mapper)` | extract a file to a directory
    `java.lang.Boolean` | `getAllowFilesToEscapeDest()` | Whether to allow the extracted file or directory to be outside of the dest directory.
    `java.lang.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​(java.lang.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​(java.io.File d)` | Set the destination directory.
    `void` | `setEncoding​(java.lang.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​(java.io.File s)` | Set the path to zip-file.
    `void` | `setStripAbsolutePathSpec​(boolean b)` | Whether leading path separators should be stripped.

    - ### 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, setProject`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### NATIVE_ENCODING

          public static final java.lang.String NATIVE_ENCODING

      See Also:
        Constant Field Values

    - #### ERROR_MULTIPLE_MAPPERS

          public static final java.lang.String ERROR_MULTIPLE_MAPPERS

      Error message when more that one mapper is defined
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Expand

          public Expand()

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

    - #### Expand

          protected Expand​(java.lang.String encoding)

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

  - ### Method Detail

    - #### 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,
                                    java.io.File srcF,
                                    java.io.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,
                                        java.io.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,
                                     java.io.File srcF,
                                     java.io.File dir,
                                     java.io.InputStream compressedInputStream,
                                     java.lang.String entryName,
                                     java.util.Date entryDate,
                                     boolean isDirectory,
                                     FileNameMapper mapper)
                              throws java.io.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:
        `java.io.IOException` - on error

    - #### setDest

          public void setDest​(java.io.File d)

      Set the destination directory. File will be unzipped into the destination directory.
      Parameters:
        `d` - Path to the directory.

    - #### setSrc

          public void setSrc​(java.io.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​(java.lang.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​(java.lang.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 java.lang.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 java.lang.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