/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package org.apache.tools.ant.taskdefs.optional.starteam;
import com.starbase.starteam.Folder;
import com.starbase.starteam.Item;
import com.starbase.starteam.Status;
import com.starbase.starteam.View;
import com.starbase.starteam.ViewConfiguration;
import java.io.IOException;
import java.io.File;
import java.util.Enumeration;
import java.util.Hashtable;
import org.apache.tools.ant.BuildException;
import org.apache.tools.ant.Project;
/**
* Checks out files from a StarTeam project.
* It also creates all working directories on the
* local directory if appropriate. Ant Usage:
* <pre>
* <taskdef name="starteamcheckout"
* classname="org.apache.tools.ant.taskdefs.StarTeamCheckout"/>
* <starteamcheckout username="BuildMaster" password="ant" starteamFolder="Source"
* starteamurl="servername:portnum/project/view"
* createworkingdirectories="true"/>
* </pre>
*
* @version 1.1
* @see <a href="http://www.borland.com/us/products/starteam/index.html"
* >borland StarTeam Web Site</a>
*
* @ant.task name="stcheckout" category="scm"
*/
public class StarTeamCheckout extends TreeBasedTask {
/**
* holder for the createDirs attribute
*/
private boolean createDirs = true;
/**
* holder for the deleteUncontrolled attribute. If true,
* all local files not in StarTeam will be deleted.
*/
private boolean deleteUncontrolled = true;
/**
* holder for the deleteUncontrolled attribute. If true,
* (default) local non-binary files will be checked out using the local
* platform's EOL convention. If false, checkouts will preserve the
* server's EOL convention.
*/
private boolean convertEOL = true;
/**
* flag (defaults to true) to create all directories
* that are in the Starteam repository even if they are empty.
*
* @param value the value to set the attribute to.
*/
public void setCreateWorkingDirs(boolean value) {
this.createDirs = value;
}
/**
* Whether or not all local files <i>not<i> in StarTeam should be deleted.
* Optional, defaults to <code>true</code>.
* @param value the value to set the attribute to.
*/
public void setDeleteUncontrolled(boolean value) {
this.deleteUncontrolled = value;
}
/**
* Set whether or not files should be checked out using the
* local machine's EOL convention.
* Optional, defaults to <code>true</code>.
* @param value the value to set the attribute to.
*/
public void setConvertEOL(boolean value) {
this.convertEOL = value;
}
/**
* Sets the label StarTeam is to use for checkout; defaults to the most recent file.
* The label must exist in starteam or an exception will be thrown.
* @param label the label to be used
*/
public void setLabel(String label) {
_setLabel(label);
}
/**
* This attribute tells whether to do a locked checkout, an unlocked
* checkout or to leave the checkout status alone (default). A locked
* checkout locks all other users out from making changes. An unlocked
* checkout reverts all local files to their previous repository status
* and removes the lock.
* @see #setLocked(boolean)
* @see #setUnlocked(boolean)
*/
private int lockStatus = Item.LockType.UNCHANGED;
/**
* Set to do a locked checkout; optional default is false.
* @param v True to do a locked checkout, false to checkout without
* changing status/.
* @exception BuildException if both locked and unlocked are set true
*/
public void setLocked(boolean v) throws BuildException {
setLockStatus(v, Item.LockType.EXCLUSIVE);
}
/**
* Set to do an unlocked checkout. Default is false;
* @param v True to do an unlocked checkout, false to checkout without
* changing status.
* @exception BuildException if both locked and unlocked are set true
*/
public void setUnlocked(boolean v) throws BuildException {
setLockStatus(v, Item.LockType.UNLOCKED);
}
private void setLockStatus(boolean v, int newStatus)
throws BuildException {
if (v) {
if (this.lockStatus == Item.LockType.UNCHANGED) {
this.lockStatus = newStatus;
} else if (this.lockStatus != newStatus) {
throw new BuildException(
"Error: cannot set locked and unlocked both true.");
}
}
}
/**
* should checked out files get the timestamp from the repository
* or the time they are checked out. True means use the repository
* timestamp.
*/
private boolean useRepositoryTimeStamp = false;
/**
* sets the useRepositoryTimestmp member.
*
* @param useRepositoryTimeStamp
* true means checked out files will get the repository timestamp.
* false means the checked out files will be timestamped at the time
* of checkout.
*/
public void setUseRepositoryTimeStamp(boolean useRepositoryTimeStamp) {
this.useRepositoryTimeStamp = useRepositoryTimeStamp;
}
/**
* returns the value of the useRepositoryTimestamp member
*
* @return the value of the useRepositoryTimestamp member
*/
public boolean getUseRepositoryTimeStamp() {
return this.useRepositoryTimeStamp;
}
/**
* List files, dates, and statuses as of this date; optional.
* If not specified, the most recent version of each file will be listed.
*
* @param asOfDateParam the date as of which the listing to be made
* @since Ant 1.6
*/
public void setAsOfDate(String asOfDateParam) {
_setAsOfDate(asOfDateParam);
}
/**
* Date Format with which asOfDate parameter to be parsed; optional.
* Must be a SimpleDateFormat compatible string.
* If not specified, and asOfDateParam is specified, parse will use ISO8601
* datetime and date formats.
*
* @param asOfDateFormat the SimpleDateFormat-compatible format string
* @since Ant 1.6
*/
public void setAsOfDateFormat(String asOfDateFormat) {
_setAsOfDateFormat(asOfDateFormat);
}
/**
* Override of base-class abstract function creates an
* appropriately configured view for checkouts - either
* the current view or a view from this.label or the raw
* view itself in the case of a revision label.
*
* @param raw the unconfigured <code>View</code>
*
* @return the snapshot <code>View</code> appropriately configured.
* @exception BuildException on error
*/
protected View createSnapshotView(View raw) throws BuildException {
int labelID = getLabelID(raw);
// if a label has been supplied and it is a view label, use it
// to configure the view
if (this.isUsingViewLabel()) {
return new View(raw, ViewConfiguration.createFromLabel(labelID));
// if a label has been supplied and it is a revision label, use the raw
// the view as the snapshot
} else if (this.isUsingRevisionLabel()) {
return raw;
}
// if a date has been supplied use a view configured to the date.
View view = getViewConfiguredByDate(raw);
if (view != null) {
return view;
// otherwise, use this view configured as the tip.
} else {
return new View(raw, ViewConfiguration.createTip());
}
}
/**
* Implements base-class abstract function to define tests for
* any preconditons required by the task.
*
* @exception BuildException thrown if both rootLocalFolder
* and viewRootLocalFolder are defined
*/
protected void testPreconditions() throws BuildException {
if (this.isUsingRevisionLabel() && this.createDirs) {
log("Ignoring createworkingdirs while using a revision label."
+ " Folders will be created only as needed.",
Project.MSG_WARN);
this.createDirs = false;
}
if (lockStatus != Item.LockType.UNCHANGED) {
boolean lockStatusBad = false;
if (null != getLabel()) {
log("Neither locked nor unlocked may be true"
+ " when checking out a labeled version.",
Project.MSG_ERR);
lockStatusBad = true;
} else if (null != getAsOfDate()) {
log("Neither locked nor unlocked may be true"
+ " when checking out by date.",
Project.MSG_ERR);
lockStatusBad = true;
}
if (lockStatusBad) {
throw new BuildException(
"Lock status may not be changed"
+ " when checking out a non-current version.");
}
}
if (null != getLabel() && null != getAsOfDate()) {
throw new BuildException(
"Both label and asOfDate specified. "
+ "Unable to process request.");
}
}
/**
* 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 void logOperationDescription(
Folder starteamrootFolder, java.io.File targetrootFolder) {
log((this.isRecursive() ? "Recursive" : "Non-recursive")
+ " Checkout from: " + starteamrootFolder.getFolderHierarchy());
log(" Checking out to"
+ (null == getRootLocalFolder() ? "(default): " : ": ")
+ targetrootFolder.getAbsolutePath());
logLabel();
logAsOfDate();
logIncludes();
logExcludes();
if (this.lockStatus == Item.LockType.EXCLUSIVE) {
log(" Items will be checked out with Exclusive locks.");
} else if (this.lockStatus == Item.LockType.UNLOCKED) {
log(" Items will be checked out unlocked "
+ "(even if presently locked).");
} else {
log(" Items will be checked out with no change in lock status.");
}
log(" Items will be checked out with "
+ (this.useRepositoryTimeStamp ? "repository timestamps."
: "the current timestamp."));
log(" Items will be checked out "
+ (this.isForced() ? "regardless of" : "in accordance with")
+ " repository status.");
if (this.deleteUncontrolled) {
log(" Local items not found in the repository will be deleted.");
}
log(" Items will be checked out "
+ (this.convertEOL ? "using the local machine's EOL convention"
: "without changing the EOL convention used on the server"));
log(" Directories will be created"
+ (this.createDirs ? " wherever they exist in the repository, even if empty."
: " only where needed to check out files."));
}
/**
* Implements base-class abstract function to perform the checkout
* operation on the files in each folder of the tree.
*
* @param starteamFolder the StarTeam folder from which files to be
* checked out
* @param targetFolder the local mapping of rootStarteamFolder
* @exception BuildException if any error occurs
*/
protected void visit(Folder starteamFolder, java.io.File targetFolder)
throws BuildException {
try {
if (null != getRootLocalFolder()) {
starteamFolder.setAlternatePathFragment(
targetFolder.getAbsolutePath());
}
if (!targetFolder.exists()) {
if (!this.isUsingRevisionLabel()) {
if (this.createDirs) {
if (targetFolder.mkdirs()) {
log("Creating folder: " + targetFolder);
} else {
throw new BuildException(
"Failed to create local folder " + targetFolder);
}
}
}
}
Folder[] foldersList = starteamFolder.getSubFolders();
Item[] filesList = starteamFolder.getItems(getTypeNames().FILE);
if (this.isUsingRevisionLabel()) {
// prune away any files not belonging to the revision label
// this is one ugly API from Starteam SDK
Hashtable labelItems = new Hashtable(filesList.length);
int s = filesList.length;
int[] ids = new int[s];
for (int i = 0; i < s; i++) {
ids[i] = filesList[i].getItemID();
labelItems.put(new Integer(ids[i]), new Integer(i));
}
int[] foundIds = getLabelInUse().getLabeledItemIDs(ids);
s = foundIds.length;
Item[] labeledFiles = new Item[s];
for (int i = 0; i < s; i++) {
Integer id = new Integer(foundIds[i]);
labeledFiles[i] =
filesList[((Integer) labelItems.get(id)).intValue()];
}
filesList = labeledFiles;
}
// note, it's important to scan the items BEFORE we make the
// Unmatched file map because that creates a bunch of NEW
// folders and files (unattached to repository) and we
// don't want to include those in our traversal.
UnmatchedFileMap ufm =
new CheckoutMap().
init(targetFolder.getAbsoluteFile(), starteamFolder);
for (int i = 0; i < foldersList.length; i++) {
Folder stFolder = foldersList[i];
java.io.File subfolder =
new java.io.File(targetFolder, stFolder.getName());
ufm.removeControlledItem(subfolder);
if (isRecursive()) {
visit(stFolder, subfolder);
}
}
for (int i = 0; i < filesList.length; i++) {
com.starbase.starteam.File stFile =
(com.starbase.starteam.File) filesList[i];
processFile(stFile, targetFolder);
ufm.removeControlledItem(
new java.io.File(targetFolder, stFile.getName()));
}
if (this.deleteUncontrolled) {
ufm.processUncontrolledItems();
}
} catch (IOException e) {
throw new BuildException(e);
}
}
/**
* provides a string showing from and to full paths for logging
*
* @param remotefile the Star Team file being processed.
*
* @return a string showing from and to full paths
*/
private String describeCheckout(com.starbase.starteam.File remotefile,
java.io.File localFile) {
StringBuffer sb = new StringBuffer();
sb.append(getFullRepositoryPath(remotefile))
.append(" --> ");
if (null == localFile) {
sb.append(remotefile.getFullName());
} else {
sb.append(localFile);
}
return sb.toString();
}
private String describeCheckout(com.starbase.starteam.File remotefile) {
return describeCheckout(remotefile, null);
}
/**
* Processes (checks out) <code>stFiles</code>files from StarTeam folder.
*
* @param eachFile repository file to process
* @param targetFolder a java.io.File (Folder) to work
* @throws IOException when StarTeam API fails to work with files
*/
private void processFile(com.starbase.starteam.File eachFile,
File targetFolder)
throws IOException {
String filename = eachFile.getName();
java.io.File localFile = new java.io.File(targetFolder, filename);
// If the file doesn't pass the include/exclude tests, skip it.
if (!shouldProcess(filename)) {
log("Excluding " + getFullRepositoryPath(eachFile),
Project.MSG_INFO);
return;
}
if (this.isUsingRevisionLabel()) {
if (!targetFolder.exists()) {
if (targetFolder.mkdirs()) {
log("Creating folder: " + targetFolder);
} else {
throw new BuildException(
"Failed to create local folder " + targetFolder);
}
}
boolean success = eachFile.checkoutByLabelID(
localFile,
getIDofLabelInUse(),
this.lockStatus,
!this.useRepositoryTimeStamp,
true,
false);
if (success) {
log("Checked out " + describeCheckout(eachFile, localFile));
}
} else {
boolean checkout = true;
// Just a note: StarTeam has a status for NEW which implies
// that there is an item on your local machine that is not
// in the repository. These are the items that show up as
// NOT IN VIEW in the Starteam GUI.
// One would think that we would want to perhaps checkin the
// NEW items (not in all cases! - Steve Cohen 15 Dec 2001)
// Unfortunately, the sdk doesn't really work, and we can't
// actually see anything with a status of NEW. That is why
// we can just check out everything here without worrying
// about losing anything.
int fileStatus = (eachFile.getStatus());
// We try to update the status once to give StarTeam
// another chance.
if (fileStatus == Status.MERGE
|| fileStatus == Status.UNKNOWN) {
eachFile.updateStatus(true, true);
fileStatus = (eachFile.getStatus());
}
log(eachFile.toString() + " has status of "
+ Status.name(fileStatus), Project.MSG_DEBUG);
switch (fileStatus) {
case Status.OUTOFDATE:
case Status.MISSING:
log("Checking out: " + describeCheckout(eachFile));
break;
default:
if (isForced() && fileStatus != Status.CURRENT) {
log("Forced checkout of "
+ describeCheckout(eachFile)
+ " over status " + Status.name(fileStatus));
} else {
log("Skipping: " + getFullRepositoryPath(eachFile)
+ " - status: " + Status.name(fileStatus));
checkout = false;
}
}
if (checkout) {
if (!targetFolder.exists()) {
if (targetFolder.mkdirs()) {
log("Creating folder: " + targetFolder);
} else {
throw new BuildException(
"Failed to create local folder " + targetFolder);
}
}
eachFile.checkout(this.lockStatus,
!this.useRepositoryTimeStamp, this.convertEOL, false);
}
}
}
/**
* handles the deletion of uncontrolled items
*/
private class CheckoutMap extends UnmatchedFileMap {
protected boolean isActive() {
return StarTeamCheckout.this.deleteUncontrolled;
}
/**
* override of the base class init. It can be much simpler, since
* the action to be taken is simply to delete the local files. No
* further interaction with the repository is necessary.
*
* @param localFolder
* the local folder from which the mappings will be made.
* @param remoteFolder
* not used in this implementation
*/
UnmatchedFileMap init(java.io.File localFolder, Folder remoteFolder) {
if (!localFolder.exists()) {
return this;
}
String[] localFiles = localFolder.list();
// PR 31965 says that it can return null
if (localFiles == null) {
return this;
}
for (int i = 0; i < localFiles.length; i++) {
java.io.File localFile =
new java.io.File(localFolder, localFiles[i]).getAbsoluteFile();
log("adding " + localFile + " to UnmatchedFileMap",
Project.MSG_DEBUG);
if (localFile.isDirectory()) {
this.put(localFile, "");
} else {
this.put(localFile, "");
}
}
return this;
}
/**
* deletes uncontrolled items from the local tree. It is assumed
* that this method will not be called until all the items in the
* corresponding folder have been processed, and that the internal map
* will contain only uncontrolled items.
*/
void processUncontrolledItems() throws BuildException {
if (this.isActive()) {
Enumeration e = this.keys();
while (e.hasMoreElements()) {
java.io.File local = (java.io.File) e.nextElement();
delete(local);
}
}
}
/**
* deletes all files and if the file is a folder recursively deletes
* everything in it.
*
* @param local The local file or folder to be deleted.
*/
void delete(java.io.File local) {
// once we find a folder that isn't in the repository,
// anything below it can be deleted.
if (local.isDirectory() && isRecursive()) {
String[] contents = local.list();
for (int i = 0; i < contents.length; i++) {
java.io.File file = new java.io.File(local, contents[i]);
delete(file);
}
}
local.delete();
log("Deleted uncontrolled item " + local.getAbsolutePath());
}
}
}
|
