ArchiveScanner (Apache Ant API)
Date: 2018-03-24

org.apache.tools.ant.types

## Class ArchiveScanner

- java.lang.Object
- - org.apache.tools.ant.DirectoryScanner
  - - org.apache.tools.ant.types.ArchiveScanner

- All Implemented Interfaces:
    FileScanner, ResourceFactory, SelectorScanner
  Direct Known Subclasses:
    TarScanner, ZipScanner

      public abstract class ArchiveScanner
      extends DirectoryScanner

  ArchiveScanner accesses the pattern matching algorithm in DirectoryScanner, which are protected methods that can only be accessed by subclassing. This implementation of FileScanner defines getIncludedFiles to return the matching archive entries.
  Since:
    Ant 1.7

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.io.File` | `srcFile` The archive file which should be scanned.

    - ### Fields inherited from class org.apache.tools.ant.DirectoryScanner

      `basedir, DEFAULTEXCLUDES, dirsDeselected, dirsExcluded, dirsIncluded, dirsNotIncluded, DOES_NOT_EXIST_POSTFIX, errorOnMissingDir, everythingIncluded, excludes, filesDeselected, filesExcluded, filesIncluded, filesNotIncluded, haveSlowResults, includes, isCaseSensitive, MAX_LEVELS_OF_SYMLINKS, selectors`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ArchiveScanner()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract void` | `fillMapsFromArchive(Resource archive, java.lang.String encoding, java.util.Map<java.lang.String,Resource> fileEntries, java.util.Map<java.lang.String,Resource> matchFileEntries, java.util.Map<java.lang.String,Resource> dirEntries, java.util.Map<java.lang.String,Resource> matchDirEntries)` Fills the file and directory maps with resources read from the archive.
    `java.lang.String[]` | `getIncludedDirectories()` Returns the names of the directories which matched at least one of the include patterns and none of the exclude patterns.
    `int` | `getIncludedDirsCount()` Override parent implementation.
    `java.lang.String[]` | `getIncludedFiles()` Returns the names of the files which matched at least one of the include patterns and none of the exclude patterns.
    `int` | `getIncludedFilesCount()` Override parent implementation.
    `Resource` | `getResource(java.lang.String name)` Get the named Resource.
    `void` | `init()` Initialize DirectoryScanner data structures.
    `boolean` | `match(java.lang.String path)` Matches a jar entry against the includes/excludes list, normalizing the path separator.
    `void` | `scan()` Don't scan when we have no zipfile.
    `void` | `setEncoding(java.lang.String encoding)` Sets encoding of file names.
    `void` | `setErrorOnMissingArchive(boolean errorOnMissingArchive)` Sets whether an error is thrown if an archive does not exist.
    `void` | `setSrc(java.io.File srcFile)` Sets the srcFile for scanning.
    `void` | `setSrc(Resource src)` Sets the src for scanning.
    `protected static java.lang.String` | `trimSeparator(java.lang.String s)` Remove trailing slash if present.

    - ### Methods inherited from class org.apache.tools.ant.DirectoryScanner

      `addDefaultExclude, addDefaultExcludes, addExcludes, clearResults, couldHoldIncluded, getBasedir, getDefaultExcludes, getDeselectedDirectories, getDeselectedFiles, getExcludedDirectories, getExcludedFiles, getNotFollowedSymlinks, getNotIncludedDirectories, getNotIncludedFiles, isCaseSensitive, isEverythingIncluded, isExcluded, isFollowSymlinks, isIncluded, isSelected, match, match, matchPath, matchPath, matchPatternStart, matchPatternStart, removeDefaultExclude, resetDefaultExcludes, scandir, setBasedir, setBasedir, setCaseSensitive, setErrorOnMissingDir, setExcludes, setFollowSymlinks, setIncludes, setMaxLevelsOfSymlinks, setSelectors, slowScan`

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

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

