Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.tools.ant.taskdefs.optional.scm
Class AntStarTeamCheckOut

    java.lang.Object
      |
      +--org.apache.tools.ant.Task
            |
            +--org.apache.tools.ant.taskdefs.optional.scm.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
Author:
  Chris Povirk, JC Mann, Jeff Gettle
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_FOLDERSETTING` The default folder to search; the root folder.
`static java.lang.String` | `DEFAULT_FORCESETTING` By default, `force` is set to "false" through this field.
`static java.lang.String` | `DEFAULT_INCLUDESETTING` This constant sets the filter to include all files.
`static java.lang.String` | `DEFAULT_RECURSIONSETTING` `DEFAULT_RECURSIONSETTING` contains the normal setting -- true -- for recursion.
`static java.lang.String` | `DEFAULT_VERBOSESETTING` This field is used in setting `verbose` to "false", the default.

Fields inherited from class org.apache.tools.ant.Task
`description, location, project, target, taskName, taskType, wrapper`

Constructor Summary
`AntStarTeamCheckOut()`

Method Summary
`void` | `execute()` Do the execution.
`protected java.lang.String` | `formatForDisplay(org.apache.tools.ant.taskdefs.optional.scm.Property p, java.lang.Object value)` Formats a property value for display to the user.
`java.lang.String` | `getExcludes()` Gets the patterns from the exclude filter.
`java.lang.String` | `getFolderName()` Gets the `folderName` attribute.
`java.lang.String` | `getForce()` Gets the `force` attribute.
`boolean` | `getForceAsBoolean()` Gets the `force` attribute as a boolean value.
`java.lang.String` | `getIncludes()` Gets the patterns from the include filter.
`java.lang.String` | `getPassword()` Gets the `password` attribute.
`protected org.apache.tools.ant.taskdefs.optional.scm.Property` | `getPrimaryDescriptor(org.apache.tools.ant.taskdefs.optional.scm.Type t)` Get the primary descriptor of the given item type.
`java.lang.String` | `getProjectName()` Gets the `projectName` attribute.
`java.lang.String` | `getRecursion()` Gets the `recursion` attribute, which tells AntStarTeamCheckOut whether to search subfolders when checking out files.
`boolean` | `getRecursionAsBoolean()` Gets the `recursion` attribute as a boolean value.
`protected org.apache.tools.ant.taskdefs.optional.scm.Property` | `getSecondaryDescriptor(org.apache.tools.ant.taskdefs.optional.scm.Type t)` Get the secondary descriptor of the given item type.
`protected org.apache.tools.ant.taskdefs.optional.scm.Server` | `getServer()` Creates and logs in to a StarTeam server.
`java.lang.String` | `getServerName()` Gets the `serverName` attribute.
`java.lang.String` | `getServerPort()` Gets the `serverPort` attribute.
`int` | `getServerPortAsInt()` Gets the `serverPort` attribute as an integer.
`java.lang.String` | `getTargetFolder()` Gets the `targetFolder` attribute.
`java.lang.String` | `getUsername()` Gets the `username` attribute.
`java.lang.String` | `getVerbose()` Gets the `verbose` attribute.
`boolean` | `getVerboseAsBoolean()` Gets the `verbose` attribute as a boolean value.
`java.lang.String` | `getViewName()` Gets the `viewName` attribute.
`protected void` | `runFolder(org.apache.tools.ant.taskdefs.optional.scm.Server s, com.starbase.starteam.Project p, org.apache.tools.ant.taskdefs.optional.scm.View v, org.apache.tools.ant.taskdefs.optional.scm.Type t, org.apache.tools.ant.taskdefs.optional.scm.Folder f)` Searches for files in the given folder.
`protected void` | `runItem(org.apache.tools.ant.taskdefs.optional.scm.Server s, com.starbase.starteam.Project p, org.apache.tools.ant.taskdefs.optional.scm.View v, org.apache.tools.ant.taskdefs.optional.scm.Type t, org.apache.tools.ant.taskdefs.optional.scm.Folder f, org.apache.tools.ant.taskdefs.optional.scm.Item item)` Check out one file if it matches the include filter but not the exclude filter.
`protected void` | `runProject(org.apache.tools.ant.taskdefs.optional.scm.Server s, com.starbase.starteam.Project p)` Searches for the given view in the project.
`protected void` | `runServer(org.apache.tools.ant.taskdefs.optional.scm.Server s)` Searches for the specified project on the server.
`protected void` | `runType(org.apache.tools.ant.taskdefs.optional.scm.Server s, com.starbase.starteam.Project p, org.apache.tools.ant.taskdefs.optional.scm.View v, org.apache.tools.ant.taskdefs.optional.scm.Type t)` Searches for folders in the given view.
`void` | `setExcludes(java.lang.String excludes)` Sets the exclude filter.
`void` | `setFolderName(java.lang.String folderName)` Sets the `folderName` attribute to the given value.
`void` | `setForce(java.lang.String force)` Sets the `force` attribute to the given value.
`void` | `setIncludes(java.lang.String includes)` Sets the include filter.
`void` | `setPassword(java.lang.String password)` Sets the `password` attribute to the given value.
`void` | `setProjectName(java.lang.String projectName)` Sets the `projectName` attribute to the given value.
`void` | `setRecursion(java.lang.String recursion)` Turns recursion on or off.
`void` | `setServerName(java.lang.String serverName)` Sets the `serverName` attribute to the given value.
`void` | `setServerPort(java.lang.String serverPort)` Sets the `serverPort` attribute to the given value.
`void` | `setTargetFolder(java.lang.String targetFolder)` Sets the `targetFolder` attribute to the given value.
`void` | `setUsername(java.lang.String username)` Sets the `username` attribute to the given value.
`void` | `setVerbose(java.lang.String verbose)` Sets the `verbose` attribute to the given value.
`void` | `setViewName(java.lang.String viewName)` Sets the `viewName` attribute to the given value.

Methods inherited from class org.apache.tools.ant.Task
`getDescription, getLocation, getOwningTarget, getProject, getRuntimeConfigurableWrapper, getTaskName, init, log, log, maybeConfigure, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### DEFAULT_FORCESETTING

    public static final java.lang.String DEFAULT_FORCESETTING

  By default, `force` is set to "false" through this field. If you set `force` to "true," AntStarTeamCheckOut will overwrite files in the target directory. If the target directory does not exist, the `force` setting does nothing. Note that `DEFAULT_FORCESETTING` and `force` are strings, not boolean values. See the links below for more information.
  See Also:
    `getForce()`, `getForceAsBoolean()`, `setForce(String force)`

