ANT_17_BRANCH/src/main/org/apache/tools/ant/taskdefs/optional/scm/AntStarTeamCheckOut.java

/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You 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.
 *
 */
package org.apache.tools.ant.taskdefs.optional.scm;

import com.starbase.starteam.Folder;
import com.starbase.starteam.Item;
import com.starbase.starteam.Property;
import com.starbase.starteam.Server;
import com.starbase.starteam.StarTeamFinder;
import com.starbase.starteam.Type;
import com.starbase.starteam.View;
import com.starbase.util.Platform;
import java.util.StringTokenizer;
import org.apache.tools.ant.BuildException;
import org.apache.tools.ant.DirectoryScanner;
import org.apache.tools.ant.Project;

/**
 * Checks out files from a specific StarTeam server, project, view, and
 * folder.
 * <BR><BR>
 * This program logs in to a StarTeam server and opens up the specified
 * project and view.  Then, it searches through that view for the given
 * folder (or, if you prefer, it uses the root folder).  Beginning with
 * that folder and optionally continuing recursivesly, AntStarTeamCheckOut
 * compares each file with your include and exclude filters and checks it
 * out only if appropriate.
 * <BR><BR>
 * Checked out files go to a directory you specify under the subfolder
 * named for the default StarTeam path to the view.  That is, if you
 * entered /home/cpovirk/work as the target folder, your project was named
 * "OurProject," the given view was named "TestView," and that view is
 * stored by default at "C:\projects\Test," your files would be checked
 * out to /home/cpovirk/work/Test."  I avoided using the project name in
 * the path because you may want to keep several versions of the same
 * project on your computer, and I didn't want to use the view name, as
 * there may be many "Test" or "Version 1.0" views, for example.  This
 * system's success, of course, depends on what you set the default path
 * to in StarTeam.
 * <BR><BR>
 * You can set AntStarTeamCheckOut to verbose or quiet mode.  Also, it has
 * a safeguard against overwriting the files on your computer:  If the
 * target directory you specify already exists, the program will throw a
 * BuildException.  To override the exception, set <CODE>force</CODE> to
 * true.
 * <BR><BR>
 * <B>This program makes use of functions from the StarTeam API.  As a result
 * AntStarTeamCheckOut is available only to licensed users of StarTeam and
 * requires the StarTeam SDK to function.  You must have
 * <CODE>starteam-sdk.jar</CODE> in your classpath to run this program.
 * For more information about the StarTeam API and how to license it, see
 * the link below.</B>
 *
 * @version 1.0
 * @see <A HREF="http://www.starbase.com/">StarBase Web Site</A>
 *
 * @ant.task name="starteam" category="scm" ignore="true"
 */
public class AntStarTeamCheckOut extends org.apache.tools.ant.Task {

    /**
     * This constant sets the filter to include all files. This default has
     * the same result as <CODE>setIncludes("*")</CODE>.
     *
     * @see #getIncludes()
     * @see #setIncludes(String includes)
     */
    public static final String DEFAULT_INCLUDESETTING = "*";

    /**
     * This disables the exclude filter by default. In other words, no files
     * are excluded. This setting is equivalent to <CODE>setExcludes(null)</CODE>
     * .
     *
     * @see #getExcludes()
     * @see #setExcludes(String excludes)
     */
    public static final String DEFAULT_EXCLUDESETTING = null;

    /**
     * The default folder to search; the root folder. Since
     * AntStarTeamCheckOut searches subfolders, by default it processes an
     * entire view.
     *
     * @see #getFolderName()
     * @see #setFolderName(String folderName)
     */
    public static final String DEFAULT_FOLDERSETTING = null;

    /**
     * This is used when formatting the output. The directory name is
     * displayed only when it changes.
     */
    private Folder prevFolder = null;

    /** This field keeps count of the number of files checked out.  */
    private int checkedOut = 0;

    // Change these through their GET and SET methods.

