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

java.lang.Object
  |
  +--org.apache.tools.ant.ProjectComponent
        |
        +--org.apache.tools.ant.Task
              |
              +--org.apache.tools.ant.taskdefs.optional.starteam.StarTeamTask
                    |
                    +--org.apache.tools.ant.taskdefs.optional.starteam.TreeBasedTask
Direct Known Subclasses:
StarTeamCheckin, StarTeamCheckout, StarTeamList

public abstract class TreeBasedTask
extends StarTeamTask

FileBasedTask.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
Author:
Steve Cohen
See Also:
StarBase Web Site

Field Summary
static java.lang.String DEFAULT_EXCLUDESETTING
          This disables the exclude filter by default.
static java.lang.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
 
Constructor Summary
TreeBasedTask()
           
 
Method Summary
protected  void _setLabel(java.lang.String label)
          protected function to allow subclasses to set the label (or not).
protected  boolean delistLocalFile(java.util.Hashtable localFiles, java.io.File thisfile)
          Removes from the collection of the local file names the supplied name of a processed file.
 void execute()
          This method does the work of opening the supplied Starteam view and calling the visit() method to perform the task.
 java.lang.String getExcludes()
          Gets the patterns from the exclude filter.
 java.lang.String getIncludes()
          Gets the patterns from the include filter.
protected  int getLabelID(com.starbase.starteam.View v)
          Helper method calls on the StarTeam API to retrieve an ID number for the specified view, corresponding to this.label.
 java.lang.String getRootLocalFolder()
          Returns the local folder specified by the user, corresponding to the starteam folder for this operation.
 java.lang.String getRootStarteamFolder()
          returns the root folder in the Starteam repository used for this operation
 boolean isForced()
          Get the value of forced.
 boolean isRecursive()
          Get the value of recursive.
protected static java.util.Hashtable listLocalFiles(java.io.File localFolder)
          Gets the collection of the local file names in the supplied directory.
protected  boolean matchPatterns(java.lang.String patterns, java.lang.String pName)
          Convenience method to see if a string match a one pattern in given set of space-separated patterns.
 void setExcludes(java.lang.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(java.lang.String includes)
          Declare files to include using standard includes patterns; optional.
 void setRecursive(boolean v)
          Flag to set to include files in subfolders in the operation; optional, default true.
 void setRootLocalFolder(java.lang.String rootLocalFolder)
          Set the local folder that will be the root of the tree to which files are checked out; optional.
 void setRootStarteamFolder(java.lang.String rootStarteamFolder)
          Set the root of the subtree in the StarTeam repository from which to work; optional.
protected  boolean shouldProcess(java.lang.String pName)
          Look if the file should be processed by the task.
protected abstract  void testPreconditions()
          Derived classes must override this method to define tests for any preconditons required by the task.
protected abstract  void visit(com.starbase.starteam.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, getPassword, getProjectname, getServer, getServername, getServerport, getURL, getUserName, getUserName, getViewname, openView, setPassword, setProjectname, setServername, setServerport, setURL, setUserName, setViewname
 
Methods inherited from class org.apache.tools.ant.Task
getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, handleErrorOutput, handleOutput, init, isInvalid, log, log, maybeConfigure, perform, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName
 
Methods inherited from class org.apache.tools.ant.ProjectComponent
getProject, setProject
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_INCLUDESETTING

public static final java.lang.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), Constant Field Values

DEFAULT_EXCLUDESETTING

public static final java.lang.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)
Constructor Detail

TreeBasedTask

public TreeBasedTask()
Method Detail

setRootStarteamFolder

public void setRootStarteamFolder(java.lang.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

getRootStarteamFolder

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

Returns:
the root folder in use

setRootLocalFolder

public void setRootLocalFolder(java.lang.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

getRootLocalFolder

public java.lang.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

setIncludes

public void setIncludes(java.lang.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()

getIncludes

public java.lang.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()

setExcludes

public void setExcludes(java.lang.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()

getExcludes

public java.lang.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()

_setLabel

protected void _setLabel(java.lang.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

isRecursive

public boolean isRecursive()
Get the value of recursive.

Returns:
value of recursive.

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.

isForced

public boolean isForced()
Get the value of forced.

Returns:
value of forced.

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.

shouldProcess

protected boolean shouldProcess(java.lang.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 checked out or not.

matchPatterns

protected boolean matchPatterns(java.lang.String patterns,
                                java.lang.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.

execute

public void execute()
             throws BuildException
This method does the work of opening the supplied Starteam view and calling the visit() method to perform the task.

Overrides:
execute in class Task
Throws:
BuildException - if any error occurs in the processing
See Also:
visit()

getLabelID

protected int getLabelID(com.starbase.starteam.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

visit

protected abstract void visit(com.starbase.starteam.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
BuildException

testPreconditions

protected abstract 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()

listLocalFiles

protected static java.util.Hashtable listLocalFiles(java.io.File localFolder)
Gets the collection of the local file names in the supplied directory. We need to check this collection against what we find in Starteam to understand what we need to do in order to synch with the repository.

Parameters:
localFolder - - the local folder to scan
Returns:
an "identity" hashtable whose keys each represent a file or directory in localFolder.

delistLocalFile

protected boolean delistLocalFile(java.util.Hashtable localFiles,
                                  java.io.File thisfile)
Removes from the collection of the local file names the supplied name of a processed file. When we are done, only files not in StarTeam will remain in localFiles.

Parameters:
localFiles - a Hashtable value
thisfile - file to remove from list.
Returns:
true if file was removed, false if it wasn't found.


Copyright 2000-2002 Apache Software Foundation. All Rights Reserved.