- - ### Field Detail

    - #### srcFile

          protected java.io.File srcFile

      The archive file which should be scanned.

  - ### Constructor Detail

    - #### ArchiveScanner

          public ArchiveScanner()

  - ### Method Detail

    - #### setErrorOnMissingArchive

          public void setErrorOnMissingArchive(boolean errorOnMissingArchive)

      Sets whether an error is thrown if an archive does not exist.
      Parameters:
        `errorOnMissingArchive` - true if missing archives cause errors, false if not.
      Since:
        Ant 1.8.0

    - #### scan

          public void scan()

      Don't scan when we have no zipfile.
      Specified by:
        `scan` in interface `FileScanner`
      Overrides:
        `scan` in class `DirectoryScanner`
      Since:
        Ant 1.7

    - #### setSrc

          public void setSrc(java.io.File srcFile)

      Sets the srcFile for scanning. This is the jar or zip file that is scanned for matching entries.
      Parameters:
        `srcFile` - the (non-null) archive file name for scanning

    - #### setSrc

          public void setSrc(Resource src)

      Sets the src for scanning. This is the jar or zip file that is scanned for matching entries.
      Parameters:
        `src` - the (non-null) archive resource

    - #### setEncoding

          public void setEncoding(java.lang.String encoding)

      Sets encoding of file names.
      Parameters:
        `encoding` - the encoding format
      Since:
        Ant 1.6

    - #### getIncludedFiles

          public java.lang.String[] getIncludedFiles()

      Returns the names of the files which matched at least one of the include patterns and none of the exclude patterns. The names are relative to the base directory.
      Specified by:
        `getIncludedFiles` in interface `FileScanner`
      Overrides:
        `getIncludedFiles` in class `DirectoryScanner`
      Returns:
        the names of the files which matched at least one of the include patterns and none of the exclude patterns.

    - #### getIncludedFilesCount

          public int getIncludedFilesCount()

      Override parent implementation.
      Overrides:
        `getIncludedFilesCount` in class `DirectoryScanner`
      Returns:
        count of included files.
      Since:
        Ant 1.7

    - #### getIncludedDirectories

          public java.lang.String[] getIncludedDirectories()

      Returns the names of the directories which matched at least one of the include patterns and none of the exclude patterns. The names are relative to the base directory.
      Specified by:
        `getIncludedDirectories` in interface `FileScanner`
      Overrides:
        `getIncludedDirectories` in class `DirectoryScanner`
      Returns:
        the names of the directories which matched at least one of the include patterns and none of the exclude patterns.

    - #### getIncludedDirsCount

          public int getIncludedDirsCount()

      Override parent implementation.
      Overrides:
        `getIncludedDirsCount` in class `DirectoryScanner`
      Returns:
        count of included directories.
      Since:
        Ant 1.7

    - #### init

          public void init()

      Initialize DirectoryScanner data structures.

    - #### match

          public boolean match(java.lang.String path)

      Matches a jar entry against the includes/excludes list, normalizing the path separator.
      Parameters:
        `path` - the (non-null) path name to test for inclusion
      Returns:
        `true` if the path should be included `false` otherwise.

    - #### getResource

          public Resource getResource(java.lang.String name)

      Get the named Resource.
      Specified by:
        `getResource` in interface `ResourceFactory`
      Overrides:
        `getResource` in class `DirectoryScanner`
      Parameters:
        `name` - path name of the file sought in the archive
      Returns:
        the resource
      Since:
        Ant 1.5.2

    - #### fillMapsFromArchive

          protected abstract void fillMapsFromArchive(Resource archive,
                                                      java.lang.String encoding,
                                                      java.util.Map<java.lang.String,Resource> fileEntries,
                                                      java.util.Map<java.lang.String,Resource> matchFileEntries,
                                                      java.util.Map<java.lang.String,Resource> dirEntries,
                                                      java.util.Map<java.lang.String,Resource> matchDirEntries)

      Fills the file and directory maps with resources read from the archive.
      Parameters:
        `archive` - the archive to scan.
        `encoding` - encoding used to encode file names inside the archive.
        `fileEntries` - Map (name to resource) of non-directory resources found inside the archive.
        `matchFileEntries` - Map (name to resource) of non-directory resources found inside the archive that matched all include patterns and didn't match any exclude patterns.
        `dirEntries` - Map (name to resource) of directory resources found inside the archive.
        `matchDirEntries` - Map (name to resource) of directory resources found inside the archive that matched all include patterns and didn't match any exclude patterns.

    - #### trimSeparator

          protected static final java.lang.String trimSeparator(java.lang.String s)

      Remove trailing slash if present.
      Parameters:
        `s` - the file name to trim.
      Returns:
        the trimmed file name.