    /** The name of the server you wish to connect to.  */
    private String serverName = null;

    /** The port on the server used for StarTeam.  */
    private int serverPort = -1;

    /** The name of your project.  */
    private String projectName = null;

    /**
     * The name of the folder you want to check out files from. All subfolders
     * will be searched, as well.
     */
    private String folderName = DEFAULT_FOLDERSETTING;

    /** The view that the files you want are in.  */
    private String viewName = null;

    /** Your username on the StarTeam server.  */
    private String username = null;

    /** Your StarTeam password.  */
    private String password = null;

    /**
     * The path to the root folder you want to check out to. This is a local
     * directory.
     */
    private String targetFolder = null;

    /**
     * If force set to true, AntStarTeamCheckOut will overwrite files in the
     * target directory.
     */
    private boolean force = false;

    /**
     * When verbose is true, the program will display all files and
     * directories as they are checked out.
     */
    private boolean verbose = false;

    /**
     * Set recursion to false to check out files in only the given folder and
     * not in its subfolders.
     */
    private boolean recursion = true;

    // These fields deal with includes and excludes

    /** All files that fit this pattern are checked out.  */
    private String includes = DEFAULT_INCLUDESETTING;

    /** All files fitting this pattern are ignored.  */
    private String excludes = DEFAULT_EXCLUDESETTING;

    /** The file delimitor on the user's system.  */
    private String delim = Platform.getFilePathDelim();

    /**
     * whether to use the Starteam "default folder" when calculating the
     * target paths to which files are checked out (false) or if targetFolder
     * represents an absolute mapping to folderName.
     */
    private boolean targetFolderAbsolute = false;


    /** convenient method to check for conditions */
    private static void assertTrue(boolean value, String msg) throws BuildException {
        if (!value) {
            throw new BuildException(msg);
        }
    }

    /**
     * Check if the attributes/elements are correct.
     * @throws BuildException if there was a problem.
     */
    protected void checkParameters() throws BuildException {
        // Check all of the properties that are required.
        assertTrue(getServerName() != null, "ServerName must be set.");
        assertTrue(getServerPort() != -1, "ServerPort must be set.");
        assertTrue(getProjectName() != null, "ProjectName must be set.");
        assertTrue(getViewName() != null, "ViewName must be set.");
        assertTrue(getUsername() != null, "Username must be set.");
        assertTrue(getPassword() != null, "Password must be set.");
        assertTrue(getTargetFolder() != null, "TargetFolder must be set.");

        // Because of the way I create the full target path, there
        // must be NO slash at the end of targetFolder and folderName
        // However, if the slash or backslash is the only character, leave it alone
        if ((getTargetFolder().endsWith("/")
                || getTargetFolder().endsWith("\\"))
             && getTargetFolder().length() > 1) {
            setTargetFolder(getTargetFolder().substring(0, getTargetFolder().length() - 1));
        }

        // Check to see if the target directory exists.
        java.io.File dirExist = new java.io.File(getTargetFolder());

        if (dirExist.isDirectory() && !getForce()) {
            throw new BuildException("Target directory exists. Set \"force\" "
                 + "to \"true\" to continue anyway.");
        }
    }


    /**
     * Do the execution.
     *
     * @throws BuildException if there was a problem.
     */
    public void execute() throws BuildException {
        log("DEPRECATED - The starteam task is deprecated.  Use stcheckout instead.",
            Project.MSG_WARN);

        // Connect to the StarTeam server, and log on.
        Server s = getServer();

        try {
            // Search the items on this server.
            runServer(s);
        } finally {
            // Disconnect from the server.
            s.disconnect();
        }
        // after you are all of the properties are ok, do your thing
        // with StarTeam.  If there are any kind of exceptions then
        // send the message to the project log.

        // Tell how many files were checked out.
        log(checkedOut + " files checked out.");
    }


