org.apache.tools.ant.taskdefs.optional.scm

Class AntStarTeamCheckOut

public class AntStarTeamCheckOut extends Task

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.

Version: 1.0

See Also: StarBase Web Site

UNKNOWN: name="starteam" category="scm" ignore="true"

Field Summary
static StringDEFAULT_EXCLUDESETTING
This disables the exclude filter by default.
static StringDEFAULT_FOLDERSETTING
The default folder to search; the root folder.
static StringDEFAULT_INCLUDESETTING
This constant sets the filter to include all files.
Method Summary
protected voidcheckParameters()
voidexecute()
Do the execution.
protected StringformatForDisplay(Property p, Object value)
Formats a property value for display to the user.
StringgetExcludes()
Gets the patterns from the exclude filter.
StringgetFolderName()
Gets the folderName attribute.
booleangetForce()
Gets the force attribute.
StringgetIncludes()
Gets the patterns from the include filter.
StringgetPassword()
Gets the password attribute.
protected PropertygetPrimaryDescriptor(Type t)
Get the primary descriptor of the given item type.
StringgetProjectName()
Gets the projectName attribute.
booleangetRecursion()
Gets the recursion attribute, which tells AntStarTeamCheckOut whether to search subfolders when checking out files.
protected PropertygetSecondaryDescriptor(Type t)
Get the secondary descriptor of the given item type.
protected ServergetServer()
Creates and logs in to a StarTeam server.
StringgetServerName()
Gets the serverName attribute.
intgetServerPort()
Gets the serverPort attribute.
StringgetTargetFolder()
Gets the targetFolder attribute.
booleangetTargetFolderAbsolute()
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
StringgetUsername()
Gets the username attribute.
booleangetVerbose()
Gets the verbose attribute.
StringgetViewName()
Gets the viewName attribute.
protected booleanmatchPatterns(String patterns, String pName)
Convenient method to see if a string match a one pattern in given set of space-separated patterns.
protected voidrunFolder(Server s, Project p, View v, Type t, Folder f, File tgt)
Searches for files in the given folder.
protected voidrunItem(Server s, Project p, View v, Type t, Folder f, Item item, File tgt)
Check out one file if it matches the include filter but not the exclude filter.
protected voidrunProject(Server s, Project p)
Searches for the given view in the project.
protected voidrunServer(Server s)
Searches for the specified project on the server.
protected voidrunType(Server s, Project p, View v, Type t)
Searches for folders in the given view.
voidsetExcludes(String excludes)
Sets the exclude filter.
voidsetFolderName(String folderName)
Sets the folderName attribute to the given value.
voidsetForce(boolean force)
Sets the force attribute to the given value.
voidsetIncludes(String includes)
Sets the include filter.
voidsetPassword(String password)
Sets the password attribute to the given value.
voidsetProjectName(String projectName)
Sets the projectName attribute to the given value.
voidsetRecursion(boolean recursion)
Turns recursion on or off.
voidsetServerName(String serverName)
Sets the serverName attribute to the given value.
voidsetServerPort(int serverPort)
Sets the serverPort attribute to the given value.
voidsetTargetFolder(String targetFolder)
Sets the targetFolder attribute to the given value.
voidsetTargetFolderAbsolute(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.
voidsetUsername(String username)
Sets the username attribute to the given value.
voidsetVerbose(boolean verbose)
Sets the verbose attribute to the given value.
voidsetViewName(String viewName)
Sets the viewName attribute to the given value.
protected booleanshouldCheckout(String pName)
Look if the file should be checked out.

Field Detail

DEFAULT_EXCLUDESETTING

public static final String DEFAULT_EXCLUDESETTING
This disables the exclude filter by default. In other words, no files are excluded. This setting is equivalent to setExcludes(null) .

See Also: getExcludes AntStarTeamCheckOut

DEFAULT_FOLDERSETTING

public static final String DEFAULT_FOLDERSETTING
The default folder to search; the root folder. Since AntStarTeamCheckOut searches subfolders, by default it processes an entire view.

See Also: getFolderName AntStarTeamCheckOut

DEFAULT_INCLUDESETTING

public static final String DEFAULT_INCLUDESETTING
This constant sets the filter to include all files. This default has the same result as setIncludes("*").

See Also: getIncludes AntStarTeamCheckOut

Method Detail

checkParameters

protected void checkParameters()

execute

public void execute()
Do the execution.

Throws: BuildException

formatForDisplay

protected String formatForDisplay(Property p, Object value)
Formats a property value for display to the user.

Parameters: p An item property to format. value

Returns: 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:

Returns: A string of filter patterns separated by spaces.

See Also: AntStarTeamCheckOut AntStarTeamCheckOut getIncludes

getFolderName

public String getFolderName()
Gets the folderName attribute.

Returns: The subfolder from which to check out files. All subfolders will be searched, as well.

See Also: AntStarTeamCheckOut

getForce

public boolean getForce()
Gets the force attribute.

Returns: whether to continue if the target directory exists.

See Also: AntStarTeamCheckOut

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:

Returns: A string of filter patterns separated by spaces.

See Also: AntStarTeamCheckOut AntStarTeamCheckOut getExcludes

getPassword

public String getPassword()
Gets the password attribute.

Returns: The password given by the user.

See Also: AntStarTeamCheckOut

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.

Parameters: t An item type. At this point it will always be "file".

Returns: The specified item's primary descriptor.

getProjectName

public String getProjectName()
Gets the projectName attribute.

Returns: The StarTeam project to search.

See Also: AntStarTeamCheckOut

getRecursion

public boolean getRecursion()
Gets the recursion attribute, which tells AntStarTeamCheckOut whether to search subfolders when checking out files.

Returns: whether to search subfolders when checking out files.

See Also: AntStarTeamCheckOut

getSecondaryDescriptor

protected Property getSecondaryDescriptor(Type t)
Get the secondary descriptor of the given item type. Returns null if there isn't one.

Parameters: t An item type. At this point it will always be "file".

Returns: 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.

Returns: A StarTeam server.

getServerName

public String getServerName()
Gets the serverName attribute.

Returns: The StarTeam server to log in to.

See Also: AntStarTeamCheckOut

getServerPort

public int getServerPort()
Gets the serverPort attribute.

Returns: A string containing the port on the StarTeam server to use.

See Also: AntStarTeamCheckOut

getTargetFolder

public String getTargetFolder()
Gets the targetFolder attribute.

Returns: The target path on the local machine to check out to.

See Also: AntStarTeamCheckOut

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: returns true if absolute mapping is used, false if it is not used.

See Also: AntStarTeamCheckOut

getUsername

public String getUsername()
Gets the username attribute.

Returns: The username given by the user.

See Also: AntStarTeamCheckOut

getVerbose

public boolean getVerbose()
Gets the verbose attribute.

Returns: whether to display all files as it checks them out.

See Also: AntStarTeamCheckOut

getViewName

public String getViewName()
Gets the viewName attribute.

Returns: The view to find the specified folder in.

See Also: AntStarTeamCheckOut

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.

Parameters: patterns the space-separated list of patterns. pName the name to look for matching.

Returns: whether the name match at least one pattern.

runFolder

protected void runFolder(Server s, Project p, View v, Type t, Folder f, File tgt)
Searches for files in the given folder. This method is recursive and thus searches all subfolders.

Parameters: 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, Project p, View v, Type t, Folder f, Item item, File tgt)
Check out one file if it matches the include filter but not the exclude filter.

