Ant example source code file (AntStarTeamCheckOut.java)

This example Ant source code file (AntStarTeamCheckOut.java) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - Ant tags/keywords

buildexception, buildexception, folder, folder, item, property, property, server, string, string, stringbuffer, stringtokenizer, type, util, view

The AntStarTeamCheckOut.java source code

/*
 *  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>

 * 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>

 * 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>

 * 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 to
 * true.
 * <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 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
 *
 * @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("*").
     *
     * @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)
     * .
     *
     * @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 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 attribute.
     *
     * @return The StarTeam server to log in to.
     * @see #setServerName(String serverName)
     */
    public String getServerName() {
        return serverName;
    }


    /**
     * Sets the <CODE>serverPort 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 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 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 attribute.
     *
     * @return The StarTeam project to search.
     * @see #setProjectName(String projectName)
     */
    public String getProjectName() {
        return projectName;
    }


    /**
     * Sets the <CODE>viewName 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 attribute.
     *
     * @return The view to find the specified folder in.
     * @see #setViewName(String viewName)
     */
    public String getViewName() {
        return viewName;
    }


    /**
     * Sets the <CODE>folderName 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 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 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 attribute.
     *
     * @return The username given by the user.
     * @see #setUsername(String username)
     */
    public String getUsername() {
        return username;
    }


    /**
     * Sets the <CODE>password 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 attribute.
     *
     * @return The password given by the user.
     * @see #setPassword(String password)
     */
    public String getPassword() {
        return password;
    }


    /**
     * Sets the <CODE>targetFolder 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 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 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 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 are scanned.
     * @see #getRecursion()
     */
    public void setRecursion(boolean recursion) {
        this.recursion = recursion;
    }


    /**
     * Gets the <CODE>recursion 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 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 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's match
     * 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 , 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");
     * Finally, note that filters have no effect on the <B>directories
     * 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) command. 

     * <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's match
     * 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 , 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");
     * Finally, note that filters have no effect on the <B>directories
     * 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 if the absolute mapping is to
     *      be used. <tt>false (the default) if the "default folder" is
     *      to be factored in.
     * @see #getTargetFolderAbsolute()
     */
    public void setTargetFolderAbsolute(boolean targetFolderAbsolute) {
        this.targetFolderAbsolute = targetFolderAbsolute;
    }
}