- Add "label" attribute on checkout per request from Greg Frank - checks out a specific view label.

- Add "recursive" attribute as in the deprecated <starteam> task.
- Add "forced" attribute as in the deprecated <starteam> task and avoid checking StarTeam statuses when true.
- Make sure all exceptions are caught on execution and rethrown as build exceptions.
- Fixed a bug (using the "forced" attribute) which were causing files to be incorrectly not checked out when a rootLocalFolder was specified because the StarTeam file statuses were being checked in relation to the default directory.
- Fixed a bug where files were deleted immediately after being checked out when a rootLocalFolder was specified because the task erroneously thought the file was not under starteam control.
- Code layout to fix weird indent issues.

PR: 5583
Submitted by: stevec@ignitesports.com (Steve Cohen)


git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@270490 13f79535-47bb-0310-9956-ffa450edef68

docs/manual/OptionalTasks/starteam.html

@@ -48,7 +48,7 @@ other tasks in Ant. Inclusion/exclusion by folder is NOT supported.
 
   <tr>
     <td valign="top">URL</td>
-    <td valign="top">A string of the form <code>"servername:portnum/project/view</code> 
+    <td valign="top">A string of the form <code>servername:portnum/project/view</code> 
 which enables user to set all of these elements in one string. </td>
     <td align="center" valign="top">yes*</td>
   </tr>  <tr>
@@ -80,7 +80,9 @@ which enables user to set all of these elements in one string. </td>
   </tr>  
   <tr>
     <td valign="top">rootlocalfolder</td>
-    <td valign="top">The local folder which will be the root of the tree to which files are checked out.  If this is not supplied, then the StarTeam "default folder" associated with <i>rootstarteamfolder</i> is used.</td>
+    <td valign="top">The local folder which will be the root of the tree to which files are checked out.  If this is not supplied, then the StarTeam "default folder" associated with <i>rootstarteamfolder</i> is used.  
+    Setting this may be thought of as setting a different mode of operation, since when set, it makes no sense to check StarTeam's status flags for each file, and they are not checked.  
+    When not set, we use the default folder and so we do check the status flags.</td>
     <td align="center" valign="top">no</td>
   </tr>  
   
@@ -104,6 +106,24 @@ which enables user to set all of these elements in one string. </td>
     <td valign="top">Do not check out files that match at least one of the patterns in this list.  Patterns must be separated by  <i>commas</i>.  Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
     <td align="center" valign="top">no</td>
   </tr>
+  <tr>
+    <td valign="top">label</td>
+    <td valign="top">Check out files as of this label.  The label must exist in starteam or an exception will be thrown.  If not specified, the most recent version of each file will be checked out.</td>
+    <td align="center" valign="top">no</td>
+  </tr>
+  <tr>
+    <td valign="top">recursive</td>
+    <td valign="top">Indicates if subfolders should be searched for files to check out.  Defaults to "true".</td>
+    <td align="center" valign="top">no</td>
+  </tr>
+  <tr>
+    <td valign="top">forced</td>
+    <td valign="top">If true, checkouts will occur regardless of the status 
+that StarTeam is maintaining for the file.  If rootlocalfolder is set then 
+this should be set "true" as otherwise the checkout will be based on statuses 
+which do not relate to the target folder.  Defaults to "false".</td>
+    <td align="center" valign="top">no</td>
+  </tr>
 </table>
 
 * Either the URL attribute or <b>all four</b> of the servername, serverport, projectname and viewname attributes must be defined. <br/>
@@ -118,6 +138,7 @@ which enables user to set all of these elements in one string. </td>
             username="auser"
             password="secret"
             rootlocalfolder="C:\dev\buildtest\co"
+	    force="true"
   /&gt;
 </pre>
 
@@ -132,6 +153,7 @@ Or more simply:
             username="auser"
             password="secret"
             rootlocalfolder="C:\dev\buildtest\co"
+	    force="true"
   /&gt;
 </pre>
 <br></br>
@@ -142,11 +164,13 @@ Or more simply:
             rootlocalfolder="C:\dev\buildtest\co"
             rootstarteamfolder="\Dev"
             excludes="*.bak *.old"
+            label="v2.6.001"
+	    force="true"
   /&gt;
 </pre>
 
 This will checkout all files from the <i>Dev</i> folder and below that do not