Parameters: 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, Project p)
Searches for the given view in the project.

Parameters: 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.

Parameters: s A StarTeam server.

runType

protected void runType(Server s, Project p, View v, Type t)
Searches for folders in the given view.

Parameters: 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:

Parameters: excludes A string of filter patterns to exclude. Separate the patterns by spaces.

See Also: AntStarTeamCheckOut getIncludes getExcludes

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.

Parameters: folderName The subfolder from which to check out files.

See Also: getFolderName

setForce

public void setForce(boolean force)
Sets the force attribute to the given value.

Parameters: 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.

See Also: getForce

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:

Parameters: includes A string of filter patterns to include. Separate the patterns by spaces.

See Also: getIncludes AntStarTeamCheckOut getExcludes

setPassword

public void setPassword(String password)
Sets the password attribute to the given value.

Parameters: password Your password for the specified StarTeam server.

See Also: getPassword

setProjectName

public void setProjectName(String projectName)
Sets the projectName attribute to the given value.

Parameters: projectName The StarTeam project to search.

See Also: getProjectName

setRecursion

public void setRecursion(boolean recursion)
Turns recursion on or off.

Parameters: recursion if it is true, the default, subfolders are searched recursively for files to check out. Otherwise, only files specified by folderName are scanned.

See Also: getRecursion

setServerName

public void setServerName(String serverName)
Sets the serverName attribute to the given value.

Parameters: serverName The name of the server you wish to connect to.

See Also: getServerName

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.

Parameters: serverPort A string containing the port on the StarTeam server to use.

See Also: getServerPort

setTargetFolder

public void setTargetFolder(String targetFolder)
Sets the targetFolder attribute to the given value.

Parameters: targetFolder The target path on the local machine to check out to.

See Also: getTargetFolder

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.

Parameters: targetFolderAbsolute true if the absolute mapping is to be used. false (the default) if the "default folder" is to be factored in.

See Also: getTargetFolderAbsolute

setUsername

public void setUsername(String username)
Sets the username attribute to the given value.

Parameters: username Your username for the specified StarTeam server.

See Also: getUsername

setVerbose

public void setVerbose(boolean verbose)
Sets the verbose attribute to the given value.

Parameters: 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.

See Also: getVerbose

setViewName

public void setViewName(String viewName)
Sets the viewName attribute to the given value.

Parameters: viewName The view to find the specified folder in.

See Also: getViewName

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.

Parameters: pName the item name to look for being included.

Returns: whether the file should be checked out or not.

Copyright