    /**
     * Creates and logs in to a StarTeam server.
     *
     * @return A StarTeam server.
     */
    protected Server getServer() {
        // Simplest constructor, uses default encryption algorithm and compression level.
        Server s = new Server(getServerName(), getServerPort());

        // Optional; logOn() connects if necessary.
        s.connect();

        // Logon using specified user name and password.
        s.logOn(getUsername(), getPassword());

        return s;
    }


    /**
     * Searches for the specified project on the server.
     *
     * @param s A StarTeam server.
     */
    protected void runServer(Server s) {
        com.starbase.starteam.Project[] projects = s.getProjects();

        for (int i = 0; i < projects.length; i++) {
            com.starbase.starteam.Project p = projects[i];

            if (p.getName().equals(getProjectName())) {
                if (getVerbose()) {
                    log("Found " + getProjectName() + delim);
                }
                runProject(s, p);
                break;
            }
        }
    }


    /**
     * Searches for the given view in the project.
     *
     * @param s A StarTeam server.
     * @param p A valid project on the given server.
     */
    protected void runProject(Server s, com.starbase.starteam.Project p) {
        View[] views = p.getViews();

        for (int i = 0; i < views.length; i++) {
            View v = views[i];

            if (v.getName().equals(getViewName())) {
                if (getVerbose()) {
                    log("Found " + getProjectName() + delim + getViewName() + delim);
                }
                runType(s, p, v, s.typeForName(s.getTypeNames().FILE));
                break;
            }
        }
    }


    /**
     * Searches for folders in the given view.
     *
     * @param s A StarTeam server.
     * @param p A valid project on the server.
     * @param v A view name from the specified project.
     * @param t An item type which is currently always "file".
     */
    protected void runType(Server s, com.starbase.starteam.Project p, View v, Type t) {
        // This is ugly; checking for the root folder.
        Folder f = v.getRootFolder();

        if (getFolderName() != null) {
            if (getFolderName().equals("\\") || getFolderName().equals("/")) {
                setFolderName(null);
            } else {
                f = StarTeamFinder.findFolder(v.getRootFolder(), getFolderName());
                assertTrue(null != f, "ERROR: " + getProjectName() + delim
                    + getViewName() + delim + v.getRootFolder() + delim
                    + getFolderName() + delim
                    + " does not exist.");
            }
        }

        if (getVerbose() && getFolderName() != null) {
            log("Found " + getProjectName() + delim + getViewName()
                + delim + getFolderName() + delim + "\n");
        }

        // For performance reasons, it is important to pre-fetch all the
        // properties we'll need for all the items we'll be searching.

        // We always display the ItemID (OBJECT_ID) and primary descriptor.
        int nProperties = 2;

        // We'll need this item type's primary descriptor.
        Property p1 = getPrimaryDescriptor(t);

        // Does this item type have a secondary descriptor?
        // If so, we'll need it.
        Property p2 = getSecondaryDescriptor(t);

        if (p2 != null) {
            nProperties++;
        }

        // Now, build an array of the property names.
        String[] strNames = new String[nProperties];
        int iProperty = 0;

        strNames[iProperty++] = s.getPropertyNames().OBJECT_ID;
        strNames[iProperty++] = p1.getName();
        if (p2 != null) {
            strNames[iProperty++] = p2.getName();
        }

        // Pre-fetch the item properties and cache them.
        f.populateNow(t.getName(), strNames, -1);

        // Now, search for items in the selected folder.
        runFolder(s, p, v, t, f, calcTargetFolder(v, f));

        // Free up the memory used by the cached items.
        f.discardItems(t.getName(), -1);
    }