-end in <i>.bak</i> or <i>.old</i>.  
+end in <i>.bak</i> or <i>.old</i> with the label <i>v2.6.001</i>.  
 
 <pre>
   &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
@@ -155,15 +179,28 @@ end in <i>.bak</i> or <i>.old</i>.
             rootlocalfolder="C:\dev\buildtest\co"
             includes="*.htm,*.html"
             excludes="index.*"
+	    force="true"
   /&gt;
 </pre>
 
-
-       
+     
 This is an example of overlapping <i>includes</i> and <i>excludes</i> attributes.  Because
 <i>excludes</i> takes precedence over <i>includes</i>, files named <code>index.html</code> will
 not be checked out by this command.
 
+<pre>
+  &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
+            username="auser"
+            password="secret"
+            rootlocalfolder="C:\dev\buildtest\co"
+            includes="*.htm,*.html"
+            excludes="index.*"
+	    force="true"
+	    recursive="false"
+  /&gt;
+</pre>
+This example is like the previous one, but will only check out files in 
+C:\dev\buildtest\co, because of the turning off of the recursive attribute.
 
 <pre>
   &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
@@ -171,6 +208,7 @@ not be checked out by this command.
             password="secret"
             rootstarteamfolder="src/java"
             rootlocalfolder="C:\dev\buildtest\co"
+	    force="true"
   /&gt;
 </pre>
 <br></br>
@@ -188,6 +226,7 @@ not be checked out by this command.
             password="secret"
             rootstarteamfolder="src/java"
             rootlocalfolder="C:\dev\buildtest\co\src\java"
+	    force="true"
   /&gt;
 </pre>
 

src/main/org/apache/tools/ant/taskdefs/optional/starteam/StarTeamCheckout.java

@@ -54,18 +54,18 @@
  */
 package org.apache.tools.ant.taskdefs.optional.starteam;
 
-import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.util.Enumeration;
-import java.util.Hashtable;
 
 import com.starbase.starteam.File;
 import com.starbase.starteam.Folder;
 import com.starbase.starteam.Item;
 import com.starbase.starteam.Status;
+import com.starbase.starteam.View;
+import com.starbase.starteam.ViewConfiguration;
 
-import org.apache.tools.ant.Project;
 import org.apache.tools.ant.BuildException;