### DEFAULT_VERBOSESETTING

    public static final java.lang.String DEFAULT_VERBOSESETTING

  This field is used in setting `verbose` to "false", the default. If `verbose` is true, AntStarTeamCheckOut will display file and directory names as it checks files out. The default setting displays only a total. Note that `DEFAULT_VERBOSESETTING` and `verbose` are strings, not boolean values. See the links below for more information.
  See Also:
    `getVerbose()`, `getVerboseAsBoolean()`, `setVerbose(String verbose)`

### DEFAULT_RECURSIONSETTING

    public static final java.lang.String DEFAULT_RECURSIONSETTING

  `DEFAULT_RECURSIONSETTING` contains the normal setting -- true -- for recursion. Thus, if you do not `setRecursion("false")` somewhere in your program, AntStarTeamCheckOut will check files out from all subfolders as well as from the given folder.
  See Also:
    `getRecursion()`, `setRecursion(String recursion)`

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

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

### DEFAULT_FOLDERSETTING

    public static final java.lang.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()`, `setFolderName(String folderName)`

Constructor Detail

### AntStarTeamCheckOut

    public AntStarTeamCheckOut()

Method Detail

### execute

    public void execute()
                 throws BuildException

  Do the execution.
  Overrides:
    `execute` in class `Task`
  Throws:
    `BuildException` -

### getServer

    protected org.apache.tools.ant.taskdefs.optional.scm.Server getServer()

  Creates and logs in to a StarTeam server.
  Returns:
    A StarTeam server.

### runServer

    protected void runServer(org.apache.tools.ant.taskdefs.optional.scm.Server s)

  Searches for the specified project on the server.
  Parameters:
    `s` - A StarTeam server.

### runProject

    protected void runProject(org.apache.tools.ant.taskdefs.optional.scm.Server s,
                              com.starbase.starteam.Project p)

  Searches for the given view in the project.
  Parameters:
    `s` - A StarTeam server.
    `p` - A valid project on the given server.

### runType

    protected void runType(org.apache.tools.ant.taskdefs.optional.scm.Server s,
                           com.starbase.starteam.Project p,
                           org.apache.tools.ant.taskdefs.optional.scm.View v,
                           org.apache.tools.ant.taskdefs.optional.scm.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".

### runFolder

    protected void runFolder(org.apache.tools.ant.taskdefs.optional.scm.Server s,
                             com.starbase.starteam.Project p,
                             org.apache.tools.ant.taskdefs.optional.scm.View v,
                             org.apache.tools.ant.taskdefs.optional.scm.Type t,
                             org.apache.tools.ant.taskdefs.optional.scm.Folder f)

  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.

### runItem

    protected void runItem(org.apache.tools.ant.taskdefs.optional.scm.Server s,
                           com.starbase.starteam.Project p,
                           org.apache.tools.ant.taskdefs.optional.scm.View v,
                           org.apache.tools.ant.taskdefs.optional.scm.Type t,
                           org.apache.tools.ant.taskdefs.optional.scm.Folder f,
                           org.apache.tools.ant.taskdefs.optional.scm.Item item)

  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.

### getPrimaryDescriptor

    protected org.apache.tools.ant.taskdefs.optional.scm.Property getPrimaryDescriptor(org.apache.tools.ant.taskdefs.optional.scm.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.

### getSecondaryDescriptor

    protected org.apache.tools.ant.taskdefs.optional.scm.Property getSecondaryDescriptor(org.apache.tools.ant.taskdefs.optional.scm.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.

### formatForDisplay

    protected java.lang.String formatForDisplay(org.apache.tools.ant.taskdefs.optional.scm.Property p,
                                                java.lang.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.

### setServerName

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

### getServerName

    public java.lang.String getServerName()

  Gets the `serverName` attribute.
  Returns:
    The StarTeam server to log in to.
  See Also:
    `setServerName(String serverName)`

### setServerPort

    public void setServerPort(java.lang.String 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()`

