From 59c8791c70d7a78fbf92ea8ba01ffb57debb95b2 Mon Sep 17 00:00:00 2001 From: Stephane Bailliez Date: Mon, 14 Jan 2002 22:25:56 +0000 Subject: [PATCH] Add additional StarTeam tasks PR: 5650 Submitted by: stevec@ignitesports.com (Steve Cohen) git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@270763 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/OptionalTasks/starteam.html | 429 +++++++++++++++--- .../tools/ant/taskdefs/defaults.properties | 2 + 2 files changed, 359 insertions(+), 72 deletions(-) diff --git a/docs/manual/OptionalTasks/starteam.html b/docs/manual/OptionalTasks/starteam.html index 57a77b741..1e4cf25e9 100644 --- a/docs/manual/OptionalTasks/starteam.html +++ b/docs/manual/OptionalTasks/starteam.html @@ -6,9 +6,10 @@

StarTeam Support

@@ -21,19 +22,12 @@ the StarBase web site.

- -

STCheckout

 - -

Description

- -Checks out files from a StarTeam project. - + +

Common Parameters for All Starteam Tasks

-The includes and excludes attributes function differently from -other tasks in Ant. Inclusion/exclusion by folder is NOT supported. +The following parameters, having to do with making the connection to a StarTeam project, are common to all the following tasks except the deprecated StarTeam task.

-

Parameters

@@ -50,28 +44,47 @@ other tasks in Ant. Inclusion/exclusion by folder is NOT supported. - - + + + - - + + - - - + - - + + +
usernameURL A string of the form servername:portnum/project/view which enables user to set all of these elements in one string. yes*
Either this ...
servername The name of the StarTeam server.yes*
... or all four of these must be defined.
serverport The port number of the StarTeam server.yes*
projectnameThe name of the StarTeam project.yes*The name of the StarTeam project on which to operate.
viewnameThe name of the view in the StarTeam project.yes*The name of the view in the StarTeam project on which to operate.
+ +
+ + +

STCheckout

 + +

Description

+ +Checks out files from a StarTeam project. + +

+The includes and excludes attributes function differently from +other tasks in Ant. Inclusion/exclusion by folder is NOT supported. +

+ +

Parameters

+See also the required common StarTeam parameters.

+ + - + @@ -123,11 +135,21 @@ 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". + + + + + + + +
rootstarteamfolder The root of the subtree in the StarTeam repository from which to @@ -80,9 +93,8 @@ which enables user to set all of these elements in one string.
rootlocalfolderThe 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 rootstarteamfolder 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.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 rootstarteamfolder is used. + no
no
lockedIf true, file will be locked against changes by other +users. If false (default) has no effect. + Either or neither, but not both, may be true.
unlockedIf true, file will be unlocked so that other users may +change it. This is a way to reverse changes that have not yet been checked in. +If false (default) has no effect.
-* Either the URL attribute or all four of the servername, serverport, projectname and viewname attributes must be defined.
-

Examples

@@ -147,15 +169,15 @@ check out all files in the AView view of the AProject project to
 C:\dev\buildtest\co.  Empty folders in StarTeam will have local folders 
 created for them and any non-StarTeam files found in the tree will be deleted.
 
-Or more simply:
 
   <stcheckout URL="STARTEAM:49201/Aproject/AView" 
             username="auser"
             password="secret"
             rootlocalfolder="C:\dev\buildtest\co"
-	    force="true"
+	    forced="true"
   />
 

+And this is a simpler way of accomplishing the same thing as the previous example, using the URL attribute.
 


 
   <stcheckout URL="STARTEAM:49201/Aproject/AView" 
@@ -165,11 +187,11 @@ Or more simply:
             rootstarteamfolder="\Dev"
             excludes="*.bak *.old"
             label="v2.6.001"
-	    force="true"
+	    forced="true"
   />
 

 
-This will checkout all files from the Dev folder and below that do not
+This will check out all files from the Dev folder and below that do not
 end in .bak or .old with the label v2.6.001.  
 
 
@@ -179,7 +201,7 @@ end in .bak or .old with the label v2.6.001.
             rootlocalfolder="C:\dev\buildtest\co"
             includes="*.htm,*.html"
             excludes="index.*"
-	    force="true"
+	    forced="true"
   />
 

 
@@ -195,7 +217,7 @@ not be checked out by this command.
             rootlocalfolder="C:\dev\buildtest\co"
             includes="*.htm,*.html"
             excludes="index.*"