+import org.apache.tools.ant.Project;
 
 /**
  * This class logs into StarTeam checks out any changes that have occurred since
@@ -85,11 +85,22 @@ import org.apache.tools.ant.BuildException;
  */
 public class StarTeamCheckout extends TreeBasedTask {
 
+    /**
+     * holder for the createDirs attribute
+     */
     private boolean createDirs = true;
+
+    /**
+     * holder for the deleteUncontrolled attribute.  If true,
+     * all local files not in StarTeam will be deleted.
+     */
     private boolean deleteUncontrolled = true;
+
     /**
      * Set the attribute that tells ant if we want to create all directories
      * that are in the Starteam repository regardless if they are empty.
+     *
+     * @param value  the value to set the attribute to.
      */
     public void setCreateWorkingDirs(boolean value) {
         this.createDirs = value;
@@ -97,112 +108,156 @@ public class StarTeamCheckout extends TreeBasedTask {
 
     /**
      * Sets the attribute that tells ant whether or not to remove local files
-     * that are NOT found in the Starteam repository.
+     * that are NOT found in the Starteam repository to the supplied value.
+     *
+     * @param value  the value to set the attribute to.
      */
     public void setDeleteUncontrolled(boolean value) {
         this.deleteUncontrolled = value;
     }
 
-
     /**
-     * Implements base-class abstract function to perform the checkout operation
-     * on the files in each folder of the tree.
+     * Sets the label StarTeam is to use for checkout.
      *
-     * @param starteamFolder the StarTeam folder from which files to be 
-     *                       checked out
-     * @param targetFolder the local mapping of rootStarteamFolder
+     * @param label the label to be used
      */
-    protected void visit(Folder starteamFolder, java.io.File targetFolder ) 
-	throws BuildException 
-    {
-	try {
-	    Hashtable localFiles = getLocalFiles(targetFolder);
-
-	    // If we have been told to create the working folders
-	    if (createDirs) {
-		// Create if it doesn't exist
-		if (!targetFolder.exists()) {
-		    targetFolder.mkdir();
-		}
-	    }
-	    // For all Files in this folder, we need to check 
-	    // if there have been modifications.
-
-	    Item[] files = starteamFolder.getItems("File");
-	    for (int i = 0; i < files.length; i++) {
-		File eachFile = (File) files[i];
-		String filename = eachFile.getName();
-		java.io.File localFile = new java.io.File(targetFolder, filename);
-		localFiles.remove(localFile.toString());
-		
-		int fileStatus = (eachFile.getStatus());
-
-		// We try to update the status once to give StarTeam another chance.
-		if (fileStatus == Status.MERGE || fileStatus == Status.UNKNOWN) {
-		    eachFile.updateStatus(true, true);
-		}
-
-		// If the file is current then skip it.
-		// If the file doesn't pass the include/exclude tests, skip it. 
-		if (fileStatus == Status.CURRENT || !shouldProcess(filename)) {
-		    continue;
-		}
-
-		// Check out anything else.
-		// Just a note: StarTeam has a status for NEW which implies that there 
-		// is an item  on your local machine that is not in the repository. 
-		// These are the items that show up as NOT IN VIEW in the Starteam GUI.
-		// One would think that we would want to perhaps checkin the NEW items
-		// (not in all cases! - Steve Cohen 15 Dec 2001)
-		// Unfortunately, the sdk doesn't really work, and we can't actually see
-		// anything with a status of NEW. That is why we can just check out 
-		// everything here without worrying about losing anything.
-
-		log("Checking Out: " + (localFile.toString()), Project.MSG_INFO);
-		eachFile.checkoutTo(localFile, Item.LockType.
-				    UNCHANGED, true, true, true);
-	    }
-
-	    // Now we recursively call this method on all sub folders in this folder.
-	    Folder[] subFolders = starteamFolder.getSubFolders();
-	    for (int i = 0; i < subFolders.length; i++) {
-		localFiles.remove(subFolders[i].getPath());
-		visit(subFolders[i], 
-		      new java.io.File(targetFolder, subFolders[i].getName()));
-	    }
-
-	    // Delete all folders or files that are not in Starteam.
-	    if (this.deleteUncontrolled && !localFiles.isEmpty()) {
-		delete(localFiles);
-	    }
-	} catch (IOException e) {
-	    throw new BuildException(e);
-	}
+    public void setLabel(String label) {
+        _setLabel(label);
     }
 
+
     /**
-     * Deletes everything on the local machine that is not in Starteam.
+     * Override of base-class abstract function creates an
+     * appropriately configured view for checkouts - either
+     * the current view or a view from this.label.
      *
-     * @param files 
+     * @param raw the unconfigured <code>View</code>
+     * @return the snapshot <code>View</code> appropriately configured.
      */
+    protected View createSnapshotView(View raw) {
+
+        int labelID = getLabelID(raw);
+
+        // if a label has been supplied, use it to configure the view
+        // otherwise use current view
+        if (labelID >= 0) {
+            return new View(raw, ViewConfiguration.createFromLabel(labelID));
+        } else {
+            return new View(raw, ViewConfiguration.createTip());
+        }
+    }
+
     /**
-     * Deletes everything on the local machine that is not in Starteam.
+     * Implements base-class abstract function to perform the checkout
+     * operation on the files in each folder of the tree.
      *
-     * @param files an "identity" <code>Hashtable</code> which we use only because
-     *              of ant's requirement to be JDK 1.1 compatible.  Otherwise, we 
-     *              could  use a set.   We are only interested in the keys,
-     *              not the associated values in this Hashtable.  Each of its keys 
-     *              represents the name of a local file to be deleted. 
+     * @param starteamFolder the StarTeam folder from which files to be
+     *                       checked out
+     * @param targetFolder the local mapping of rootStarteamFolder
      */
-    private void delete(Hashtable files) {
+    protected void visit(Folder starteamFolder, java.io.File targetFolder)
+            throws BuildException {
         try {
+            listLocalFiles(targetFolder);
+
+            // If we have been told to create the working folders
+            if (createDirs) {
+                // Create if it doesn't exist
+                if (!targetFolder.exists()) {
+                    targetFolder.mkdir();
+                }
+            }
+            // For all Files in this folder, we need to check
+            // if there have been modifications.
+
+            Item[] files = starteamFolder.getItems("File");
+            for (int i = 0; i < files.length; i++) {
+                File eachFile = (File) files[i];
+                String filename = eachFile.getName();
+                java.io.File localFile =
+                        new java.io.File(targetFolder, filename);
+
+                delistLocalFile(localFile);
+
+                // If the file doesn't pass the include/exclude tests, skip it.
+                if (!shouldProcess(filename)) {
+                    log("Skipping " + eachFile.toString(), Project.MSG_INFO);
+                    continue;
+                }
+
+
+                // If forced is not set then we may save ourselves some work by
+                // looking at the status flag.
+                // Otherwise, we care nothing about these statuses.
+
+                if (!isForced()) {
+                    int fileStatus = (eachFile.getStatus());
+
+                    // We try to update the status once to give StarTeam
+                    // another chance.
+                    if (fileStatus == Status.MERGE || fileStatus == Status.UNKNOWN) {
+                        eachFile.updateStatus(true, true);
+                        fileStatus = (eachFile.getStatus());
+                    }
+                    if (fileStatus == Status.CURRENT) {
+                        log("Not processing " + eachFile.toString()
+                                + " as it is current.",
+                                Project.MSG_INFO);
+                        continue;
+                    }
+                }
+
+
+                // Check out anything else.
+                // Just a note: StarTeam has a status for NEW which implies
+                // that there is an item  on your local machine that is not
+                // in the repository.  These are the items that show up as
+                // NOT IN VIEW in the Starteam GUI.
+                // One would think that we would want to perhaps checkin the
+                // NEW items (not in all cases! - Steve Cohen 15 Dec 2001)
+                // Unfortunately, the sdk doesn't really work, and we can't
+                // actually see  anything with a status of NEW. That is why
+                // we can just check out  everything here without worrying
+                // about losing anything.
+
+                log("Checking Out: " + (localFile.toString()), Project.MSG_INFO);
+                eachFile.checkoutTo(localFile, Item.LockType.UNCHANGED,
+                        true, true, true);
+            }
+
+            // Now we recursively call this method on all sub folders in this
+            // folder unless recursive attribute is off.
+            Folder[] subFolders = starteamFolder.getSubFolders();
+            for (int i = 0; i < subFolders.length; i++) {
+                java.io.File targetSubfolder =
+                        new java.io.File(targetFolder, subFolders[i].getName());
+                delistLocalFile(targetSubfolder);
+                if (isRecursive()) {
+                    visit(subFolders[i], targetSubfolder);
+                }
+            }
 
-            Enumeration e = files.keys();
+            if (this.deleteUncontrolled) {
+                deleteUncontrolledItems();
+            }
+
+        } catch (IOException e) {
+            throw new BuildException(e);
+        }
+    }
+
+
+    /**
+     * Deletes everything on the local machine that is not in the repository.
+     */
+    private void deleteUncontrolledItems() {
+        try {
+            Enumeration e = getLocalFiles().keys();
             while (e.hasMoreElements()) {
-                java.io.File file = new java.io.File(e.nextElement().toString());
+                java.io.File file =
+                        new java.io.File(e.nextElement().toString());
                 delete(file);
             }
-
         } catch (SecurityException e) {
             log("Error deleting file: " + e, Project.MSG_ERR);
         }
@@ -214,7 +269,8 @@ public class StarTeamCheckout extends TreeBasedTask {
      * @return true if the file was successfully deleted otherwise false.
      */
     private boolean delete(java.io.File file) {
-        // If the current file is a Directory, we need to delete all its children as well.
+        // If the current file is a Directory, we need to delete all
+        // of its children as well.
         if (file.isDirectory()) {
             java.io.File[] children = file.listFiles();
             for (int i = 0; i < children.length; i++) {
@@ -226,31 +282,7 @@ public class StarTeamCheckout extends TreeBasedTask {
         return file.delete();
     }
 
-    /**
-     * Gets the collection of the local file names in the current directory We
-     * need to check this collection against what we find in Starteam to
-     * understand what we need to delete in order to synch with the repos.
-     *
-     * @param folder
-     * @return
-     */
-    private static Hashtable getLocalFiles(java.io.File localFolder) {
-
-	// we can't use java 2 collections so we will use an identity Hashtable to 
-        // hold the file names.  We only care about the keys, not the values 
-	// (which will all be "").
-
-	Hashtable results = new Hashtable();
 
-        if (localFolder.exists()) {
-            String[] localFiles = localFolder.list();
-            for (int i = 0; i < localFiles.length; i++) {
-		results.put( localFolder.toString() + 
-			     java.io.File.separatorChar + localFiles[i], "");
-            }
-        }
-	return results;
-    }
 }
 
 

src/main/org/apache/tools/ant/taskdefs/optional/starteam/TreeBasedTask.java

@@ -54,44 +54,42 @@
  */
 package org.apache.tools.ant.taskdefs.optional.starteam;
 
-import org.apache.tools.ant.DirectoryScanner;
-import org.apache.tools.ant.BuildException;
-
+import java.util.Hashtable;
 import java.util.StringTokenizer;
-import java.io.IOException;
 
-import com.starbase.starteam.File;
 import com.starbase.starteam.Folder;
-import com.starbase.starteam.View;
-import com.starbase.starteam.ViewConfiguration;
-import com.starbase.util.OLEDate;
+import com.starbase.starteam.Label;
 import com.starbase.starteam.StarTeamFinder;
+import com.starbase.starteam.View;
+
+import org.apache.tools.ant.BuildException;
+import org.apache.tools.ant.DirectoryScanner;
+import org.apache.tools.ant.Project;
 
 /**
  * FileBasedTask.java
  * This abstract class is the base for any tasks that are tree-based, that
  * is, for tasks which iterate over a tree of folders in StarTeam which
- * is reflected in a tree of folder the local machine.  
+ * is reflected in a tree of folder the local machine.
  *
  * This class provides the tree-iteration functionality.  Derived classes
  * will implement their specific task functionality by the visitor pattern,
- * specifically by implementing the method 
+ * specifically by implementing the method
  * <code>visit(Folder rootStarteamFolder, java.io.File rootLocalFolder)</code>
  *
  * Created: Sat Dec 15 16:55:19 2001
  *
  * @author <a href="mailto:stevec@ignitesports.com">Steve Cohen</a>
  * @version 1.0
- * @see <A HREF="http://www.starbase.com/">StarBase Web Site</A> 
+ * @see <A HREF="http://www.starbase.com/">StarBase Web Site</A>
  */
 
 public abstract class TreeBasedTask extends StarTeamTask {
 
- 
 
     ///////////////////////////////////////////////////////////////
     // default values for attributes.
-    ///////////////////////////////////////////////////////////////    
+    ///////////////////////////////////////////////////////////////
     /**
      * This constant sets the filter to include all files. This default has
      * the same result as <CODE>setIncludes("*")</CODE>.
@@ -134,8 +132,30 @@ public abstract class TreeBasedTask extends StarTeamTask {
      */
     private String excludes = DEFAULT_EXCLUDESETTING;
 
+    /**
+     * StarTeam label on which to perform task.
+     */
+    private String label = null;
+
+    /**
+     * Set recursion to false to check out files in only the given folder
+     * and not in its subfolders.
+     */
+    private boolean recursive = true;
+
+    /**
+     * If forced set to true, files in the target directory will
+     * be processed regardless of status in the repository.
+     * Usually this should be  true if rootlocalfolder is set
+     * because status will be relative to the default folder, not
+     * to the one being processed.
+     */
+    private boolean forced = false;
+
+    private Hashtable localFiles = new Hashtable();
+
     ///////////////////////////////////////////////////////////////
-    // GET/SET methods.  
+    // GET/SET methods.
     // Setters, of course are where ant user passes in values.
     ///////////////////////////////////////////////////////////////
 
@@ -147,7 +167,7 @@ public abstract class TreeBasedTask extends StarTeamTask {
     }
 
     /**
-     * returns the root folder in the Starteam repository 
+     * returns the root folder in the Starteam repository
      * used for this operation
      */
     public String getRootStarteamFolder() {
@@ -155,16 +175,17 @@ public abstract class TreeBasedTask extends StarTeamTask {
     }
 
     /**
-     * Set the local folder corresponding to the 
+     * Set the local folder corresponding to the
      * starteam folder for this operation.
-     * If not specified, the StarTeam default will be used 
+     * If not specified, the StarTeam default will be used
      * the default is used.
      */
     public void setRootLocalFolder(String rootLocalFolder) {
         this.rootLocalFolder = rootLocalFolder;
     }
+
     /**
-     * Returns the local folder specified by the user, 
+     * Returns the local folder specified by the user,
      * corresponding to the starteam folder for this operation.
      * or null if not specified
      */
@@ -173,7 +194,7 @@ public abstract class TreeBasedTask extends StarTeamTask {
     }
 
     /**
-     * sets the pattern of files to be included.  See setExcludes() for a 
+     * sets the pattern of files to be included.  See setExcludes() for a
      * description
      * @param includes A string of filter patterns to include. Separate the
      *                 patterns by spaces.
@@ -189,7 +210,7 @@ public abstract class TreeBasedTask extends StarTeamTask {
      * 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)
@@ -225,7 +246,7 @@ public abstract class TreeBasedTask extends StarTeamTask {
      * 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)
@@ -250,18 +271,65 @@ public abstract class TreeBasedTask extends StarTeamTask {
         return excludes;
     }
 
+    /**
+     * protected function to allow subclasses to set the label (or not).
+     * sets the StarTeam label
+     *
+     * @param label name of the StarTeam label to be set
+     */
+    protected void _setLabel(String label) {
+        if (null != label) {
+            label = label.trim();
+            if (label.length() > 0) {
+                this.label = label;
+            }
+        }
+    }
+
+    /**
+     * Get the value of recursive.
+     * @return value of recursive.
+     */
+    public boolean isRecursive() {
+        return this.recursive;
+    }
+
+    /**
+     * Set the value of recursive.
+     * @param v  Value to assign to recursive.
+     */
+    public void setRecursive(boolean v) {
+        this.recursive = v;
+    }
+
+    /**
+     * Get the value of forced.
+     * @return value of forced.
+     */
+    public boolean isForced() {
+        return this.forced;
+    }
+
+    /**
+     * Set the value of forced.
+     * @param v  Value to assign to forced.
+     */
+    public void setForced(boolean v) {
+        this.forced = v;
+    }
+
     ///////////////////////////////////////////////////////////////
     // INCLUDE-EXCLUDE processing
     ///////////////////////////////////////////////////////////////
 
     /**
-     * Look if the file should be processed by the task. 
-     * Don't process it if it fits no include filters or if 
+     * Look if the file should be processed by the task.
+     * Don't process it if it fits no include filters or if
      * 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 shouldProcess(String pName){
+    protected boolean shouldProcess(String pName) {
         boolean includeIt = matchPatterns(getIncludes(), pName);
         boolean excludeIt = matchPatterns(getExcludes(), pName);
         return (includeIt && !excludeIt);
@@ -274,15 +342,13 @@ public abstract class TreeBasedTask extends StarTeamTask {
      * @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){
+    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))
-            {
+        while (exStr.hasMoreTokens()) {
+            if (DirectoryScanner.match(exStr.nextToken(), pName)) {
                 return true;
             }
         }
@@ -290,52 +356,148 @@ public abstract class TreeBasedTask extends StarTeamTask {
     }
 
     /**
-     * This method does the work of opening the supplied  Starteam view and calling 
-     * the visit method to perform the task.
+     * Derived classes must override <code>createSnapshotView</code>
+     * defining the kind of configured view appropriate to its task.
+     *
+     * @param rawview the unconfigured <code>View</code>
+     * @return the snapshot <code>View</code> appropriately configured.
+     */
+    protected abstract View createSnapshotView(View rawview);
+
+    /**
+     * This method does the work of opening the supplied  Starteam view and
+     * calling the <code>visit()</code> method to perform the task.
      *
      * @exception BuildException if any error occurs in the processing
+     * @see <code>visit()</code>
      */
-     
-     public void execute() throws BuildException {
-        // Get view as of the current time?
-        View view = StarTeamFinder.openView(getUserName() + ":" + getPassword()
-                + "@" + getURL());
-        View snapshot = new View(view, ViewConfiguration.createFromTime(
-                new OLEDate()));
-        Folder starteamrootfolder = 
-	    StarTeamFinder.findFolder(snapshot.getRootFolder(), this.rootStarteamFolder);
-
-        if ( null == starteamrootfolder) {
-            throw new BuildException("Unable to find root folderin repository.");
-        }
 
-	java.io.File localrootfolder;
+    public void execute() throws BuildException {
+        try {
+            if (null != this.rootLocalFolder && !this.forced) {
+                log("Warning: rootLocalFolder specified, but forcing off.",
+                        Project.MSG_WARN);
+            }
+            // Open the view
+            View view =
+                    StarTeamFinder.openView(getUserName() + ":"
+                    + getPassword()
+                    + "@" + getURL());
+
+            if (null == view) {
+                throw new BuildException("Cannot find view" + getURL() +
+                        " in repository()");
+            }
+
+            View snapshot = createSnapshotView(view);
+
+            // find the starteam folder specified to be the root of the
+            // operation.  Throw if it can't be found.
+            Folder starteamrootfolder =
+                    StarTeamFinder.findFolder(snapshot.getRootFolder(),
+                            this.rootStarteamFolder);
+
+            if (null == starteamrootfolder) {
+                throw new BuildException(
+                        "Unable to find root folder in repository.");
+            }
+
+            // set the local folder.
+            java.io.File localrootfolder;
+            if (null == this.rootLocalFolder) {
+                // use Star Team's default
+                localrootfolder =
+                        new java.io.File(starteamrootfolder.getPath());
+            } else {
+                // force StarTeam to use our folder
+                localrootfolder = new java.io.File(getRootLocalFolder());
+                log("overriding local folder to " + localrootfolder);
+            }
 
-	if (null == this.rootLocalFolder) {
-	    // use Star Team's default
-	    localrootfolder = new java.io.File(starteamrootfolder.getPath());
-	} else {
-	    // force StarTeam to use our folder
-	    localrootfolder = new java.io.File(getRootLocalFolder());
-	    log("overriding local folder to " + localrootfolder);
-	}
+            // Inspect everything in the root folder and then recursively
+            visit(starteamrootfolder, localrootfolder);
+        } catch (Exception e) {
+            throw new BuildException(e);
+        }
+    }
 
-        // Inspect everything in the root folder and then recursively
-        visit(starteamrootfolder, localrootfolder);
+    /**
+     * Helper method calls on the StarTeam API to retrieve an ID number
+     * for the specified view, corresponding to this.label.
+     * @param v the <code>View</code> in which to search for <code>this.label</code>
+     * @return the ID number corresponding to <code>this.label</code> or -1 if
+     *         no label was provided.
+     * @exception BuildException if <code>this.label</code> does not correspond
+     *                           to any label in the supplied view
+     */
+    protected int getLabelID(View v) throws BuildException {
+        if (null != this.label) {
+            Label[] allLabels = v.getLabels();
+            for (int i = 0; i < allLabels.length; i++) {
+                if (allLabels[i].getName().equals(this.label))
+                    return allLabels[i].getID();
+            }
+            throw new BuildException("Error: label "
+                    + this.label
+                    + " does not exist in view");
+        }
+        return -1;
     }
 
+
     /**
-     * Derived classes must override this class to define the actual processing 
-     * to performed on each folder in the tree defined for the task
+     * Derived classes must override this class to define actual processing
+     * to be performed on each folder in the tree defined for the task
      *
      * @param rootStarteamFolder the StarTeam folderto be visited
      * @param rootLocalFolder the local mapping of rootStarteamFolder
      */
-    protected abstract void visit(Folder rootStarteamFolder, java.io.File rootLocalFolder) 
-	throws BuildException;
+    protected abstract void visit(Folder rootStarteamFolder,
+                                  java.io.File rootLocalFolder)
+            throws BuildException;
+
+
+    protected Hashtable getLocalFiles() {
+        return this.localFiles;
+    }
+
+    /**
+     * Gets the collection of the local file names in the supplied directory.
+     * We need to check this collection against what we find in Starteam to
+     * understand what we need to do in order to synch with the repository.
+     *
+     * @param localFolder - the local folder to scan
+     */
+    protected void listLocalFiles(java.io.File localFolder) {
+
+        this.localFiles.clear();
+        // we can't use java 2 collections so we will use an identity
+        // Hashtable to  hold the file names.  We only care about the keys,
+        // not the values (which will all be "").
+
+        if (localFolder.exists()) {
+            String[] localFiles = localFolder.list();
+            for (int i = 0; i < localFiles.length; i++) {
+                this.localFiles.put(localFolder.toString() +
+                        java.io.File.separatorChar + localFiles[i], "");
+            }
+        }
+    }
 
+    /**
+     * Removes from the collection of the local file names
+     * the supplied name of a processed file.  When we are done, only
+     * files not in StarTeam will remain in localFiles.
+     *
+     * @param thisfile - file to remove from list.
+     * @return         - true if file was removed, false if it wasn't found.
+     */
+    protected boolean delistLocalFile(java.io.File thisfile) {
+        return null != this.localFiles.remove(thisfile.toString());
+    }
 }
 
 
 
 
+