File	Doc	Category	Size	Date	Package
TreeBasedTask.java	API Doc	Apache Ant 1.70	30407	Wed Dec 13 06:16:22 GMT 2006	org.apache.tools.ant.taskdefs.optional.starteam

TreeBasedTask

• java.lang.Object
  • StarTeamTask

Fields Summary
public static final String	DEFAULT_INCLUDESETTING This constant sets the filter to include all files. This default has the same result as setIncludes("*").
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).
private String	rootStarteamFolder The root folder of the operation in StarTeam.
private String	rootLocalFolder The local folder corresponding to starteamFolder. If not specified the Star Team default folder will be used.
private String	includes All files that fit this pattern are checked out.
private String	excludes All files fitting this pattern are ignored.
private String	label StarTeam label on which to perform task.
private boolean	recursive Set recursion to false to check out files in only the given folder and not in its subfolders.
private boolean	preloadFileInformation Set preloadFileInformation to true to load all file information from the server at once. Increases performance significantly for projects with many files and/or folders.
private boolean	forced If forced set to true, files in the target directory will be processed regardless of status in the repository. Usually this should be true if rootlocalfolder is set because status will be relative to the default folder, not to the one being processed.
private com.starbase.starteam.Label	labelInUse
private String	asOfDate holder for the asofdate attribute
private String	asOfDateFormat holder for the asofdateformat attribute

Constructors Summary