### getServerPort

    public java.lang.String getServerPort()

  Gets the `serverPort` attribute.
  Returns:
    A string containing the port on the StarTeam server to use.
  See Also:
    `getServerPortAsInt()`, `setServerPort(String serverPort)`

### getServerPortAsInt

    public int getServerPortAsInt()

  Gets the `serverPort` attribute as an integer.
  Returns:
    An integer value for the port on the StarTeam server to use.
  See Also:
    `getServerPort()`, `setServerPort(String serverPort)`

### setProjectName

    public void setProjectName(java.lang.String projectName)

  Sets the `projectName` attribute to the given value.
  Parameters:
    `projectName` - The StarTeam project to search.
  See Also:
    `getProjectName()`

### getProjectName

    public java.lang.String getProjectName()

  Gets the `projectName` attribute.
  Returns:
    The StarTeam project to search.
  See Also:
    `setProjectName(String projectName)`

### setViewName

    public void setViewName(java.lang.String viewName)

  Sets the `viewName` attribute to the given value.
  Parameters:
    `viewName` - The view to find the specified folder in.
  See Also:
    `getViewName()`

### getViewName

    public java.lang.String getViewName()

  Gets the `viewName` attribute.
  Returns:
    The view to find the specified folder in.
  See Also:
    `setViewName(String viewName)`

### setFolderName

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

### getFolderName

    public java.lang.String getFolderName()

  Gets the `folderName` attribute.
  Returns:
    The subfolder from which to check out files. All subfolders will be searched, as well.
  See Also:
    `setFolderName(String folderName)`

### setUsername

    public void setUsername(java.lang.String username)

  Sets the `username` attribute to the given value.
  Parameters:
    `username` - Your username for the specified StarTeam server.
  See Also:
    `getUsername()`

### getUsername

    public java.lang.String getUsername()

  Gets the `username` attribute.
  Returns:
    The username given by the user.
  See Also:
    `setUsername(String username)`

### setPassword

    public void setPassword(java.lang.String password)

  Sets the `password` attribute to the given value.
  Parameters:
    `password` - Your password for the specified StarTeam server.
  See Also:
    `getPassword()`

### getPassword

    public java.lang.String getPassword()

  Gets the `password` attribute.
  Returns:
    The password given by the user.
  See Also:
    `setPassword(String password)`