    /**
     * Returns a file object that defines the root of the local checkout tree.
     * Depending on the value of targetFolderAbsolute, this will be either the
     * targetFolder exactly as set by the user or the path formed by appending
     * the default folder onto the specified target folder.
     *
     * @param v view from which the file is checked out, supplies the "default
     *      folder"
     * @param rootSourceFolder root folder of the checkout operation in Star
     *      Team
     * @return an object referencing the local file
     * @see #getTargetFolderAbsolute()
     */
    private java.io.File calcTargetFolder(View v, Folder rootSourceFolder) {
        java.io.File root = new java.io.File(getTargetFolder());

        if (!getTargetFolderAbsolute()) {
            // Create a variable dir that contains the name of
            // the StarTeam folder that is the root folder in this view.
            // Get the default path to the current view.
            String defaultPath = v.getDefaultPath();

            // convert whatever separator char is in starteam to that of the target system.
            defaultPath = defaultPath.replace('/', java.io.File.separatorChar);
            defaultPath = defaultPath.replace('\\', java.io.File.separatorChar);

            java.io.File dir = new java.io.File(defaultPath);
            String dirName = dir.getName();

            // If it ends with separator then strip it off
            if (dirName.endsWith(delim)) {
                dirName = dirName.substring(0, dirName.length() - 1);
            }

            // Replace the projectName in the file's absolute path to the viewName.
            // This makes the root target of a checkout operation equal to:
            // targetFolder + dirName
            StringTokenizer pathTokenizer
                = new StringTokenizer(rootSourceFolder.getFolderHierarchy(), delim);
            String currentToken = null;
            boolean foundRoot = false;

            while (pathTokenizer.hasMoreTokens()) {
                currentToken = pathTokenizer.nextToken();
                if (currentToken.equals(getProjectName()) && !foundRoot) {
                    currentToken = dirName;
                    foundRoot = true; // only want to do this the first time
                }
                root = new java.io.File(root, currentToken);
            }
        }

        return root;
    }


    /**
     * Searches for files in the given folder. This method is recursive and
     * thus searches all subfolders.
     *
     * @param s A StarTeam server.
     * @param p A valid project on the server.
     * @param v A view name from the specified project.
     * @param t An item type which is currently always "file".
     * @param f The folder to search.
     * @param tgt Target folder on local machine
     */
    protected void runFolder(Server s,
                             com.starbase.starteam.Project p,
                             View v,
                             Type t,
                             Folder f,
                             java.io.File tgt) {
        // Process all items in this folder.
        Item[] items = f.getItems(t.getName());

        for (int i = 0; i < items.length; i++) {
            runItem(s, p, v, t, f, items[i], tgt);
        }

        // Process all subfolders recursively if recursion is on.
        if (getRecursion()) {
            Folder[] subfolders = f.getSubFolders();

            for (int i = 0; i < subfolders.length; i++) {
                runFolder(s, p, v, t, subfolders[i],
                          new java.io.File(tgt, subfolders[i].getName()));
            }
        }
    }


