Clover coverage report - Ant Coverage
Coverage timestamp: Tue Apr 8 2003 20:43:55 EST
file stats: LOC: 1,113   Methods: 43
NCLOC: 366   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
AntStarTeamCheckOut.java 0% 0% 0% 0%
 1   
 /*
 2   
  * The Apache Software License, Version 1.1
 3   
  *
 4   
  * Copyright (c) 2000-2002 The Apache Software Foundation.  All rights
 5   
  * reserved.
 6   
  *
 7   
  * Redistribution and use in source and binary forms, with or without
 8   
  * modification, are permitted provided that the following conditions
 9   
  * are met:
 10   
  *
 11   
  * 1. Redistributions of source code must retain the above copyright
 12   
  *    notice, this list of conditions and the following disclaimer.
 13   
  *
 14   
  * 2. Redistributions in binary form must reproduce the above copyright
 15   
  *    notice, this list of conditions and the following disclaimer in
 16   
  *    the documentation and/or other materials provided with the
 17   
  *    distribution.
 18   
  *
 19   
  * 3. The end-user documentation included with the redistribution, if
 20   
  *    any, must include the following acknowlegement:
 21   
  *       "This product includes software developed by the
 22   
  *        Apache Software Foundation (http://www.apache.org/)."
 23   
  *    Alternately, this acknowlegement may appear in the software itself,
 24   
  *    if and wherever such third-party acknowlegements normally appear.
 25   
  *
 26   
  * 4. The names "Ant" and "Apache Software
 27   
  *    Foundation" must not be used to endorse or promote products derived
 28   
  *    from this software without prior written permission. For written
 29   
  *    permission, please contact apache@apache.org.
 30   
  *
 31   
  * 5. Products derived from this software may not be called "Apache"
 32   
  *    nor may "Apache" appear in their names without prior written
 33   
  *    permission of the Apache Group.
 34   
  *
 35   
  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 36   
  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 37   
  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 38   
  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
 39   
  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 40   
  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 41   
  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 42   
  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 43   
  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 44   
  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 45   
  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 46   
  * SUCH DAMAGE.
 47   
  * ====================================================================
 48   
  *
 49   
  * This software consists of voluntary contributions made by many
 50   
  * individuals on behalf of the Apache Software Foundation.  For more
 51   
  * information on the Apache Software Foundation, please see
 52   
  * <http://www.apache.org/>.
 53   
  */
 54   
 package org.apache.tools.ant.taskdefs.optional.scm;
 55   
 
 56   
 import com.starbase.starteam.Folder;
 57   
 import com.starbase.starteam.Item;
 58   
 import com.starbase.starteam.Property;
 59   
 import com.starbase.starteam.Server;
 60   
 import com.starbase.starteam.StarTeamFinder;
 61   
 import com.starbase.starteam.Type;
 62   
 import com.starbase.starteam.View;
 63   
 import com.starbase.util.Platform;
 64   
 import java.util.StringTokenizer;
 65   
 import org.apache.tools.ant.BuildException;
 66   
 import org.apache.tools.ant.DirectoryScanner;
 67   
 import org.apache.tools.ant.Project;
 68   
 
 69   
 /**
 70   
  * Checks out files from a specific StarTeam server, project, view, and
 71   
  * folder.
 72   
  * <BR><BR>
 73   
  * This program logs in to a StarTeam server and opens up the specified
 74   
  * project and view.  Then, it searches through that view for the given
 75   
  * folder (or, if you prefer, it uses the root folder).  Beginning with
 76   
  * that folder and optionally continuing recursivesly, AntStarTeamCheckOut
 77   
  * compares each file with your include and exclude filters and checks it
 78   
  * out only if appropriate.
 79   
  * <BR><BR>
 80   
  * Checked out files go to a directory you specify under the subfolder
 81   
  * named for the default StarTeam path to the view.  That is, if you
 82   
  * entered /home/cpovirk/work as the target folder, your project was named
 83   
  * "OurProject," the given view was named "TestView," and that view is
 84   
  * stored by default at "C:\projects\Test," your files would be checked
 85   
  * out to /home/cpovirk/work/Test."  I avoided using the project name in
 86   
  * the path because you may want to keep several versions of the same
 87   
  * project on your computer, and I didn't want to use the view name, as
 88   
  * there may be many "Test" or "Version 1.0" views, for example.  This
 89   
  * system's success, of course, depends on what you set the default path
 90   
  * to in StarTeam.
 91   
  * <BR><BR>
 92   
  * You can set AntStarTeamCheckOut to verbose or quiet mode.  Also, it has
 93   
  * a safeguard against overwriting the files on your computer:  If the
 94   
  * target directory you specify already exists, the program will throw a
 95   
  * BuildException.  To override the exception, set <CODE>force</CODE> to
 96   
  * true.
 97   
  * <BR><BR>
 98   
  * <B>This program makes use of functions from the StarTeam API.  As a result
 99   
  * AntStarTeamCheckOut is available only to licensed users of StarTeam and
 100   
  * requires the StarTeam SDK to function.  You must have
 101   
  * <CODE>starteam-sdk.jar</CODE> in your classpath to run this program.
 102   
  * For more information about the StarTeam API and how to license it, see
 103   
  * the link below.</B>
 104   
  *
 105   
  * @author <A HREF="mailto:chris.povirk@paytec.com">Chris Povirk</A>
 106   
  * @author <A HREF="mailto:jc.mann@paytec.com">JC Mann</A>
 107   
  * @author <A HREF="mailto:jeff.gettle@paytec.com">Jeff Gettle</A>
 108   
  * @author <A HREF="mailto:stevec@ignitesports.com">Steve Cohen</A>
 109   
  * @version 1.0
 110   
  * @see <A HREF="http://www.starbase.com/">StarBase Web Site</A>
 111   
  *
 112   
  * @ant.task name="starteam" category="scm" ignore="true"
 113   
  */
 114   
 public class AntStarTeamCheckOut extends org.apache.tools.ant.Task {
 115   
 
 116   
     /**
 117   
      * This constant sets the filter to include all files. This default has
 118   
      * the same result as <CODE>setIncludes("*")</CODE>.
 119   
      *
 120   
      * @see #getIncludes()
 121   
      * @see #setIncludes(String includes)
 122   
      */
 123   
     public static final String DEFAULT_INCLUDESETTING = "*";
 124   
 
 125   
     /**
 126   
      * This disables the exclude filter by default. In other words, no files
 127   
      * are excluded. This setting is equivalent to <CODE>setExcludes(null)</CODE>
 128   
      * .
 129   
      *
 130   
      * @see #getExcludes()
 131   
      * @see #setExcludes(String excludes)
 132   
      */
 133   
     public static final String DEFAULT_EXCLUDESETTING = null;
 134   
 
 135   
     /**
 136   
      * The default folder to search; the root folder. Since
 137   
      * AntStarTeamCheckOut searches subfolders, by default it processes an
 138   
      * entire view.
 139   
      *
 140   
      * @see #getFolderName()
 141   
      * @see #setFolderName(String folderName)
 142   
      */
 143   
     public static final String DEFAULT_FOLDERSETTING = null;
 144   
 
 145   
     /**
 146   
      * This is used when formatting the output. The directory name is
 147   
      * displayed only when it changes.
 148   
      */
 149   
     private Folder prevFolder = null;
 150   
 
 151   
     /** This field keeps count of the number of files checked out.  */
 152   
     private int checkedOut = 0;
 153   
 
 154   
     // Change these through their GET and SET methods.
 155   
 
 156   
     /** The name of the server you wish to connect to.  */
 157   
     private String serverName = null;
 158   
 
 159   
     /** The port on the server used for StarTeam.  */
 160   
     private int serverPort = -1;
 161   
 
 162   
     /** The name of your project.  */
 163   
     private String projectName = null;
 164   
 
 165   
     /**
 166   
      * The name of the folder you want to check out files from. All subfolders
 167   
      * will be searched, as well.
 168   
      */
 169   
     private String folderName = DEFAULT_FOLDERSETTING;
 170   
 
 171   
     /** The view that the files you want are in.  */
 172   
     private String viewName = null;
 173   
 
 174   
     /** Your username on the StarTeam server.  */
 175   
     private String username = null;
 176   
 
 177   
     /** Your StarTeam password.  */
 178   
     private String password = null;
 179   
 
 180   
     /**
 181   
      * The path to the root folder you want to check out to. This is a local
 182   
      * directory.
 183   
      */
 184   
     private String targetFolder = null;
 185   
 
 186   
     /**
 187   
      * If force set to true, AntStarTeamCheckOut will overwrite files in the
 188   
      * target directory.
 189   
      */
 190   
     private boolean force = false;
 191   
 
 192   
     /**
 193   
      * When verbose is true, the program will display all files and
 194   
      * directories as they are checked out.
 195   
      */
 196   
     private boolean verbose = false;
 197   
 
 198   
     /**
 199   
      * Set recursion to false to check out files in only the given folder and
 200   
      * not in its subfolders.
 201   
      */
 202   
     private boolean recursion = true;
 203   
 
 204   
     // These fields deal with includes and excludes
 205   
 
 206   
     /** All files that fit this pattern are checked out.  */
 207   
     private String includes = DEFAULT_INCLUDESETTING;
 208   
 
 209   
     /** All files fitting this pattern are ignored.  */
 210   
     private String excludes = DEFAULT_EXCLUDESETTING;
 211   
 
 212   
     /** The file delimitor on the user's system.  */
 213   
     private String delim = Platform.getFilePathDelim();
 214   
 
 215   
     /**
 216   
      * whether to use the Starteam "default folder" when calculating the
 217   
      * target paths to which files are checked out (false) or if targetFolder
 218   
      * represents an absolute mapping to folderName.
 219   
      */
 220   
     private boolean targetFolderAbsolute = false;
 221   
 
 222   
 
 223   
     /** convenient method to check for conditions */
 224  0
     private static void assertTrue(boolean value, String msg) throws BuildException {
 225  0
         if (!value) {
 226  0
             throw new BuildException(msg);
 227   
         }
 228   
     }
 229   
 
 230   
 
 231  0
     protected void checkParameters() throws BuildException {
 232   
         // Check all of the properties that are required.
 233  0
         assertTrue(getServerName() != null, "ServerName must be set.");
 234  0
         assertTrue(getServerPort() != -1, "ServerPort must be set.");
 235  0
         assertTrue(getProjectName() != null, "ProjectName must be set.");
 236  0
         assertTrue(getViewName() != null, "ViewName must be set.");
 237  0
         assertTrue(getUsername() != null, "Username must be set.");
 238  0
         assertTrue(getPassword() != null, "Password must be set.");
 239  0
         assertTrue(getTargetFolder() != null, "TargetFolder must be set.");
 240   
 
 241   
         // Because of the way I create the full target path, there
 242   
         // must be NO slash at the end of targetFolder and folderName
 243   
         // However, if the slash or backslash is the only character, leave it alone
 244  0
         if ((getTargetFolder().endsWith("/") ||
 245   
             getTargetFolder().endsWith("\\"))
 246   
              && getTargetFolder().length() > 1) {
 247  0
             setTargetFolder(getTargetFolder().substring(0, getTargetFolder().length() - 1));
 248   
         }
 249   
 
 250   
         // Check to see if the target directory exists.
 251  0
         java.io.File dirExist = new java.io.File(getTargetFolder());
 252   
 
 253  0
         if (dirExist.isDirectory() && !getForce()) {
 254  0
             throw new BuildException("Target directory exists. Set \"force\" "
 255   
                  + "to \"true\" to continue anyway.");
 256   
         }
 257   
     }
 258   
 
 259   
 
 260   
     /**
 261   
      * Do the execution.
 262   
      *
 263   
      * @exception BuildException
 264   
      */
 265  0
     public void execute() throws BuildException {
 266  0
         log("DEPRECATED - The starteam task is deprecated.  Use stcheckout instead.",
 267   
             Project.MSG_WARN);
 268   
 
 269   
         // Connect to the StarTeam server, and log on.
 270  0
         Server s = getServer();
 271   
 
 272  0
         try {
 273   
             // Search the items on this server.
 274  0
             runServer(s);
 275   
         } finally {
 276   
             // Disconnect from the server.
 277  0
             s.disconnect();
 278   
         }
 279   
         // after you are all of the properties are ok, do your thing
 280   
         // with StarTeam.  If there are any kind of exceptions then
 281   
         // send the message to the project log.
 282   
 
 283   
         // Tell how many files were checked out.
 284  0
         log(checkedOut + " files checked out.");
 285   
     }
 286   
 
 287   
 
 288   
     /**
 289   
      * Creates and logs in to a StarTeam server.
 290   
      *
 291   
      * @return A StarTeam server.
 292   
      */
 293  0
     protected Server getServer() {
 294   
         // Simplest constructor, uses default encryption algorithm and compression level.
 295  0
         Server s = new Server(getServerName(), getServerPort());
 296   
 
 297   
         // Optional; logOn() connects if necessary.
 298  0
         s.connect();
 299   
 
 300   
         // Logon using specified user name and password.
 301  0
         s.logOn(getUsername(), getPassword());
 302   
 
 303  0
         return s;
 304   
     }
 305   
 
 306   
 
 307   
     /**
 308   
      * Searches for the specified project on the server.
 309   
      *
 310   
      * @param s A StarTeam server.
 311   
      */
 312  0
     protected void runServer(Server s) {
 313  0
         com.starbase.starteam.Project[] projects = s.getProjects();
 314   
 
 315  0
         for (int i = 0; i < projects.length; i++) {
 316  0
             com.starbase.starteam.Project p = projects[i];
 317   
 
 318  0
             if (p.getName().equals(getProjectName())) {
 319  0
                 if (getVerbose()) {
 320  0
                     log("Found " + getProjectName() + delim);
 321   
                 }
 322  0
                 runProject(s, p);
 323  0
                 break;
 324   
             }
 325   
         }
 326   
     }
 327   
 
 328   
 
 329   
     /**
 330   
      * Searches for the given view in the project.
 331   
      *
 332   
      * @param s A StarTeam server.
 333   
      * @param p A valid project on the given server.
 334   
      */
 335  0
     protected void runProject(Server s, com.starbase.starteam.Project p) {
 336  0
         View[] views = p.getViews();
 337   
 
 338  0
         for (int i = 0; i < views.length; i++) {
 339  0
             View v = views[i];
 340   
 
 341  0
             if (v.getName().equals(getViewName())) {
 342  0
                 if (getVerbose()) {
 343  0
                     log("Found " + getProjectName() + delim + getViewName() + delim);
 344   
                 }
 345  0
                 runType(s, p, v, s.typeForName(s.getTypeNames().FILE));
 346  0
                 break;
 347   
             }
 348   
         }
 349   
     }
 350   
 
 351   
 
 352   
     /**
 353   
      * Searches for folders in the given view.
 354   
      *
 355   
      * @param s A StarTeam server.
 356   
      * @param p A valid project on the server.
 357   
      * @param v A view name from the specified project.
 358   
      * @param t An item type which is currently always "file".
 359   
      */
 360  0
     protected void runType(Server s, com.starbase.starteam.Project p, View v, Type t) {
 361   
         // This is ugly; checking for the root folder.
 362  0
         Folder f = v.getRootFolder();
 363   
 
 364  0
         if (getFolderName() != null) {
 365  0
             if (getFolderName().equals("\\") || getFolderName().equals("/")) {
 366  0
                 setFolderName(null);
 367   
             } else {
 368  0
                 f = StarTeamFinder.findFolder(v.getRootFolder(), getFolderName());
 369  0
                 assertTrue(null != f, "ERROR: " + getProjectName() + delim + getViewName() + delim +
 370   
                     v.getRootFolder() + delim + getFolderName() + delim +
 371   
                     " does not exist.");
 372   
             }
 373   
         }
 374   
 
 375  0
         if (getVerbose() && getFolderName() != null) {
 376  0
             log("Found " + getProjectName() + delim + getViewName() +
 377   
                 delim + getFolderName() + delim + "\n");
 378   
         }
 379   
 
 380   
         // For performance reasons, it is important to pre-fetch all the
 381   
         // properties we'll need for all the items we'll be searching.
 382   
 
 383   
         // We always display the ItemID (OBJECT_ID) and primary descriptor.
 384  0
         int nProperties = 2;
 385   
 
 386   
         // We'll need this item type's primary descriptor.
 387  0
         Property p1 = getPrimaryDescriptor(t);
 388   
 
 389   
         // Does this item type have a secondary descriptor?
 390   
         // If so, we'll need it.
 391  0
         Property p2 = getSecondaryDescriptor(t);
 392   
 
 393  0
         if (p2 != null) {
 394  0
             nProperties++;
 395   
         }
 396   
 
 397   
         // Now, build an array of the property names.
 398  0
         String[] strNames = new String[nProperties];
 399  0
         int iProperty = 0;
 400   
 
 401  0
         strNames[iProperty++] = s.getPropertyNames().OBJECT_ID;
 402  0
         strNames[iProperty++] = p1.getName();
 403  0
         if (p2 != null) {
 404  0
             strNames[iProperty++] = p2.getName();
 405   
         }
 406   
 
 407   
         // Pre-fetch the item properties and cache them.
 408  0
         f.populateNow(t.getName(), strNames, -1);
 409   
 
 410   
         // Now, search for items in the selected folder.
 411  0
         runFolder(s, p, v, t, f, calcTargetFolder(v, f));
 412   
 
 413   
         // Free up the memory used by the cached items.
 414  0
         f.discardItems(t.getName(), -1);
 415   
     }
 416   
 
 417   
 
 418   
     /**
 419   
      * Returns a file object that defines the root of the local checkout tree.
 420   
      * Depending on the value of targetFolderAbsolute, this will be either the
 421   
      * targetFolder exactly as set by the user or the path formed by appending
 422   
      * the default folder onto the specified target folder.
 423   
      *
 424   
      * @param v view from which the file is checked out, supplies the "default
 425   
      *      folder"
 426   
      * @param rootSourceFolder root folder of the checkout operation in Star
 427   
      *      Team
 428   
      * @return an object referencing the local file
 429   
      * @see #getTargetFolderAbsolute()
 430   
      */
 431  0
     private java.io.File calcTargetFolder(View v, Folder rootSourceFolder) {
 432  0
         java.io.File root = new java.io.File(getTargetFolder());
 433   
 
 434  0
         if (!getTargetFolderAbsolute()) {
 435   
             // Create a variable dir that contains the name of
 436   
             // the StarTeam folder that is the root folder in this view.
 437   
             // Get the default path to the current view.
 438  0
             String defaultPath = v.getDefaultPath();
 439   
 
 440   
             // convert whatever separator char is in starteam to that of the target system.
 441  0
             defaultPath = defaultPath.replace('/', java.io.File.separatorChar);
 442  0
             defaultPath = defaultPath.replace('\\', java.io.File.separatorChar);
 443   
 
 444  0
             java.io.File dir = new java.io.File(defaultPath);
 445  0
             String dirName = dir.getName();
 446   
 
 447   
             // If it ends with separator then strip it off
 448  0
             if (dirName.endsWith(delim)) {
 449  0
                 dirName = dirName.substring(0, dirName.length() - 1);
 450   
             }
 451   
 
 452   
             // Replace the projectName in the file's absolute path to the viewName.
 453   
             // This makes the root target of a checkout operation equal to:
 454   
             // targetFolder + dirName
 455  0
             StringTokenizer pathTokenizer = new StringTokenizer(rootSourceFolder.getFolderHierarchy(), delim);
 456  0
             String currentToken = null;
 457  0
             boolean foundRoot = false;
 458   
 
 459  0
             while (pathTokenizer.hasMoreTokens()) {
 460  0
                 currentToken = pathTokenizer.nextToken();
 461  0
                 if (currentToken.equals(getProjectName()) && !foundRoot) {
 462  0
                     currentToken = dirName;
 463  0
                     foundRoot = true;// only want to do this the first time
 464   
                 }
 465  0
                 root = new java.io.File(root, currentToken);
 466   
             }
 467   
         }
 468   
 
 469  0
         return root;
 470   
     }
 471   
 
 472   
 
 473   
     /**
 474   
      * Searches for files in the given folder. This method is recursive and
 475   
      * thus searches all subfolders.
 476   
      *
 477   
      * @param s A StarTeam server.
 478   
      * @param p A valid project on the server.
 479   
      * @param v A view name from the specified project.
 480   
      * @param t An item type which is currently always "file".
 481   
      * @param f The folder to search.
 482   
      * @param tgt Target folder on local machine
 483   
      */
 484  0
     protected void runFolder(Server s,
 485   
                              com.starbase.starteam.Project p,
 486   
                              View v,
 487   
                              Type t,
 488   
                              Folder f,
 489   
                              java.io.File tgt) {
 490   
         // Process all items in this folder.
 491  0
         Item[] items = f.getItems(t.getName());
 492   
 
 493  0
         for (int i = 0; i < items.length; i++) {
 494  0
             runItem(s, p, v, t, f, items[i], tgt);
 495   
         }
 496   
 
 497   
         // Process all subfolders recursively if recursion is on.
 498  0
         if (getRecursion()) {
 499  0
             Folder[] subfolders = f.getSubFolders();
 500   
 
 501  0
             for (int i = 0; i < subfolders.length; i++) {
 502  0
                 runFolder(s, p, v, t, subfolders[i], new java.io.File(tgt, subfolders[i].getName()));
 503   
             }
 504   
         }
 505   
     }
 506   
 
 507   
 
 508   
     /**
 509   
      * Check out one file if it matches the include filter but not the exclude
 510   
      * filter.
 511   
      *
 512   
      * @param s A StarTeam server.
 513   
      * @param p A valid project on the server.
 514   
      * @param v A view name from the specified project.
 515   
      * @param t An item type which is currently always "file".
 516   
      * @param f The folder the file is localed in.
 517   
      * @param item The file to check out.
 518   
      * @param tgt target folder on local machine
 519   
      */
 520  0
     protected void runItem(Server s,
 521   
                            com.starbase.starteam.Project p,
 522   
                            View v,
 523   
                            Type t,
 524   
                            Folder f,
 525   
                            Item item,
 526   
                            java.io.File tgt) {
 527   
         // Get descriptors for this item type.
 528  0
         Property p1 = getPrimaryDescriptor(t);
 529  0
         Property p2 = getSecondaryDescriptor(t);
 530   
 
 531  0
         String pName = (String) item.get(p1.getName());
 532   
 
 533  0
         if (!shouldCheckout(pName)) {
 534  0
             return;
 535   
         }
 536   
 
 537   
         // VERBOSE MODE ONLY
 538  0
         if (getVerbose()) {
 539   
             // Show folder only if changed.
 540  0
             boolean bShowHeader = (f != prevFolder);
 541   
 
 542  0
             if (bShowHeader) {
 543   
                 // We want to display the folder the same way you would
 544   
                 // enter it on the command line ... so we remove the
 545   
                 // View name (which is also the name of the root folder,
 546   
                 // and therefore shows up at the start of the path).
 547  0
                 String strFolder = f.getFolderHierarchy();
 548  0
                 int i = strFolder.indexOf(delim);
 549   
 
 550  0
                 if (i >= 0) {
 551  0
                     strFolder = strFolder.substring(i + 1);
 552   
                 }
 553  0
                 log("            Folder: \"" + strFolder + "\"");
 554  0
                 prevFolder = f;
 555   
 
 556   
                 // If we displayed the project, view, item type, or folder,
 557   
                 // then show the list of relevant item properties.
 558  0
                 StringBuffer header = new StringBuffer("                Item");
 559   
 
 560  0
                 header.append(",\t").append(p1.getDisplayName());
 561  0
                 if (p2 != null) {
 562  0
                     header.append(",\t").append(p2.getDisplayName());
 563   
                 }
 564  0
                 log(header.toString());
 565   
             }
 566   
 
 567   
             // Finally, show the Item properties ...
 568   
             // Always show the ItemID.
 569  0
             StringBuffer itemLine = new StringBuffer("                ");
 570   
 
 571  0
             itemLine.append(item.getItemID());
 572   
 
 573   
             // Show the primary descriptor.
 574   
             // There should always be one.
 575  0
             itemLine.append(",\t").append(formatForDisplay(p1, item.get(p1.getName())));
 576   
 
 577   
             // Show the secondary descriptor, if there is one.
 578   
             // Some item types have one, some don't.
 579  0
             if (p2 != null) {
 580  0
                 itemLine.append(",\t").append(formatForDisplay(p2, item.get(p2.getName())));
 581   
             }
 582   
 
 583   
             // Show if the file is locked.
 584  0
             int locker = item.getLocker();
 585   
 
 586  0
             if (locker > -1) {
 587  0
                 itemLine.append(",\tLocked by ").append(locker);
 588   
             } else {
 589  0
                 itemLine.append(",\tNot locked");
 590   
             }
 591  0
             log(itemLine.toString());
 592   
         }
 593   
         // END VERBOSE ONLY
 594   
 
 595   
         // Check it out; also ugly.
 596   
 
 597   
         // Change the item to be checked out to a StarTeam File.
 598  0
         com.starbase.starteam.File remote = (com.starbase.starteam.File) item;
 599   
 
 600   
         // The local file name is simply the local target path (tgt) which has
 601   
         // been passed recursively down from the top of the tree, with the item's name appended.
 602  0
         java.io.File local = new java.io.File(tgt, (String) item.get(p1.getName()));
 603   
 
 604  0
         try {
 605  0
             remote.checkoutTo(local, Item.LockType.UNCHANGED, false, true, true);
 606  0
             checkedOut++;
 607   
         } catch (Exception e) {
 608  0
             throw new BuildException("Failed to checkout '" + local + "'", e);
 609   
         }
 610   
     }
 611   
 
 612   
 
 613   
     /**
 614   
      * Look if the file should be checked out. Don't check it out if It fits
 615   
      * no include filters and It fits an exclude filter.
 616   
      *
 617   
      * @param pName the item name to look for being included.
 618   
      * @return whether the file should be checked out or not.
 619   
      */
 620  0
     protected boolean shouldCheckout(String pName) {
 621  0
         boolean includeIt = matchPatterns(getIncludes(), pName);
 622  0
         boolean excludeIt = matchPatterns(getExcludes(), pName);
 623   
 
 624  0
         return (includeIt && !excludeIt);
 625   
     }
 626   
 
 627   
 
 628   
     /**
 629   
      * Convenient method to see if a string match a one pattern in given set
 630   
      * of space-separated patterns.
 631   
      *
 632   
      * @param patterns the space-separated list of patterns.
 633   
      * @param pName the name to look for matching.
 634   
      * @return whether the name match at least one pattern.
 635   
      */
 636  0
     protected boolean matchPatterns(String patterns, String pName) {
 637  0
         if (patterns == null) {
 638  0
             return false;
 639   
         }
 640  0
         StringTokenizer exStr = new StringTokenizer(patterns, " ");
 641   
 
 642  0
         while (exStr.hasMoreTokens()) {
 643  0
             if (DirectoryScanner.match(exStr.nextToken(), pName)) {
 644  0
                 return true;
 645   
             }
 646   
         }
 647  0
         return false;
 648   
     }
 649   
 
 650   
 
 651   
     /**
 652   
      * Get the primary descriptor of the given item type. Returns null if
 653   
      * there isn't one. In practice, all item types have a primary descriptor.
 654   
      *
 655   
      * @param t An item type. At this point it will always be "file".
 656   
      * @return The specified item's primary descriptor.
 657   
      */
 658  0
     protected Property getPrimaryDescriptor(Type t) {
 659  0
         Property[] properties = t.getProperties();
 660   
 
 661  0
         for (int i = 0; i < properties.length; i++) {
 662  0
             Property p = properties[i];
 663   
 
 664  0
             if (p.isPrimaryDescriptor()) {
 665  0
                 return p;
 666   
             }
 667   
         }
 668  0
         return null;
 669   
     }
 670   
 
 671   
 
 672   
     /**
 673   
      * Get the secondary descriptor of the given item type. Returns null if
 674   
      * there isn't one.
 675   
      *
 676   
      * @param t An item type. At this point it will always be "file".
 677   
      * @return The specified item's secondary descriptor. There may not be one
 678   
      *      for every file.
 679   
      */
 680  0
     protected Property getSecondaryDescriptor(Type t) {
 681  0
         Property[] properties = t.getProperties();
 682   
 
 683  0
         for (int i = 0; i < properties.length; i++) {
 684  0
             Property p = properties[i];
 685   
 
 686  0
             if (p.isDescriptor() && !p.isPrimaryDescriptor()) {
 687  0
                 return p;
 688   
             }
 689   
         }
 690  0
         return null;
 691   
     }
 692   
 
 693   
 
 694   
     /**
 695   
      * Formats a property value for display to the user.
 696   
      *
 697   
      * @param p An item property to format.
 698   
      * @param value
 699   
      * @return A string containing the property, which is truncated to 35
 700   
      *      characters for display.
 701   
      */
 702  0
     protected String formatForDisplay(Property p, Object value) {
 703  0
         if (p.getTypeCode() == Property.Types.TEXT) {
 704  0
             String str = value.toString();
 705   
 
 706  0
             if (str.length() > 35) {
 707  0
                 str = str.substring(0, 32) + "...";
 708   
             }
 709  0
             return "\"" + str + "\"";
 710   
         } else {
 711  0
             if (p.getTypeCode() == Property.Types.ENUMERATED) {
 712  0
                 return "\"" + p.getEnumDisplayName(((Integer) value).intValue()) + "\"";
 713   
             } else {
 714  0
                 return value.toString();
 715   
             }
 716   
         }
 717   
     }
 718   
 
 719   
     // Begin SET and GET methods
 720   
 
 721   
     /**
 722   
      * Sets the <CODE>serverName</CODE> attribute to the given value.
 723   
      *
 724   
      * @param serverName The name of the server you wish to connect to.
 725   
      * @see #getServerName()
 726   
      */
 727  0
     public void setServerName(String serverName) {
 728  0
         this.serverName = serverName;
 729   
     }
 730   
 
 731   
 
 732   
     /**
 733   
      * Gets the <CODE>serverName</CODE> attribute.
 734   
      *
 735   
      * @return The StarTeam server to log in to.
 736   
      * @see #setServerName(String serverName)
 737   
      */
 738  0
     public String getServerName() {
 739  0
         return serverName;
 740   
     }
 741   
 
 742   
 
 743   
     /**
 744   
      * Sets the <CODE>serverPort</CODE> attribute to the given value. The
 745   
      * given value must be a valid integer, but it must be a string object.
 746   
      *
 747   
      * @param serverPort A string containing the port on the StarTeam server
 748   
      *      to use.
 749   
      * @see #getServerPort()
 750   
      */
 751  0
     public void setServerPort(int serverPort) {
 752  0
         this.serverPort = serverPort;
 753   
     }
 754   
 
 755   
 
 756   
     /**
 757   
      * Gets the <CODE>serverPort</CODE> attribute.
 758   
      *
 759   
      * @return A string containing the port on the StarTeam server to use.
 760   
      * @see #setServerPort(int)
 761   
      */
 762  0
     public int getServerPort() {
 763  0
         return serverPort;
 764   
     }
 765   
 
 766   
 
 767   
     /**
 768   
      * Sets the <CODE>projectName</CODE> attribute to the given value.
 769   
      *
 770   
      * @param projectName The StarTeam project to search.
 771   
      * @see #getProjectName()
 772   
      */
 773  0
     public void setProjectName(String projectName) {
 774  0
         this.projectName = projectName;
 775   
     }
 776   
 
 777   
 
 778   
     /**
 779   
      * Gets the <CODE>projectName</CODE> attribute.
 780   
      *
 781   
      * @return The StarTeam project to search.
 782   
      * @see #setProjectName(String projectName)
 783   
      */
 784  0
     public String getProjectName() {
 785  0
         return projectName;
 786   
     }
 787   
 
 788   
 
 789   
     /**
 790   
      * Sets the <CODE>viewName</CODE> attribute to the given value.
 791   
      *
 792   
      * @param viewName The view to find the specified folder in.
 793   
      * @see #getViewName()
 794   
      */
 795  0
     public void setViewName(String viewName) {
 796  0
         this.viewName = viewName;
 797   
     }
 798   
 
 799   
 
 800   
     /**
 801   
      * Gets the <CODE>viewName</CODE> attribute.
 802   
      *
 803   
      * @return The view to find the specified folder in.
 804   
      * @see #setViewName(String viewName)
 805   
      */
 806  0
     public String getViewName() {
 807  0
         return viewName;
 808   
     }
 809   
 
 810   
 
 811   
     /**
 812   
      * Sets the <CODE>folderName</CODE> attribute to the given value. To
 813   
      * search the root folder, use a slash or backslash, or simply don't set a
 814   
      * folder at all.
 815   
      *
 816   
      * @param folderName The subfolder from which to check out files.
 817   
      * @see #getFolderName()
 818   
      */
 819  0
     public void setFolderName(String folderName) {
 820  0
         this.folderName = folderName;
 821   
     }
 822   
 
 823   
 
 824   
     /**
 825   
      * Gets the <CODE>folderName</CODE> attribute.
 826   
      *
 827   
      * @return The subfolder from which to check out files. All subfolders
 828   
      *      will be searched, as well.
 829   
      * @see #setFolderName(String folderName)
 830   
      */
 831  0
     public String getFolderName() {
 832  0
         return folderName;
 833   
     }
 834   
 
 835   
 
 836   
     /**
 837   
      * Sets the <CODE>username</CODE> attribute to the given value.
 838   
      *
 839   
      * @param username Your username for the specified StarTeam server.
 840   
      * @see #getUsername()
 841   
      */
 842  0
     public void setUsername(String username) {
 843  0
         this.username = username;
 844   
     }
 845   
 
 846   
 
 847   
     /**
 848   
      * Gets the <CODE>username</CODE> attribute.
 849   
      *
 850   
      * @return The username given by the user.
 851   
      * @see #setUsername(String username)
 852   
      */
 853  0
     public String getUsername() {
 854  0
         return username;
 855   
     }
 856   
 
 857   
 
 858   
     /**
 859   
      * Sets the <CODE>password</CODE> attribute to the given value.
 860   
      *
 861   
      * @param password Your password for the specified StarTeam server.
 862   
      * @see #getPassword()
 863   
      */
 864  0
     public void setPassword(String password) {
 865  0
         this.password = password;
 866   
     }
 867   
 
 868   
 
 869   
     /**
 870   
      * Gets the <CODE>password</CODE> attribute.
 871   
      *
 872   
      * @return The password given by the user.
 873   
      * @see #setPassword(String password)
 874   
      */
 875  0
     public String getPassword() {
 876  0
         return password;
 877   
     }
 878   
 
 879   
 
 880   
     /**
 881   
      * Sets the <CODE>targetFolder</CODE> attribute to the given value.
 882   
      *
 883   
      * @param target The target path on the local machine to check out to.
 884   
      * @see #getTargetFolder()
 885   
      */
 886  0
     public void setTargetFolder(String targetFolder) {
 887  0
         this.targetFolder = targetFolder;
 888   
     }
 889   
 
 890   
 
 891   
     /**
 892   
      * Gets the <CODE>targetFolder</CODE> attribute.
 893   
      *
 894   
      * @return The target path on the local machine to check out to.
 895   
      * @see #setTargetFolder(String targetFolder)
 896   
      */
 897  0
     public String getTargetFolder() {
 898  0
         return targetFolder;
 899   
     }
 900   
 
 901   
 
 902   
     /**
 903   
      * Sets the <CODE>force</CODE> attribute to the given value.
 904   
      *
 905   
      * @param force if true, it overwrites files in the target directory. By
 906   
      *      default it set to false as a safeguard. Note that if the target
 907   
      *      directory does not exist, this setting has no effect.
 908   
      * @see #getForce()
 909   
      */
 910  0
     public void setForce(boolean force) {
 911  0
         this.force = force;
 912   
     }
 913   
 
 914   
 
 915   
     /**
 916   
      * Gets the <CODE>force</CODE> attribute.
 917   
      *
 918   
      * @return whether to continue if the target directory exists.
 919   
      * @see #setForce(boolean)
 920   
      */
 921  0
     public boolean getForce() {
 922  0
         return force;
 923   
     }
 924   
 
 925   
 
 926   
     /**
 927   
      * Turns recursion on or off.
 928   
      *
 929   
      * @param recursion if it is true, the default, subfolders are searched
 930   
      *      recursively for files to check out. Otherwise, only files
 931   
      *      specified by <CODE>folderName</CODE> are scanned.
 932   
      * @see #getRecursion()
 933   
      */
 934  0
     public void setRecursion(boolean recursion) {
 935  0
         this.recursion = recursion;
 936   
     }
 937   
 
 938   
 
 939   
     /**
 940   
      * Gets the <CODE>recursion</CODE> attribute, which tells
 941   
      * AntStarTeamCheckOut whether to search subfolders when checking out
 942   
      * files.
 943   
      *
 944   
      * @return whether to search subfolders when checking out files.
 945   
      * @see #setRecursion(boolean)
 946   
      */
 947  0
     public boolean getRecursion() {
 948  0
         return recursion;
 949   
     }
 950   
 
 951   
 
 952   
     /**
 953   
      * Sets the <CODE>verbose</CODE> attribute to the given value.
 954   
      *
 955   
      * @param verbose whether to display all files as it checks them out. By
 956   
      *      default it is false, so the program only displays the total number
 957   
      *      of files unless you override this default.
 958   
      * @see #getVerbose()
 959   
      */
 960  0
     public void setVerbose(boolean verbose) {
 961  0
         this.verbose = verbose;
 962   
     }
 963   
 
 964   
 
 965   
     /**
 966   
      * Gets the <CODE>verbose</CODE> attribute.
 967   
      *
 968   
      * @return whether to display all files as it checks them out.
 969   
      * @see #setVerbose(boolean verbose)
 970   
      */
 971  0
     public boolean getVerbose() {
 972  0
         return verbose;
 973   
     }
 974   
 
 975   
     // Begin filter getters and setters
 976   
 
 977   
     /**
 978   
      * Sets the include filter. When filtering files, AntStarTeamCheckOut uses
 979   
      * an unmodified version of <CODE>DirectoryScanner</CODE>'s <CODE>match</CODE>
 980   
      * method, so here are the patterns straight from the Ant source code:
 981   
      * <BR>
 982   
      * <BR>
 983   
      * Matches a string against a pattern. The pattern contains two special
 984   
      * characters: <BR>
 985   
      * '*' which means zero or more characters, <BR>
 986   
      * '?' which means one and only one character. <BR>
 987   
      * <BR>
 988   
      * Separate multiple inlcude filters by <I>spaces</I> , not commas as Ant
 989   
      * uses. For example, if you want to check out all .java and .class\
 990   
      * files, you would put the following line in your program: <CODE>setIncludes("*.java *.class");</CODE>
 991   
      * Finally, note that filters have no effect on the <B>directories</B>
 992   
      * that are scanned; you could not check out files from directories with
 993   
      * names beginning only with "build," for instance. Of course, you could
 994   
      * limit AntStarTeamCheckOut to a particular folder and its subfolders
 995   
      * with the <CODE>setFolderName(String folderName)</CODE> command. <BR>
 996   
      * <BR>
 997   
      * Treatment of overlapping inlcudes and excludes: To give a simplistic
 998   
      * example suppose that you set your include filter to "*.htm *.html" and
 999   
      * your exclude filter to "index.*". What happens to index.html?
 1000   
      * AntStarTeamCheckOut will not check out index.html, as it matches an
 1001   
      * exclude filter ("index.*"), even though it matches the include filter,
 1002   
      * as well. <BR>
 1003   
      * <BR>
 1004   
      * Please also read the following sections before using filters:
 1005   
      *
 1006   
      * @param includes A string of filter patterns to include. Separate the
 1007   
      *      patterns by spaces.
 1008   
      * @see #getIncludes()
 1009   
      * @see #setExcludes(String excludes)
 1010   
      * @see #getExcludes()
 1011   
      */
 1012  0
     public void setIncludes(String includes) {
 1013  0
         this.includes = includes;
 1014   
     }
 1015   
 
 1016   
 
 1017   
     /**
 1018   
      * Gets the patterns from the include filter. Rather that duplicate the
 1019   
      * details of AntStarTeanCheckOut's filtering here, refer to these links:
 1020   
      *
 1021   
      * @return A string of filter patterns separated by spaces.
 1022   
      * @see #setIncludes(String includes)
 1023   
      * @see #setExcludes(String excludes)
 1024   
      * @see #getExcludes()
 1025   
      */
 1026  0
     public String getIncludes() {
 1027  0
         return includes;
 1028   
     }
 1029   
 
 1030   
 
 1031   
     /**
 1032   
      * Sets the exclude filter. When filtering files, AntStarTeamCheckOut uses
 1033   
      * an unmodified version of <CODE>DirectoryScanner</CODE>'s <CODE>match</CODE>
 1034   
      * method, so here are the patterns straight from the Ant source code:
 1035   
      * <BR>
 1036   
      * <BR>
 1037   
      * Matches a string against a pattern. The pattern contains two special
 1038   
      * characters: <BR>
 1039   
      * '*' which means zero or more characters, <BR>
 1040   
      * '?' which means one and only one character. <BR>
 1041   
      * <BR>
 1042   
      * Separate multiple exlcude filters by <I>spaces</I> , not commas as Ant
 1043   
      * uses. For example, if you want to check out all files except .XML and
 1044   
      * .HTML files, you would put the following line in your program: <CODE>setExcludes("*.XML *.HTML");</CODE>
 1045   
      * Finally, note that filters have no effect on the <B>directories</B>
 1046   
      * that are scanned; you could not skip over all files in directories
 1047   
      * whose names begin with "project," for instance. <BR>
 1048   
      * <BR>
 1049   
      * Treatment of overlapping inlcudes and excludes: To give a simplistic
 1050   
      * example suppose that you set your include filter to "*.htm *.html" and
 1051   
      * your exclude filter to "index.*". What happens to index.html?
 1052   
      * AntStarTeamCheckOut will not check out index.html, as it matches an
 1053   
      * exclude filter ("index.*"), even though it matches the include filter,
 1054   
      * as well. <BR>
 1055   
      * <BR>
 1056   
      * Please also read the following sections before using filters:
 1057   
      *
 1058   
      * @param excludes A string of filter patterns to exclude. Separate the
 1059   
      *      patterns by spaces.
 1060   
      * @see #setIncludes(String includes)
 1061   
      * @see #getIncludes()
 1062   
      * @see #getExcludes()
 1063   
      */
 1064  0
     public void setExcludes(String excludes) {
 1065  0
         this.excludes = excludes;
 1066   
     }
 1067   
 
 1068   
 
 1069   
     /**
 1070   
      * Gets the patterns from the exclude filter. Rather that duplicate the
 1071   
      * details of AntStarTeanCheckOut's filtering here, refer to these links:
 1072   
      *
 1073   
      * @return A string of filter patterns separated by spaces.
 1074   
      * @see #setExcludes(String excludes)
 1075   
      * @see #setIncludes(String includes)
 1076   
      * @see #getIncludes()
 1077   
      */
 1078  0
     public String getExcludes() {
 1079  0
         return excludes;
 1080   
     }
 1081   
 
 1082   
 
 1083   
     /**
 1084   
      * returns whether the StarTeam default path is factored into calculated
 1085   
      * target path locations (false) or whether targetFolder is an absolute
 1086   
      * mapping to the root folder named by folderName
 1087   
      *
 1088   
      * @return returns true if absolute mapping is used, false if it is not
 1089   
      *      used.
 1090   
      * @see #setTargetFolderAbsolute(boolean)
 1091   
      */
 1092  0
     public boolean getTargetFolderAbsolute() {
 1093  0
         return this.targetFolderAbsolute;
 1094   
     }
 1095   
 
 1096   
 
 1097   
     /**
 1098   
      * sets the property that indicates whether or not the Star Team "default
 1099   
      * folder" is to be used when calculation paths for items on the target
 1100   
      * (false) or if targetFolder is an absolute mapping to the root folder
 1101   
      * named by foldername.
 1102   
      *
 1103   
      * @param targetFolderAbsolute <tt>true</tt> if the absolute mapping is to
 1104   
      *      be used. <tt>false</tt> (the default) if the "default folder" is
 1105   
      *      to be factored in.
 1106   
      * @see #getTargetFolderAbsolute()
 1107   
      */
 1108  0
     public void setTargetFolderAbsolute(boolean targetFolderAbsolute) {
 1109  0
         this.targetFolderAbsolute = targetFolderAbsolute;
 1110   
     }
 1111   
 }
 1112   
 
 1113