package org.codehaus.plexus.util;

/*
 * Copyright The Codehaus Foundation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import java.io.File;
import java.util.Comparator;

Scan a directory tree for files, with specified inclusions and exclusions.
/**
 * Scan a directory tree for files, with specified inclusions and exclusions.
 */
public interface Scanner
{

    
Sets the list of include patterns to use. All '/' and '\' characters are replaced by
File.separatorChar, so the separator used need not match File.separatorChar.

When a pattern ends with a '/' or '\', "**" is appended.
Params:
includes – A list of include patterns. May be null, indicating that all files should be
           included. If a non-null list is given, all elements must be non-null./**
     * 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>.
     */
    void setIncludes( String[] includes );

    
Sets the list of exclude patterns to use. All '/' and '\' characters are replaced by
File.separatorChar, so the separator used need not match File.separatorChar.

When a pattern ends with a '/' or '\', "**" is appended.
Params:
excludes – A list of exclude patterns. May be null, indicating that no files should be
           excluded. If a non-null list is given, all elements must be non-null./**
     * 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>.
     */
    void setExcludes( String[] excludes );

    
Adds default exclusions to the current exclusions set.
/**
     * Adds default exclusions to the current exclusions set.
     */
    void addDefaultExcludes();

    
Scans the base directory for files which match at least one include pattern and don't match any exclude patterns.
Throws:
IllegalStateException – if the base directory was set incorrectly (i.e. if it is null,
               doesn't exist, or isn't a directory)./**
     * Scans the base directory for files which match at least one include pattern and don't match any exclude patterns.
     *
     * @exception IllegalStateException if the base directory was set incorrectly (i.e. if it is <code>null</code>,
     *                doesn't exist, or isn't a directory).
     */
    void scan();

    
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.
Returns:
the names of the files which matched at least one of the include patterns and none of the exclude
        patterns./**
     * 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.
     */
    String[] getIncludedFiles();

    
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.
Returns:
the names of the directories which matched at least one of the include patterns and none of the exclude
        patterns./**
     * 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.
     */
    String[] getIncludedDirectories();

    
Returns the base directory to be scanned. This is the directory which is scanned recursively.
Returns:
the base directory to be scanned/**
     * Returns the base directory to be scanned. This is the directory which is scanned recursively.
     *
     * @return the base directory to be scanned
     */
    File getBasedir();

    
Use a filename comparator in each directory when scanning.
Params:
filenameComparator – 
Since:
3.3.0/**
     * Use a filename comparator in each directory when scanning.
     *
     * @param filenameComparator
     * @since 3.3.0
     */
    void setFilenameComparator( Comparator<String> filenameComparator );
}