    /**
     * Check out one file if it matches the include filter but not the exclude
     * filter.
     *
     * @param s A StarTeam server.
     * @param p A valid project on the server.
     * @param v A view name from the specified project.
     * @param t An item type which is currently always "file".
     * @param f The folder the file is localed in.
     * @param item The file to check out.
     * @param tgt target folder on local machine
     */
    protected void runItem(Server s,
                           com.starbase.starteam.Project p,
                           View v,
                           Type t,
                           Folder f,
                           Item item,
                           java.io.File tgt) {
        // Get descriptors for this item type.
        Property p1 = getPrimaryDescriptor(t);
        Property p2 = getSecondaryDescriptor(t);

        String pName = (String) item.get(p1.getName());

        if (!shouldCheckout(pName)) {
            return;
        }

        // VERBOSE MODE ONLY
        if (getVerbose()) {
            // Show folder only if changed.
            boolean bShowHeader = (f != prevFolder);

            if (bShowHeader) {
                // We want to display the folder the same way you would
                // enter it on the command line ... so we remove the
                // View name (which is also the name of the root folder,
                // and therefore shows up at the start of the path).
                String strFolder = f.getFolderHierarchy();
                int i = strFolder.indexOf(delim);

                if (i >= 0) {
                    strFolder = strFolder.substring(i + 1);
                }
                log("            Folder: \"" + strFolder + "\"");
                prevFolder = f;

                // If we displayed the project, view, item type, or folder,
                // then show the list of relevant item properties.
                StringBuffer header = new StringBuffer("                Item");

                header.append(",\t").append(p1.getDisplayName());
                if (p2 != null) {
                    header.append(",\t").append(p2.getDisplayName());
                }
                log(header.toString());
            }

            // Finally, show the Item properties ...
            // Always show the ItemID.
            StringBuffer itemLine = new StringBuffer("                ");

            itemLine.append(item.getItemID());

            // Show the primary descriptor.
            // There should always be one.
            itemLine.append(",\t").append(formatForDisplay(p1, item.get(p1.getName())));

            // Show the secondary descriptor, if there is one.
            // Some item types have one, some don't.
            if (p2 != null) {
                itemLine.append(",\t").append(formatForDisplay(p2, item.get(p2.getName())));
            }

            // Show if the file is locked.
            int locker = item.getLocker();

            if (locker > -1) {
                itemLine.append(",\tLocked by ").append(locker);
            } else {
                itemLine.append(",\tNot locked");
            }
            log(itemLine.toString());
        }
        // END VERBOSE ONLY

        // Check it out; also ugly.

        // Change the item to be checked out to a StarTeam File.
        com.starbase.starteam.File remote = (com.starbase.starteam.File) item;

        // The local file name is simply the local target path (tgt) which has
        // been passed recursively down from the top of the tree, with the item's name appended.
        java.io.File local = new java.io.File(tgt, (String) item.get(p1.getName()));

        try {
            remote.checkoutTo(local, Item.LockType.UNCHANGED, false, true, true);
            checkedOut++;
        } catch (Exception e) {
            throw new BuildException("Failed to checkout '" + local + "'", e);
        }
    }


    /**
     * Look if the file should be checked out. Don't check it out if It fits
     * no include filters and It fits an exclude filter.
     *
     * @param pName the item name to look for being included.
     * @return whether the file should be checked out or not.
     */
    protected boolean shouldCheckout(String pName) {
        boolean includeIt = matchPatterns(getIncludes(), pName);
        boolean excludeIt = matchPatterns(getExcludes(), pName);

        return (includeIt && !excludeIt);
    }


    /**
     * Convenient method to see if a string match a one pattern in given set
     * of space-separated patterns.
     *
     * @param patterns the space-separated list of patterns.
     * @param pName the name to look for matching.
     * @return whether the name match at least one pattern.
     */
    protected boolean matchPatterns(String patterns, String pName) {
        if (patterns == null) {
            return false;
        }
        StringTokenizer exStr = new StringTokenizer(patterns, " ");

        while (exStr.hasMoreTokens()) {
            if (DirectoryScanner.match(exStr.nextToken(), pName)) {
                return true;
            }
        }
        return false;
    }


    /**
     * Get the primary descriptor of the given item type. Returns null if
     * there isn't one. In practice, all item types have a primary descriptor.
     *
     * @param t An item type. At this point it will always be "file".
     * @return The specified item's primary descriptor.
     */
    protected Property getPrimaryDescriptor(Type t) {
        Property[] properties = t.getProperties();

        for (int i = 0; i < properties.length; i++) {
            Property p = properties[i];

            if (p.isPrimaryDescriptor()) {
                return p;
            }
        }
        return null;
    }


    /**
     * Get the secondary descriptor of the given item type. Returns null if
     * there isn't one.
     *
     * @param t An item type. At this point it will always be "file".
     * @return The specified item's secondary descriptor. There may not be one
     *      for every file.
     */
    protected Property getSecondaryDescriptor(Type t) {
        Property[] properties = t.getProperties();

        for (int i = 0; i < properties.length; i++) {
            Property p = properties[i];

            if (p.isDescriptor() && !p.isPrimaryDescriptor()) {
                return p;
            }
        }
        return null;
    }