Methods Summary
protected void	_setAsOfDate(java.lang.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. param asOfDate asOfDate entered by user. since Ant 1.6 if (asOfDate != null && asOfDate.length() > 0) { this.asOfDate = asOfDate; }
protected void	_setAsOfDateFormat(java.lang.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. param asOfDateFormat asOfDate format entered by user. since Ant 1.6 if (asOfDateFormat != null && asOfDateFormat.length() > 0) { this.asOfDateFormat = asOfDateFormat; }
protected void	_setLabel(java.lang.String label) protected function to allow subclasses to set the label (or not). sets the StarTeam label param label name of the StarTeam label to be set if (null != label) { label = label.trim(); if (label.length() > 0) { this.label = label; } }
private com.starbase.starteam.Folder	configureRootStarteamFolder() Finds and opens the root starteam folder of the operation specified by this task. This will be one of the following cases: return Starteam's root folder for the operation. exception BuildException if the root folder cannot be found in the repository Folder starteamrootfolder = null; try { // no root local mapping has been specified. View snapshot = openView(); // find the starteam folder specified to be the root of the // operation. Throw if it can't be found. starteamrootfolder = StarTeamFinder.findFolder(snapshot.getRootFolder(), this.rootStarteamFolder); if (this.isPreloadFileInformation()) { PropertyNames pn = getServer().getPropertyNames(); String[] props = new String[] {pn.FILE_NAME, pn.FILE_PATH, pn.FILE_STATUS, pn.MODIFIED_TIME, pn.FILE_FILE_TIME_AT_CHECKIN, pn.MODIFIED_USER_ID, pn.FILE_SIZE, pn.FILE_ENCODING}; int depth = this.isRecursive() ? -1 : 0; starteamrootfolder.populateNow(getServer().getTypeNames().FILE, props, depth); } } catch (BuildException e) { throw e; } catch (Exception e) { StringBuffer msg = new StringBuffer("Unable to find root folder ") .append(this.rootStarteamFolder) .append(" in repository at ") .append(getURL()); if (this.label != null) { msg.append(" using specified label ").append(this.label); } if (this.asOfDate != null) { msg.append(" as of specified date ") .append(this.asOfDate); } throw new BuildException(msg.toString(), e); } if (null == starteamrootfolder) { throw new BuildException("Unable to find root folder " + this.rootStarteamFolder + " in repository at " + getURL()); } return starteamrootfolder;
public final void	execute() 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(). exception BuildException if any error occurs in the processing see testPreconditions() see visit() try { Folder starteamrootfolder = configureRootStarteamFolder(); // set the local folder. java.io.File localrootfolder = getLocalRootMapping(starteamrootfolder); testPreconditions(); // Tell user what he is doing logOperationDescription(starteamrootfolder, localrootfolder); // Inspect everything in the root folder and then recursively visit(starteamrootfolder, localrootfolder); } catch (Exception e) { throw new BuildException(e); } finally { disconnectFromServer(); }
private void	findLabel(com.starbase.starteam.View v) Label[] allLabels = v.getLabels(); for (int i = 0; i < allLabels.length; i++) { Label stLabel = allLabels[i]; log("checking label " + stLabel.getName(), Project.MSG_DEBUG); if (stLabel != null && !stLabel.isDeleted() && stLabel.getName().equals(this.label)) { if (!stLabel.isRevisionLabel() && !stLabel.isViewLabel()) { throw new BuildException("Unexpected label type."); } log("using label " + stLabel.getName(), Project.MSG_VERBOSE); this.labelInUse = stLabel; return; } } throw new BuildException("Error: label " + this.label + " does not exist in view " + v.getFullName());
protected java.lang.String	getAsOfDate() return the asOfDate entered by the user for internal use by derived classes. return the asOfDate entered by the user since Ant 1.6 return this.asOfDate;
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: return A string of filter patterns separated by spaces. see #setExcludes(String excludes) see #setIncludes(String includes) see #getIncludes() return excludes;
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. param remotefile the Star Team file whose path is to be returned return the full repository path name of a file. StringBuffer sb = new StringBuffer(); sb.append(remotefile.getParentFolderHierarchy()) .append(remotefile.getName()); return sb.toString();
protected int	getIDofLabelInUse() Get the id of the label in use. return id of the label in use, if labelinuse is present, otherwise return null if (null != this.labelInUse) { return this.labelInUse.getID(); } return -1;
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: return A string of filter patterns separated by spaces. see #setIncludes(String includes) see #setExcludes(String excludes) see #getExcludes() return includes;
protected java.lang.String	getLabel() return the label passed to the task by the user as a string return the label passed to the task by the user as a string return this.label;
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. param v the View in which to search for this.label return the ID number corresponding to this.label or -1 if no label was provided. exception BuildException if this.label does not correspond to any label in the supplied view if (null != this.label) { findLabel(v); return this.labelInUse.getID(); } return -1;
protected com.starbase.starteam.Label	getLabelInUse() returns the label being used return the label being used return this.labelInUse;
private java.io.File	getLocalRootMapping(com.starbase.starteam.Folder starteamrootfolder) Returns the local folder mapped to the given StarTeam root folder of the operation. There are two cases here, depending on whether rootLocalFolder is defined. If rootLocalFolder is defined, it will be used to establish a root mapping. Otherwise, the repository's default root folder will be used. param starteamrootfolder root Starteam folder initialized for the operation return the local folder corresponding to the root Starteam folder. see findRootStarteamFolder // set the local folder. String localrootfolder; if (null != this.rootLocalFolder) { localrootfolder = rootLocalFolder; } else { // either use default path or root local mapping, // which is now embedded in the root folder localrootfolder = starteamrootfolder.getPathFragment(); } return new java.io.File(localrootfolder);
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. return the local folder that mirrors this.rootStarteamFolder return this.rootLocalFolder;
public java.lang.String	getRootStarteamFolder() returns the root folder in the Starteam repository used for this operation return the root folder in use return this.rootStarteamFolder;
protected com.starbase.starteam.View	getViewConfiguredByDate(com.starbase.starteam.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. If no asofDate has been specified, return null. This method is meant to be called from within implementations of the createSnapshotView abstract method. param raw the raw view to be configured as of the supplied date return the view as configured. exception BuildException thrown if the date is not parsable by the default or supplied format patterns. since Ant 1.6 if (this.asOfDate == null) { return null; } Date asOfDate = null; SimpleDateFormat fmt = null; if (this.asOfDateFormat != null) { fmt = new SimpleDateFormat(this.asOfDateFormat); try { asOfDate = fmt.parse(this.asOfDate); } catch (ParseException px) { throw new BuildException("AsOfDate " + this.asOfDate + " not parsable by supplied format " + this.asOfDateFormat); } } else { try { asOfDate = DateUtils.parseIso8601DateTimeOrDate( this.asOfDate); } catch (ParseException px) { throw new BuildException("AsOfDate " + this.asOfDate + " not parsable by default" + " ISO8601 formats"); } } return new View(raw, ViewConfiguration.createFromTime( new OLEDate(asOfDate)));
public boolean	isForced() Get the value of forced. return value of forced. return this.forced;
public boolean	isPreloadFileInformation() Get the value of preloadFileInformation. return value of preloadFileInformation. return this.preloadFileInformation;
public boolean	isRecursive() Get the value of recursive. return value of recursive. return this.recursive;
protected boolean	isUsingRevisionLabel() returns true if a label has been specified and it is a revision label. return true if a label has been specified and it is a revision label return null != this.labelInUse && this.labelInUse.isRevisionLabel();
protected boolean	isUsingViewLabel() returns true if a label has been specified and it is a view label. return true if a label has been specified and it is a view label return null != this.labelInUse && this.labelInUse.isViewLabel();
protected void	logAsOfDate() show the asofDate in the log since Ant 1.6 if (null != this.asOfDate) { log(" Using view as of date " + getAsOfDate()); }
protected void	logExcludes() if excludes have been specified, emit the list to the log if (DEFAULT_EXCLUDESETTING != this.excludes) { log(" Excludes specified: " + this.excludes); }
protected void	logIncludes() if excludes have been specified, emit the list to the log if (DEFAULT_INCLUDESETTING != this.includes) { log(" Includes specified: " + this.includes); }
protected void	logLabel() show the label in the log and its type. if (this.isUsingViewLabel()) { log(" Using view label " + getLabel()); } else if (this.isUsingRevisionLabel()) { log(" Using revision label " + getLabel()); }
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. param starteamrootFolder root folder in StarTeam for the operation param targetrootFolder root local folder for the operation (whether specified by the user or not.
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. param patterns the space-separated list of patterns. param pName the name to look for matching. return whether the name match at least one pattern. if (patterns == null) { return false; } StringTokenizer exStr = new StringTokenizer(patterns, ","); while (exStr.hasMoreTokens()) { if (DirectoryScanner.match(exStr.nextToken(), pName)) { return true; } } return false;
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: param excludes A string of filter patterns to exclude. Separate the patterns by spaces. see #setIncludes(String includes) see #getIncludes() see #getExcludes() this.excludes = excludes;
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. param v Value to assign to forced. this.forced = v;
public void	setIncludes(java.lang.String includes) Declare files to include using standard includes patterns; optional. param includes A string of filter patterns to include. Separate the patterns by spaces. see #getIncludes() see #setExcludes(String excludes) see #getExcludes() this.includes = includes;
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. param v Value to assign to preloadFileInformation. this.preloadFileInformation = v;
public void	setRecursive(boolean v) Flag to set to include files in subfolders in the operation; optional, default true. param v Value to assign to recursive. this.recursive = v;
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. param rootLocalFolder the local folder that will mirror this.rootStarteamFolder this.rootLocalFolder = rootLocalFolder;
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 ('/'). param rootStarteamFolder the root folder /////////////////////////////////////////////////////////////// // GET/SET methods. // Setters, of course are where ant user passes in values. /////////////////////////////////////////////////////////////// this.rootStarteamFolder = rootStarteamFolder;
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. param pName the item name to look for being included. return whether the file should be processed or not. boolean includeIt = matchPatterns(getIncludes(), pName); boolean excludeIt = matchPatterns(getExcludes(), pName); return (includeIt && !excludeIt);
protected abstract void	testPreconditions() 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. exception 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 execute()
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 param rootStarteamFolder the StarTeam folderto be visited param rootLocalFolder the local mapping of rootStarteamFolder throws BuildException on error