### setTargetFolder

    public void setTargetFolder(java.lang.String targetFolder)

  Sets the `targetFolder` attribute to the given value.
  Parameters:
    `target` - The target path on the local machine to check out to.
  See Also:
    `getTargetFolder()`

### getTargetFolder

    public java.lang.String getTargetFolder()

  Gets the `targetFolder` attribute.
  Returns:
    The target path on the local machine to check out to.
  See Also:
    `setTargetFolder(String targetFolder)`

### setForce

    public void setForce(java.lang.String force)

  Sets the `force` attribute to the given value.
  Parameters:
    `force` - A string containing "true" or "false" that tells the application whether to continue if the target directory exists. If `force` is true, AntStarTeamCheckOut will overwrite 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:
    `DEFAULT_FORCESETTING`, `getForce()`, `getForceAsBoolean()`

### getForce

    public java.lang.String getForce()

  Gets the `force` attribute.
  Returns:
    A string containing "true" or "false" telling the application whether to continue if the target directory exists. If `force` is true, AntStarTeamCheckOut will overwrite files in the target directory. If it is false and the target directory exists, AntStarTeamCheckOut will exit with a warning. If the target directory does not exist, this setting has no effect. The default setting is false.
  See Also:
    `DEFAULT_FORCESETTING`, `getForceAsBoolean()`, `setForce(String force)`

### getForceAsBoolean

    public boolean getForceAsBoolean()

  Gets the `force` attribute as a boolean value.
  Returns:
    A boolean value telling whether to continue if the target directory exists.
  See Also:
    `DEFAULT_FORCESETTING`, `getForce()`, `setForce(String force)`

### setRecursion

    public void setRecursion(java.lang.String recursion)

  Turns recursion on or off.
  Parameters:
    `verbose` - A string containing "true" or "false." 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:
    `DEFAULT_RECURSIONSETTING`, `getRecursion()`, `getRecursionAsBoolean()`

### getRecursion

    public java.lang.String getRecursion()

  Gets the `recursion` attribute, which tells AntStarTeamCheckOut whether to search subfolders when checking out files.
  Returns:
    A string telling whether `recursion` is "true" or "false."
  See Also:
    `DEFAULT_RECURSIONSETTING`, `getRecursionAsBoolean()`, `setRecursion(String recursion)`

### getRecursionAsBoolean

    public boolean getRecursionAsBoolean()

  Gets the `recursion` attribute as a boolean value.
  Returns:
    A boolean value telling whether subfolders of `folderName` will be scanned for files to check out.
  See Also:
    `DEFAULT_RECURSIONSETTING`, `getRecursion()`, `setRecursion(String recursion)`

### setVerbose

    public void setVerbose(java.lang.String verbose)

  Sets the `verbose` attribute to the given value.
  Parameters:
    `verbose` - A string containing "true" or "false" to tell AntStarTeamCheckOut whether to display files as they are checked out. By default it is false, so the program only displays the total number of files unless you override this default.
  See Also:
    `DEFAULT_FORCESETTING`, `getForce()`, `getForceAsBoolean()`

### getVerbose

    public java.lang.String getVerbose()

  Gets the `verbose` attribute.
  Returns:
    A string containing "true" or "false" telling the application to display all files as it checks them out. By default it is false, so the program only displays the total number of files.
  See Also:
    `DEFAULT_VERBOSESETTING`, `getVerboseAsBoolean()`, `setVerbose(String verbose)`

### getVerboseAsBoolean

    public boolean getVerboseAsBoolean()

  Gets the `verbose` attribute as a boolean value.
  Returns:
    A boolean value telling whether to display all files as they are checked out.
  See Also:
    `DEFAULT_VERBOSESETTING`, `getVerbose()`, `setVerbose(String verbose)`

### setIncludes

    public void setIncludes(java.lang.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.
  I would have used the Ant method directly from its class, but `match` is a private member, so I cannot access it from this program.
  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()`, `setExcludes(String excludes)`, `getExcludes()`

### getIncludes

    public java.lang.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:
    `setIncludes(String includes)`, `setExcludes(String excludes)`, `getExcludes()`

### setExcludes

    public void setExcludes(java.lang.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.
  I would have used the Ant method directly from its class, but `match` is a private member, so I cannot access it from this program.
  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:
    `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()`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000 Apache Software Foundation. All Rights Reserved.