    /**
     * Formats a property value for display to the user.
     *
     * @param p An item property to format.
     * @param value the object to format.
     * @return A string containing the property, which is truncated to 35
     *      characters for display.
     */
    protected String formatForDisplay(Property p, Object value) {
        if (p.getTypeCode() == Property.Types.TEXT) {
            String str = value.toString();

            if (str.length() > 35) {
                str = str.substring(0, 32) + "...";
            }
            return "\"" + str + "\"";
        } else {
            if (p.getTypeCode() == Property.Types.ENUMERATED) {
                return "\"" + p.getEnumDisplayName(((Integer) value).intValue()) + "\"";
            } else {
                return value.toString();
            }
        }
    }

    // Begin SET and GET methods

    /**
     * Sets the <CODE>serverName</CODE> attribute to the given value.
     *
     * @param serverName The name of the server you wish to connect to.
     * @see #getServerName()
     */
    public void setServerName(String serverName) {
        this.serverName = serverName;
    }


    /**
     * Gets the <CODE>serverName</CODE> attribute.
     *
     * @return The StarTeam server to log in to.
     * @see #setServerName(String serverName)
     */
    public String getServerName() {
        return serverName;
    }


    /**
     * Sets the <CODE>serverPort</CODE> attribute to the given value. The
     * given value must be a valid integer, but it must be a string object.
     *
     * @param serverPort A string containing the port on the StarTeam server
     *      to use.
     * @see #getServerPort()
     */
    public void setServerPort(int serverPort) {
        this.serverPort = serverPort;
    }


    /**
     * Gets the <CODE>serverPort</CODE> attribute.
     *
     * @return A string containing the port on the StarTeam server to use.
     * @see #setServerPort(int)
     */
    public int getServerPort() {
        return serverPort;
    }


    /**
     * Sets the <CODE>projectName</CODE> attribute to the given value.
     *
     * @param projectName The StarTeam project to search.
     * @see #getProjectName()
     */
    public void setProjectName(String projectName) {
        this.projectName = projectName;
    }


    /**
     * Gets the <CODE>projectName</CODE> attribute.
     *
     * @return The StarTeam project to search.
     * @see #setProjectName(String projectName)
     */
    public String getProjectName() {
        return projectName;
    }


    /**
     * Sets the <CODE>viewName</CODE> attribute to the given value.
     *
     * @param viewName The view to find the specified folder in.
     * @see #getViewName()
     */
    public void setViewName(String viewName) {
        this.viewName = viewName;
    }


    /**
     * Gets the <CODE>viewName</CODE> attribute.
     *
     * @return The view to find the specified folder in.
     * @see #setViewName(String viewName)
     */
    public String getViewName() {
        return viewName;
    }


    /**
     * Sets the <CODE>folderName</CODE> attribute to the given value. To
     * search the root folder, use a slash or backslash, or simply don't set a
     * folder at all.
     *
     * @param folderName The subfolder from which to check out files.
     * @see #getFolderName()
     */
    public void setFolderName(String folderName) {
        this.folderName = folderName;
    }


    /**
     * Gets the <CODE>folderName</CODE> attribute.
     *
     * @return The subfolder from which to check out files. All subfolders
     *      will be searched, as well.
     * @see #setFolderName(String folderName)
     */
    public String getFolderName() {
        return folderName;
    }


    /**
     * Sets the <CODE>username</CODE> attribute to the given value.
     *
     * @param username Your username for the specified StarTeam server.
     * @see #getUsername()
     */
    public void setUsername(String username) {
        this.username = username;
    }


    /**
     * Gets the <CODE>username</CODE> attribute.
     *
     * @return The username given by the user.
     * @see #setUsername(String username)
     */
    public String getUsername() {
        return username;
    }