-	    force="true"
+	    forced="true"
 	    recursive="false"
   />
@@ -208,7 +230,7 @@ C:\dev\buildtest\co, because of the turning off of the recursive attribute. password="secret" rootstarteamfolder="src/java" rootlocalfolder="C:\dev\buildtest\co" - force="true" + forced="true" />

@@ -226,59 +248,231 @@ C:\dev\buildtest\co, because of the turning off of the recursive attribute. password="secret" rootstarteamfolder="src/java" rootlocalfolder="C:\dev\buildtest\co\src\java" - force="true" + forced="true" /> In the preceding three examples, assuming that the AProject project has a default folder of -"AProject", the first example will check the files located in starteam under src/java out to a tree rooted at C:\dev\buildtest\co, -the second to a tree rooted at C:\dev\buildtest\co\AProject\src\java and the third to a tree rooted at C:\dev\buildtest\co\src\java. +"C:\work\AProject", the first example will check out the tree of files rooted in the src/java folder of the AView view of the AProject in the StarTeam repository to a local tree rooted at C:\dev\buildtest\co, +the second to a tree rooted at C:\work\AProject\src\java (since no rootlocalfolder is specified) and the third to a tree rooted at C:\dev\buildtest\co\src\java. Note also, that since the second example does not set "forced" true, only those files which the repository considers out-of-date will be checked out. +
- -

STLabel

 + +

STCheckin

Description

-Creates a view label in StarTeam at the specified view. The label will be classified by StarTeam as a "build label". This task will fail if there already exexists in viewname a label with the same name as the label parameter. +Checks files into a StarTeam project. Optionally adds files and in the local tree that are not managed by the repository to its control. + +

+The includes and excludes attributes function differently from +other tasks in Ant. Inclusion/exclusion by folder is NOT supported. +

Parameters

+See also the required common StarTeam parameters.

- - - - + + + + - - - + + + + + + - - - - - - - + + + + + + + + - - - + + + - - - + + + - - - + + + + + +
usernameThe username of the account used to log in to the StarTeam server.yes
rootstarteamfolderThe root of the subtree in the StarTeam repository into which to + files will be checked. Defaults to the root folder of the view ('/'). no
passwordThe password of the account used to log in to the StarTeam server.yesrootlocalfolderThe 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 rootstarteamfolder is used. no
URLA string of the form "servername:portnum/project/view" -which enables user to set all of these elements in one string. yes*
servernameThe name of the StarTeam server.yes*adduncontrolledif true, any files or folders NOT in StarTeam will be +added to the repository. Defaults to "false".no
includesOnly check in files that match at least one of the patterns in this list. Patterns must be separated by commas. Patterns in excludes take precedence over patterns in includes.no
serverportThe port number of the StarTeam server.yes*excludesDo not check in files that match at least one of the patterns in this list. Patterns must be separated by commas. Patterns in excludes take precedence over patterns in includes.no
projectnameThe name of the StarTeam project.yes*recursiveIndicates if subfolders should be searched for files to check in. Defaults to "true".no
viewnameThe name of the view in the StarTeam project.yes*forcedIf true, checkins 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 checkin will be based on statuses +which do not relate to the target folder. Defaults to "false".no
unlockedIf true, file will be unlocked so that other users may +change it. If false (default) lock status will not change. + no
+ +

Examples

+ +
+  <stcheckin servername="STARTEAM" 
+            serverport="49201"
+            projectname="AProject" 
+            viewname="AView"
+            username="auser"
+            password="secret"
+            rootlocalfolder="C:\dev\buildtest\co"
+	    forced="true"
+  />
+
+ +The minimum necessary to check files into a StarTeam server. This will +check all files on the local tree rooted at C:\dev\buildtest\co +into the AView view of the AProject project in the repository. +For files and folders in the local tree but not in starteam, nothing will be done. Since the forced attribute is set, the files which are checked in will be checked in without regard to what the StarTeam repository considers their status to be. This is a reasonable choice of attributes since StarTeam's status for a file is calculated based on the local file in the StarTeam default directory, not on the directory we are actually working with. + +
+  <stcheckin URL="STARTEAM:49201/Aproject/AView" 
+            username="auser"
+            password="secret"
+            rootlocalfolder="C:\dev\buildtest\co"
+	    forced="true"
+  />
+
+And this is a simpler way of giving the same commands as the command above using the URL shortcut. +

