StarTeam performance enhancement

PR: 15730
Submitted by: Steve Cohen


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

docs/manual/OptionalTasks/starteam.html

@@ -14,11 +14,12 @@
 </ul>
 
 <p>
-These tasks make use of functions from the StarTeam API.  As a result
-they are only available to licensed users of StarTeam.  You must have
+The StarTeam revision control system was recently acquired by Borland.
+These tasks make use of functions from the StarTeam API to work with that system.  
+As a result they are only available to licensed users of StarTeam.  You must have
 <CODE>starteam-sdk.jar</CODE> in your classpath to run these tasks.
 For more information about the StarTeam API and how to license it, see
-the <a href="http://www.starbase.com">StarBase</a> web site.</p>
+the <a href="http://www.borland.com/starteam/">Borland</a> web site.</p>
 
 <hr></hr>
 
@@ -166,6 +167,14 @@ false(default) means the checked out files will be timestamped at the time
 of checkout.</td>    <td align="center" valign="top">no</td>
 
   </tr>
+  <tr>
+    <td valign="top">preloadfileinformation</td>
+    <td valign="top">The StarTeam server has the ability to preload file metadata for an
+    entire tree prior to beginning action on that tree.  Doing so can in some instances 
+    lead to substantially faster actions, particularly over large trees.  Setting this 
+    to "yes" (default) engages this functionality, setting it to "no" turns it off.</td>    
+    <td align="center" valign="top">yes</td>
+  </tr>
     
 </table>
 
@@ -348,7 +357,16 @@ that StarTeam is maintaining for the file.  If false, checkins will use this sta
     <td valign="top">If true, file will be unlocked so that other users may
 change it.  If false (default) lock status will not change.
     <td align="center" valign="top">no</td> 
-  </tr></table>
+  </tr>
+  <tr>
+    <td valign="top">preloadfileinformation</td>
+    <td valign="top">The StarTeam server has the ability to preload file metadata for an
+    entire tree prior to beginning action on that tree.  Doing so can in some instances 
+    lead to substantially faster actions, particularly over large trees.  Setting this 
+    to "yes" (default) engages this functionality, setting it to "no" turns it off.</td>    
+    <td align="center" valign="top">yes</td>
+  </tr>
+  </table>
 
 <h3>Examples</h3>
 
@@ -635,6 +653,15 @@ See also <A href="#common-params">the required common StarTeam parameters</A>.<b
     If false, they won't.  Defaults to "true".</td>
     <td align="center" valign="top">no</td>
     </tr>
+  
+  <tr>
+    <td valign="top">preloadfileinformation</td>
+    <td valign="top">The StarTeam server has the ability to preload file metadata for an
+    entire tree prior to beginning action on that tree.  Doing so can in some instances 
+    lead to substantially faster actions, particularly over large trees.  Setting this 
+    to "yes" (default) engages this functionality, setting it to "no" turns it off.</td>    
+    <td align="center" valign="top">yes</td>
+  </tr>
 
 </table>
 <h3>Examples</h3>

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

@@ -55,6 +55,7 @@ package org.apache.tools.ant.taskdefs.optional.starteam;
 
 import com.starbase.starteam.Folder;
 import com.starbase.starteam.Label;
+import com.starbase.starteam.PropertyNames;
 import com.starbase.starteam.StarTeamFinder;
 import com.starbase.starteam.View;
 import java.util.Hashtable;
@@ -64,7 +65,7 @@ import org.apache.tools.ant.DirectoryScanner;
 import org.apache.tools.ant.Project;
 
 /**
- * FileBasedTask.java
+ * TreeBasedTask.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.
@@ -76,7 +77,7 @@ import org.apache.tools.ant.Project;
  *
  * Created: Sat Dec 15 16:55:19 2001
  *
- * @author <a href="mailto:stevec@ignitesports.com">Steve Cohen</a>
+ * @author <a href="mailto:scohen@apache.org">Steve Cohen</a>
  * @version 1.0
  * @see <A HREF="http://www.starbase.com/">StarBase Web Site</A>
  */
@@ -140,6 +141,12 @@ public abstract class TreeBasedTask extends StarTeamTask {
      */
     private boolean recursive = true;
 
+    /**
+     * Set preloadFileInformation to true to load all file information from the server
+     * at once.  Increases performance significantly for projects with many files and/or folders.
+     */
+    private boolean preloadFileInformation = true;
+
     /**
      * If forced set to true, files in the target directory will
      * be processed regardless of status in the repository.
@@ -338,6 +345,25 @@ public abstract class TreeBasedTask extends StarTeamTask {
         this.recursive = v;
     }
 
+    /**
+     * Get the value of preloadFileInformation.
+     * @return value of preloadFileInformation.
+     */
+    public boolean isPreloadFileInformation() {
+        return this.preloadFileInformation;
+    }
+
+    /**
+     * Flag to set to preload file information from the server; optional,
+     * default true.
+     * Increases performance significantly for projects with many files
+     * and/or folders.
+     * @param v  Value to assign to preloadFileInformation.
+     */
+    public void setPreloadFileInformation(boolean v) {
+        this.preloadFileInformation = v;
+    }
+
     /**
      * Get the value of forced.
      * @return value of forced.
@@ -463,6 +489,19 @@ public abstract class TreeBasedTask extends StarTeamTask {
                     StarTeamFinder.findFolder(snapshot.getRootFolder(),
                             this.rootStarteamFolder);
 
+            if (this.isPreloadFileInformation()) {
+                PropertyNames pn = getServer().getPropertyNames();
+                String[] props = new String[] {pn.FILE_NAME, pn.FILE_PATH,
+                                               pn.FILE_STATUS, pn.MODIFIED_TIME,
+                                               pn.FILE_FILE_TIME_AT_CHECKIN,
+                                               pn.MODIFIED_USER_ID, pn.FILE_SIZE};
+
+                int depth = this.isRecursive() ? -1 : 0;
+                starteamrootfolder.populateNow(getServer().getTypeNames().FILE,
+                                                props, depth);
+            }
+
+
         } 
         catch (BuildException e) {
             throw e;
@@ -665,7 +704,7 @@ public abstract class TreeBasedTask extends StarTeamTask {
      * whatever items left in the UnmatchedFileMap are uncontrolled items
      * and can be processed as appropriate to the task.  In the case of
      * Checkouts, they can be optionally deleted from the local tree.  In the 
-     * case of Checkins they can optionally be added to the resository.
+     * case of Checkins they can optionally be added to the repository.
      */
     protected abstract class UnmatchedFileMap extends Hashtable {