    /**
     * Sets the <CODE>password</CODE> attribute to the given value.
     *
     * @param password Your password for the specified StarTeam server.
     * @see #getPassword()
     */
    public void setPassword(String password) {
        this.password = password;
    }


    /**
     * Gets the <CODE>password</CODE> attribute.
     *
     * @return The password given by the user.
     * @see #setPassword(String password)
     */
    public String getPassword() {
        return password;
    }


    /**
     * Sets the <CODE>targetFolder</CODE> attribute to the given value.
     *
     * @param targetFolder The target path on the local machine to check out to.
     * @see #getTargetFolder()
     */
    public void setTargetFolder(String targetFolder) {
        this.targetFolder = targetFolder;
    }


    /**
     * Gets the <CODE>targetFolder</CODE> attribute.
     *
     * @return The target path on the local machine to check out to.
     * @see #setTargetFolder(String targetFolder)
     */
    public String getTargetFolder() {
        return targetFolder;
    }


    /**
     * Sets the <CODE>force</CODE> attribute to the given value.
     *
     * @param force if true, it overwrites files in the target directory. By
     *      default it set to false as a safeguard. Note that if the target
     *      directory does not exist, this setting has no effect.
     * @see #getForce()
     */
    public void setForce(boolean force) {
        this.force = force;
    }


    /**
     * Gets the <CODE>force</CODE> attribute.
     *
     * @return whether to continue if the target directory exists.
     * @see #setForce(boolean)
     */
    public boolean getForce() {
        return force;
    }


    /**
     * Turns recursion on or off.
     *
     * @param recursion if it is true, the default, subfolders are searched
     *      recursively for files to check out. Otherwise, only files
     *      specified by <CODE>folderName</CODE> are scanned.
     * @see #getRecursion()
     */
    public void setRecursion(boolean recursion) {
        this.recursion = recursion;
    }


    /**
     * Gets the <CODE>recursion</CODE> attribute, which tells
     * AntStarTeamCheckOut whether to search subfolders when checking out
     * files.
     *
     * @return whether to search subfolders when checking out files.
     * @see #setRecursion(boolean)
     */
    public boolean getRecursion() {
        return recursion;
    }


    /**
     * Sets the <CODE>verbose</CODE> attribute to the given value.
     *
     * @param verbose whether to display all files as it checks them out. By
     *      default it is false, so the program only displays the total number
     *      of files unless you override this default.
     * @see #getVerbose()
     */
    public void setVerbose(boolean verbose) {
        this.verbose = verbose;
    }


    /**
     * Gets the <CODE>verbose</CODE> attribute.
     *
     * @return whether to display all files as it checks them out.
     * @see #setVerbose(boolean verbose)
     */
    public boolean getVerbose() {
        return verbose;
    }

    // Begin filter getters and setters

    /**
     * Sets the include filter. When filtering files, AntStarTeamCheckOut uses
     * an unmodified version of <CODE>DirectoryScanner</CODE>'s <CODE>match</CODE>
     * method, so here are the patterns straight from the Ant source code:
     * <BR>
     * <BR>
     * Matches a string against a pattern. The pattern contains two special
     * characters: <BR>
     * '*' which means zero or more characters, <BR>
     * '?' which means one and only one character. <BR>
     * <BR>
     * Separate multiple inlcude filters by <I>spaces</I> , not commas as Ant
     * uses. For example, if you want to check out all .java and .class\
     * files, you would put the following line in your program:
     * <CODE>setIncludes("*.java *.class");</CODE>
     * Finally, note that filters have no effect on the <B>directories</B>
     * that are scanned; you could not check out files from directories with
     * names beginning only with "build," for instance. Of course, you could
     * limit AntStarTeamCheckOut to a particular folder and its subfolders
     * with the <CODE>setFolderName(String folderName)</CODE> command. <BR>
     * <BR>
     * Treatment of overlapping inlcudes and excludes: To give a simplistic
     * example suppose that you set your include filter to "*.htm *.html" and
     * your exclude filter to "index.*". What happens to index.html?
     * AntStarTeamCheckOut will not check out index.html, as it matches an
     * exclude filter ("index.*"), even though it matches the include filter,
     * as well. <BR>
     * <BR>
     * Please also read the following sections before using filters:
     *
     * @param includes A string of filter patterns to include. Separate the
     *      patterns by spaces.
     * @see #getIncludes()
     * @see #setExcludes(String excludes)
     * @see #getExcludes()
     */
    public void setIncludes(String includes) {
        this.includes = includes;
    }


