/*
    * REPOWEB, repository manager.
    *
    * Terms of license - http://opensource.org/licenses/apachepl.php
    */
   /* Derived from Ant source. */
   package org.repoweb.model.file.util;
   import java.io.File;
   import java.io.FileFilter;
  import java.io.IOException;
  import java.util.ArrayList;
  import java.util.List;
  
  /***
   * Class for scanning a directory for files/directories which match certain
   * criteria.
   * <p>
   * These criteria consist of selectors and patterns which have been specified.
   * With the selectors you can select which files you want to have included.
   * Files which are not selected are excluded. With patterns you can include
   * or exclude files based on their filename.
   * <p>
   * The idea is simple. A given directory is recursively scanned for all files
   * and directories. Each file/directory is matched against a set of selectors,
   * including special support for matching against filenames with include and
   * and exclude patterns. Only files/directories which match at least one
   * pattern of the include pattern list or other file selector, and don't match
   * any pattern of the exclude pattern list or fail to match against a required
   * selector will be placed in the list of files/directories found.
   * <p>
   * When no list of include patterns is supplied, "**" will be used, which
   * means that everything will be matched. When no list of exclude patterns is
   * supplied, an empty list is used, such that nothing will be excluded. When
   * no selectors are supplied, none are applied.
   * <p>
   * The filename pattern matching is done as follows:
   * The name to be matched is split up in path segments. A path segment is the
   * name of a directory or file, which is bounded by
   * <code>File.separator</code> ('/' under UNIX, '\' under Windows).
   * For example, "abc/def/ghi/xyz.java" is split up in the segments "abc",
   * "def","ghi" and "xyz.java".
   * The same is done for the pattern against which should be matched.
   * <p>
   * The segments of the name and the pattern are then matched against each
   * other. When '**' is used for a path segment in the pattern, it matches
   * zero or more path segments of the name.
   * <p>
   * There is a special case regarding the use of <code>File.separator</code>s
   * at the beginning of the pattern and the string to match:<br>
   * When a pattern starts with a <code>File.separator</code>, the string
   * to match must also start with a <code>File.separator</code>.
   * When a pattern does not start with a <code>File.separator</code>, the
   * string to match may not start with a <code>File.separator</code>.
   * When one of these rules is not obeyed, the string will not
   * match.
   * <p>
   * When a name path segment is matched against a pattern path segment, the
   * following special characters can be used:<br>
   * '*' matches zero or more characters<br>
   * '?' matches one character.
   * <p>
   * Examples:
   * <p>
   * "**\*.class" matches all .class files/dirs in a directory tree.
   * <p>
   * "test\a??.java" matches all files/dirs which start with an 'a', then two
   * more characters and then ".java", in a directory called test.
   * <p>
   * "**" matches everything in a directory tree.
   * <p>
   * "**\test\**\XYZ*" matches all files/dirs which start with "XYZ" and where
   * there is a parent directory called test (e.g. "abc\test\def\ghi\XYZ123").
   * <p>
   * Case sensitivity may be turned off if necessary. By default, it is
   * turned on.
   * <p>
   * Example of usage:
   * <pre>
   *   String[] includes = {"**//*.class"};
   *   String[] excludes = {"modules//*//**"};
   *   ds.setIncludes(includes);
   *   ds.setExcludes(excludes);
   *   ds.setBasedir(new File("test"));
   *   ds.setCaseSensitive(true);
   *   ds.scan();
   *
   *   LOG.info("FILES:");
   *   String[] files = ds.getIncludedFiles();
   *   for (int i = 0; i < files.length; i++) {
   *     LOG.info(files[i]);
   *   }
   * </pre>
   * This will scan a directory called test for .class files, but excludes all
   * files in all proper subdirectories of a directory called "modules"
   *
   * @author Arnout J. Kuiper
   * <a href="mailto:ajkuiper@wxs.nl">ajkuiper@wxs.nl</a>
   * @author Magesh Umasankar
   * @author <a href="mailto:bruce@callenish.com">Bruce Atherton</a>
  * @author <a href="mailto:levylambert@tiscali-dsl.de">Antoine Levy-Lambert</a>
  */
 public class DirectoryScanner {
     private static final String EMPTY = "";
     /***
      * Patterns which should be excluded by default.
      *
      * @see #addDefaultExcludes()
      */
     private static final String[] DEFAULTEXCLUDES =
     {
         // Miscellaneous typical temporary files
         "**/*~",
         "**/#*#",
         "**/.#*",
         "**/%*%",
         "**/._*", // CVS
         "**/CVS",
         "**/CVS/**",
         "**/.cvsignore", // SCCS
         "**/SCCS",
         "**/SCCS/**", // Visual SourceSafe
         "**/vssver.scc", // Subversion
         "**/.svn",
         "**/.svn/**", // Mac
         "**/.DS_Store"
     };
 
     /*** The base directory to be scanned. */
     private File _basedir;
 
     /*** The patterns for the files to be included. */
     private String[] _includes;
 
     /*** The patterns for the files to be excluded. */
     private String[] _excludes;
 
     /*** Selectors that will filter which files are in our candidate list. */
     private FileFilter[] _selectors = null;
 
     /*** The files which matched at least one include and no excludes
      *  and were selected.
      */
     private List _filesIncluded;
 
     /*** The files which did not match any includes or selectors. */
     private List _filesNotIncluded;
 
     /***
      * The files which matched at least one include and at least
      * one exclude.
      */
     private List _filesExcluded;
 
     /*** The directories which matched at least one include and no excludes
      *  and were selected.
      */
     private List _dirsIncluded;
 
     /*** The directories which were found and did not match any includes. */
     private List _dirsNotIncluded;
 
     /***
      * The directories which matched at least one include and at least one
      * exclude.
      */
     private List _dirsExcluded;
 
     /*** The files which matched at least one include and no excludes and
      *  which a selector discarded.
      */
     private List _filesDeselected;
 
     /*** The directories which matched at least one include and no excludes
      *  but which a selector discarded.
      */
     private List _dirsDeselected;
 
     /*** Whether or not our results were built by a slow scan. */
     private boolean _haveSlowResults = false;
 
     /***
      * Whether or not the file system should be treated as a case sensitive
      * one.
      */
     private boolean _isCaseSensitive = true;
 
     /***
      * Whether or not symbolic links should be followed.
      *
      * @since Ant 1.5
      */
     private boolean _followSymlinks = true;
 
     /*** Whether or not everything tested so far has been included. */
     private boolean _everythingIncluded = true;
 
     /***
      * Sole constructor.
      */
     public DirectoryScanner() {}
 
     /***
      * Tests whether or not a given path matches the start of a given
      * pattern up to the first "**".
      * <p>
      * This is not a general purpose test and should only be used if you
      * can live with false positives. For example, <code>pattern=**\a</code>
      * and <code>str=b</code> will yield <code>true</code>.
      *
      * @param pattern The pattern to match against. Must not be
      *                <code>null</code>.
      * @param str     The path to match, as a String. Must not be
      *                <code>null</code>.
      * @param isCaseSensitive Whether or not matching should be performed
      *                        case sensitively.
      *
      * @return whether or not a given path matches the start of a given
      * pattern up to the first "**".
      */
     private static boolean matchPatternStart(String pattern, String str,
         boolean isCaseSensitive) {
         return SelectorUtils.matchPatternStart(pattern, str, isCaseSensitive);
     }
 
 
     /***
      * Tests whether or not a given path matches a given pattern.
      *
      * @param pattern The pattern to match against. Must not be
      *                <code>null</code>.
      * @param str     The path to match, as a String. Must not be
      *                <code>null</code>.
      * @param isCaseSensitive Whether or not matching should be performed
      *                        case sensitively.
      *
      * @return <code>true</code> if the pattern matches against the string,
      *         or <code>false</code> otherwise.
      */
     private static boolean matchPath(String pattern, String str, boolean isCaseSensitive) {
         return SelectorUtils.matchPath(pattern, str, isCaseSensitive);
     }
 
 
     /***
      * Sets the base directory to be scanned. This is the directory which is
      * scanned recursively. All '/' and '\' characters are replaced by
      * <code>File.separatorChar</code>, so the separator used need not match
      * <code>File.separatorChar</code>.
      *
      * @param basedir The base directory to scan.
      *                Must not be <code>null</code>.
      */
     public void setBasedir(String basedir) {
         setBasedir(new File(basedir.replace('/', File.separatorChar).replace('//',
                     File.separatorChar)));
     }
 
 
     /***
      * Sets the base directory to be scanned. This is the directory which is
      * scanned recursively.
      *
      * @param basedir The base directory for scanning.
      *                Should not be <code>null</code>.
      */
     public void setBasedir(File basedir) {
         this._basedir = basedir;
     }
 
 
     /***
      * Returns the base directory to be scanned.
      * This is the directory which is scanned recursively.
      *
      * @return the base directory to be scanned
      */
     public File getBasedir() {
         return _basedir;
     }
 
 
     /***
      * Sets whether or not the file system should be regarded as case sensitive.
      *
      * @param isCaseSensitive whether or not the file system should be
      *                        regarded as a case sensitive one
      */
     public void setCaseSensitive(boolean isCaseSensitive) {
         this._isCaseSensitive = isCaseSensitive;
     }
 
 
     /***
      * Sets whether or not symbolic links should be followed.
      *
      * @param followSymlinks whether or not symbolic links should be followed
      */
     public void setFollowSymlinks(boolean followSymlinks) {
         this._followSymlinks = followSymlinks;
     }
 
 
     /***
      * Sets the list of include patterns to use. All '/' and '\' characters
      * are replaced by <code>File.separatorChar</code>, so the separator used
      * need not match <code>File.separatorChar</code>.
      * <p>
      * When a pattern ends with a '/' or '\', "**" is appended.
      *
      * @param includes A list of include patterns.
      *                 May be <code>null</code>, indicating that all files
      *                 should be included. If a non-<code>null</code>
      *                 list is given, all elements must be
      * non-<code>null</code>.
      */
     public void setIncludes(String[] includes) {
         this._includes = copyPatternArray(includes);
     }
 
 
     /***
      * Sets the list of exclude patterns to use. All '/' and '\' characters
      * are replaced by <code>File.separatorChar</code>, so the separator used
      * need not match <code>File.separatorChar</code>.
      * <p>
      * When a pattern ends with a '/' or '\', "**" is appended.
      *
      * @param excludes A list of exclude patterns.
      *                 May be <code>null</code>, indicating that no files
      *                 should be excluded. If a non-<code>null</code> list is
      *                 given, all elements must be non-<code>null</code>.
      */
     public void setExcludes(String[] excludes) {
         this._excludes = copyPatternArray(excludes);
     }
 
 
     /***
      * Sets the selectors that will select the filelist.
      *
      * @param selectors specifies the selectors to be invoked on a scan
      */
     public void setSelectors(FileFilter[] selectors) {
         this._selectors = selectors;
     }
 
 
     /***
      * Returns whether or not the scanner has included all the files or
      * directories it has come across so far.
      *
      * @return <code>true</code> if all files and directories which have
      *         been found so far have been included.
      */
     public boolean isEverythingIncluded() {
         return _everythingIncluded;
     }
 
 
     /***
      * Scans the base directory for files which match at least one include
      * pattern and don't match any exclude patterns. If there are selectors
      * then the files must pass muster there, as well.
      *
      * @exception ScanException if the base directory was set
      *            incorrectly (i.e. if it is <code>null</code>, doesn't exist,
      *            or isn't a directory).
      */
     public void scan() {
         if (_basedir == null) {
             throw new ScanException("No basedir set");
         }
         if (!_basedir.exists()) {
             throw new ScanException("basedir " + _basedir + " does not exist");
         }
         if (!_basedir.isDirectory()) {
             throw new ScanException("basedir " + _basedir + " is not a directory");
         }
 
         if (_includes == null) {
             // No includes supplied, so set it to 'matches all'
             _includes = new String[1];
             _includes[0] = "**";
         }
         if (_excludes == null) {
             _excludes = new String[0];
         }
 
         _filesIncluded = new ArrayList();
         _filesNotIncluded = new ArrayList();
         _filesExcluded = new ArrayList();
         _filesDeselected = new ArrayList();
         _dirsIncluded = new ArrayList();
         _dirsNotIncluded = new ArrayList();
         _dirsExcluded = new ArrayList();
         _dirsDeselected = new ArrayList();
 
         if (isIncluded(EMPTY)) {
             if (!isExcluded(EMPTY)) {
                 if (isSelected(_basedir)) {
                     _dirsIncluded.add(EMPTY);
                 }
                 else {
                     _dirsDeselected.add(EMPTY);
                 }
             }
             else {
                 _dirsExcluded.add(EMPTY);
             }
         }
         else {
             _dirsNotIncluded.add(EMPTY);
         }
         scandir(_basedir, EMPTY, true);
     }
 
 
     /***
      * Top level invocation for a slow scan. A slow scan builds up a full
      * list of excluded/included files/directories, whereas a fast scan
      * will only have full results for included files, as it ignores
      * directories which can't possibly hold any included files/directories.
      * <p>
      * Returns immediately if a slow scan has already been completed.
      */
     private void slowScan() {
         if (_haveSlowResults) {
             return;
         }
 
         String[] excl = (String[])_dirsExcluded.toArray(new String[_dirsExcluded.size()]);
 
         String[] notIncl =
             (String[])_dirsNotIncluded.toArray(new String[_dirsNotIncluded.size()]);
 
         for (int i = 0; i < excl.length; i++) {
             if (!couldHoldIncluded(excl[i])) {
                 scandir(new File(_basedir, excl[i]), excl[i] + File.separator, false);
             }
         }
 
         for (int i = 0; i < notIncl.length; i++) {
             if (!couldHoldIncluded(notIncl[i])) {
                 scandir(new File(_basedir, notIncl[i]), notIncl[i] + File.separator, false);
             }
         }
 
         _haveSlowResults = true;
     }
 
 
     /***
      * Scans the given directory for files and directories. Found files and
      * directories are placed in their respective collections, based on the
      * matching of includes, excludes, and the selectors.  When a directory
      * is found, it is scanned recursively.
      *
      * @param dir   The directory to scan. Must not be <code>null</code>.
      * @param vpath The path relative to the base directory (needed to
      *              prevent problems with an absolute path when using
      *              dir). Must not be <code>null</code>.
      * @param fast  Whether or not this call is part of a fast scan.
      *
      * @see #_filesIncluded
      * @see #_filesNotIncluded
      * @see #_filesExcluded
      * @see #_dirsIncluded
      * @see #_dirsNotIncluded
      * @see #_dirsExcluded
      */
     private void scandir(File dir, String vpath, boolean fast) {
         String[] newfiles = dir.list();
 
         if (newfiles == null) {
             /*
              * two reasons are mentioned in the API docs for File.list
              * (1) dir is not a directory. This is impossible as
              *     we wouldn't get here in this case.
              * (2) an IO error occurred (why doesn't it throw an exception
              *     then???)
              */
             throw new ScanException("IO error scanning directory "
                 + dir.getAbsolutePath());
         }
 
         if (!_followSymlinks) {
             List noLinks = new ArrayList();
             for (int i = 0; i < newfiles.length; i++) {
                 try {
                     if (isSymbolicLink(dir, newfiles[i])) {
                         String name = vpath + newfiles[i];
                         File file = new File(dir, newfiles[i]);
                         if (file.isDirectory()) {
                             _dirsExcluded.add(name);
                         }
                         else {
                             _filesExcluded.add(name);
                         }
                     }
                     else {
                         noLinks.add(newfiles[i]);
                     }
                 }
                 catch (IOException ioe) {
                     String msg =
                         "IOException caught while checking "
                         + "for links, couldn't get cannonical path!";
 
                     // will be caught and redirected to Ant's logging system
                     System.err.println(msg);
                     noLinks.add(newfiles[i]);
                 }
             }
             newfiles = (String[])noLinks.toArray(new String[noLinks.size()]);
         }
 
         for (int i = 0; i < newfiles.length; i++) {
             String name = vpath + newfiles[i];
             File file = new File(dir, newfiles[i]);
             if (file.isDirectory()) {
                 if (isIncluded(name)) {
                     if (!isExcluded(name)) {
                         if (isSelected(file)) {
                             _dirsIncluded.add(file);
                             if (fast) {
                                 scandir(file, name + File.separator, fast);
                             }
                         }
                         else {
                             _everythingIncluded = false;
                             _dirsDeselected.add(name);
                             if (fast && couldHoldIncluded(name)) {
                                 scandir(file, name + File.separator, fast);
                             }
                         }
                     }
                     else {
                         _everythingIncluded = false;
                         _dirsExcluded.add(name);
                         if (fast && couldHoldIncluded(name)) {
                             scandir(file, name + File.separator, fast);
                         }
                     }
                 }
                 else {
                     _everythingIncluded = false;
                     _dirsNotIncluded.add(name);
                     if (fast && couldHoldIncluded(name)) {
                         scandir(file, name + File.separator, fast);
                     }
                 }
                 if (!fast) {
                     scandir(file, name + File.separator, fast);
                 }
             }
             else if (file.isFile()) {
                 if (isIncluded(name)) {
                     if (!isExcluded(name)) {
                         if (isSelected(file)) {
                             _filesIncluded.add(file);
                         }
                         else {
                             _everythingIncluded = false;
                             _filesDeselected.add(name);
                         }
                     }
                     else {
                         _everythingIncluded = false;
                         _filesExcluded.add(name);
                     }
                 }
                 else {
                     _everythingIncluded = false;
                     _filesNotIncluded.add(name);
                 }
             }
         }
     }
 
 
     /***
      * Tests whether or not a name matches against at least one include
      * pattern.
      *
      * @param name The name to match. Must not be <code>null</code>.
      * @return <code>true</code> when the name matches against at least one
      *         include pattern, or <code>false</code> otherwise.
      */
     private boolean isIncluded(String name) {
         for (int i = 0; i < _includes.length; i++) {
             if (matchPath(_includes[i], name, _isCaseSensitive)) {
                 return true;
             }
         }
         return false;
     }
 
 
     /***
      * Tests whether or not a name matches the start of at least one include
      * pattern.
      *
      * @param name The name to match. Must not be <code>null</code>.
      * @return <code>true</code> when the name matches against the start of at
      *         least one include pattern, or <code>false</code> otherwise.
      */
     private boolean couldHoldIncluded(String name) {
         for (int i = 0; i < _includes.length; i++) {
             if (matchPatternStart(_includes[i], name, _isCaseSensitive)) {
                 return true;
             }
         }
         return false;
     }
 
 
     /***
      * Tests whether or not a name matches against at least one exclude
      * pattern.
      *
      * @param name The name to match. Must not be <code>null</code>.
      * @return <code>true</code> when the name matches against at least one
      *         exclude pattern, or <code>false</code> otherwise.
      */
     private boolean isExcluded(String name) {
         for (int i = 0; i < _excludes.length; i++) {
             if (matchPath(_excludes[i], name, _isCaseSensitive)) {
                 return true;
             }
         }
         return false;
     }
 
 
     /***
      * Tests whether a name should be selected.
      *
      * @param file the java.io.File object for this filename
      * @return <code>false</code> when the selectors says that the file
      *         should not be selected, <code>true</code> otherwise.
      */
     private boolean isSelected(File file) {
         if (_selectors != null) {
             for (int i = 0; i < _selectors.length; i++) {
                 if (!(_selectors[i].accept(file))) {
                     return false;
                 }
             }
         }
         return true;
     }
 
 
     /***
      * 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.
      *
      * @return the names of the files which matched at least one of the
      *         include patterns and none of the exclude patterns.
      */
     public File[] getIncludedFiles() {
         return (File[])_filesIncluded.toArray(new File[_filesIncluded.size()]);
     }
 
 
     /***
      * Returns the names of the files which matched none of the include
      * patterns. The names are relative to the base directory. This involves
      * performing a slow scan if one has not already been completed.
      *
      * @return the names of the files which matched none of the include
      *         patterns.
      */
     public String[] getNotIncludedFiles() {
         slowScan();
         return (String[])_filesNotIncluded.toArray(new String[_filesNotIncluded.size()]);
     }
 
 
     /***
      * Returns the names of the files which matched at least one of the
      * include patterns and at least one of the exclude patterns.
      * The names are relative to the base directory. This involves
      * performing a slow scan if one has not already been completed.
      *
      * @return the names of the files which matched at least one of the
      *         include patterns and at at least one of the exclude patterns.
      */
     public String[] getExcludedFiles() {
         slowScan();
         return (String[])_filesExcluded.toArray(new String[_filesExcluded.size()]);
     }
 
 
     /***
      * <p>Returns the names of the files which were selected out and
      * therefore not ultimately included.</p>
      *
      * <p>The names are relative to the base directory. This involves
      * performing a slow scan if one has not already been completed.</p>
      *
      * @return the names of the files which were deselected.
      */
     public String[] getDeselectedFiles() {
         slowScan();
         return (String[])_filesDeselected.toArray(new String[_filesDeselected.size()]);
     }
 
 
     /***
      * 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.
      *
      * @return the names of the directories which matched at least one of the
      * include patterns and none of the exclude patterns.
      */
     public File[] getIncludedDirectories() {
         return (File[])_dirsIncluded.toArray(new File[_dirsIncluded.size()]);
     }
 
 
     /***
      * Returns the names of the directories which matched none of the include
      * patterns. The names are relative to the base directory. This involves
      * performing a slow scan if one has not already been completed.
      *
      * @return the names of the directories which matched none of the include
      * patterns.
      */
     public String[] getNotIncludedDirectories() {
         slowScan();
         return (String[])_dirsNotIncluded.toArray(new String[_dirsNotIncluded.size()]);
     }
 
 
     /***
      * Returns the names of the directories which matched at least one of the
      * include patterns and at least one of the exclude patterns.
      * The names are relative to the base directory. This involves
      * performing a slow scan if one has not already been completed.
      *
      * @return the names of the directories which matched at least one of the
      * include patterns and at least one of the exclude patterns.
      */
     public String[] getExcludedDirectories() {
         slowScan();
         return (String[])_dirsExcluded.toArray(new String[_dirsExcluded.size()]);
     }
 
 
     /***
      * <p>Returns the names of the directories which were selected out and
      * therefore not ultimately included.</p>
      *
      * <p>The names are relative to the base directory. This involves
      * performing a slow scan if one has not already been completed.</p>
      *
      * @return the names of the directories which were deselected.
      */
     public String[] getDeselectedDirectories() {
         slowScan();
         return (String[])_dirsDeselected.toArray(new String[_dirsDeselected.size()]);
     }
 
 
     /***
      * Adds default exclusions to the current exclusions set.
      */
     public void addDefaultExcludes() {
         int excludesLength = _excludes == null ? 0 : _excludes.length;
         String[] newExcludes;
         newExcludes = new String[excludesLength + DEFAULTEXCLUDES.length];
         if (excludesLength > 0) {
             System.arraycopy(_excludes, 0, newExcludes, 0, excludesLength);
         }
         for (int i = 0; i < DEFAULTEXCLUDES.length; i++) {
             newExcludes[i + excludesLength] =
                 DEFAULTEXCLUDES[i].replace('/', File.separatorChar).replace('//',
                     File.separatorChar);
         }
         _excludes = newExcludes;
     }
 
 
     private static boolean isSymbolicLink(File parent, String name)
         throws IOException {
         File resolvedParent = new File(parent.getCanonicalPath());
         File toTest = new File(resolvedParent, name);
         return !toTest.getAbsolutePath().equals(toTest.getCanonicalPath());
     }
 
 
     private static final String[] copyPatternArray(String[] source) {
         if (source == null) {
             return null;
         }
 
         String[] results = new String[source.length];
         for (int i = 0; i < source.length; i++) {
             String pattern;
             pattern =
                 source[i].replace('/', File.separatorChar).replace('//',
                     File.separatorChar);
             if (pattern.endsWith(File.separator)) {
                 pattern += "**";
             }
             results[i] = pattern;
         }
         return results;
     }
 }