org.apache.tools.ant.taskdefs.optional.starteam

Class TreeBasedTask

Known Direct Subclasses:
StarTeamCheckin, StarTeamCheckout, StarTeamList

public abstract class TreeBasedTask
extends StarTeamTask

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. This class provides the tree-iteration functionality. Derived classes will implement their specific task functionality by the visitor pattern, specifically by implementing the method visit(Folder rootStarteamFolder, java.io.File rootLocalFolder) Created: Sat Dec 15 16:55:19 2001

Version:
1.0

See Also:
StarBase Web Site

Nested Class Summary

protected abstract class
TreeBasedTask.UnmatchedFileMap
This class implements a map of existing local files to possibly existing repository files.

Field Summary

static String
DEFAULT_EXCLUDESETTING
This disables the exclude filter by default.
static String
DEFAULT_INCLUDESETTING
This constant sets the filter to include all files.

Fields inherited from class org.apache.tools.ant.Task

description, location, target, taskName, taskType, wrapper

Fields inherited from class org.apache.tools.ant.ProjectComponent

project

Method Summary

protected void
_setAsOfDate(String asOfDate)
non-public method callable only by derived classes that implement setAsOfDate (so that derived tasks that do not accept this parameter will fail if user attempts to use it.
protected void
_setAsOfDateFormat(String asOfDateFormat)
non-public method callable only by derived classes that implement setAsOfDateFormat (so that derived tasks that do not accept this parameter will fail if user attempts to use it.
protected void
_setLabel(String label)
protected function to allow subclasses to set the label (or not).
void
execute()
This method does the work of opening the supplied Starteam view and calling the visit() method to perform the task.
protected String
getAsOfDate()
return the asOfDate entered by the user for internal use by derived classes.
String
getExcludes()
Gets the patterns from the exclude filter.
static String
getFullRepositoryPath(com.starbase.starteam.File remotefile)
Return the full repository path name of a file.
protected int
getIDofLabelInUse()
String
getIncludes()
Gets the patterns from the include filter.
protected String
getLabel()
return the label passed to the task by the user as a string
protected int
getLabelID(View v)
Helper method calls on the StarTeam API to retrieve an ID number for the specified view, corresponding to this.label.
protected Label
getLabelInUse()
returns the label being used
String
getRootLocalFolder()
Returns the local folder specified by the user, corresponding to the starteam folder for this operation or null if not specified.
String
getRootStarteamFolder()
returns the root folder in the Starteam repository used for this operation
protected View
getViewConfiguredByDate(View raw)
If an asofDate parameter has been supplied by the user return a StarTeam view based on the configuration of the StarTeam view specified the user as of the date specified in the parameter.
boolean
isForced()
Get the value of forced.
boolean
isPreloadFileInformation()
Get the value of preloadFileInformation.
boolean
isRecursive()
Get the value of recursive.
protected boolean
isUsingRevisionLabel()
returns true if a label has been specified and it is a revision label.
protected boolean
isUsingViewLabel()
returns true if a label has been specified and it is a view label.
protected void
logAsOfDate()
show the asofDate in the log
protected void
logExcludes()
if excludes have been specified, emit the list to the log
protected void
logIncludes()
if excludes have been specified, emit the list to the log
protected void
logLabel()
show the label in the log and its type.
protected void
logOperationDescription(Folder starteamrootFolder, java.io.File targetrootFolder)
extenders should emit to the log an entry describing the parameters that will be used by this operation.
protected boolean
matchPatterns(String patterns, String pName)
Convenience method to see if a string match a one pattern in given set of space-separated patterns.
void
setExcludes(String excludes)
Declare files to exclude using standard excludes patterns; optional.
void
setForced(boolean v)
Flag to force actions regardless of the status that StarTeam is maintaining for the file; optional, default false.
void
setIncludes(String includes)
Declare files to include using standard includes patterns; optional.
void
setPreloadFileInformation(boolean v)
Flag to set to preload file information from the server; optional, default true.
void
setRecursive(boolean v)
Flag to set to include files in subfolders in the operation; optional, default true.
void
setRootLocalFolder(String rootLocalFolder)
Set the local folder that will be the root of the tree to which files are checked out; optional.
void
setRootStarteamFolder(String rootStarteamFolder)
Set the root of the subtree in the StarTeam repository from which to work; optional.
protected boolean
shouldProcess(String pName)
Look if the file should be processed by the task.
protected void
testPreconditions()
Derived classes must override this method to define tests for any preconditons required by the task.
protected void
visit(Folder rootStarteamFolder, java.io.File rootLocalFolder)
Derived classes must override this class to define actual processing to be performed on each folder in the tree defined for the task

Methods inherited from class org.apache.tools.ant.taskdefs.optional.starteam.StarTeamTask

createSnapshotView, disconnectFromServer, getPassword, getProjectname, getServer, getServername, getServerport, getTypeNames, getURL, getUserName, getUserName, getViewURL, getViewname, openView, setPassword, setProjectname, setServername, setServerport, setURL, setUserName, setViewname

Methods inherited from class org.apache.tools.ant.Task

execute, getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, maybeConfigure, perform, reconfigure, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType

Methods inherited from class org.apache.tools.ant.ProjectComponent

getProject, log, log, setProject

Field Details

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(), setExcludes(String excludes)


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(), setIncludes(String includes)

Method Details

_setAsOfDate

protected void _setAsOfDate(String asOfDate)
non-public method callable only by derived classes that implement setAsOfDate (so that derived tasks that do not accept this parameter will fail if user attempts to use it.

Parameters:
asOfDate - asOfDate entered by user.

Since:
Ant 1.6


_setAsOfDateFormat

protected void _setAsOfDateFormat(String asOfDateFormat)
non-public method callable only by derived classes that implement setAsOfDateFormat (so that derived tasks that do not accept this parameter will fail if user attempts to use it.

Parameters:
asOfDateFormat - asOfDate format entered by user.

Since:
Ant 1.6


_setLabel

protected void _setLabel(String label)
protected function to allow subclasses to set the label (or not). sets the StarTeam label

Parameters:
label - name of the StarTeam label to be set


execute

public final void execute()
            throws BuildException
This method does the work of opening the supplied Starteam view and calling the visit() method to perform the task. Derived classes can customize the called methods testPreconditions() and visit().
Overrides:
execute in interface Task

Throws:
BuildException - if any error occurs in the processing

See Also:
testPreconditions(), visit()


getAsOfDate

protected String getAsOfDate()
return the asOfDate entered by the user for internal use by derived classes.

Returns:
the asOfDate entered by the user

Since:
Ant 1.6


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:
setExcludes(String excludes), setIncludes(String includes), getIncludes()


getFullRepositoryPath

public static String getFullRepositoryPath(com.starbase.starteam.File remotefile)
Return the full repository path name of a file. Surprisingly there's no method in com.starbase.starteam.File to provide this.

Parameters:
remotefile - the Star Team file whose path is to be returned

Returns:
the full repository path name of a file.


getIDofLabelInUse

protected int getIDofLabelInUse()


getIncludes

public String getIncludes()
Gets the patterns from the include filter. Rather that duplicate the details of AntStarTeamCheckOut's filtering here, refer to these links:

Returns:
A string of filter patterns separated by spaces.

See Also:
setIncludes(String includes), setExcludes(String excludes), getExcludes()


getLabel

protected String getLabel()
return the label passed to the task by the user as a string

Returns:
the label passed to the task by the user as a string


getLabelID

protected int getLabelID(View v)
            throws BuildException
Helper method calls on the StarTeam API to retrieve an ID number for the specified view, corresponding to this.label.

Parameters:
v - the View in which to search for this.label

Returns:
the ID number corresponding to this.label or -1 if no label was provided.

Throws:
BuildException - if this.label does not correspond to any label in the supplied view


getLabelInUse

protected Label getLabelInUse()
returns the label being used

Returns:
the label being used


getRootLocalFolder

public String getRootLocalFolder()
Returns the local folder specified by the user, corresponding to the starteam folder for this operation or null if not specified.

Returns:
the local folder that mirrors this.rootStarteamFolder

See Also:
rootLocalFolder


getRootStarteamFolder

public String getRootStarteamFolder()
returns the root folder in the Starteam repository used for this operation

Returns:
the root folder in use


getViewConfiguredByDate

protected View getViewConfiguredByDate(View raw)
            throws BuildException
If an asofDate parameter has been supplied by the user return a StarTeam view based on the configuration of the StarTeam view specified the user as of the date specified in the parameter. If no asofDate has been specified, return null. This method is meant to be called from within implementations of the createSnapshotView abstract method.

Parameters:
raw - the raw view to be configured as of the supplied date

Returns:
the view as configured.

Throws:
BuildException - thrown if the date is not parsable by the default or supplied format patterns.

Since:
Ant 1.6


isForced

public boolean isForced()
Get the value of forced.

Returns:
value of forced.


isPreloadFileInformation

public boolean isPreloadFileInformation()
Get the value of preloadFileInformation.

Returns:
value of preloadFileInformation.


isRecursive

public boolean isRecursive()
Get the value of recursive.

Returns:
value of recursive.


isUsingRevisionLabel

protected boolean isUsingRevisionLabel()
returns true if a label has been specified and it is a revision label.

Returns:
true if a label has been specified and it is a revision label


isUsingViewLabel

protected boolean isUsingViewLabel()
returns true if a label has been specified and it is a view label.

Returns:
true if a label has been specified and it is a view label


logAsOfDate

protected void logAsOfDate()
show the asofDate in the log

Since:
Ant 1.6


logExcludes

protected void logExcludes()
if excludes have been specified, emit the list to the log


logIncludes

protected void logIncludes()
if excludes have been specified, emit the list to the log


logLabel

protected void logLabel()
show the label in the log and its type.


logOperationDescription

protected void logOperationDescription(Folder starteamrootFolder,
                                       java.io.File targetrootFolder)
extenders should emit to the log an entry describing the parameters that will be used by this operation.

Parameters:
starteamrootFolder - root folder in StarTeam for the operation
targetrootFolder - root local folder for the operation (whether specified by the user or not.


matchPatterns

protected boolean matchPatterns(String patterns,
                                String pName)
Convenience 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.


setExcludes

public void setExcludes(String excludes)
Declare files to exclude using standard excludes patterns; optional. 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.

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:
setIncludes(String includes), getIncludes(), getExcludes()


setForced

public void setForced(boolean v)
Flag to force actions regardless of the status that StarTeam is maintaining for the file; optional, default false. 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.

Parameters:
v - Value to assign to forced.


setIncludes

public void setIncludes(String includes)
Declare files to include using standard includes patterns; optional.

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

See Also:
getIncludes(), setExcludes(String excludes), getExcludes()


setPreloadFileInformation

public void setPreloadFileInformation(boolean v)
Flag to set to preload file information from the server; optional, default true. Increases performance significantly for projects with many files and/or folders.

Parameters:
v - Value to assign to preloadFileInformation.


setRecursive

public void setRecursive(boolean v)
Flag to set to include files in subfolders in the operation; optional, default true.

Parameters:
v - Value to assign to recursive.


setRootLocalFolder

public void setRootLocalFolder(String rootLocalFolder)
Set the local folder that will be the root of the tree to which files are checked out; optional. If this is not supplied, then the StarTeam "default folder" associated with rootstarteamfolder is used.

Parameters:
rootLocalFolder - the local folder that will mirror this.rootStarteamFolder

See Also:
rootLocalFolder


setRootStarteamFolder

public void setRootStarteamFolder(String rootStarteamFolder)
Set the root of the subtree in the StarTeam repository from which to work; optional. Defaults to the root folder of the view ('/').

Parameters:
rootStarteamFolder - the root folder


shouldProcess

protected boolean shouldProcess(String pName)
Look if the file should be processed by the task. Don't process it if it fits no include filters or if it fits an exclude filter.

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

Returns:
whether the file should be processed or not.


testPreconditions

protected void testPreconditions()
            throws BuildException
Derived classes must override this method to define tests for any preconditons required by the task. This method is called at the beginning of the execute() method.

Throws:
BuildException - throw if any fatal error exists in the parameters supplied. If there is a non-fatal condition, just writing to the log may be appropriate.

See Also:
execute()


visit

protected void visit(Folder rootStarteamFolder,
                     java.io.File rootLocalFolder)
            throws BuildException
Derived classes must override this class to define actual processing to be performed on each folder in the tree defined for the task

Parameters:
rootStarteamFolder - the StarTeam folderto be visited
rootLocalFolder - the local mapping of rootStarteamFolder

Throws:
BuildException -


Copyright B) 2000-2005 Apache Software Foundation. All Rights Reserved.