    /**
     * Gets the patterns from the include filter. Rather that duplicate the
     * details of AntStarTeanCheckOut's filtering here, refer to these links:
     *
     * @return A string of filter patterns separated by spaces.
     * @see #setIncludes(String includes)
     * @see #setExcludes(String excludes)
     * @see #getExcludes()
     */
    public String getIncludes() {
        return includes;
    }


    /**
     * Sets the exclude filter. When filtering files, AntStarTeamCheckOut uses
     * an unmodified version of <CODE>DirectoryScanner</CODE>'s <CODE>match</CODE>
     * method, so here are the patterns straight from the Ant source code:
     * <BR>
     * <BR>
     * Matches a string against a pattern. The pattern contains two special
     * characters: <BR>
     * '*' which means zero or more characters, <BR>
     * '?' which means one and only one character. <BR>
     * <BR>
     * Separate multiple exlcude filters by <I>spaces</I> , not commas as Ant
     * uses. For example, if you want to check out all files except .XML and
     * .HTML files, you would put the following line in your program:
     * <CODE>setExcludes("*.XML *.HTML");</CODE>
     * Finally, note that filters have no effect on the <B>directories</B>
     * that are scanned; you could not skip over all files in directories
     * whose names begin with "project," for instance. <BR>
     * <BR>
     * Treatment of overlapping inlcudes and excludes: To give a simplistic
     * example suppose that you set your include filter to "*.htm *.html" and
     * your exclude filter to "index.*". What happens to index.html?
     * AntStarTeamCheckOut will not check out index.html, as it matches an
     * exclude filter ("index.*"), even though it matches the include filter,
     * as well. <BR>
     * <BR>
     * Please also read the following sections before using filters:
     *
     * @param excludes A string of filter patterns to exclude. Separate the
     *      patterns by spaces.
     * @see #setIncludes(String includes)
     * @see #getIncludes()
     * @see #getExcludes()
     */
    public void setExcludes(String excludes) {
        this.excludes = excludes;
    }


    /**
     * Gets the patterns from the exclude filter. Rather that duplicate the
     * details of AntStarTeanCheckOut's filtering here, refer to these links:
     *
     * @return A string of filter patterns separated by spaces.
     * @see #setExcludes(String excludes)
     * @see #setIncludes(String includes)
     * @see #getIncludes()
     */
    public String getExcludes() {
        return excludes;
    }


    /**
     * returns whether the StarTeam default path is factored into calculated
     * target path locations (false) or whether targetFolder is an absolute
     * mapping to the root folder named by folderName
     *
     * @return returns true if absolute mapping is used, false if it is not
     *      used.
     * @see #setTargetFolderAbsolute(boolean)
     */
    public boolean getTargetFolderAbsolute() {
        return this.targetFolderAbsolute;
    }


    /**
     * sets the property that indicates whether or not the Star Team "default
     * folder" is to be used when calculation paths for items on the target
     * (false) or if targetFolder is an absolute mapping to the root folder
     * named by foldername.
     *
     * @param targetFolderAbsolute <tt>true</tt> if the absolute mapping is to
     *      be used. <tt>false</tt> (the default) if the "default folder" is
     *      to be factored in.
     * @see #getTargetFolderAbsolute()
     */
    public void setTargetFolderAbsolute(boolean targetFolderAbsolute) {
        this.targetFolderAbsolute = targetFolderAbsolute;
    }
}