+
+  <stcheckin URL="STARTEAM:49201/Aproject/AView" 
+            username="auser"
+            password="secret"
+            rootlocalfolder="C:\dev\buildtest\co"
+            rootstarteamfolder="\Dev"
+            excludes="*.bak *.old"
+	    forced="true"
+  />
+
+ +This will check all files in to the Dev folder and below that do not +end in .bak or .old from the tree rooted at"C:\dev\buildtest\co" . + +
+  <stcheckin URL="STARTEAM:49201/Aproject/AView"
+            username="auser"
+            password="secret"
+            rootlocalfolder="C:\dev\buildtest\co"
+            includes="*.htm,*.html"
+            excludes="index.*"
+	    forced="true"
+  />
+
+ + +This is an example of overlapping includes and excludes attributes. Because +excludes takes precedence over includes, files named index.html will +not be checked in by this command. + +
+  <stcheckin URL="STARTEAM:49201/Aproject/AView"
+            username="auser"
+            password="secret"
+            rootlocalfolder="C:\dev\buildtest\co"
+            rootstarteamfolder="src/java"
+            includes="*.htm,*.html"
+            excludes="index.*"
+	    forced="true"
+	    recursive="false"
+  />
+
+This example is like the previous one, but will only check in files from +C:\dev\buildtest\co, because of the turning off of the recursive attribute. + +
+  <stcheckin URL="STARTEAM:49201/Aproject/AView"
+            username="auser"
+            password="secret"
+            rootlocalfolder="C:\dev\buildtest\co"
+            rootstarteamfolder="src/java"
+            includes="version.txt"
+	    forced="true"
+	    recursive="false"
+  />
+
+This example is like the previous one, but will only check only in one file, C:\dev\buildtest\co\version.txt to the StarTeam folder src/java. + +
+  <stcheckin URL="STARTEAM:49201/Aproject/AView"
+            username="auser"
+            password="secret"
+            rootlocalfolder="C:\dev\buildtest\co"
+            rootstarteamfolder="src/java"
+            includes="version.txt"
+	    forced="true"
+	    recursive="false"
+	    addUncontrolled="true"
+  />
+
+This example is like the previous one, but will only check only in one file, C:\dev\buildtest\co\version.txt to the StarTeam folder src/java. Because the addUncontrolled attribute has been set, if StarTeam does not already control this file in this location, it will be added to the repository. + +
+  <stcheckin URL="STARTEAM:49201/Aproject/AView"
+            username="auser"
+            password="secret"
+            rootstarteamfolder="src/java"
+            rootlocalfolder="C:\dev\buildtest\co"
+	    forced="true"
+  />
+
+

+
+  <stcheckin URL="STARTEAM:49201/Aproject/AView"
+            username="auser"
+            password="secret"
+            rootstarteamfolder="src/java"
+  />
+
+

+
+ <stcheckin URL="STARTEAM:49201/Aproject/AView"
+            username="auser"
+            password="secret"
+            rootstarteamfolder="src/java"
+            rootlocalfolder="C:\dev\buildtest\co\src\java"
+	    forced="true"
+  />
+
+ +In the preceding three examples, assuming that the AProject project has a default folder of C:\work\buildtest\co\AProject, +the first example will check in files from a tree rooted at C:\dev\buildtest\co, +the second from a tree rooted at C:\work\buildtest\co\AProject\src\java, +and the third from a tree rooted at C:\dev\buildtest\co\src\java all to a tree rooted at src/java + +
+ + +

STLabel

 + +

Description

+ +Creates a view label in StarTeam at the specified view. The label will be classified by StarTeam as a "build label". This task will fail if there already exexists in viewname a label with the same name as the label parameter. + +

Parameters

+See also the required common StarTeam parameters.

+ + @@ -295,7 +489,6 @@ which enables user to set all of these elements in one string.
label The name to be given to the label no
-* Either the URL attribute or all four of the servername, serverport, projectname and viewname attributes must be defined.

Examples

@@ -305,21 +498,113 @@ This example shows the use of this tag. It will create a label named Version <tstamp> <format property="nowstamp" pattern="yyyyMMddHHmmss" locale="en"/> </tstamp> - <starteamlabel URL="STARTEAM:49201/Aproject/AView" - username="auser" - password="secret" - label="Version 6.2" - lastbuild="${nowstamp}" - description-"Thorough description" + <stlabel URL="STARTEAM:49201/Aproject/AView" + username="auser" + password="secret" + label="Version 6.2" + lastbuild="${nowstamp}" + description-"Thorough description" /> +
+ +

