## 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

Nested Class Summary
`protected class` `TreeBasedTask.UnmatchedFileMap` This class implements a map of existing local files to possibly existing repository files.

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).
`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.
`static java.lang.String` `getFullRepositoryPath(com.starbase.starteam.File remotefile)` Return the full repository path name of a file.
`protected int` `getIDofLabelInUse()`
`java.lang.String` `getIncludes()` Gets the patterns from the include filter.
`protected java.lang.String` `getLabel()`
`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.
`protected com.starbase.starteam.Label` `getLabelInUse()` returns the label being used
`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.
`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 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` `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 abstract void` `logOperationDescription(com.starbase.starteam.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(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, getTypeNames, getURL, getUserName, getUserName, getViewname, getViewURL, openView, setPassword, setProjectname, setServername, setServerport, setURL, setUserName, setViewname`

Methods inherited from class org.apache.tools.ant.Task
`getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, handleErrorFlush, handleErrorOutput, handleFlush, 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
  See Also:
    `rootLocalFolder`

### 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
  See Also:
    `rootLocalFolder`

### 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()`

### logIncludes

    protected void logIncludes()

  if excludes have been specified, emit the list to the log

### 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()`

### logExcludes

    protected void logExcludes()

  if excludes have been specified, emit the list to the log

### _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

### getLabel

    protected java.lang.String getLabel()

### 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.

### 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

### 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

### getLabelInUse

    protected com.starbase.starteam.Label getLabelInUse()

  returns the label being used

  Returns:

### logLabel

    protected void logLabel()

  show the label in the log and its type.

### 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 processed 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.

### logOperationDescription

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

### 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 class `Task`
  Throws:
    `BuildException` - if any error occurs in the processing
  See Also:
    `testPreconditions()`, `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

### getIDofLabelInUse

    protected int getIDofLabelInUse()

### 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
  Throws:
    `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()`

### getFullRepositoryPath

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

Copyright © 2000-2003 Apache Software Foundation. All Rights Reserved.