Patch about targetfolder from Steve Cohen.

I also refactored the task a little bit to support directly primitive types such as
int or boolean and fixed a couple of mistakes about error handling in the original code.

It should be a good starting point for further refactoring.

pr: 5138, 5187
by: stevec@ignitesports.com (Steve Cohen)


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

docs/manual/OptionalTasks/starteam.html

@@ -62,9 +62,16 @@ the <a href="http://www.starbase.com">StarBase</a> web site.</p>
   </tr>
   <tr>
     <td valign="top">targetfolder</td>
-    <td valign="top">The folder to which files are checked out.</td>
+    <td valign="top">The folder to which files are checked out.  What this precisely means is determined by the <i>usesDefaultFolder</i> param.</td>
     <td align="center" valign="top">yes</td>
   </tr>  
+  <tr>
+    <td valign="top">usesDefaultFolder</td>
+    <td valign="top">Determines how <i>targetfolder</i> is interpreted, that is, whether the StarTeam "default folder" for the project is factored in.
+      If "true", the target tree will be rooted at <i>targetfolder+"default folder"</i>.  If false, the target tree will be rooted at <i>targetfolder</i>.  Defaults to "false".  
+      The behavior of older versions was as if this were "true".</td>
+    <td align="center" valign="top">no</td>
+  </tr>  
   <tr>
     <td valign="top">foldername</td>
     <td valign="top">The subfolder in the project from which to check out files.</td>
@@ -145,10 +152,41 @@ overwritten by the version in StarTeam.
   /&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;starteam servername="STARTEAM" 
+            serverport="49201"
+            projectname="AProject" 
+            viewname="AView"
+            username="auser"
+            password="secret"
+            targetfolder="C:\dev\buildtest\co"
+            usesDefaultFolder="false"
+  /&gt;
+</pre>
+<br>
+<pre>
+ &lt;starteam servername="STARTEAM" 
+            serverport="49201"
+            projectname="AProject" 
+            viewname="AView"
+            username="auser"
+            password="secret"
+            targetfolder="C:\dev\buildtest\co"
+            usesDefaultFolder="true"
+  /&gt;
+</pre>
+
+In the preceding two examples, assuming that the AProject project has a default folder of
+"AProject", the first example will check the files out to a tree rooted at C:\dev\buildtest\co 
+and the second will check them out to a tree rooted at C:\dev\buildtest\co\AProject.
+
 <hr>
 <p align="center">
 Copyright &copy; 2000,2001 Apache Software Foundation. All rights Reserved.