STList

 + +

Description

+ +Produces a listing of the contents of the StarTeam repository at the specified view and StarTeamFolder. The listing will contain the name of the user, if any, who has the file locked, the size of the file, its lastModifiedDate in the repository, and the name of the file. Unless the rootLocalFolder is specified, listing will also show the status of the local file in the default local directory relative to the repository. + +

Parameters

+See also the required common StarTeam parameters.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
rootstarteamfolderThe root of the subtree in the StarTeam repository to be listed. Defaults to the root folder of the view ('/'). no
rootlocalfolderThe local folder which will be the root of the tree to which files are compared. If this is not supplied, then the StarTeam "default folder" associated with rootstarteamfolder is used and a status field will appear in the listing. Otherwise, the status field will not appear. + no
includesOnly list files that match at least one of the patterns in this list. Patterns must be separated by commas. Patterns in excludes take precedence over patterns in includes.no
excludesDo not list files that match at least one of the patterns in this list. Patterns must be separated by commas. Patterns in excludes take precedence over patterns in includes.no
labelList files, dates, and statuses 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 listed.no
recursiveIndicates if subfolders should be searched for files to list. Defaults to "true".no
+

Examples

+ +
+
+  <stlist url="WASHINGTON:49201/build"
+             username="auser"
+             password="secret"
+ />
+
+ +The above command might produce the following listing: + +
+   [stlist] Folder: Build (Default folder: C:/work/build)
+   [stlist] Folder: dev (Default folder: C:/work/build/dev)
+   [stlist] Out of date  Sue Developer        1/1/02 7:25:47 PM CST     4368 build.xml
+   [stlist] Missing      George Hacker        1/1/02 7:25:49 PM CST       36 Test01.properties
+   [stlist] Current                           1/1/02 7:25:49 PM CST     4368 build2.xml
+   [stlist] Folder: test (Default folder C:/work/build/dev/test)
+   [stlist] Missing                           1/1/02 7:25:50 PM CST     4368 build2.xml
+
+ +while adding a rootlocalfolder and an excludes param ... + +
+
+  <stlist url="WASHINGTON:49201/build"
+             username="auser"
+             password="secret"
+	     rootlocalfolder="srcdir2"
+	     excludes="*.properties"
+ />
+
+ +might produce this listing. The status is missing because we are not going against the default folder. + +
+   [stlist] overriding local folder to srcdir2
+   [stlist] Folder: Build (Local folder: srcdir2)
+   [stlist] Folder: dev (Local folder: srcdir2/dev)
+   [stlist] Sue Developer        1/1/02 7:25:47 PM CST     4368 build.xml
+   [stlist]                      1/1/02 7:25:49 PM CST     4368 build2.xml
+   [stlist] Folder: test (Local folder: srcdir2/dev/test)
+   [stlist]                      1/1/02 7:25:50 PM CST     4368 build2.xml
+ 
+
+
+

Starteam

Deprecated

-

This task has been deprecated. Use the STCheckout task instead.

+

This task has been deprecated. Use the STCheckout task instead.

Description

Checks out files from a StarTeam project. diff --git a/src/main/org/apache/tools/ant/taskdefs/defaults.properties b/src/main/org/apache/tools/ant/taskdefs/defaults.properties index bab415e86..eb16bc559 100644 --- a/src/main/org/apache/tools/ant/taskdefs/defaults.properties +++ b/src/main/org/apache/tools/ant/taskdefs/defaults.properties @@ -81,7 +81,9 @@ icontract=org.apache.tools.ant.taskdefs.optional.IContract javacc=org.apache.tools.ant.taskdefs.optional.javacc.JavaCC jjtree=org.apache.tools.ant.taskdefs.optional.javacc.JJTree stcheckout=org.apache.tools.ant.taskdefs.optional.starteam.StarTeamCheckout +stcheckin=org.apache.tools.ant.taskdefs.optional.starteam.StarTeamCheckin stlabel=org.apache.tools.ant.taskdefs.optional.starteam.StarTeamLabel +stlist=org.apache.tools.ant.taskdefs.optional.starteam.StarTeamList wljspc=org.apache.tools.ant.taskdefs.optional.jsp.WLJspc jlink=org.apache.tools.ant.taskdefs.optional.jlink.JlinkTask native2ascii=org.apache.tools.ant.taskdefs.optional.Native2Ascii