0001: /*
0002: * Licensed to the Apache Software Foundation (ASF) under one or more
0003: * contributor license agreements. See the NOTICE file distributed with
0004: * this work for additional information regarding copyright ownership.
0005: * The ASF licenses this file to You under the Apache License, Version 2.0
0006: * (the "License"); you may not use this file except in compliance with
0007: * the License. You may obtain a copy of the License at
0008: *
0009: * http://www.apache.org/licenses/LICENSE-2.0
0010: *
0011: * Unless required by applicable law or agreed to in writing, software
0012: * distributed under the License is distributed on an "AS IS" BASIS,
0013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014: * See the License for the specific language governing permissions and
0015: * limitations under the License.
0016: *
0017: */
0018: package org.apache.tools.ant.taskdefs.optional.scm;
0019:
0020: import com.starbase.starteam.Folder;
0021: import com.starbase.starteam.Item;
0022: import com.starbase.starteam.Property;
0023: import com.starbase.starteam.Server;
0024: import com.starbase.starteam.StarTeamFinder;
0025: import com.starbase.starteam.Type;
0026: import com.starbase.starteam.View;
0027: import com.starbase.util.Platform;
0028: import java.util.StringTokenizer;
0029: import org.apache.tools.ant.BuildException;
0030: import org.apache.tools.ant.DirectoryScanner;
0031: import org.apache.tools.ant.Project;
0032:
0033: /**
0034: * Checks out files from a specific StarTeam server, project, view, and
0035: * folder.
0036: * <BR><BR>
0037: * This program logs in to a StarTeam server and opens up the specified
0038: * project and view. Then, it searches through that view for the given
0039: * folder (or, if you prefer, it uses the root folder). Beginning with
0040: * that folder and optionally continuing recursivesly, AntStarTeamCheckOut
0041: * compares each file with your include and exclude filters and checks it
0042: * out only if appropriate.
0043: * <BR><BR>
0044: * Checked out files go to a directory you specify under the subfolder
0045: * named for the default StarTeam path to the view. That is, if you
0046: * entered /home/cpovirk/work as the target folder, your project was named
0047: * "OurProject," the given view was named "TestView," and that view is
0048: * stored by default at "C:\projects\Test," your files would be checked
0049: * out to /home/cpovirk/work/Test." I avoided using the project name in
0050: * the path because you may want to keep several versions of the same
0051: * project on your computer, and I didn't want to use the view name, as
0052: * there may be many "Test" or "Version 1.0" views, for example. This
0053: * system's success, of course, depends on what you set the default path
0054: * to in StarTeam.
0055: * <BR><BR>
0056: * You can set AntStarTeamCheckOut to verbose or quiet mode. Also, it has
0057: * a safeguard against overwriting the files on your computer: If the
0058: * target directory you specify already exists, the program will throw a
0059: * BuildException. To override the exception, set <CODE>force</CODE> to
0060: * true.
0061: * <BR><BR>
0062: * <B>This program makes use of functions from the StarTeam API. As a result
0063: * AntStarTeamCheckOut is available only to licensed users of StarTeam and
0064: * requires the StarTeam SDK to function. You must have
0065: * <CODE>starteam-sdk.jar</CODE> in your classpath to run this program.
0066: * For more information about the StarTeam API and how to license it, see
0067: * the link below.</B>
0068: *
0069: * @version 1.0
0070: * @see <A HREF="http://www.starbase.com/">StarBase Web Site</A>
0071: *
0072: * @ant.task name="starteam" category="scm" ignore="true"
0073: */
0074: public class AntStarTeamCheckOut extends org.apache.tools.ant.Task {
0075:
0076: /**
0077: * This constant sets the filter to include all files. This default has
0078: * the same result as <CODE>setIncludes("*")</CODE>.
0079: *
0080: * @see #getIncludes()
0081: * @see #setIncludes(String includes)
0082: */
0083: public static final String DEFAULT_INCLUDESETTING = "*";
0084:
0085: /**
0086: * This disables the exclude filter by default. In other words, no files
0087: * are excluded. This setting is equivalent to <CODE>setExcludes(null)</CODE>
0088: * .
0089: *
0090: * @see #getExcludes()
0091: * @see #setExcludes(String excludes)
0092: */
0093: public static final String DEFAULT_EXCLUDESETTING = null;
0094:
0095: /**
0096: * The default folder to search; the root folder. Since
0097: * AntStarTeamCheckOut searches subfolders, by default it processes an
0098: * entire view.
0099: *
0100: * @see #getFolderName()
0101: * @see #setFolderName(String folderName)
0102: */
0103: public static final String DEFAULT_FOLDERSETTING = null;
0104:
0105: /**
0106: * This is used when formatting the output. The directory name is
0107: * displayed only when it changes.
0108: */
0109: private Folder prevFolder = null;
0110:
0111: /** This field keeps count of the number of files checked out. */
0112: private int checkedOut = 0;
0113:
0114: // Change these through their GET and SET methods.
0115:
0116: /** The name of the server you wish to connect to. */
0117: private String serverName = null;
0118:
0119: /** The port on the server used for StarTeam. */
0120: private int serverPort = -1;
0121:
0122: /** The name of your project. */
0123: private String projectName = null;
0124:
0125: /**
0126: * The name of the folder you want to check out files from. All subfolders
0127: * will be searched, as well.
0128: */
0129: private String folderName = DEFAULT_FOLDERSETTING;
0130:
0131: /** The view that the files you want are in. */
0132: private String viewName = null;
0133:
0134: /** Your username on the StarTeam server. */
0135: private String username = null;
0136:
0137: /** Your StarTeam password. */
0138: private String password = null;
0139:
0140: /**
0141: * The path to the root folder you want to check out to. This is a local
0142: * directory.
0143: */
0144: private String targetFolder = null;
0145:
0146: /**
0147: * If force set to true, AntStarTeamCheckOut will overwrite files in the
0148: * target directory.
0149: */
0150: private boolean force = false;
0151:
0152: /**
0153: * When verbose is true, the program will display all files and
0154: * directories as they are checked out.
0155: */
0156: private boolean verbose = false;
0157:
0158: /**
0159: * Set recursion to false to check out files in only the given folder and
0160: * not in its subfolders.
0161: */
0162: private boolean recursion = true;
0163:
0164: // These fields deal with includes and excludes
0165:
0166: /** All files that fit this pattern are checked out. */
0167: private String includes = DEFAULT_INCLUDESETTING;
0168:
0169: /** All files fitting this pattern are ignored. */
0170: private String excludes = DEFAULT_EXCLUDESETTING;
0171:
0172: /** The file delimitor on the user's system. */
0173: private String delim = Platform.getFilePathDelim();
0174:
0175: /**
0176: * whether to use the Starteam "default folder" when calculating the
0177: * target paths to which files are checked out (false) or if targetFolder
0178: * represents an absolute mapping to folderName.
0179: */
0180: private boolean targetFolderAbsolute = false;
0181:
0182: /** convenient method to check for conditions */
0183: private static void assertTrue(boolean value, String msg)
0184: throws BuildException {
0185: if (!value) {
0186: throw new BuildException(msg);
0187: }
0188: }
0189:
0190: /**
0191: * Check if the attributes/elements are correct.
0192: * @throws BuildException if there was a problem.
0193: */
0194: protected void checkParameters() throws BuildException {
0195: // Check all of the properties that are required.
0196: assertTrue(getServerName() != null, "ServerName must be set.");
0197: assertTrue(getServerPort() != -1, "ServerPort must be set.");
0198: assertTrue(getProjectName() != null, "ProjectName must be set.");
0199: assertTrue(getViewName() != null, "ViewName must be set.");
0200: assertTrue(getUsername() != null, "Username must be set.");
0201: assertTrue(getPassword() != null, "Password must be set.");
0202: assertTrue(getTargetFolder() != null,
0203: "TargetFolder must be set.");
0204:
0205: // Because of the way I create the full target path, there
0206: // must be NO slash at the end of targetFolder and folderName
0207: // However, if the slash or backslash is the only character, leave it alone
0208: if ((getTargetFolder().endsWith("/") || getTargetFolder()
0209: .endsWith("\\"))
0210: && getTargetFolder().length() > 1) {
0211: setTargetFolder(getTargetFolder().substring(0,
0212: getTargetFolder().length() - 1));
0213: }
0214:
0215: // Check to see if the target directory exists.
0216: java.io.File dirExist = new java.io.File(getTargetFolder());
0217:
0218: if (dirExist.isDirectory() && !getForce()) {
0219: throw new BuildException(
0220: "Target directory exists. Set \"force\" "
0221: + "to \"true\" to continue anyway.");
0222: }
0223: }
0224:
0225: /**
0226: * Do the execution.
0227: *
0228: * @throws BuildException if there was a problem.
0229: */
0230: public void execute() throws BuildException {
0231: log(
0232: "DEPRECATED - The starteam task is deprecated. Use stcheckout instead.",
0233: Project.MSG_WARN);
0234:
0235: // Connect to the StarTeam server, and log on.
0236: Server s = getServer();
0237:
0238: try {
0239: // Search the items on this server.
0240: runServer(s);
0241: } finally {
0242: // Disconnect from the server.
0243: s.disconnect();
0244: }
0245: // after you are all of the properties are ok, do your thing
0246: // with StarTeam. If there are any kind of exceptions then
0247: // send the message to the project log.
0248:
0249: // Tell how many files were checked out.
0250: log(checkedOut + " files checked out.");
0251: }
0252:
0253: /**
0254: * Creates and logs in to a StarTeam server.
0255: *
0256: * @return A StarTeam server.
0257: */
0258: protected Server getServer() {
0259: // Simplest constructor, uses default encryption algorithm and compression level.
0260: Server s = new Server(getServerName(), getServerPort());
0261:
0262: // Optional; logOn() connects if necessary.
0263: s.connect();
0264:
0265: // Logon using specified user name and password.
0266: s.logOn(getUsername(), getPassword());
0267:
0268: return s;
0269: }
0270:
0271: /**
0272: * Searches for the specified project on the server.
0273: *
0274: * @param s A StarTeam server.
0275: */
0276: protected void runServer(Server s) {
0277: com.starbase.starteam.Project[] projects = s.getProjects();
0278:
0279: for (int i = 0; i < projects.length; i++) {
0280: com.starbase.starteam.Project p = projects[i];
0281:
0282: if (p.getName().equals(getProjectName())) {
0283: if (getVerbose()) {
0284: log("Found " + getProjectName() + delim);
0285: }
0286: runProject(s, p);
0287: break;
0288: }
0289: }
0290: }
0291:
0292: /**
0293: * Searches for the given view in the project.
0294: *
0295: * @param s A StarTeam server.
0296: * @param p A valid project on the given server.
0297: */
0298: protected void runProject(Server s, com.starbase.starteam.Project p) {
0299: View[] views = p.getViews();
0300:
0301: for (int i = 0; i < views.length; i++) {
0302: View v = views[i];
0303:
0304: if (v.getName().equals(getViewName())) {
0305: if (getVerbose()) {
0306: log("Found " + getProjectName() + delim
0307: + getViewName() + delim);
0308: }
0309: runType(s, p, v, s.typeForName(s.getTypeNames().FILE));
0310: break;
0311: }
0312: }
0313: }
0314:
0315: /**
0316: * Searches for folders in the given view.
0317: *
0318: * @param s A StarTeam server.
0319: * @param p A valid project on the server.
0320: * @param v A view name from the specified project.
0321: * @param t An item type which is currently always "file".
0322: */
0323: protected void runType(Server s, com.starbase.starteam.Project p,
0324: View v, Type t) {
0325: // This is ugly; checking for the root folder.
0326: Folder f = v.getRootFolder();
0327:
0328: if (getFolderName() != null) {
0329: if (getFolderName().equals("\\")
0330: || getFolderName().equals("/")) {
0331: setFolderName(null);
0332: } else {
0333: f = StarTeamFinder.findFolder(v.getRootFolder(),
0334: getFolderName());
0335: assertTrue(null != f, "ERROR: " + getProjectName()
0336: + delim + getViewName() + delim
0337: + v.getRootFolder() + delim + getFolderName()
0338: + delim + " does not exist.");
0339: }
0340: }
0341:
0342: if (getVerbose() && getFolderName() != null) {
0343: log("Found " + getProjectName() + delim + getViewName()
0344: + delim + getFolderName() + delim + "\n");
0345: }
0346:
0347: // For performance reasons, it is important to pre-fetch all the
0348: // properties we'll need for all the items we'll be searching.
0349:
0350: // We always display the ItemID (OBJECT_ID) and primary descriptor.
0351: int nProperties = 2;
0352:
0353: // We'll need this item type's primary descriptor.
0354: Property p1 = getPrimaryDescriptor(t);
0355:
0356: // Does this item type have a secondary descriptor?
0357: // If so, we'll need it.
0358: Property p2 = getSecondaryDescriptor(t);
0359:
0360: if (p2 != null) {
0361: nProperties++;
0362: }
0363:
0364: // Now, build an array of the property names.
0365: String[] strNames = new String[nProperties];
0366: int iProperty = 0;
0367:
0368: strNames[iProperty++] = s.getPropertyNames().OBJECT_ID;
0369: strNames[iProperty++] = p1.getName();
0370: if (p2 != null) {
0371: strNames[iProperty++] = p2.getName();
0372: }
0373:
0374: // Pre-fetch the item properties and cache them.
0375: f.populateNow(t.getName(), strNames, -1);
0376:
0377: // Now, search for items in the selected folder.
0378: runFolder(s, p, v, t, f, calcTargetFolder(v, f));
0379:
0380: // Free up the memory used by the cached items.
0381: f.discardItems(t.getName(), -1);
0382: }
0383:
0384: /**
0385: * Returns a file object that defines the root of the local checkout tree.
0386: * Depending on the value of targetFolderAbsolute, this will be either the
0387: * targetFolder exactly as set by the user or the path formed by appending
0388: * the default folder onto the specified target folder.
0389: *
0390: * @param v view from which the file is checked out, supplies the "default
0391: * folder"
0392: * @param rootSourceFolder root folder of the checkout operation in Star
0393: * Team
0394: * @return an object referencing the local file
0395: * @see #getTargetFolderAbsolute()
0396: */
0397: private java.io.File calcTargetFolder(View v,
0398: Folder rootSourceFolder) {
0399: java.io.File root = new java.io.File(getTargetFolder());
0400:
0401: if (!getTargetFolderAbsolute()) {
0402: // Create a variable dir that contains the name of
0403: // the StarTeam folder that is the root folder in this view.
0404: // Get the default path to the current view.
0405: String defaultPath = v.getDefaultPath();
0406:
0407: // convert whatever separator char is in starteam to that of the target system.
0408: defaultPath = defaultPath.replace('/',
0409: java.io.File.separatorChar);
0410: defaultPath = defaultPath.replace('\\',
0411: java.io.File.separatorChar);
0412:
0413: java.io.File dir = new java.io.File(defaultPath);
0414: String dirName = dir.getName();
0415:
0416: // If it ends with separator then strip it off
0417: if (dirName.endsWith(delim)) {
0418: dirName = dirName.substring(0, dirName.length() - 1);
0419: }
0420:
0421: // Replace the projectName in the file's absolute path to the viewName.
0422: // This makes the root target of a checkout operation equal to:
0423: // targetFolder + dirName
0424: StringTokenizer pathTokenizer = new StringTokenizer(
0425: rootSourceFolder.getFolderHierarchy(), delim);
0426: String currentToken = null;
0427: boolean foundRoot = false;
0428:
0429: while (pathTokenizer.hasMoreTokens()) {
0430: currentToken = pathTokenizer.nextToken();
0431: if (currentToken.equals(getProjectName()) && !foundRoot) {
0432: currentToken = dirName;
0433: foundRoot = true; // only want to do this the first time
0434: }
0435: root = new java.io.File(root, currentToken);
0436: }
0437: }
0438:
0439: return root;
0440: }
0441:
0442: /**
0443: * Searches for files in the given folder. This method is recursive and
0444: * thus searches all subfolders.
0445: *
0446: * @param s A StarTeam server.
0447: * @param p A valid project on the server.
0448: * @param v A view name from the specified project.
0449: * @param t An item type which is currently always "file".
0450: * @param f The folder to search.
0451: * @param tgt Target folder on local machine
0452: */
0453: protected void runFolder(Server s, com.starbase.starteam.Project p,
0454: View v, Type t, Folder f, java.io.File tgt) {
0455: // Process all items in this folder.
0456: Item[] items = f.getItems(t.getName());
0457:
0458: for (int i = 0; i < items.length; i++) {
0459: runItem(s, p, v, t, f, items[i], tgt);
0460: }
0461:
0462: // Process all subfolders recursively if recursion is on.
0463: if (getRecursion()) {
0464: Folder[] subfolders = f.getSubFolders();
0465:
0466: for (int i = 0; i < subfolders.length; i++) {
0467: runFolder(s, p, v, t, subfolders[i], new java.io.File(
0468: tgt, subfolders[i].getName()));
0469: }
0470: }
0471: }
0472:
0473: /**
0474: * Check out one file if it matches the include filter but not the exclude
0475: * filter.
0476: *
0477: * @param s A StarTeam server.
0478: * @param p A valid project on the server.
0479: * @param v A view name from the specified project.
0480: * @param t An item type which is currently always "file".
0481: * @param f The folder the file is localed in.
0482: * @param item The file to check out.
0483: * @param tgt target folder on local machine
0484: */
0485: protected void runItem(Server s, com.starbase.starteam.Project p,
0486: View v, Type t, Folder f, Item item, java.io.File tgt) {
0487: // Get descriptors for this item type.
0488: Property p1 = getPrimaryDescriptor(t);
0489: Property p2 = getSecondaryDescriptor(t);
0490:
0491: String pName = (String) item.get(p1.getName());
0492:
0493: if (!shouldCheckout(pName)) {
0494: return;
0495: }
0496:
0497: // VERBOSE MODE ONLY
0498: if (getVerbose()) {
0499: // Show folder only if changed.
0500: boolean bShowHeader = (f != prevFolder);
0501:
0502: if (bShowHeader) {
0503: // We want to display the folder the same way you would
0504: // enter it on the command line ... so we remove the
0505: // View name (which is also the name of the root folder,
0506: // and therefore shows up at the start of the path).
0507: String strFolder = f.getFolderHierarchy();
0508: int i = strFolder.indexOf(delim);
0509:
0510: if (i >= 0) {
0511: strFolder = strFolder.substring(i + 1);
0512: }
0513: log(" Folder: \"" + strFolder + "\"");
0514: prevFolder = f;
0515:
0516: // If we displayed the project, view, item type, or folder,
0517: // then show the list of relevant item properties.
0518: StringBuffer header = new StringBuffer(
0519: " Item");
0520:
0521: header.append(",\t").append(p1.getDisplayName());
0522: if (p2 != null) {
0523: header.append(",\t").append(p2.getDisplayName());
0524: }
0525: log(header.toString());
0526: }
0527:
0528: // Finally, show the Item properties ...
0529: // Always show the ItemID.
0530: StringBuffer itemLine = new StringBuffer(" ");
0531:
0532: itemLine.append(item.getItemID());
0533:
0534: // Show the primary descriptor.
0535: // There should always be one.
0536: itemLine.append(",\t").append(
0537: formatForDisplay(p1, item.get(p1.getName())));
0538:
0539: // Show the secondary descriptor, if there is one.
0540: // Some item types have one, some don't.
0541: if (p2 != null) {
0542: itemLine.append(",\t").append(
0543: formatForDisplay(p2, item.get(p2.getName())));
0544: }
0545:
0546: // Show if the file is locked.
0547: int locker = item.getLocker();
0548:
0549: if (locker > -1) {
0550: itemLine.append(",\tLocked by ").append(locker);
0551: } else {
0552: itemLine.append(",\tNot locked");
0553: }
0554: log(itemLine.toString());
0555: }
0556: // END VERBOSE ONLY
0557:
0558: // Check it out; also ugly.
0559:
0560: // Change the item to be checked out to a StarTeam File.
0561: com.starbase.starteam.File remote = (com.starbase.starteam.File) item;
0562:
0563: // The local file name is simply the local target path (tgt) which has
0564: // been passed recursively down from the top of the tree, with the item's name appended.
0565: java.io.File local = new java.io.File(tgt, (String) item.get(p1
0566: .getName()));
0567:
0568: try {
0569: remote.checkoutTo(local, Item.LockType.UNCHANGED, false,
0570: true, true);
0571: checkedOut++;
0572: } catch (Exception e) {
0573: throw new BuildException("Failed to checkout '" + local
0574: + "'", e);
0575: }
0576: }
0577:
0578: /**
0579: * Look if the file should be checked out. Don't check it out if It fits
0580: * no include filters and It fits an exclude filter.
0581: *
0582: * @param pName the item name to look for being included.
0583: * @return whether the file should be checked out or not.
0584: */
0585: protected boolean shouldCheckout(String pName) {
0586: boolean includeIt = matchPatterns(getIncludes(), pName);
0587: boolean excludeIt = matchPatterns(getExcludes(), pName);
0588:
0589: return (includeIt && !excludeIt);
0590: }
0591:
0592: /**
0593: * Convenient method to see if a string match a one pattern in given set
0594: * of space-separated patterns.
0595: *
0596: * @param patterns the space-separated list of patterns.
0597: * @param pName the name to look for matching.
0598: * @return whether the name match at least one pattern.
0599: */
0600: protected boolean matchPatterns(String patterns, String pName) {
0601: if (patterns == null) {
0602: return false;
0603: }
0604: StringTokenizer exStr = new StringTokenizer(patterns, " ");
0605:
0606: while (exStr.hasMoreTokens()) {
0607: if (DirectoryScanner.match(exStr.nextToken(), pName)) {
0608: return true;
0609: }
0610: }
0611: return false;
0612: }
0613:
0614: /**
0615: * Get the primary descriptor of the given item type. Returns null if
0616: * there isn't one. In practice, all item types have a primary descriptor.
0617: *
0618: * @param t An item type. At this point it will always be "file".
0619: * @return The specified item's primary descriptor.
0620: */
0621: protected Property getPrimaryDescriptor(Type t) {
0622: Property[] properties = t.getProperties();
0623:
0624: for (int i = 0; i < properties.length; i++) {
0625: Property p = properties[i];
0626:
0627: if (p.isPrimaryDescriptor()) {
0628: return p;
0629: }
0630: }
0631: return null;
0632: }
0633:
0634: /**
0635: * Get the secondary descriptor of the given item type. Returns null if
0636: * there isn't one.
0637: *
0638: * @param t An item type. At this point it will always be "file".
0639: * @return The specified item's secondary descriptor. There may not be one
0640: * for every file.
0641: */
0642: protected Property getSecondaryDescriptor(Type t) {
0643: Property[] properties = t.getProperties();
0644:
0645: for (int i = 0; i < properties.length; i++) {
0646: Property p = properties[i];
0647:
0648: if (p.isDescriptor() && !p.isPrimaryDescriptor()) {
0649: return p;
0650: }
0651: }
0652: return null;
0653: }
0654:
0655: /**
0656: * Formats a property value for display to the user.
0657: *
0658: * @param p An item property to format.
0659: * @param value the object to format.
0660: * @return A string containing the property, which is truncated to 35
0661: * characters for display.
0662: */
0663: protected String formatForDisplay(Property p, Object value) {
0664: if (p.getTypeCode() == Property.Types.TEXT) {
0665: String str = value.toString();
0666:
0667: if (str.length() > 35) {
0668: str = str.substring(0, 32) + "...";
0669: }
0670: return "\"" + str + "\"";
0671: } else {
0672: if (p.getTypeCode() == Property.Types.ENUMERATED) {
0673: return "\""
0674: + p.getEnumDisplayName(((Integer) value)
0675: .intValue()) + "\"";
0676: } else {
0677: return value.toString();
0678: }
0679: }
0680: }
0681:
0682: // Begin SET and GET methods
0683:
0684: /**
0685: * Sets the <CODE>serverName</CODE> attribute to the given value.
0686: *
0687: * @param serverName The name of the server you wish to connect to.
0688: * @see #getServerName()
0689: */
0690: public void setServerName(String serverName) {
0691: this .serverName = serverName;
0692: }
0693:
0694: /**
0695: * Gets the <CODE>serverName</CODE> attribute.
0696: *
0697: * @return The StarTeam server to log in to.
0698: * @see #setServerName(String serverName)
0699: */
0700: public String getServerName() {
0701: return serverName;
0702: }
0703:
0704: /**
0705: * Sets the <CODE>serverPort</CODE> attribute to the given value. The
0706: * given value must be a valid integer, but it must be a string object.
0707: *
0708: * @param serverPort A string containing the port on the StarTeam server
0709: * to use.
0710: * @see #getServerPort()
0711: */
0712: public void setServerPort(int serverPort) {
0713: this .serverPort = serverPort;
0714: }
0715:
0716: /**
0717: * Gets the <CODE>serverPort</CODE> attribute.
0718: *
0719: * @return A string containing the port on the StarTeam server to use.
0720: * @see #setServerPort(int)
0721: */
0722: public int getServerPort() {
0723: return serverPort;
0724: }
0725:
0726: /**
0727: * Sets the <CODE>projectName</CODE> attribute to the given value.
0728: *
0729: * @param projectName The StarTeam project to search.
0730: * @see #getProjectName()
0731: */
0732: public void setProjectName(String projectName) {
0733: this .projectName = projectName;
0734: }
0735:
0736: /**
0737: * Gets the <CODE>projectName</CODE> attribute.
0738: *
0739: * @return The StarTeam project to search.
0740: * @see #setProjectName(String projectName)
0741: */
0742: public String getProjectName() {
0743: return projectName;
0744: }
0745:
0746: /**
0747: * Sets the <CODE>viewName</CODE> attribute to the given value.
0748: *
0749: * @param viewName The view to find the specified folder in.
0750: * @see #getViewName()
0751: */
0752: public void setViewName(String viewName) {
0753: this .viewName = viewName;
0754: }
0755:
0756: /**
0757: * Gets the <CODE>viewName</CODE> attribute.
0758: *
0759: * @return The view to find the specified folder in.
0760: * @see #setViewName(String viewName)
0761: */
0762: public String getViewName() {
0763: return viewName;
0764: }
0765:
0766: /**
0767: * Sets the <CODE>folderName</CODE> attribute to the given value. To
0768: * search the root folder, use a slash or backslash, or simply don't set a
0769: * folder at all.
0770: *
0771: * @param folderName The subfolder from which to check out files.
0772: * @see #getFolderName()
0773: */
0774: public void setFolderName(String folderName) {
0775: this .folderName = folderName;
0776: }
0777:
0778: /**
0779: * Gets the <CODE>folderName</CODE> attribute.
0780: *
0781: * @return The subfolder from which to check out files. All subfolders
0782: * will be searched, as well.
0783: * @see #setFolderName(String folderName)
0784: */
0785: public String getFolderName() {
0786: return folderName;
0787: }
0788:
0789: /**
0790: * Sets the <CODE>username</CODE> attribute to the given value.
0791: *
0792: * @param username Your username for the specified StarTeam server.
0793: * @see #getUsername()
0794: */
0795: public void setUsername(String username) {
0796: this .username = username;
0797: }
0798:
0799: /**
0800: * Gets the <CODE>username</CODE> attribute.
0801: *
0802: * @return The username given by the user.
0803: * @see #setUsername(String username)
0804: */
0805: public String getUsername() {
0806: return username;
0807: }
0808:
0809: /**
0810: * Sets the <CODE>password</CODE> attribute to the given value.
0811: *
0812: * @param password Your password for the specified StarTeam server.
0813: * @see #getPassword()
0814: */
0815: public void setPassword(String password) {
0816: this .password = password;
0817: }
0818:
0819: /**
0820: * Gets the <CODE>password</CODE> attribute.
0821: *
0822: * @return The password given by the user.
0823: * @see #setPassword(String password)
0824: */
0825: public String getPassword() {
0826: return password;
0827: }
0828:
0829: /**
0830: * Sets the <CODE>targetFolder</CODE> attribute to the given value.
0831: *
0832: * @param targetFolder The target path on the local machine to check out to.
0833: * @see #getTargetFolder()
0834: */
0835: public void setTargetFolder(String targetFolder) {
0836: this .targetFolder = targetFolder;
0837: }
0838:
0839: /**
0840: * Gets the <CODE>targetFolder</CODE> attribute.
0841: *
0842: * @return The target path on the local machine to check out to.
0843: * @see #setTargetFolder(String targetFolder)
0844: */
0845: public String getTargetFolder() {
0846: return targetFolder;
0847: }
0848:
0849: /**
0850: * Sets the <CODE>force</CODE> attribute to the given value.
0851: *
0852: * @param force if true, it overwrites files in the target directory. By
0853: * default it set to false as a safeguard. Note that if the target
0854: * directory does not exist, this setting has no effect.
0855: * @see #getForce()
0856: */
0857: public void setForce(boolean force) {
0858: this .force = force;
0859: }
0860:
0861: /**
0862: * Gets the <CODE>force</CODE> attribute.
0863: *
0864: * @return whether to continue if the target directory exists.
0865: * @see #setForce(boolean)
0866: */
0867: public boolean getForce() {
0868: return force;
0869: }
0870:
0871: /**
0872: * Turns recursion on or off.
0873: *
0874: * @param recursion if it is true, the default, subfolders are searched
0875: * recursively for files to check out. Otherwise, only files
0876: * specified by <CODE>folderName</CODE> are scanned.
0877: * @see #getRecursion()
0878: */
0879: public void setRecursion(boolean recursion) {
0880: this .recursion = recursion;
0881: }
0882:
0883: /**
0884: * Gets the <CODE>recursion</CODE> attribute, which tells
0885: * AntStarTeamCheckOut whether to search subfolders when checking out
0886: * files.
0887: *
0888: * @return whether to search subfolders when checking out files.
0889: * @see #setRecursion(boolean)
0890: */
0891: public boolean getRecursion() {
0892: return recursion;
0893: }
0894:
0895: /**
0896: * Sets the <CODE>verbose</CODE> attribute to the given value.
0897: *
0898: * @param verbose whether to display all files as it checks them out. By
0899: * default it is false, so the program only displays the total number
0900: * of files unless you override this default.
0901: * @see #getVerbose()
0902: */
0903: public void setVerbose(boolean verbose) {
0904: this .verbose = verbose;
0905: }
0906:
0907: /**
0908: * Gets the <CODE>verbose</CODE> attribute.
0909: *
0910: * @return whether to display all files as it checks them out.
0911: * @see #setVerbose(boolean verbose)
0912: */
0913: public boolean getVerbose() {
0914: return verbose;
0915: }
0916:
0917: // Begin filter getters and setters
0918:
0919: /**
0920: * Sets the include filter. When filtering files, AntStarTeamCheckOut uses
0921: * an unmodified version of <CODE>DirectoryScanner</CODE>'s <CODE>match</CODE>
0922: * method, so here are the patterns straight from the Ant source code:
0923: * <BR>
0924: * <BR>
0925: * Matches a string against a pattern. The pattern contains two special
0926: * characters: <BR>
0927: * '*' which means zero or more characters, <BR>
0928: * '?' which means one and only one character. <BR>
0929: * <BR>
0930: * Separate multiple inlcude filters by <I>spaces</I> , not commas as Ant
0931: * uses. For example, if you want to check out all .java and .class\
0932: * files, you would put the following line in your program:
0933: * <CODE>setIncludes("*.java *.class");</CODE>
0934: * Finally, note that filters have no effect on the <B>directories</B>
0935: * that are scanned; you could not check out files from directories with
0936: * names beginning only with "build," for instance. Of course, you could
0937: * limit AntStarTeamCheckOut to a particular folder and its subfolders
0938: * with the <CODE>setFolderName(String folderName)</CODE> command. <BR>
0939: * <BR>
0940: * Treatment of overlapping inlcudes and excludes: To give a simplistic
0941: * example suppose that you set your include filter to "*.htm *.html" and
0942: * your exclude filter to "index.*". What happens to index.html?
0943: * AntStarTeamCheckOut will not check out index.html, as it matches an
0944: * exclude filter ("index.*"), even though it matches the include filter,
0945: * as well. <BR>
0946: * <BR>
0947: * Please also read the following sections before using filters:
0948: *
0949: * @param includes A string of filter patterns to include. Separate the
0950: * patterns by spaces.
0951: * @see #getIncludes()
0952: * @see #setExcludes(String excludes)
0953: * @see #getExcludes()
0954: */
0955: public void setIncludes(String includes) {
0956: this .includes = includes;
0957: }
0958:
0959: /**
0960: * Gets the patterns from the include filter. Rather that duplicate the
0961: * details of AntStarTeanCheckOut's filtering here, refer to these links:
0962: *
0963: * @return A string of filter patterns separated by spaces.
0964: * @see #setIncludes(String includes)
0965: * @see #setExcludes(String excludes)
0966: * @see #getExcludes()
0967: */
0968: public String getIncludes() {
0969: return includes;
0970: }
0971:
0972: /**
0973: * Sets the exclude filter. When filtering files, AntStarTeamCheckOut uses
0974: * an unmodified version of <CODE>DirectoryScanner</CODE>'s <CODE>match</CODE>
0975: * method, so here are the patterns straight from the Ant source code:
0976: * <BR>
0977: * <BR>
0978: * Matches a string against a pattern. The pattern contains two special
0979: * characters: <BR>
0980: * '*' which means zero or more characters, <BR>
0981: * '?' which means one and only one character. <BR>
0982: * <BR>
0983: * Separate multiple exlcude filters by <I>spaces</I> , not commas as Ant
0984: * uses. For example, if you want to check out all files except .XML and
0985: * .HTML files, you would put the following line in your program:
0986: * <CODE>setExcludes("*.XML *.HTML");</CODE>
0987: * Finally, note that filters have no effect on the <B>directories</B>
0988: * that are scanned; you could not skip over all files in directories
0989: * whose names begin with "project," for instance. <BR>
0990: * <BR>
0991: * Treatment of overlapping inlcudes and excludes: To give a simplistic
0992: * example suppose that you set your include filter to "*.htm *.html" and
0993: * your exclude filter to "index.*". What happens to index.html?
0994: * AntStarTeamCheckOut will not check out index.html, as it matches an
0995: * exclude filter ("index.*"), even though it matches the include filter,
0996: * as well. <BR>
0997: * <BR>
0998: * Please also read the following sections before using filters:
0999: *
1000: * @param excludes A string of filter patterns to exclude. Separate the
1001: * patterns by spaces.
1002: * @see #setIncludes(String includes)
1003: * @see #getIncludes()
1004: * @see #getExcludes()
1005: */
1006: public void setExcludes(String excludes) {
1007: this .excludes = excludes;
1008: }
1009:
1010: /**
1011: * Gets the patterns from the exclude filter. Rather that duplicate the
1012: * details of AntStarTeanCheckOut's filtering here, refer to these links:
1013: *
1014: * @return A string of filter patterns separated by spaces.
1015: * @see #setExcludes(String excludes)
1016: * @see #setIncludes(String includes)
1017: * @see #getIncludes()
1018: */
1019: public String getExcludes() {
1020: return excludes;
1021: }
1022:
1023: /**
1024: * returns whether the StarTeam default path is factored into calculated
1025: * target path locations (false) or whether targetFolder is an absolute
1026: * mapping to the root folder named by folderName
1027: *
1028: * @return returns true if absolute mapping is used, false if it is not
1029: * used.
1030: * @see #setTargetFolderAbsolute(boolean)
1031: */
1032: public boolean getTargetFolderAbsolute() {
1033: return this .targetFolderAbsolute;
1034: }
1035:
1036: /**
1037: * sets the property that indicates whether or not the Star Team "default
1038: * folder" is to be used when calculation paths for items on the target
1039: * (false) or if targetFolder is an absolute mapping to the root folder
1040: * named by foldername.
1041: *
1042: * @param targetFolderAbsolute <tt>true</tt> if the absolute mapping is to
1043: * be used. <tt>false</tt> (the default) if the "default folder" is
1044: * to be factored in.
1045: * @see #getTargetFolderAbsolute()
1046: */
1047: public void setTargetFolderAbsolute(boolean targetFolderAbsolute) {
1048: this.targetFolderAbsolute = targetFolderAbsolute;
1049: }
1050: }
|