Checks out files from a specific StarTeam server, project, view, and
folder.
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.
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.
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 force
to
true.
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
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.
formatForDisplay
protected String formatForDisplay(Property p,
Object value)
Formats a property value for display to the user.
p
- An item property to format.value
-
- A string containing the property, which is truncated to 35
characters for display.
getExcludes
public String getExcludes()
Gets the patterns from the exclude filter. Rather that duplicate the
details of AntStarTeanCheckOut's filtering here, refer to these links:
- A string of filter patterns separated by spaces.
setExcludes(String excludes)
, setIncludes(String includes)
, getIncludes()
getFolderName
public String getFolderName()
Gets the folderName
attribute.
- The subfolder from which to check out files. All subfolders
will be searched, as well.
setFolderName(String folderName)
getForce
public boolean getForce()
Gets the force
attribute.
- whether to continue if the target directory exists.
getIncludes
public String getIncludes()
Gets the patterns from the include filter. Rather that duplicate the
details of AntStarTeanCheckOut's filtering here, refer to these links:
- A string of filter patterns separated by spaces.
setIncludes(String includes)
, setExcludes(String excludes)
, getExcludes()
getPassword
public String getPassword()
Gets the password
attribute.
- The password given by the user.
setPassword(String password)
getPrimaryDescriptor
protected Property getPrimaryDescriptor(Type t)
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.
t
- An item type. At this point it will always be "file".
- The specified item's primary descriptor.
getProjectName
public String getProjectName()
Gets the projectName
attribute.
- The StarTeam project to search.
setProjectName(String projectName)
getRecursion
public boolean getRecursion()
Gets the recursion
attribute, which tells
AntStarTeamCheckOut whether to search subfolders when checking out
files.
- whether to search subfolders when checking out files.
getSecondaryDescriptor
protected Property getSecondaryDescriptor(Type t)
Get the secondary descriptor of the given item type. Returns null if
there isn't one.
t
- An item type. At this point it will always be "file".
- The specified item's secondary descriptor. There may not be one
for every file.
getServer
protected Server getServer()
Creates and logs in to a StarTeam server.
getServerName
public String getServerName()
Gets the serverName
attribute.
- The StarTeam server to log in to.
setServerName(String serverName)
getServerPort
public int getServerPort()
Gets the serverPort
attribute.
- A string containing the port on the StarTeam server to use.
getTargetFolder
public String getTargetFolder()
Gets the targetFolder
attribute.
- The target path on the local machine to check out to.
setTargetFolder(String targetFolder)
getTargetFolderAbsolute
public boolean getTargetFolderAbsolute()
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
- returns true if absolute mapping is used, false if it is not
used.
getUsername
public String getUsername()
Gets the username
attribute.
- The username given by the user.
setUsername(String username)
getVerbose
public boolean getVerbose()
Gets the verbose
attribute.
- whether to display all files as it checks them out.
setVerbose(boolean verbose)
getViewName
public String getViewName()
Gets the viewName
attribute.
- The view to find the specified folder in.
setViewName(String viewName)
matchPatterns
protected boolean matchPatterns(String patterns,
String pName)
Convenient method to see if a string match a one pattern in given set
of space-separated patterns.
patterns
- the space-separated list of patterns.pName
- the name to look for matching.
- whether the name match at least one pattern.
runFolder
protected void runFolder(Server s,
com.starbase.starteam.Project p,
View v,
Type t,
Folder f,
java.io.File tgt)
Searches for files in the given folder. This method is recursive and
thus searches all subfolders.
s
- A StarTeam server.p
- A valid project on the server.v
- A view name from the specified project.t
- An item type which is currently always "file".f
- The folder to search.tgt
- Target folder on local machine
runItem
protected void runItem(Server s,
com.starbase.starteam.Project p,
View v,
Type t,
Folder f,
Item item,
java.io.File tgt)
Check out one file if it matches the include filter but not the exclude
filter.
s
- A StarTeam server.p
- A valid project on the server.v
- A view name from the specified project.t
- An item type which is currently always "file".f
- The folder the file is localed in.item
- The file to check out.tgt
- target folder on local machine
runProject
protected void runProject(Server s,
com.starbase.starteam.Project p)
Searches for the given view in the project.
s
- A StarTeam server.p
- A valid project on the given server.
runServer
protected void runServer(Server s)
Searches for the specified project on the server.
runType
protected void runType(Server s,
com.starbase.starteam.Project p,
View v,
Type t)
Searches for folders in the given view.
s
- A StarTeam server.p
- A valid project on the server.v
- A view name from the specified project.t
- An item type which is currently always "file".
setExcludes
public void setExcludes(String excludes)
Sets the exclude filter. When filtering files, AntStarTeamCheckOut uses
an unmodified version of DirectoryScanner
's match
method, so here are the patterns straight from the Ant source code:
Matches a string against a pattern. The pattern contains two special
characters:
'*' which means zero or more characters,
'?' which means one and only one character.
Separate multiple exlcude filters by 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:
setExcludes("*.XML *.HTML");
Finally, note that filters have no effect on the directories
that are scanned; you could not skip over all files in directories
whose names begin with "project," for instance.
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.
Please also read the following sections before using filters:
excludes
- A string of filter patterns to exclude. Separate the
patterns by spaces.
setFolderName
public void setFolderName(String folderName)
Sets the 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.
folderName
- The subfolder from which to check out files.
setForce
public void setForce(boolean force)
Sets the force
attribute to the given value.
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.
setIncludes
public void setIncludes(String includes)
Sets the include filter. When filtering files, AntStarTeamCheckOut uses
an unmodified version of DirectoryScanner
's match
method, so here are the patterns straight from the Ant source code:
Matches a string against a pattern. The pattern contains two special
characters:
'*' which means zero or more characters,
'?' which means one and only one character.
Separate multiple inlcude filters by 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:
setIncludes("*.java *.class");
Finally, note that filters have no effect on the 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 setFolderName(String folderName)
command.
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.
Please also read the following sections before using filters:
includes
- A string of filter patterns to include. Separate the
patterns by spaces.
setPassword
public void setPassword(String password)
Sets the password
attribute to the given value.
password
- Your password for the specified StarTeam server.
setProjectName
public void setProjectName(String projectName)
Sets the projectName
attribute to the given value.
projectName
- The StarTeam project to search.
setRecursion
public void setRecursion(boolean recursion)
Turns recursion on or off.
recursion
- if it is true, the default, subfolders are searched
recursively for files to check out. Otherwise, only files
specified by folderName
are scanned.
setServerName
public void setServerName(String serverName)
Sets the serverName
attribute to the given value.
serverName
- The name of the server you wish to connect to.
setServerPort
public void setServerPort(int serverPort)
Sets the serverPort
attribute to the given value. The
given value must be a valid integer, but it must be a string object.
serverPort
- A string containing the port on the StarTeam server
to use.
setTargetFolder
public void setTargetFolder(String targetFolder)
Sets the targetFolder
attribute to the given value.
targetFolder
- The target path on the local machine to check out to.
setTargetFolderAbsolute
public void setTargetFolderAbsolute(boolean 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.
targetFolderAbsolute
- true if the absolute mapping is to
be used. false (the default) if the "default folder" is
to be factored in.
setUsername
public void setUsername(String username)
Sets the username
attribute to the given value.
username
- Your username for the specified StarTeam server.
setVerbose
public void setVerbose(boolean verbose)
Sets the verbose
attribute to the given value.
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.
setViewName
public void setViewName(String viewName)
Sets the viewName
attribute to the given value.
viewName
- The view to find the specified folder in.
shouldCheckout
protected boolean shouldCheckout(String pName)
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.
pName
- the item name to look for being included.
- whether the file should be checked out or not.