View Javadoc
1   package org.codehaus.plexus.util;
2   
3   /*
4    * Copyright The Codehaus Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import java.io.File;
20  
21  /**
22   * Scan a directory tree for files, with specified inclusions and exclusions.
23   */
24  public interface Scanner
25  {
26  
27      /**
28       * Sets the list of include patterns to use. All '/' and '\' characters are replaced by
29       * <code>File.separatorChar</code>, so the separator used need not match <code>File.separatorChar</code>.
30       * <p>
31       * When a pattern ends with a '/' or '\', "**" is appended.
32       *
33       * @param includes A list of include patterns. May be <code>null</code>, indicating that all files should be
34       *            included. If a non-<code>null</code> list is given, all elements must be non-<code>null</code>.
35       */
36      void setIncludes( String[] includes );
37  
38      /**
39       * Sets the list of exclude patterns to use. All '/' and '\' characters are replaced by
40       * <code>File.separatorChar</code>, so the separator used need not match <code>File.separatorChar</code>.
41       * <p>
42       * When a pattern ends with a '/' or '\', "**" is appended.
43       *
44       * @param excludes A list of exclude patterns. May be <code>null</code>, indicating that no files should be
45       *            excluded. If a non-<code>null</code> list is given, all elements must be non-<code>null</code>.
46       */
47      void setExcludes( String[] excludes );
48  
49      /**
50       * Adds default exclusions to the current exclusions set.
51       */
52      void addDefaultExcludes();
53  
54      /**
55       * Scans the base directory for files which match at least one include pattern and don't match any exclude patterns.
56       *
57       * @exception IllegalStateException if the base directory was set incorrectly (i.e. if it is <code>null</code>,
58       *                doesn't exist, or isn't a directory).
59       */
60      void scan();
61  
62      /**
63       * Returns the names of the files which matched at least one of the include patterns and none of the exclude
64       * patterns. The names are relative to the base directory.
65       *
66       * @return the names of the files which matched at least one of the include patterns and none of the exclude
67       *         patterns.
68       */
69      String[] getIncludedFiles();
70  
71      /**
72       * Returns the names of the directories which matched at least one of the include patterns and none of the exclude
73       * patterns. The names are relative to the base directory.
74       *
75       * @return the names of the directories which matched at least one of the include patterns and none of the exclude
76       *         patterns.
77       */
78      String[] getIncludedDirectories();
79  
80      /**
81       * Returns the base directory to be scanned. This is the directory which is scanned recursively.
82       *
83       * @return the base directory to be scanned
84       */
85      File getBasedir();
86  }