com.microsoft.tfs.core.clients.versioncontrol
Class VersionControlClient

java.lang.Object
  extended by com.microsoft.tfs.core.clients.versioncontrol.VersionControlClient
All Implemented Interfaces:
com.microsoft.tfs.util.Closable

public final class VersionControlClient
extends java.lang.Object
implements com.microsoft.tfs.util.Closable

Performs client tasks for source control, including workspace management, item status, history, labels, branching, etc., communicating with the Team Foundation Server when necessary.

This class publishes several events. To register for event notification, get the VersionControlEventEngine from your instance using getEventEngine(), then add listeners to it.

Don't create an instance of this class directly, instead use TFSTeamProjectCollection.getVersionControlClient().

Since:
TEE-SDK-10.1
Thread-safety:
thread-compatible

Field Summary
static com.microsoft.tfs.util.GUID WORKSPACE_SECURITY_NAMESPACE_ID
          GUID This is the set of namespaces that exist in the version control.
 
Constructor Summary
  VersionControlClient(TFSTeamProjectCollection connection, ms.tfs.versioncontrol.clientservices._03._RepositorySoap repository, ms.tfs.versioncontrol.clientservices._03._RepositoryExtensionsSoap repositoryExtensions, ms.tfs.versioncontrol.clientservices._03._Repository4Soap repository4, ms.tfs.versioncontrol.clientservices._03._Repository5Soap repository5)
          Creates a VersionControlClient that will use the given web service proxy class and the given connection.
protected VersionControlClient(TFSTeamProjectCollection connection, ms.tfs.versioncontrol.clientservices._03._RepositorySoap webService, ms.tfs.versioncontrol.clientservices._03._RepositoryExtensionsSoap webServiceExtensions, ms.tfs.versioncontrol.clientservices._03._Repository4Soap repository4, ms.tfs.versioncontrol.clientservices._03._Repository5Soap repository5, int maximumGetEngineWorkerThreads, int getEngineWorkerThreadIdleTimeoutSeconds)
           Creates a VersionControlClient that will use the given web service proxy class and the given connection.
 
Method Summary
 Conflict[] autoResolveValidConflicts(Workspace workspace, Conflict[] conflicts, AutoResolveOptions resolveOptions)
          Takes a list of candidates for AutoResolve and attempts to resolve them with the correct resolution and performing a content merge if necessary.
 PostMethod beginUploadRequest()
          Begins a file upload.
 void close()
          
 void createAnnotation(java.lang.String annotationName, java.lang.String annotatedServerItem, int version, java.lang.String annotationValue, java.lang.String comment, boolean overwrite)
          Creates an annotation.
 int createBranch(java.lang.String sourceServerPath, java.lang.String targetServerPath, VersionSpec version)
          Creates a branch of the given source path at the given version to the given target path.
 int createBranch(java.lang.String sourceServerPath, java.lang.String targetServerPath, VersionSpec version, java.lang.String owner, java.lang.String comment, CheckinNote checkinNote, PolicyOverrideInfo policyOverride, Mapping[] mappings)
          Creates a branch of the given source path at the given version to the given target path.
 LabelResult[] createLabel(VersionControlLabel label, LabelItemSpec[] items, LabelChildOption options)
          Create or update a label for items in this workspace.
 Workspace createWorkspace(WorkingFolder[] workingFolders, java.lang.String workspaceName, java.lang.String owner, java.lang.String ownerDisplayName, java.lang.String comment, WorkspaceLocation location, WorkspaceOptions options)
          Create a workspace on the server.
 Workspace createWorkspace(WorkingFolder[] workingFolders, java.lang.String workspaceName, java.lang.String owner, java.lang.String ownerDisplayName, java.lang.String comment, WorkspaceLocation location, WorkspaceOptions options, WorkspacePermissionProfile permissionProfile)
           
 Workspace createWorkspace(WorkingFolder[] workingFolders, java.lang.String workspaceName, java.lang.String comment, WorkspaceLocation location, WorkspaceOptions options)
          Create a workspace on the server.
 Workspace createWorkspace(WorkingFolder[] workingFolders, java.lang.String workspaceName, java.lang.String comment, WorkspaceLocation location, WorkspaceOptions options, WorkspacePermissionProfile permissionProfile)
           
 void deleteAnnotation(java.lang.String annotationName, java.lang.String annotatedServerItem, int version, java.lang.String annotationValue)
          Deletes an annotation.
 void deleteBranchObject(ItemIdentifier branch)
          Deletes a branch object.
 LabelResult[] deleteLabel(java.lang.String label, java.lang.String scope)
          Deletes the specified label.
 void deleteShelveset(java.lang.String name, java.lang.String owner)
          Delete a shelveset on the server.
 void deleteWorkspace(Workspace workspace)
          Delete a workspace on the server.
 Item[] destroy(ItemSpec itemSpec, VersionSpec versionSpec, VersionSpec stopAt, DestroyFlags flags)
          Permanently destroys a versioned item.
 Item[] destroy(ItemSpec itemSpec, VersionSpec versionSpec, VersionSpec stopAt, DestroyFlags flags, java.util.List<PendingSet> affectedPendingChanges, java.util.List<PendingSet> affectedShelvedChanges)
          Permanently destroys a versioned item.
 void determineWorkspaceNameAndOwner(ItemSpec[] itemSpecs, java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceName, java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceOwner)
          Determine the workspace name and owner for all given items which are local paths.
 void determineWorkspaceNameAndOwner(ItemSpec itemSpec, java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceName, java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceOwner)
           
 void determineWorkspaceNameAndOwner(LabelItemSpec[] labelItemSpecs, java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceName, java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceOwner)
           
 void determineWorkspaceNameAndOwner(SecurityChange[] securityChanges, java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceName, java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceOwner)
           
 void determineWorkspaceNameAndOwner(java.lang.String[] paths, java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceName, java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceOwner)
           
 void determineWorkspaceNameAndOwner(java.lang.String path, java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceName, java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceOwner)
           
 void downloadFile(DownloadSpec spec, java.io.File destinationFile, boolean autoGunzip)
           
 void downloadFile(DownloadSpec spec, java.io.File destinationFile, boolean autoGunzip, EventSource eventSource, TaskMonitor taskMonitor)
          Download the file described by spec to the destination file.
 void downloadFileToStream(DownloadSpec spec, java.io.OutputStream outputStream, boolean autoGunzip)
          This convenience method does not support retrying downloads that failed with transient network problems.
 void downloadFileToStream(DownloadSpec spec, java.io.OutputStream outputStream, boolean autoGunzip, EventSource eventSource, TaskMonitor taskMonitor)
          This convenience method does not support retrying downloads that failed with transient network problems.
 void downloadFileToStreams(DownloadSpec spec, DownloadOutput[] outputs, EventSource eventSource, TaskMonitor taskMonitor)
          Download the file described by spec to the destination stream or streams.
 java.io.File downloadFileToTempLocation(DownloadSpec spec, java.lang.String fileName)
          Downloads a file to a temporary location (created by the method), gunzipping if necessary.
 java.lang.String downloadItems(Item[] items, java.lang.String serverRoot, java.lang.String localRoot)
          Downloads a collection of Items to a temporary location preserving the server path structure.
 void executeUploadRequest(PostMethod method)
          Executes a file upload.
 void finishUploadRequest(PostMethod method)
          Finishes a file upload.
 Changeset getChangeset(int changesetID)
          Gets Changeset information including individual change information, excluding download information.
 Changeset getChangeset(int changesetID, boolean includeChanges, boolean includeDownloadInfo, java.lang.String[] changesetPropertyFilters, java.lang.String[] itemPropertyFilters)
          Gets the Changeset object that describes the given changeset ID.
 Change[] getChangesForChangeset(int changesetID, boolean includeDownloadInfo, int pageSize, ItemSpec lastItem, java.lang.String[] itemPropertyFilters, boolean includeMergeSourceInfo)
          Gets the changes within a changeset Allows the caller to page changes back from the server.
 PolicyDefinition[] getCheckinPoliciesForServerPaths(java.lang.String[] serverPaths)
          Gets the checkin policies defined for the given server paths, which must be team projects.
 TFSTeamProjectCollection getConnection()
           
 java.lang.String[] getDefaultItemPropertyFilters()
          Gets the list of item property filters automatically appended to the specified filters in methods that send item property filters to the server.
protected  java.net.URI getDownloadURI()
           
 VersionControlEventEngine getEventEngine()
           
 ExtendedItem[][] getExtendedItems(ItemSpec[] itemSpecs, DeletedState deletedState, ItemType itemType)
           
 ExtendedItem[][] getExtendedItems(ItemSpec[] itemSpecs, DeletedState deletedState, ItemType itemType, GetItemsOptions options)
           
 ExtendedItem[] getExtendedItems(java.lang.String itemPath, DeletedState deletedState, ItemType itemType)
           
 ExtendedItem[][] getExtendedItems(java.lang.String workspaceName, java.lang.String workspaceOwner, ItemSpec[] itemSpecs, DeletedState deletedState, ItemType itemType, GetItemsOptions options)
           
 ExtendedItem[][] getExtendedItems(java.lang.String workspaceName, java.lang.String workspaceOwner, ItemSpec[] itemSpecs, DeletedState deletedState, ItemType itemType, GetItemsOptions options, java.lang.String[] itemPropertyFilters)
          Gets extended information about items, with full results control.
 FileType[] getFileTypes()
           
 Item getItem(int itemID, int changesetNumber)
           
 Item getItem(int itemID, int changesetNumber, boolean includeDownloadInfo)
           
 Item getItem(int itemID, int changesetNumber, GetItemsOptions options)
           
 Item getItem(java.lang.String path)
           
 Item getItem(java.lang.String path, VersionSpec version)
           
 Item getItem(java.lang.String path, VersionSpec version, DeletedState deletedState)
           
 Item getItem(java.lang.String path, VersionSpec version, DeletedState deletedState, boolean includeDownloadInfo)
           
 Item getItem(java.lang.String path, VersionSpec version, DeletedState deletedState, GetItemsOptions options)
          Gets information about one item.
 Item getItem(java.lang.String path, VersionSpec version, int deletionID)
           
 Item getItem(java.lang.String path, VersionSpec version, int deletionID, boolean includeDownloadInfo)
           
 Item getItem(java.lang.String path, VersionSpec version, int deletionID, GetItemsOptions options)
           
 Item[] getItems(int[] itemIDs, int changesetNumber)
           
 Item[] getItems(int[] itemIDs, int changesetNumber, boolean includeDownloadInfo)
           
 Item[] getItems(int[] itemIDs, int changesetNumber, GetItemsOptions options)
           
 ItemSet[] getItems(ItemSpec[] itemSpecs, VersionSpec version, DeletedState deletedState, ItemType itemType)
           
 ItemSet[] getItems(ItemSpec[] itemSpecs, VersionSpec version, DeletedState deletedState, ItemType itemType, boolean includeDownloadInfo)
           
 ItemSet[] getItems(ItemSpec[] itemSpecs, VersionSpec version, DeletedState deletedState, ItemType itemType, GetItemsOptions options)
           
 ItemSet[] getItems(ItemSpec[] itemSpecs, VersionSpec version, DeletedState deletedState, ItemType itemType, GetItemsOptions options, java.lang.String[] itemPropertyFilters)
          Gets information about multiple items.
 ItemSet getItems(ItemSpec itemSpec, VersionSpec version, DeletedState deletedState, ItemType itemType, boolean includeDownloadInfo)
           
 ItemSet getItems(ItemSpec itemSpec, VersionSpec version, DeletedState deletedState, ItemType itemType, GetItemsOptions options)
           
 ItemSet getItems(java.lang.String path)
           
 ItemSet getItems(java.lang.String path, RecursionType recursion)
           
 ItemSet getItems(java.lang.String path, VersionSpec version, RecursionType recursion)
           
 ItemSet getItems(java.lang.String path, VersionSpec version, RecursionType recursion, DeletedState deletedState, ItemType itemType)
           
 ItemSet getItems(java.lang.String path, VersionSpec version, RecursionType recursion, DeletedState deletedState, ItemType itemType, boolean includeDownloadInfo)
           
 int getLatestChangesetID()
          Gets the latest changeset ID from the server.
 Workspace getLocalWorkspace(java.lang.String localPath, boolean throwIfNotFound)
          Gets the workspace containing a mapping for the given path.
 Workspace getLocalWorkspace(java.lang.String workspaceName, java.lang.String workspaceOwner)
          Look up the local workspace for the specified repository, workspaceName and workspaceOwner combo.
 int getMaxServerPathLength()
           
 MergeCandidate[] getMergeCandidates(java.lang.String sourcePath, java.lang.String targetPath, RecursionType recursion, MergeFlags mergeFlags)
          Look up the merge candidates for merging between the requested items.
 PathWatcherFactory getPathWatcherFactory()
          Gets the factory used to construct PathWatchers for local workspaces.
 Workspace getRepositoryWorkspace(java.lang.String workspaceName, java.lang.String workspaceOwner)
          Retrieve the specified workspace directly from the repository server.
 Workspace[] getRepositoryWorkspaces(java.lang.String workspaceName, java.lang.String workspaceOwner, java.lang.String computer)
          Get a list of matching workspaces.
 Workspace[] getRepositoryWorkspaces(java.lang.String workspaceName, java.lang.String workspaceOwner, java.lang.String computer, WorkspacePermissions permissionsFilter)
          Get a list of matching workspaces.
 com.microsoft.tfs.core.clients.versioncontrol.workspacecache.internal.RuntimeWorkspaceCache getRuntimeWorkspaceCache()
          This method is for internal use only.
 com.microsoft.tfs.util.GUID getServerGUID()
           
 ServerSettings getServerSettingsWithFallback(java.util.concurrent.atomic.AtomicBoolean fallbackUsed)
          Gets ServerSettings from the Server if available If not, it will return a settings object with appropriate defaults.
 SupportedFeatures getServerSupportedFeatures()
          Gets the SupportedFeatures for the server this VersionControlClient is connected to.
 WebServiceLevel getServiceLevel()
           
 com.microsoft.tfs.core.clients.versioncontrol.internal.concurrent.BoundedExecutor getUploadDownloadWorkerExecutor()
           
protected  java.net.URI getUploadURI()
           
 com.microsoft.tfs.core.clients.versioncontrol.internal.WebServiceLayer getWebServiceLayer()
           
 Workspace getWorkspace(java.lang.String localPath)
          Retrieve the workspace that is mapped to the provided local path.
 Workspace getWorkspace(java.lang.String workspaceName, java.lang.String workspaceOwner)
          Retrieve a workspace from the name and owner in the specified WorkspaceInfo.
 Workspace getWorkspace(WorkspaceInfo workspaceInfo)
          Retrieve a workspace from the name and owner in the specified WorkspaceInfo.
 SecurityNamespace getWorkspaceSecurity()
           
 boolean isAuthorizedUser(java.lang.String name)
           
 java.lang.String[] mergeWithDefaultItemPropertyFilters(java.lang.String[] filters)
          Merges the specified filters with the default item property filters configured on this VersionControlClient.
 Annotation[] queryAnnotation(java.lang.String annotationName, java.lang.String annotatedServerItem, int version)
          Gets the value associated with the given annotation name for the given item at the given version.
 BranchObject[] queryBranchObjects(ItemIdentifier rootItem, RecursionType recursion)
          Gets the branch objects inside the given root item with the given recursion.
 FileType queryCachedFileType(java.lang.String extension)
           
 java.util.SortedSet<CheckinNoteFieldDefinition> queryCheckinNoteFieldDefinitionsForServerPaths(java.lang.String[] serverPaths)
          For the passed array of server paths, work out the list of Team Projects associated with those items then query the server for the Checkin Note Field Definitions for those projects.
 Changeset[] queryHistory(java.lang.String serverOrLocalPath, VersionSpec version, int deletionID, RecursionType recursion, java.lang.String user, VersionSpec versionFrom, VersionSpec versionTo, int maxCount, boolean includeFileDetails, boolean slotMode, boolean includeDownloadInfo, boolean sortAscending)
          Queries the server for history about an item.
 java.util.Iterator<Changeset> queryHistoryIterator(java.lang.String serverOrLocalPath, VersionSpec version, int deletionID, RecursionType recursion, java.lang.String user, VersionSpec versionFrom, VersionSpec versionTo, int maxCount, boolean includeFileDetails, boolean slotMode, boolean includeDownloadInfo, boolean sortAscending)
          Queries the server for history about an item.
 VersionControlLabel[] queryLabels(java.lang.String label, java.lang.String scope, java.lang.String owner, boolean includeItemDetails, java.lang.String filterItem, VersionSpec filterItemVersion)
          Query the collection of labels that match the given specifications.
 ItemIdentifier[] queryMergeRelationships(java.lang.String serverItem)
          Returns all items which have a merge relationship to the provided item.
 ChangesetMerge[] queryMerges(java.lang.String sourceItem, VersionSpec sourceVersion, java.lang.String targetItem, VersionSpec targetVersion, VersionSpec versionFrom, VersionSpec versionTo, RecursionType recursion)
          Gets information about merges performed on the given target item (and version), optionally qualified by a source item (which can be null).
 ExtendedMerge[] queryMergesExtended(ItemSpec targetItemSpec, VersionSpec targetVersionSpec, VersionSpec versionFrom, VersionSpec versionTo, QueryMergesExtendedOptions options)
          Gets source changes for a given ItemSpec in a specific version range.
 ChangesetMergeDetails queryMergesWithDetails(java.lang.String sourceItem, VersionSpec sourceVersion, int sourceDeletionID, java.lang.String targetItem, VersionSpec targetVersion, int targetDeletionID, VersionSpec versionFrom, VersionSpec versionTo, RecursionType recursion)
          Gets detailed information about merges performed on the given target item (and version), optionally qualified by a source item (which can be null).
 PendingSet[] queryPendingSets(ItemSpec[] itemSpecs, boolean includeDownloadInfo, java.lang.String queryWorkspaceName, java.lang.String queryWorkspaceOwner)
           
 PendingSet[] queryPendingSets(ItemSpec[] itemSpecs, boolean includeDownloadInfo, java.lang.String queryWorkspaceName, java.lang.String queryWorkspaceOwner, boolean includeCandidates)
           
 PendingSet[] queryPendingSets(ItemSpec[] itemSpecs, boolean includeDownloadInfo, java.lang.String queryWorkspaceName, java.lang.String queryWorkspaceOwner, boolean includeCandidates, java.lang.String[] itemPropertyFilters)
          Get pending changes for the given item specs, even from another user's workspace.
 PendingSet[] queryPendingSets(java.lang.String[] serverOrLocalPaths, RecursionType recursionType, boolean includeDownloadInfo, java.lang.String queryWorkspaceName, java.lang.String queryWorkspaceOwner)
           
 PendingSet[] queryPendingSets(java.lang.String[] serverOrLocalPaths, RecursionType recursionType, boolean includeDownloadInfo, java.lang.String queryWorkspaceName, java.lang.String queryWorkspaceOwner, java.lang.String[] itemPropertyFilters)
          Get pending changes for the given item paths, even from another user's workspace.
 PendingSet[] queryShelvedChanges(java.lang.String shelvesetName, java.lang.String shelvesetOwner, ItemSpec[] itemSpecs, boolean includeDownloadInfo)
           
 PendingSet[] queryShelvedChanges(java.lang.String shelvesetName, java.lang.String shelvesetOwner, ItemSpec[] itemSpecs, boolean includeDownloadInfo, java.lang.String[] itemPropertyFilters)
          Gets the shelved changes for the given item specs.
 PendingSet[] queryShelvedChanges(java.lang.String workspaceName, java.lang.String workspaceOwner, java.lang.String shelvesetName, java.lang.String shelvesetOwner, ItemSpec[] itemSpecs, boolean includeDownloadInfo, java.lang.String[] itemPropertyFilters)
          Gets the shelved changes for the given item specs.
 Shelveset[] queryShelvesets(java.lang.String shelvesetName, java.lang.String shelvesetOwner, java.lang.String[] itemPropertyFilters)
          Queries the server for the set of matching shelvesets.
 Workspace queryWorkspace(java.lang.String name, java.lang.String owner)
          Returns the workspace on the server that matches the given parameters.
 Workspace[] queryWorkspaces(java.lang.String name, java.lang.String owner, java.lang.String computer)
          Always queries the server immediately; does not check the local workspace cache.
 Workspace[] queryWorkspaces(java.lang.String workspaceName, java.lang.String workspaceOwner, java.lang.String computer, WorkspacePermissions permissionsFilter)
          Returns all workspaces on the server that match the given parameters.
 void recordDownloadProxyFailure()
          Called to record that the download proxy has failed.
 void refreshServerGUID()
          Called by Workstation when refreshing the workspace cache file.
 WorkspaceInfo removeCachedWorkspace(java.lang.String workspaceName, java.lang.String workspaceOwner)
          Removes a cached workspace that matches the given name and owner and this client's server's GUID from the Workstation's cache.
 void reportFailures(Workspace workspace, Failure[] failures)
          Report failures from the server to the user.
 void resolveConflicts(Workspace workspace, Conflict[] conflicts, java.lang.String[] itemPropertyFilters, ResolveErrorOptions errorOptions, java.util.concurrent.atomic.AtomicReference<Conflict[]> resolvedConflicts)
           
 void resolveLocalConflicts(Workspace workspace, Conflict[] conflicts, ResolveErrorOptions errorOptions)
          Resolve local file conflicts.
 java.lang.String resolveUserDisplayName(java.lang.String user)
          Resolve the specified user name to an actual, fully qualified user name.
 java.lang.String resolveUserUniqueName(java.lang.String user)
          Resolve the specified user name to an actual, fully qualified unique user name.
 void setCheckinPolicies(java.lang.String teamProjectPath, PolicyDefinition[] definitions)
          Sets the checkin policies for the given team project path.
 void setDefaultItemPropertyFilters(java.lang.String[] filters)
          Sets the list of item property filters automatically appended to the specified filters in methods that send item property filters to the server.
 void setExclusiveCheckout(java.lang.String serverPath, boolean exclusiveCheckout)
          Set the exclusive checkout property on a project.
 void setPathWatcherFactory(PathWatcherFactory pathWatcherFactory)
          Sets the factory used to construct PathWatchers for local workspaces.
 boolean testItemExists(java.lang.String path)
           
 boolean testItemExists(java.lang.String path, VersionSpec version)
           
 boolean testItemExists(java.lang.String path, VersionSpec version, DeletedState deletedState)
          Tests whether an item exists in the repository at the given version.
 Workspace tryGetWorkspace(java.lang.String localPath)
          This is the same as GetWorkspace() except that it returns null rather than throwing ItemNotMappedException if the path is not in any known local workspace.
 LabelResult[] unlabelItem(java.lang.String label, java.lang.String scope, ItemSpec[] items, VersionSpec version)
          Removes a label that was applied to an item.
 void updateBranchObject(BranchProperties branchProperties, boolean updateExisting)
           
 void updateChangeset(Changeset changeset)
          Updates a changeset's information with the comment and check-in notes in the given Changeset.
 void updateUserName()
          Asks the server to update the authenticated user's display name.
 void updateWorkspace(Workspace workspace, java.lang.String newName, java.lang.String newOwner, java.lang.String newComment, WorkingFolder[] newMappings, java.lang.String newComputer)
          Update a workspace.
 void updateWorkspace(Workspace workspace, java.lang.String newName, java.lang.String newOwner, java.lang.String newComment, WorkingFolder[] newMappings, java.lang.String newComputer, WorkspacePermissionProfile newPermissionProfile)
          Update a workspace.
 void updateWorkspace(Workspace workspace, java.lang.String newName, java.lang.String newOwner, java.lang.String newComment, WorkingFolder[] newMappings, java.lang.String newComputer, WorkspacePermissionProfile newPermissionProfile, boolean removeUnparentedCloaks, WorkspaceOptions newOptions, WorkspaceLocation newLocation)
          Update a workspace.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

WORKSPACE_SECURITY_NAMESPACE_ID

public static final com.microsoft.tfs.util.GUID WORKSPACE_SECURITY_NAMESPACE_ID
GUID This is the set of namespaces that exist in the version control.

Constructor Detail

VersionControlClient

protected VersionControlClient(TFSTeamProjectCollection connection,
                               ms.tfs.versioncontrol.clientservices._03._RepositorySoap webService,
                               ms.tfs.versioncontrol.clientservices._03._RepositoryExtensionsSoap webServiceExtensions,
                               ms.tfs.versioncontrol.clientservices._03._Repository4Soap repository4,
                               ms.tfs.versioncontrol.clientservices._03._Repository5Soap repository5,
                               int maximumGetEngineWorkerThreads,
                               int getEngineWorkerThreadIdleTimeoutSeconds)

Creates a VersionControlClient that will use the given web service proxy class and the given connection. The size of the download worker thread pool and the thread idle timeouts can also be specified.

Generally you do not instantiate this class yourself. See TFSConnection.getClient(Class).

Parameters:
connection - the connection to use (must not be null)
webService - the _RepositorySoap web service proxy to use (must not be null)
webServiceExtensions - the _RepositoryExtensionsSoap proxy to use for TFS 2010 features (may be null)
repository4 - the _Repository4Soap proxy to use for TFS 2012 features (may be null)
repository5 - the _Repository5Soap proxy to use for TFS 2012 QU1 features (may be null)
maximumGetEngineWorkerThreads - the maximum number of simultaneous worker threads started to process get operations. This controls the maximum number of threads that could be performing a file download in parallel, though these worker threads perform non-network work that may prevent the workers reaching maximum theoretical network parallelism. Must be > 0.
getEngineWorkerThreadIdleTimeoutSeconds - the number of seconds of consecutive idle time after which a get engine worker thread stops running. Choose a number that provides for some thread re-use between calls that process get operations (so threads can be reused from previous operations). Choosing a very large number will result in idle threads hanging around long after their last get operation, possibly consuming resources when it is unlikely there will be any get-related work for them to perform in the near future. Must be >= 0.

VersionControlClient

public VersionControlClient(TFSTeamProjectCollection connection,
                            ms.tfs.versioncontrol.clientservices._03._RepositorySoap repository,
                            ms.tfs.versioncontrol.clientservices._03._RepositoryExtensionsSoap repositoryExtensions,
                            ms.tfs.versioncontrol.clientservices._03._Repository4Soap repository4,
                            ms.tfs.versioncontrol.clientservices._03._Repository5Soap repository5)
Creates a VersionControlClient that will use the given web service proxy class and the given connection. This client will use the default download worker thread pool size and timeout. Generally you do not instantiate this class yourself. See TFSConnection.getClient(Class).

Parameters:
connection - the connection to use (must not be null)
repository - the _RepositorySoap web service proxy to use (must not be null)
repositoryExtensions - the _RepositoryExtensionsSoap proxy to use for TFS 2010 features (may be null)
repository4 - the _Repository4Soap proxy to use for TFS 2012 features (may be null)
Method Detail

close

public void close()

Specified by:
close in interface com.microsoft.tfs.util.Closable

getWebServiceLayer

public com.microsoft.tfs.core.clients.versioncontrol.internal.WebServiceLayer getWebServiceLayer()
Returns:
the web service proxy layer (never null)

getRuntimeWorkspaceCache

public com.microsoft.tfs.core.clients.versioncontrol.workspacecache.internal.RuntimeWorkspaceCache getRuntimeWorkspaceCache()
This method is for internal use only.

Returns:
the RuntimeWorkspaceCache (never null)

getPathWatcherFactory

public PathWatcherFactory getPathWatcherFactory()
Gets the factory used to construct PathWatchers for local workspaces.


setPathWatcherFactory

public void setPathWatcherFactory(PathWatcherFactory pathWatcherFactory)
Sets the factory used to construct PathWatchers for local workspaces.


getDefaultItemPropertyFilters

public java.lang.String[] getDefaultItemPropertyFilters()
Gets the list of item property filters automatically appended to the specified filters in methods that send item property filters to the server.

Returns:
the default item property filters (may be null)

setDefaultItemPropertyFilters

public void setDefaultItemPropertyFilters(java.lang.String[] filters)
Sets the list of item property filters automatically appended to the specified filters in methods that send item property filters to the server.

Parameters:
filters - the default item property filters (may be null or empty)

getServiceLevel

public WebServiceLevel getServiceLevel()
Returns:
the web service level (never null)

getEventEngine

public VersionControlEventEngine getEventEngine()
Returns:
a reference to the EventEngine used by this client. Add (and remove) listeners to this event engine instance in order to be notified of events. All client events are dispatched through this event engine.

getServerGUID

public final com.microsoft.tfs.util.GUID getServerGUID()
Returns:
the GUID that the Team Foundation Server uses to identify itself, This may change if the server software is re-installed.

refreshServerGUID

public void refreshServerGUID()
Called by Workstation when refreshing the workspace cache file. Refreshes the server GUID for this version control server.


getUploadDownloadWorkerExecutor

public com.microsoft.tfs.core.clients.versioncontrol.internal.concurrent.BoundedExecutor getUploadDownloadWorkerExecutor()
Returns:
the BoundedExecutor that throttles access to the worker process pool for uploads and downloads.

getLocalWorkspace

public Workspace getLocalWorkspace(java.lang.String localPath,
                                   boolean throwIfNotFound)
                            throws ItemNotMappedException
Gets the workspace containing a mapping for the given path. May throw a ItemNotMappedException if there is no mapping or it's not mapped for this server.

Parameters:
localPath - a local path (must not be null or empty)
throwIfNotFound - if true, this method throws ItemNotMappedException if the path is not mapped; otherwise, returns null
Returns:
the workspace containing a mapping for the path or null if throwIfNotFound is false and no matching workspace was found
Throws:
ItemNotMappedException - if the path is not mapped to any local workspace

getLocalWorkspace

public Workspace getLocalWorkspace(java.lang.String workspaceName,
                                   java.lang.String workspaceOwner)
Look up the local workspace for the specified repository, workspaceName and workspaceOwner combo. This will only ever return anything if the workspaceOwner matches the current user. This returns the actual instance, not a copy!


getRepositoryWorkspace

public Workspace getRepositoryWorkspace(java.lang.String workspaceName,
                                        java.lang.String workspaceOwner)
                                 throws WorkspaceNotFoundException
Retrieve the specified workspace directly from the repository server. The server throws an exception if it does not have a workspace that matches. If the server reports that the workspace does not exist, the workspace will be deleted from the cache if it exists there.

Parameters:
workspaceName - the workspace name (must not be null or empty)
workspaceOwner - (must not be null or empty)
Returns:
the workspace that matches
Throws:
WorkspaceNotFoundException - if the workspace could not be found

getRepositoryWorkspaces

public Workspace[] getRepositoryWorkspaces(java.lang.String workspaceName,
                                           java.lang.String workspaceOwner,
                                           java.lang.String computer)
Get a list of matching workspaces. The repository must be a valid repository but the workspace name, owner, and computer may be null, which means match all: Note that this method returns a "private" copy of the workspace so that any future changes to the workspace will not affect the returned workspaces.

Parameters:
workspaceName - the name of the workspaces (null matches any)
workspaceOwner - the owner name of the workspaces (null matches any)
computer - the computer the workspaces are on (null matches any)
Returns:
the set of workspaces matching the provided filters

getRepositoryWorkspaces

public Workspace[] getRepositoryWorkspaces(java.lang.String workspaceName,
                                           java.lang.String workspaceOwner,
                                           java.lang.String computer,
                                           WorkspacePermissions permissionsFilter)
Get a list of matching workspaces. The repository must be a valid repository but the workspace name, owner, and computer may be null, which means match all: Note that this method returns a "private" copy of the workspace so that any future changes to the workspace will not affect the returned workspaces.

Parameters:
workspaceName - the name of the workspaces (null matches any)
workspaceOwner - the owner name of the workspaces (null matches any)
computer - the computer the workspaces are on (null matches any)
permissionsFilter - WorkspacePermissions to use for filtering by the AuthorizedUsers's permissions. Supply WorkspacePermissions.NONE_OR_NOT_SUPPORTED to not use permission filtering.
Returns:
the set of workspaces matching the provided filters

createWorkspace

public Workspace createWorkspace(WorkingFolder[] workingFolders,
                                 java.lang.String workspaceName,
                                 java.lang.String comment,
                                 WorkspaceLocation location,
                                 WorkspaceOptions options)
Create a workspace on the server.

This method is an core event origination point. The EventSource object that accompanies each event fired by this method describes the execution context (current thread, etc.) when and where this method was invoked.

Parameters:
workingFolders - the initial working folder mappings for this workspace. May be null, which means no working folders mapped.
workspaceName - the name of the new workspace (must not be null)
comment - an optional comment to be stored with this workspace (may be null).
location - where the workspace data is stored (if null, the server's default is used)
options - options to use on the newly created workspace (if null, the default options are used)
Returns:
the workspace object created by the server.

createWorkspace

public Workspace createWorkspace(WorkingFolder[] workingFolders,
                                 java.lang.String workspaceName,
                                 java.lang.String comment,
                                 WorkspaceLocation location,
                                 WorkspaceOptions options,
                                 WorkspacePermissionProfile permissionProfile)

createWorkspace

public Workspace createWorkspace(WorkingFolder[] workingFolders,
                                 java.lang.String workspaceName,
                                 java.lang.String owner,
                                 java.lang.String ownerDisplayName,
                                 java.lang.String comment,
                                 WorkspaceLocation location,
                                 WorkspaceOptions options)
Create a workspace on the server.

This method is an core event origination point. The EventSource object that accompanies each event fired by this method describes the execution context (current thread, etc.) when and where this method was invoked.

Parameters:
workingFolders - the initial working folder mappings for this workspace. May be null, which means no working folders mapped.
workspaceName - the name of the new workspace (must not be null)
owner - the name of the workspace owner (if null, empty, or VersionControlConstants.AUTHENTICATED_USER the currently authorized user's name is used)
ownerDisplayName - the display name of the workspace owner (if null, empty, or VersionControlConstants.AUTHENTICATED_USER the currently authorized user's display name is used)
comment - an optional comment to be stored with this workspace (may be null).
location - where the workspace data is stored (if null, the server's default is used)
options - options to use on the newly created workspace (if null, the default options are used)
Returns:
the workspace object created by the server.

createWorkspace

public Workspace createWorkspace(WorkingFolder[] workingFolders,
                                 java.lang.String workspaceName,
                                 java.lang.String owner,
                                 java.lang.String ownerDisplayName,
                                 java.lang.String comment,
                                 WorkspaceLocation location,
                                 WorkspaceOptions options,
                                 WorkspacePermissionProfile permissionProfile)

updateWorkspace

public void updateWorkspace(Workspace workspace,
                            java.lang.String newName,
                            java.lang.String newOwner,
                            java.lang.String newComment,
                            WorkingFolder[] newMappings,
                            java.lang.String newComputer)
Update a workspace.

Parameters:
workspace - the workspace to update; after this method completes, the object will match server's properties for this workspace (must not be null)
newName - the new name or null to keep the existing value
newOwner - the new owner or null to keep the existing value
newComment - the new comment or null to keep the existing value
newMappings - the new mappings or null to keep the existing value
newComputer - the new computer or null to keep the existing value

updateWorkspace

public void updateWorkspace(Workspace workspace,
                            java.lang.String newName,
                            java.lang.String newOwner,
                            java.lang.String newComment,
                            WorkingFolder[] newMappings,
                            java.lang.String newComputer,
                            WorkspacePermissionProfile newPermissionProfile)
Update a workspace.

Parameters:
workspace - the workspace to update; after this method completes, the object will match server's properties for this workspace (must not be null)
newName - the new name or null to keep the existing value
newOwner - the new owner or null to keep the existing value
newComment - the new comment or null to keep the existing value
newMappings - the new mappings or null to keep the existing value
newComputer - the new computer or null to keep the existing value
newPermissionProfile - the new permissions or null to keep the existing value

updateWorkspace

public void updateWorkspace(Workspace workspace,
                            java.lang.String newName,
                            java.lang.String newOwner,
                            java.lang.String newComment,
                            WorkingFolder[] newMappings,
                            java.lang.String newComputer,
                            WorkspacePermissionProfile newPermissionProfile,
                            boolean removeUnparentedCloaks,
                            WorkspaceOptions newOptions,
                            WorkspaceLocation newLocation)
Update a workspace.

Parameters:
workspace - the workspace to update; after this method completes, the object will match server's properties for this workspace (must not be null)
newName - the new name or null to keep the existing value
newOwner - the new owner or null to keep the existing value
newComment - the new comment or null to keep the existing value
newMappings - the new mappings or null to keep the existing value
newComputer - the new computer or null to keep the existing value
newPermissionProfile - the new permissions or null to keep the existing value
removeUnparentedCloaks - When true, will strip from the mappings any cloaks not parented by a mapping (default is false when other overloads are used)
newOptions - the new workspace options or null to keep the existing value
newLocation - the new workspace location or null to keep the existing value

deleteWorkspace

public void deleteWorkspace(Workspace workspace)
Delete a workspace on the server.

This method is an core event origination point. The EventSource object that accompanies each event fired by this method describes the execution context (current thread, etc.) when and where this method was invoked.

Parameters:
workspace - the workspace to delete.

getWorkspace

public Workspace getWorkspace(java.lang.String localPath)
                       throws ItemNotMappedException
Retrieve the workspace that is mapped to the provided local path. This method searches all known workspaces on the current computer to identify a workspace that has explicitly or implicitly mapped the provided local path. If no workspace is found, this method throws a ItemNotMappedException.

Parameters:
localPath - A local path for which a workspace is desired (must not be null)
Returns:
A reference to the workspace object that has mapped the specified local path
Throws:
ItemNotMappedException - if the path is not mapped to any local workspace

tryGetWorkspace

public Workspace tryGetWorkspace(java.lang.String localPath)
This is the same as GetWorkspace() except that it returns null rather than throwing ItemNotMappedException if the path is not in any known local workspace.

Parameters:
localPath - A local path for which a workspace is desired (must not be null)
Returns:
A reference to the workspace object that has mapped the specified local path or null if the local path is not in a local workspace

getWorkspace

public Workspace getWorkspace(WorkspaceInfo workspaceInfo)
                       throws WorkspaceNotFoundException
Retrieve a workspace from the name and owner in the specified WorkspaceInfo. The workspace does not need to be on the current computer. The local cache is consulted first, and if it does not contain a matching workspace, the server is queried. If the workspace cannot be found, the method throws.

Parameters:
workspaceInfo - workspace information object (must not be null)
Returns:
a reference to the workspace object representing the workspace with the specified name and owner
Throws:
WorkspaceNotFoundException - if no matching workspace was found

getWorkspace

public Workspace getWorkspace(java.lang.String workspaceName,
                              java.lang.String workspaceOwner)
                       throws WorkspaceNotFoundException
Retrieve a workspace from the name and owner in the specified WorkspaceInfo. The workspace does not need to be on the current computer. The local cache is consulted first, and if it does not contain a matching workspace, the server is queried. If the workspace cannot be found, the method throws.

Parameters:
workspaceName - The name of the workspace (must not be null)
workspaceOwner - The owner of the workspace (must not be null)
Returns:
a reference to the workspace object representing the workspace with the specified name and owner
Throws:
WorkspaceNotFoundException - if no matching workspace was found

queryWorkspace

public Workspace queryWorkspace(java.lang.String name,
                                java.lang.String owner)
Returns the workspace on the server that matches the given parameters. Always queries the server immediately; does not check the local workspace cache.

Unlike queryWorkspaces(String, String, String), this method does not update the local workspace cache when workspaces are queried, because the workspace's computer is unknown (and the computer must be know to update the cache).

Parameters:
name - the workspace name to match, null to match all.
owner - the owner name to match, null to match all. Use VersionControlConstants.AUTHENTICATED_USER to retrieve workspaces owned by the currently logged in user.
Returns:
the matching workspace or null if no matching workspace was found.

queryWorkspaces

public Workspace[] queryWorkspaces(java.lang.String name,
                                   java.lang.String owner,
                                   java.lang.String computer)
Always queries the server immediately; does not check the local workspace cache.

See Also:
queryWorkspaces(String, String, String, WorkspacePermissions)

queryWorkspaces

public Workspace[] queryWorkspaces(java.lang.String workspaceName,
                                   java.lang.String workspaceOwner,
                                   java.lang.String computer,
                                   WorkspacePermissions permissionsFilter)
Returns all workspaces on the server that match the given parameters. Always queries the server immediately; does not check the local workspace cache.

Parameters:
workspaceName - the workspace name to match, null to match all.
workspaceOwner - the owner name to match, null to match all. Use VersionControlConstants.AUTHENTICATED_USER to retrieve workspaces owned by the currently logged in user.
computer - the computer name to match, null to match all. Use LocalHost.getShortName() to match workspaces for this computer.
permissions - find only workspaces matching the given permissions (must not be null) Use WorkspacePermissions.NONE_OR_NOT_SUPPORTED to find all workspaces.
Returns:
an array of matching workspaces. May be empty but never null.

queryShelvesets

public Shelveset[] queryShelvesets(java.lang.String shelvesetName,
                                   java.lang.String shelvesetOwner,
                                   java.lang.String[] itemPropertyFilters)
Queries the server for the set of matching shelvesets.

Parameters:
shelvesetName - the name of the desired shelvesets; null to match all.
shelvesetOwner - the owner of the desired shelvesets; null to match all.
itemPropertyFilters - the list of properties to be returned on the shelvesets. To get all properties pass a single filter that is simply "*" (may be null)
Returns:
the shelvesets that matched the query parameters. May be empty but never null.

deleteShelveset

public void deleteShelveset(java.lang.String name,
                            java.lang.String owner)
Delete a shelveset on the server.

Parameters:
name - the name of the shelveset to delete (must not be null or empty).
owner - the owner of the shelveset to delete (must not be null or empty).

reportFailures

public void reportFailures(Workspace workspace,
                           Failure[] failures)
Report failures from the server to the user. This method is generally not called by users of this library.

Parameters:
workspace - the workspace where these failures occurred (must not be null)
failures - the failure array returned from the server (if null, this method does nothing)

recordDownloadProxyFailure

public void recordDownloadProxyFailure()
Called to record that the download proxy has failed. This is called when a download via proxy fails and the proxy should be disabled before the download is retried.


getDownloadURI

protected java.net.URI getDownloadURI()
Returns:
the URI for downloading files.

getUploadURI

protected java.net.URI getUploadURI()
Returns:
the URI for uploading files.

downloadFile

public void downloadFile(DownloadSpec spec,
                         java.io.File destinationFile,
                         boolean autoGunzip)
                  throws CanceledException
Equivalent To:
downloadFile(spec, destinationFile, autoGunzip, null, null)
Throws:
CanceledException

downloadFile

public void downloadFile(DownloadSpec spec,
                         java.io.File destinationFile,
                         boolean autoGunzip,
                         EventSource eventSource,
                         TaskMonitor taskMonitor)
                  throws CanceledException
Download the file described by spec to the destination file. This method can try the download multiple times to work around some kinds of transient errors (VC proxy unreachable, TCP socket resets). If a fatal error is encountered, an exception is thrown and the destination file is deleted if it exists (but this may fail).

If a download proxy is configured and enabled, and an error is encountered download the file, the VersionControlClient is configured to bypass the download proxy for the rest of its lifetime and the download is retried one time directly from the TFS application server.

This method is an core event origination point. The EventSource object that accompanies each event fired by this method describes the execution context (current thread, etc.) when and where this method was invoked.

Parameters:
spec - the spec that describes the file to download (must not be null)
destinationFile - the local file that will receive the contents of the downloaded file (must not be null or empty). This file will be created if it does not exist, otherwise it will be overwritten.
autoGunzip - if true, the content downloaded is automatically decompressed via gzip if its Content-Type is application/gzip before being written to disk (almost all users of this class want this behavior). If false, the file is written directly to disk without being uncompressed.
eventSource - a custom EventSource or null to use EventSource.newFromHere()
taskMonitor - a custom TaskMonitor or null to use the monitor from the TaskMonitorService
Throws:
CanceledException - if the download was canceled by the user via the TaskMonitor. This method tries to delete the destinationFile after cancelation but this may fail (and these errors are logged but not rethrown).

downloadFileToTempLocation

public java.io.File downloadFileToTempLocation(DownloadSpec spec,
                                               java.lang.String fileName)
                                        throws CanceledException
Downloads a file to a temporary location (created by the method), gunzipping if necessary. The file in the temporary folder is given the name in the fileName parameter.

Has the same transient network problem retry behavior as downloadFile(DownloadSpec, File, boolean).

Parameters:
spec - the spec that describes the file to download (must not be null)
fileName - the file name (not full path) to give the file locally, once it is downloaded (must not be null or empty)
Returns:
the FileAttachmentDownloadException where the file's data was written.
Throws:
CanceledException - if the operation was canceled via the default TaskMonitor

downloadFileToStream

public void downloadFileToStream(DownloadSpec spec,
                                 java.io.OutputStream outputStream,
                                 boolean autoGunzip)
                          throws CanceledException
This convenience method does not support retrying downloads that failed with transient network problems. Call downloadFileToStreams(DownloadSpec, DownloadOutput[], EventSource, TaskMonitor) with a DownloadOutput that supports stream reset if you need retries.

Equivalent To:
downloadFileToStream(spec, outputStream, autoGunzip, null,
             null)
Throws:
CanceledException

downloadFileToStream

public void downloadFileToStream(DownloadSpec spec,
                                 java.io.OutputStream outputStream,
                                 boolean autoGunzip,
                                 EventSource eventSource,
                                 TaskMonitor taskMonitor)
                          throws CanceledException
This convenience method does not support retrying downloads that failed with transient network problems. Call downloadFileToStreams(DownloadSpec, DownloadOutput[], EventSource, TaskMonitor) with a DownloadOutput that supports stream reset if you need retries.

Equivalent To:
downloadFileToStreams(spec, new DownloadOutput[] { new
             OutputStreamDownloadOutput(outputStream, autoGunzip) },
             eventSource, taskMonitor)
Throws:
CanceledException

downloadFileToStreams

public void downloadFileToStreams(DownloadSpec spec,
                                  DownloadOutput[] outputs,
                                  EventSource eventSource,
                                  TaskMonitor taskMonitor)
                           throws CanceledException
Download the file described by spec to the destination stream or streams.

Notice:

This method can only recover from transient network problems (TCP socket resets) if all DownloadOutputs support stream reset. Download proxy connect errors do not require output stream reset because not data will have been written to them yet.

The output streams are always left open (they may have been reset, but no effort is made to finally close them), even when an exception is thrown.

Parameters:
spec - the spec that describes the file to download (must not be null)
outputs - the outputs where the downloaded data will be written (must not be null or empty)
eventSource - a custom EventSource or null to use EventSource.newFromHere()
taskMonitor - a custom TaskMonitor or null to use the monitor from the TaskMonitorService
Throws:
CanceledException - if the download was cancelled by the user via core's TaskMonitor. The output streams may have had some data written to them.

downloadItems

public java.lang.String downloadItems(Item[] items,
                                      java.lang.String serverRoot,
                                      java.lang.String localRoot)
                               throws CanceledException
Downloads a collection of Items to a temporary location preserving the server path structure. The local download location is specified by the localRoot parameter, which can be null (a temporary location is chosen by the method in this case).

Items that are files must have a non-null download URL. Folder Items will be created on disk even if empty.

This method is an core event origination point. The EventSource object that accompanies each event fired by this method describes the execution context (current thread, etc.) when and where this method was invoked.

Parameters:
items - the set of items to download (must not be null)
serverRoot - the server path shared by all items (must not be null or empty).
localRoot - the local path where the downloaded items will be placed. If null, a temporary path is chosen by the method.
Returns:
the full local path to the directory where the items were downloaded.
Throws:
CanceledException - if this operation is canceled by the default TaskMonitor

beginUploadRequest

public PostMethod beginUploadRequest()
Begins a file upload. Creates PostMethod object configured with the URL of the TFS and all required authentication information. The caller should configure this object's post data, then pass the object into this class's executeUploadRequest().

NOTE: This method is not synchronized (but is thread-safe) because doing so would allow deadlock during concurrent uploads. When there are more uploader threads than available connections in the HttpClient's pool, a thread may sleep in the HttpClient code (while holding a lock on this object) until a connection becomes available, which can only happen if other threads finish using their connections (which they can't because they need to acquire a lock on this object to do so).

Returns:
a new PostMethod object set to the Team Foundation Server's upload page URL. The caller should set the request stream using setRequestBody(), then execute this class's executeUploadRequest() with the configured object.

executeUploadRequest

public void executeUploadRequest(PostMethod method)
                          throws java.io.IOException
Executes a file upload. First call beginUploadRequest(), then configure the object it returns, then supply that object to this method. The HTTP status code is returned. After this method completes, and you have checked its status code, you must call this class's finishUploadRequest().

Parameters:
method - the object constructed by beginUploadRequest() and configured with your post data.
Throws:
java.io.IOException - if an error occurred opening the connection to the server
VersionControlException - if an error occurred executing the method (if the status code is not HttpStatus.SC_OK).

finishUploadRequest

public void finishUploadRequest(PostMethod method)
Finishes a file upload.

Parameters:
method - the object constructed by beginUploadRequest().

getChangeset

public Changeset getChangeset(int changesetID)
Gets Changeset information including individual change information, excluding download information.


getChangeset

public Changeset getChangeset(int changesetID,
                              boolean includeChanges,
                              boolean includeDownloadInfo,
                              java.lang.String[] changesetPropertyFilters,
                              java.lang.String[] itemPropertyFilters)
Gets the Changeset object that describes the given changeset ID.

Parameters:
changesetID - the ID of the changeset to get information for.
includeChanges - if true information about the individual changes in the changeset are returned
includeDownloadInfo - if true the individual change items will have download URLs
changesetPropertyFilters - a list of properties to return with the changeset (may be null)
itemPropertyFilters - a list of properties to return on the items in the changeset (may be null)
Returns:
an Changeset that describes the changeset information.

getChangesForChangeset

public Change[] getChangesForChangeset(int changesetID,
                                       boolean includeDownloadInfo,
                                       int pageSize,
                                       ItemSpec lastItem,
                                       java.lang.String[] itemPropertyFilters,
                                       boolean includeMergeSourceInfo)
Gets the changes within a changeset Allows the caller to page changes back from the server.

Parameters:
changesetID - the changeset for which to get changes
includeDownloadInfo - If true, the server will include the information needed to download files. Only set this to true if you are going to be downloading the files using the objects that are returned. The call will be faster and require less bandwidth when this parameter is false.
pageSize - the number of items to return
lastItem - instructs the server to return items which sort after this item. If null, the server will begin from the start of the changeset. This parameter should be null in the first call to this method, and then should be the last seen value on subsequent calls
itemPropertyFilters - a list of versioned item properties to return with each item (may be null)
includeMergeSourceInfo - whether to include source information about renames / merges
Returns:
the changes in the changeset

getItem

public Item getItem(int itemID,
                    int changesetNumber)

getItem

public Item getItem(int itemID,
                    int changesetNumber,
                    GetItemsOptions options)

getItem

public Item getItem(int itemID,
                    int changesetNumber,
                    boolean includeDownloadInfo)

getItems

public Item[] getItems(int[] itemIDs,
                       int changesetNumber)

getItems

public Item[] getItems(int[] itemIDs,
                       int changesetNumber,
                       boolean includeDownloadInfo)

getItems

public Item[] getItems(int[] itemIDs,
                       int changesetNumber,
                       GetItemsOptions options)

getItem

public Item getItem(java.lang.String path)
Equivalent To:
getItem(path, LatestVersionSpec.INSTANCE)

getItem

public Item getItem(java.lang.String path,
                    VersionSpec version)
Equivalent To:
getItem(path, version, 0)

getItem

public Item getItem(java.lang.String path,
                    VersionSpec version,
                    DeletedState deletedState)
Equivalent To:
getItem(path, version, deletedState, false)

getItem

public Item getItem(java.lang.String path,
                    VersionSpec version,
                    int deletionID)
Equivalent To:
getItem(path, version, deletionId, false);

getItem

public Item getItem(java.lang.String path,
                    VersionSpec version,
                    DeletedState deletedState,
                    boolean includeDownloadInfo)
Equivalent To:
getItem(path, version, deletedState, includeDownloadInfo ?
             GetItemsOptions.DOWNLOAD : GetItemsOptions.NONE)

getItem

public Item getItem(java.lang.String path,
                    VersionSpec version,
                    int deletionID,
                    GetItemsOptions options)
Equivalent To:
getItem(path, version, (deletionID > 0) ?
             DeletedState.DELETED : DeletedState.NON_DELETED, options)

getItem

public Item getItem(java.lang.String path,
                    VersionSpec version,
                    int deletionID,
                    boolean includeDownloadInfo)
Equivalent To:
getItem(path, version, deletionID, includeDownloadInfo ?
             GetItemsOptions.DOWNLOAD : GetItemsOptions.NONE)

getItem

public Item getItem(java.lang.String path,
                    VersionSpec version,
                    DeletedState deletedState,
                    GetItemsOptions options)
Gets information about one item.

Parameters:
path - the server or local path of the item to get information for (no wildcards) (must not be null or empty)
version - the version of the item to get information about (must not be null)
options - flags that control the amount of information returned for the item
Returns:
an Item describing the given path, never null (throws VersionControlException if the item was not found)
Throws:
VersionControlException - if wildcards were present in the path, or if the item was not found in the repository

testItemExists

public boolean testItemExists(java.lang.String path)
Equivalent To:
testItemExists(path, LatestVersionSpec.INSTANCE,
             DeletedState.NON_DELETED)

testItemExists

public boolean testItemExists(java.lang.String path,
                              VersionSpec version)
Equivalent To:
testItemExists(path, version, DeletedState.NON_DELETED)

testItemExists

public boolean testItemExists(java.lang.String path,
                              VersionSpec version,
                              DeletedState deletedState)
Tests whether an item exists in the repository at the given version.

Parameters:
path - the server or local path to test for existence (must not be null or empty)
version - the version of the item to test for (must not be null )
deletedState - the deleted state of the item to test for (must not be null)
Returns:
true if the item exists at the given version and deleted state, false if it does not
Throws:
VersionControlException - if the path contained wildcards

getItems

public ItemSet getItems(java.lang.String path)
Equivalent To:
getItems(path, LatestVersionSpec.INSTANCE,
             RecursionType.NONE)

getItems

public ItemSet getItems(java.lang.String path,
                        RecursionType recursion)
Equivalent To:
getItems(path, LatestVersionSpec.INSTANCE, recursion)

getItems

public ItemSet getItems(java.lang.String path,
                        VersionSpec version,
                        RecursionType recursion)
Equivalent To:
getItems(path, version, recursion, DeletedState.NON_DELETED,
             ItemType.ANY, false)

getItems

public ItemSet[] getItems(ItemSpec[] itemSpecs,
                          VersionSpec version,
                          DeletedState deletedState,
                          ItemType itemType)
Equivalent To:
getItems(itemSpecs, version, deletedState, itemType, false)

getItems

public ItemSet getItems(ItemSpec itemSpec,
                        VersionSpec version,
                        DeletedState deletedState,
                        ItemType itemType,
                        GetItemsOptions options)
Equivalent To:
getItems(new ItemSpec[] { itemSpec }, version, deletedState,
             itemType, options)[0]

getItems

public ItemSet getItems(ItemSpec itemSpec,
                        VersionSpec version,
                        DeletedState deletedState,
                        ItemType itemType,
                        boolean includeDownloadInfo)
Equivalent To:
getItems(new ItemSpec[] { itemSpec }, version, deletedState,
             itemType, includeDownloadInfo)[0]

getItems

public ItemSet[] getItems(ItemSpec[] itemSpecs,
                          VersionSpec version,
                          DeletedState deletedState,
                          ItemType itemType,
                          boolean includeDownloadInfo)
Equivalent To:
getItems(itemSpecs, version, deletedState, itemType,
             includeDownloadInfo ? GetItemsOptions.DOWNLOAD :
             GetItemsOptions.NONE)

getItems

public ItemSet getItems(java.lang.String path,
                        VersionSpec version,
                        RecursionType recursion,
                        DeletedState deletedState,
                        ItemType itemType)
Equivalent To:
getItems(path, version, recursion, deletedState, itemType,
             false)

getItems

public ItemSet getItems(java.lang.String path,
                        VersionSpec version,
                        RecursionType recursion,
                        DeletedState deletedState,
                        ItemType itemType,
                        boolean includeDownloadInfo)
Equivalent To:
getItems(new ItemSpec(path, recursion), version,
             deletedState, itemType, includeDownloadInfo)

getItems

public ItemSet[] getItems(ItemSpec[] itemSpecs,
                          VersionSpec version,
                          DeletedState deletedState,
                          ItemType itemType,
                          GetItemsOptions options)
Equivalent To:
getItems(itemSpecs, version, deletedState, itemType,
             options, null)

getItems

public ItemSet[] getItems(ItemSpec[] itemSpecs,
                          VersionSpec version,
                          DeletedState deletedState,
                          ItemType itemType,
                          GetItemsOptions options,
                          java.lang.String[] itemPropertyFilters)
Gets information about multiple items. An ItemSet is returned for each query item.

Parameters:
itemSpecs - the items to get information about (must not be null or empty)
version - the version of each of the items to get information about (not null)
deletedState - the deleted state of items (must not be null)
itemType - the types of matching items that should be returned (must not be null)
options - flags that control the amount of information returned for the item
itemPropertyFilters - a list of versioned item properties to return with each item (may be null)
Returns:
an array of ItemSet instances, one for each given ItemSpec in the original order. May be empty but never null.

getExtendedItems

public ExtendedItem[][] getExtendedItems(ItemSpec[] itemSpecs,
                                         DeletedState deletedState,
                                         ItemType itemType)
Equivalent To:
getExtendedItems(itemSpecs, deletedState, itemType,
             GetItemsOptions.NONE)

getExtendedItems

public ExtendedItem[][] getExtendedItems(ItemSpec[] itemSpecs,
                                         DeletedState deletedState,
                                         ItemType itemType,
                                         GetItemsOptions options)
Equivalent To:
getExtendedItems(null, null, itemSpecs, deletedState,
             itemType, options)

getExtendedItems

public ExtendedItem[] getExtendedItems(java.lang.String itemPath,
                                       DeletedState deletedState,
                                       ItemType itemType)
Equivalent To:
getExtendedItems(new ItemSpec[] { new ItemSpec(itemPath,
             RecursionType.NONE) }, deletedState, itemType,
             GetItemsOptions.NONE)[0]

getExtendedItems

public ExtendedItem[][] getExtendedItems(java.lang.String workspaceName,
                                         java.lang.String workspaceOwner,
                                         ItemSpec[] itemSpecs,
                                         DeletedState deletedState,
                                         ItemType itemType,
                                         GetItemsOptions options)
Equivalent To:
getExtendedItems(workspaceName, workspaceOwner, itemSpecs,
             deletedState, itemType, options, null)

getExtendedItems

public ExtendedItem[][] getExtendedItems(java.lang.String workspaceName,
                                         java.lang.String workspaceOwner,
                                         ItemSpec[] itemSpecs,
                                         DeletedState deletedState,
                                         ItemType itemType,
                                         GetItemsOptions options,
                                         java.lang.String[] itemPropertyFilters)
Gets extended information about items, with full results control.

Parameters:
workspaceName - the name of the workspace to get extended information for. If the paths in the itemSpecs are server paths, this parameter is ignored (may be null). If this parameter is null and the itemSpec paths are local, the correct local workspace is determined automatically.
workspaceOwner - the owner of the workspace to get extended information for. If the paths in the itemSpecs are server paths, this parameter is ignored (may be null). If this parameter is null and the itemSpec paths are local, the correct local workspace is determined automatically.
itemSpecs - instances of ItemSpec that describe the item sets you want returned. One ItemSet will be returned for each ItemSpec (must not be null or empty)
deletedState - the deleted state of items you want to list (must not be null)
itemType - the types of items you want to list (must not be null )
options - the GetItemsOptions which control the returned results (must not be null)
itemPropertyFilters - a list of versioned item properties to return with each extended item (may be null)
Returns:
an array of ExtendedItem arrays, each outer array representing one given ItemSpec, and each inner array representing the matches found for those ItemSpecs (should be only one object in these inner arrays because recursion is not an option). Inner arrays may be empty but are never null.

queryCheckinNoteFieldDefinitionsForServerPaths

public final java.util.SortedSet<CheckinNoteFieldDefinition> queryCheckinNoteFieldDefinitionsForServerPaths(java.lang.String[] serverPaths)
For the passed array of server paths, work out the list of Team Projects associated with those items then query the server for the Checkin Note Field Definitions for those projects.

Parameters:
serverPaths - Sting array containing paths to server items that the calling method requires the checkin note field definitions.
Returns:
SortedSet of unique ACheckinNoteFieldDefinition objects in display order.

setExclusiveCheckout

public final void setExclusiveCheckout(java.lang.String serverPath,
                                       boolean exclusiveCheckout)
Set the exclusive checkout property on a project.

Parameters:
serverPath - server path of project or file in project (must not be null or empty).
exclusiveCheckout - flag indicating if force exclusive checkout should be enabled or disabled.

queryAnnotation

public Annotation[] queryAnnotation(java.lang.String annotationName,
                                    java.lang.String annotatedServerItem,
                                    int version)
Gets the value associated with the given annotation name for the given item at the given version. Either annotationName or annotatedServerItem, or both, must be supplied (must not be null)

Parameters:
annotationName - the name of the annotation to query. If null, annotatedServerItem must not be null, and all annotations for the given server item and version are returned.
annotatedServerItem - the server path of the item to query annotations for. If null, annotationName must not be null, and all annotations for all server items that match the given annotation name and version will be returned.
version - the version of the given annotatedServerItem to query annotations for. If 0, annotations that are not attached to any version of that item are returned.
Returns:
the annotations that matched the query. May be empty but never null.

createAnnotation

public void createAnnotation(java.lang.String annotationName,
                             java.lang.String annotatedServerItem,
                             int version,
                             java.lang.String annotationValue,
                             java.lang.String comment,
                             boolean overwrite)
Creates an annotation.

Parameters:
annotationName - the name of the annotation to create. If null, annotatedServerItem must not be null, and an annotation for the given server item and version is created.
annotatedServerItem - the server path of the item to create an annotation on (must not be null) deleted.
version - the version of the given annotatedServerItem to create. If 0, an annotation that is not attached to any version of that item is created.
annotationValue - the value to store in the annotation. Can be a very large string (must not be null)
comment - an optional comment (may be null).
overwrite - true to overwrite an existing annotation with the same location information, false to error if one already exists.

deleteAnnotation

public void deleteAnnotation(java.lang.String annotationName,
                             java.lang.String annotatedServerItem,
                             int version,
                             java.lang.String annotationValue)
Deletes an annotation.

Parameters:
annotationName - the name of the annotation to delete. If null, annotatedServerItem must not be null, and all annotations for the given server item and version are deleted.
annotatedServerItem - the server path of the item to delete annotations on. If null, annotationName must not be null, and all annotations for all server items that match the given annotation name and version will be deleted.
version - the version of the given annotatedServerItem to delete annotations for. If 0, annotations that are not attached to any version of that item are deleted.
annotationValue - the value (may be null)

getConnection

public TFSTeamProjectCollection getConnection()

queryHistory

public Changeset[] queryHistory(java.lang.String serverOrLocalPath,
                                VersionSpec version,
                                int deletionID,
                                RecursionType recursion,
                                java.lang.String user,
                                VersionSpec versionFrom,
                                VersionSpec versionTo,
                                int maxCount,
                                boolean includeFileDetails,
                                boolean slotMode,
                                boolean includeDownloadInfo,
                                boolean sortAscending)
                         throws ServerPathFormatException
Queries the server for history about an item. History items are returned as an array of changesets.

Parameters:
serverOrLocalPath - the server or local path to the server item being queried for its history (must not be null or empty).
version - the version of the item to query history for (history older than this version will be returned) (must not be null)
deletionID - the deletion ID for the item, if it is a deleted item (pass 0 if the item is not deleted).
recursion - whether to query recursively (must not be null)
user - only include historical changes made by this user (pass null to retrieve changes made by all users).
versionFrom - the beginning version to query historical changes from (pass null to start at the first version).
versionTo - the ending version to query historical changes to (pass null to end at the most recent version).
maxCount - the maximum number of changes to return (pass Integer.MAX_VALUE for all available values). Must be > 0.
includeFileDetails - true to include individual file change details with the returned results, false to return only general changeset information.
slotMode - if true, all items that have occupied the given serverPath (during different times) will have their changes returned. If false, only the item that matches that path at the given version will have its changes returned.
sortAscending - when true gets the top maxCount changes in ascending order, when false gets them in descending order
Returns:
the changesets that matched the history query, null if the server did not return a changeset array.
Throws:
ServerPathFormatException

queryHistoryIterator

public java.util.Iterator<Changeset> queryHistoryIterator(java.lang.String serverOrLocalPath,
                                                          VersionSpec version,
                                                          int deletionID,
                                                          RecursionType recursion,
                                                          java.lang.String user,
                                                          VersionSpec versionFrom,
                                                          VersionSpec versionTo,
                                                          int maxCount,
                                                          boolean includeFileDetails,
                                                          boolean slotMode,
                                                          boolean includeDownloadInfo,
                                                          boolean sortAscending)
                                                   throws ServerPathFormatException
Queries the server for history about an item. Results are returned as an Iterator of Changesets.

Parameters:
serverOrLocalPath - the server or local path to the server item being queried for its history (must not be null or empty).
version - the version of the item to query history for (history older than this version will be returned) (must not be null)
deletionID - the deletion ID for the item, if it is a deleted item (pass 0 if the item is not deleted).
recursion - whether to query recursively (must not be null)
user - only include historical changes made by this user (pass null to retrieve changes made by all users).
versionFrom - the beginning version to query historical changes from (pass null to start at the first version).
versionTo - the ending version to query historical changes to (pass null to end at the most recent version).
maxCount - the maximum number of changes to return (pass Integer.MAX_VALUE for all available values). Must be > 0.
includeFileDetails - true to include individual file change details with the returned results, false to return only general changeset information.
slotMode - if true, all items that have occupied the given serverPath (during different times) will have their changes returned. If false, only the item that matches that path at the given version will have its changes returned.
sortAscending - when true gets the top maxCount changes in ascending order, when false gets them in descending order
Returns:
the changesets that matched the history query, null if the server did not return a changeset array.
Throws:
ServerPathFormatException

createBranch

public int createBranch(java.lang.String sourceServerPath,
                        java.lang.String targetServerPath,
                        VersionSpec version)
Creates a branch of the given source path at the given version to the given target path.

Note

This method exists as a fast alternative to the standard method of creating a branch: by pending a branch change, then checking in those changes.

Only server paths are accepted.

This method is only supported by Team Foundation Server 2008 SP1 and later.

Parameters:
sourceServerPath - the server path to an existing item which will be branched (must not be null)
targetServerPath - the server path to the destination where the branch will be made (not null).
version - the version of the source item to branch into the target item (not null).
Returns:
the changeset identifier that resulted from the check-in.
Throws:
java.lang.UnsupportedOperationException - if this method is used when connected to a server that does not support branch creation without pending changes.

createBranch

public int createBranch(java.lang.String sourceServerPath,
                        java.lang.String targetServerPath,
                        VersionSpec version,
                        java.lang.String owner,
                        java.lang.String comment,
                        CheckinNote checkinNote,
                        PolicyOverrideInfo policyOverride,
                        Mapping[] mappings)
Creates a branch of the given source path at the given version to the given target path.

Note

This method exists as a fast alternative to the standard method of creating a branch: by pending a branch change, then checking in those changes.

Only server paths are accepted.

This method is only supported by Team Foundation Server 2008 SP1 and later.

Parameters:
sourceServerPath - the server path to an existing item which will be branched (must not be null)
targetServerPath - the server path to the destination where the branch will be made (not null).
version - the version of the source item to branch into the target item (not null).
owner - the owner of the changeset that creates the branch (may be null)
comment - the comment for the changeset that creates the branch (may be null)
checkinNote - the checkin note provided with the changeset that creates the branch (may be null)
policyOverride - the check-in policy override information for the changeset that creates the branch (may be null)
mappings - the mappings to use for the branch (may be null)
Returns:
the changeset identifier that resulted from the check-in.
Throws:
java.lang.UnsupportedOperationException - if this method is used when connected to a server that does not support branch creation without pending changes.

updateChangeset

public void updateChangeset(Changeset changeset)
Updates a changeset's information with the comment and check-in notes in the given Changeset.

Parameters:
changeset - the new changeset information, where the changeset ID number matches an existing changeset (must not be null)

createLabel

public LabelResult[] createLabel(VersionControlLabel label,
                                 LabelItemSpec[] items,
                                 LabelChildOption options)
Create or update a label for items in this workspace.

Parameters:
label - the label to create or update (must not be null)
items - the items to be included in the label creation or update (not null).
options - options that affect the processing of the label creation or update (must not be null or empty).
Returns:
the label results, null if none were returned. May be empty but never null.

deleteLabel

public LabelResult[] deleteLabel(java.lang.String label,
                                 java.lang.String scope)
Deletes the specified label.

Parameters:
label - the label to delete (must not be null)
scope - the scope of the label to delete (must not be null)
Returns:
the result of the label deletion. May be empty but never null.

unlabelItem

public LabelResult[] unlabelItem(java.lang.String label,
                                 java.lang.String scope,
                                 ItemSpec[] items,
                                 VersionSpec version)
Removes a label that was applied to an item.

Parameters:
label - the label to remove (must not be null)
scope - the scope of the label to remove (must not be null)
items - the items to remove from the label (must not be null or empty)
version - the version of the items to remove to match (may be null)
Returns:
the label results, null if none were returned. May be empty but never null.

queryLabels

public VersionControlLabel[] queryLabels(java.lang.String label,
                                         java.lang.String scope,
                                         java.lang.String owner,
                                         boolean includeItemDetails,
                                         java.lang.String filterItem,
                                         VersionSpec filterItemVersion)
Query the collection of labels that match the given specifications.

Parameters:
label - the label name to match (may be null?).
scope - the scope of the label to match (may be null?).
owner - the owner of the label to match (may be null?).
includeItemDetails - if true, details about the labeled items are included in the results, otherwise only general label information is included.
filterItem - if not null, only labels containing this item are returned.
filterItemVersion - if filterItem was supplied, only labels that include this version of the filterItem are returned, otherwise may be null.
Returns:
the label items that matched the query. May be empty but never null.

queryPendingSets

public PendingSet[] queryPendingSets(java.lang.String[] serverOrLocalPaths,
                                     RecursionType recursionType,
                                     boolean includeDownloadInfo,
                                     java.lang.String queryWorkspaceName,
                                     java.lang.String queryWorkspaceOwner)
Equivalent To:
queryPendingSets( serverOrLocalPaths, recursionType,
             includeDownloadInfo, queryWorkspaceName,
             queryWorkspaceOwner, null)

queryPendingSets

public PendingSet[] queryPendingSets(java.lang.String[] serverOrLocalPaths,
                                     RecursionType recursionType,
                                     boolean includeDownloadInfo,
                                     java.lang.String queryWorkspaceName,
                                     java.lang.String queryWorkspaceOwner,
                                     java.lang.String[] itemPropertyFilters)
Get pending changes for the given item paths, even from another user's workspace.

Parameters:
serverOrLocalPaths - the items (files or directories) to get pending changes for. Pass ServerPath.ROOT with RecursionType.FULL to match all (must not be null or empty)
recursionType - the type of recursion to apply to the given server paths (must not be null)
queryWorkspaceName - the name of the workspace to query for pending changes. Pass null to match all.
queryWorkspaceOwner - the owner of the workspace to query for pending changes. Pass null to match all.
itemPropertyFilters - a list of property names to return on the pending change object if they exist (may be null)
Returns:
a pending set including all the pending changes. May be empty but never null.

queryPendingSets

public PendingSet[] queryPendingSets(ItemSpec[] itemSpecs,
                                     boolean includeDownloadInfo,
                                     java.lang.String queryWorkspaceName,
                                     java.lang.String queryWorkspaceOwner)
Equivalent To:
queryPendingSets(itemSpecs, includeDownloadInfo,
             queryWorkspaceName, queryWorkspaceOwner, false)

queryPendingSets

public PendingSet[] queryPendingSets(ItemSpec[] itemSpecs,
                                     boolean includeDownloadInfo,
                                     java.lang.String queryWorkspaceName,
                                     java.lang.String queryWorkspaceOwner,
                                     boolean includeCandidates)
Equivalent To:
queryPendingSets( itemSpecs, includeDownloadInfo,
             queryWorkspaceName, queryWorkspaceOwner, includeCandidates,
             null)

queryPendingSets

public PendingSet[] queryPendingSets(ItemSpec[] itemSpecs,
                                     boolean includeDownloadInfo,
                                     java.lang.String queryWorkspaceName,
                                     java.lang.String queryWorkspaceOwner,
                                     boolean includeCandidates,
                                     java.lang.String[] itemPropertyFilters)
Get pending changes for the given item specs, even from another user's workspace.

Parameters:
itemSpecs - the ItemSpecs to get pending changes for (must not be null or empty)
queryWorkspaceName - the name of the workspace to query for pending changes. Pass null to match all.
queryWorkspaceOwner - the owner of the workspace to query for pending changes. Pass null to match all.
includeCandidates - if true for a local workspace, candidate changes will be populated on the pending set. A pending set will be returned if the workspace contains pending changes or candidate changes
itemPropertyFilters - a list of property names to return on the pending change object if they exist (may be null)
Returns:
a pending set including all the pending changes. May be empty but never null.

queryShelvedChanges

public PendingSet[] queryShelvedChanges(java.lang.String shelvesetName,
                                        java.lang.String shelvesetOwner,
                                        ItemSpec[] itemSpecs,
                                        boolean includeDownloadInfo)
Equivalent To:
queryShelvedChanges(shelvesetName, shelvesetOwner,
             itemSpecs, includeDownloadInfo, null)

queryShelvedChanges

public PendingSet[] queryShelvedChanges(java.lang.String shelvesetName,
                                        java.lang.String shelvesetOwner,
                                        ItemSpec[] itemSpecs,
                                        boolean includeDownloadInfo,
                                        java.lang.String[] itemPropertyFilters)
Gets the shelved changes for the given item specs.

Parameters:
shelvesetName - the shelveset name (may be null)
shelvesetOwner - the user name (may be null), which is the shelveset owner if the shelveset name is not null
itemSpecs - the items to query changes for (null for all).
includeDownloadInfo - If true, the server will include the information needed to download files. Only set this to true if you are going to be downloading the files using the objects that are returned. The call will be faster and require less bandwidth when this parameter is false (default for overloads that don't specify it)
itemPropertyFilters - a list of property names to return on the pending change object if they exist (may be null)
Returns:
an array of pending sets with the pending changes for the shelved changes. May be empty but never null.

queryShelvedChanges

public PendingSet[] queryShelvedChanges(java.lang.String workspaceName,
                                        java.lang.String workspaceOwner,
                                        java.lang.String shelvesetName,
                                        java.lang.String shelvesetOwner,
                                        ItemSpec[] itemSpecs,
                                        boolean includeDownloadInfo,
                                        java.lang.String[] itemPropertyFilters)
Gets the shelved changes for the given item specs.

Parameters:
workspaceName - the name of the workspace to query for (may be null)
workspaceOwner - the owner of the workspace to query for (may be null)
shelvesetName - the shelveset name (may be null)
shelvesetOwner - the user name (may be null), which is the shelveset owner if the shelveset name is not null
itemSpecs - the items to query changes for (null for all).
includeDownloadInfo - If true, the server will include the information needed to download files. Only set this to true if you are going to be downloading the files using the objects that are returned. The call will be faster and require less bandwidth when this parameter is false (default for overloads that don't specify it)
itemPropertyFilters - a list of property names to return on the pending change object if they exist (may be null)
Returns:
an array of pending sets with the pending changes for the shelved changes. May be empty but never null.

getCheckinPoliciesForServerPaths

public PolicyDefinition[] getCheckinPoliciesForServerPaths(java.lang.String[] serverPaths)
                                                    throws PolicySerializationException
Gets the checkin policies defined for the given server paths, which must be team projects.

Parameters:
serverPaths - the paths to get policy definitions for. If null, an empty array is returned.
Returns:
the definitions loaded from the server. May be empty but never null.
Throws:
PolicySerializationException - if an error occurred reading the policy definitions from the server.

getMergeCandidates

public MergeCandidate[] getMergeCandidates(java.lang.String sourcePath,
                                           java.lang.String targetPath,
                                           RecursionType recursion,
                                           MergeFlags mergeFlags)
Look up the merge candidates for merging between the requested items.

Parameters:
sourcePath - the local or server path of the source of the potential merge (must not be null or empty)
targetPath - the local or server path of the target of the potential merge (must not be null or empty)
recursion - what level of recursion we should apply to the candidate search (may be null).
mergeFlags - merge command option(s) compatible with the /cadidate option (must not be null).
Returns:
the array of merge candidates returned by the server. May be empty but never null.

queryBranchObjects

public BranchObject[] queryBranchObjects(ItemIdentifier rootItem,
                                         RecursionType recursion)
Gets the branch objects inside the given root item with the given recursion.

Parameters:
rootItem - the root item (must not be null)
recursion - the recursion type (must not be null)
Returns:
the branch objects found
Since:
TFS 2010

updateBranchObject

public void updateBranchObject(BranchProperties branchProperties,
                               boolean updateExisting)

deleteBranchObject

public void deleteBranchObject(ItemIdentifier branch)
Deletes a branch object.

Parameters:
branch - the branch item to delete (must not be null)
Since:
TFS 2010

queryMerges

public ChangesetMerge[] queryMerges(java.lang.String sourceItem,
                                    VersionSpec sourceVersion,
                                    java.lang.String targetItem,
                                    VersionSpec targetVersion,
                                    VersionSpec versionFrom,
                                    VersionSpec versionTo,
                                    RecursionType recursion)
Gets information about merges performed on the given target item (and version), optionally qualified by a source item (which can be null).

Parameters:
sourceItem - the item that is the source of merges to be returned (may be null)
sourceVersion - the version of the source item for the merges (may be null if sourceItem is null)
targetItem - the item that is the target of merges to be returned (must not be null or empty)
targetVersion - the version of the target item for the merges (must not be null)
versionFrom - the oldest version to be included in the results (may be null)
versionTo - the most recent version to be included in the results (may be null)
recursion - the type of recursion to apply to the given items (must not be null)
Returns:
the ChangesetMerges returned by the server. May be empty but never null.

queryMergesWithDetails

public ChangesetMergeDetails queryMergesWithDetails(java.lang.String sourceItem,
                                                    VersionSpec sourceVersion,
                                                    int sourceDeletionID,
                                                    java.lang.String targetItem,
                                                    VersionSpec targetVersion,
                                                    int targetDeletionID,
                                                    VersionSpec versionFrom,
                                                    VersionSpec versionTo,
                                                    RecursionType recursion)
Gets detailed information about merges performed on the given target item (and version), optionally qualified by a source item (which can be null).

Parameters:
sourceItem - the item that is the source of merges to be returned (may be null)
sourceVersion - the version of the source item for the merges (may be null if sourceItem is null)
sourceDeletionID - the deletion ID for the source item, if a specific deletion is being queried.
targetItem - the item that is the target of merges to be returned (must not be null or empty)
targetVersion - the version of the target item for the merges (must not be null)
targetDeletionID - the deletion ID for the target item, if a specific deletion is being queried.
versionFrom - the oldest version to be included in the results (may be null)
versionTo - the most recent version to be included in the results (may be null)
recursion - the type of recursion to apply to the given items (must not be null)
Returns:
the ChangesetMergeDetails returned by the server.

queryMergesExtended

public ExtendedMerge[] queryMergesExtended(ItemSpec targetItemSpec,
                                           VersionSpec targetVersionSpec,
                                           VersionSpec versionFrom,
                                           VersionSpec versionTo,
                                           QueryMergesExtendedOptions options)
Gets source changes for a given ItemSpec in a specific version range. The result is the set of changes as ExtendedMerge objects, which contain the source of the merge (item, version, deletionID, and change) as well as the changeset details. The Changeset is not a complete object: only the owner, committer, date, comment, and changesetID are available. No items, release notes, or other data are available.

Parameters:
targetItemSpec - the item that is the target of merges to be queried (must not be null)
targetVersionSpec - the version of the target item to query at (must not be null)
versionFrom - the oldest version to be included in the results (may be null)
versionTo - the most recent version to be included in the results (may be null)
options - the options to use (must not be null)
Returns:
the ChangesetMergeDetails returned by the server.

queryMergeRelationships

public ItemIdentifier[] queryMergeRelationships(java.lang.String serverItem)
Returns all items which have a merge relationship to the provided item.

Parameters:
serverItem - Server Item to query.
Returns:
Array of ItemIdentifier objects.

setCheckinPolicies

public void setCheckinPolicies(java.lang.String teamProjectPath,
                               PolicyDefinition[] definitions)
Sets the checkin policies for the given team project path. If the given definitions are null or empty, all policies are removed (annotation is deleted).

Parameters:
teamProjectPath - the team project path to set policies for (must not be null)
definitions - the policy definitions to set for the path, overwriting any previously set policy definitions. If null or empty, all policies are removed for the team project.

getServerSupportedFeatures

public SupportedFeatures getServerSupportedFeatures()
Gets the SupportedFeatures for the server this VersionControlClient is connected to. This value is retrieved from the server the first time this method is called. Subsequent calls to this method will return the cached value.

Returns:
the server supported features (never null)

getServerSettingsWithFallback

public ServerSettings getServerSettingsWithFallback(java.util.concurrent.atomic.AtomicBoolean fallbackUsed)
Gets ServerSettings from the Server if available If not, it will return a settings object with appropriate defaults.

Parameters:
fallbackUsed - Returns true if the default was used due to the server not supporting this feature

getMaxServerPathLength

public int getMaxServerPathLength()

getLatestChangesetID

public int getLatestChangesetID()
Gets the latest changeset ID from the server.

Returns:
the changeset ID number of the latest changeset.

destroy

public Item[] destroy(ItemSpec itemSpec,
                      VersionSpec versionSpec,
                      VersionSpec stopAt,
                      DestroyFlags flags)
Permanently destroys a versioned item. The item to be destroyed is identified by an ItemSpec (which must contain a server path and use full recursion) and an VersionSpec. The destroyed item is the item that has the specified server path at the specified version. The item to be destroyed does not need to be deleted before calling destroy. If the item is deleted, a deletion ID can be specified in the item spec.

If destroy is successful, the items are immediately destroyed on the server - destroy does not create pending changes like many other version control methods.

The destroy feature is not available in TFS 2005. This method will throw an exception if this VersionControlClient is connected to a Team Foundation server that does not support destroy. Additionally, the authenticated user must have the AdminProjectRights permission on all items that will be destroyed.

This method is an core event origination point. The EventSource object that accompanies each event fired by this method describes the execution context (current thread, etc.) when and where this method was invoked.

Parameters:
itemSpec - identifies the item to destroy (must not be null and must contain a server path, not a local path)
versionSpec - identifies the item to destroy (must not be null)
stopAt - if keeping history, identifies the version including and after which file contents will be preserved for - defaults to latest version (must be null if not passing DestroyFlags.KEEP_HISTORY)
flags - the flags for this destroy operation, or DestroyFlags.NONE for default options
Returns:
the items that were destroyed as a result of this call (never null)

destroy

public Item[] destroy(ItemSpec itemSpec,
                      VersionSpec versionSpec,
                      VersionSpec stopAt,
                      DestroyFlags flags,
                      java.util.List<PendingSet> affectedPendingChanges,
                      java.util.List<PendingSet> affectedShelvedChanges)
Permanently destroys a versioned item. The item to be destroyed is identified by an ItemSpec (which must contain a server path and use full recursion) and an VersionSpec. The destroyed item is the item that has the specified server path at the specified version. The item to be destroyed does not need to be deleted before calling destroy. If the item is deleted, a deletion ID can be specified in the item spec.

If destroy is successful (and DestroyFlags.PREVIEW was not specified), the items are immediately destroyed on the server - destroy does not create pending changes like many other version control methods.

The destroy feature is not available in TFS 2005. This method will throw an exception if this VersionControlClient is connected to a Team Foundation server that does not support destroy. Additionally, the authenticated user must have the AdminProjectRights permission on all items that will be destroyed.

This method is an core event origination point. The EventSource object that accompanies each event fired by this method describes the execution context (current thread, etc.) when and where this method was invoked.

Parameters:
itemSpec - identifies the item to destroy (must not be null and must contain a server path, not a local path)
versionSpec - identifies the item to destroy (must not be null)
stopAt - if keeping history, identifies the version including and after which file contents will be preserved for - defaults to latest version (must be null if not passing DestroyFlags.KEEP_HISTORY)
flags - the flags for this destroy operation, or DestroyFlags.NONE for default options
affectedPendingChanges - a list to be filled with the pending sets affected by the destroy operation if the DestroyFlags.AFFECTED_CHANGES flag is set. May be null if the list of changes is not required.
affectedShelvedChanges - a list to be filled with the shelved sets affected by the destroy operation if the DestroyFlags.AFFECTED_CHANGES flag is set. May be null if the list of changes is not required.
Returns:
the items that were destroyed as a result of this call (never null)

resolveLocalConflicts

public void resolveLocalConflicts(Workspace workspace,
                                  Conflict[] conflicts,
                                  ResolveErrorOptions errorOptions)
Resolve local file conflicts.


autoResolveValidConflicts

public Conflict[] autoResolveValidConflicts(Workspace workspace,
                                            Conflict[] conflicts,
                                            AutoResolveOptions resolveOptions)
Takes a list of candidates for AutoResolve and attempts to resolve them with the correct resolution and performing a content merge if necessary.

Parameters:
conflicts - The candidate conflicts
resolveOptions - Resolution options
Returns:
unresolved conflicts

resolveConflicts

public void resolveConflicts(Workspace workspace,
                             Conflict[] conflicts,
                             java.lang.String[] itemPropertyFilters,
                             ResolveErrorOptions errorOptions,
                             java.util.concurrent.atomic.AtomicReference<Conflict[]> resolvedConflicts)

updateUserName

public void updateUserName()
Asks the server to update the authenticated user's display name. No client state is changed by this method, but subsequent requests to the server will reveal any changes made to the user's full name.


determineWorkspaceNameAndOwner

public void determineWorkspaceNameAndOwner(ItemSpec itemSpec,
                                           java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceName,
                                           java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceOwner)
See Also:
#determineWorkspaceNameAndOwner(ItemSpec[], AtomicReference, AtomicReference)

determineWorkspaceNameAndOwner

public void determineWorkspaceNameAndOwner(java.lang.String path,
                                           java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceName,
                                           java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceOwner)
See Also:
#determineWorkspaceNameAndOwner(ItemSpec[], AtomicReference, AtomicReference)

determineWorkspaceNameAndOwner

public void determineWorkspaceNameAndOwner(LabelItemSpec[] labelItemSpecs,
                                           java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceName,
                                           java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceOwner)
See Also:
#determineWorkspaceNameAndOwner(ItemSpec[], AtomicReference, AtomicReference)

determineWorkspaceNameAndOwner

public void determineWorkspaceNameAndOwner(SecurityChange[] securityChanges,
                                           java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceName,
                                           java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceOwner)
See Also:
#determineWorkspaceNameAndOwner(ItemSpec[], AtomicReference, AtomicReference)

determineWorkspaceNameAndOwner

public void determineWorkspaceNameAndOwner(java.lang.String[] paths,
                                           java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceName,
                                           java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceOwner)
See Also:
#determineWorkspaceNameAndOwner(ItemSpec[], AtomicReference, AtomicReference)

determineWorkspaceNameAndOwner

public void determineWorkspaceNameAndOwner(ItemSpec[] itemSpecs,
                                           java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceName,
                                           java.util.concurrent.atomic.AtomicReference<java.lang.String> workspaceOwner)
Determine the workspace name and owner for all given items which are local paths. Throws if any two paths are in different workspaces. Does not throw if no workspace was found (AtomicReference values are set to null).

Parameters:
itemSpecs - the ItemSpecs to determine name and owner for (if null, both AtomicReference values are set to null)
workspaceName - the AtomicReference to update with the workspace name (must not be null)
workspaceOwner - the AtomicReference to update with the workspace owner (must not be null)
Throws:
OnlyOneWorkspaceException - if any two paths are in different workspaces

resolveUserUniqueName

public java.lang.String resolveUserUniqueName(java.lang.String user)
Resolve the specified user name to an actual, fully qualified unique user name. This may involve contacting the server to find out the current authorized identity.

Parameters:
user - the user name to resolve (if null, null is returned)
Returns:
the resolved display name, null if null was given

resolveUserDisplayName

public java.lang.String resolveUserDisplayName(java.lang.String user)
Resolve the specified user name to an actual, fully qualified user name. This may involve contacting the server to find out the current authorized identity.

Parameters:
user - the user name to resolve (if null, null is returned)
Returns:
the resolved display name, null if null was given

isAuthorizedUser

public boolean isAuthorizedUser(java.lang.String name)
Returns:
true if the passed in name represents the authorized user.

removeCachedWorkspace

public WorkspaceInfo removeCachedWorkspace(java.lang.String workspaceName,
                                           java.lang.String workspaceOwner)
Removes a cached workspace that matches the given name and owner and this client's server's GUID from the Workstation's cache. The caller is responsible for saving the Workstation cache.


queryCachedFileType

public FileType queryCachedFileType(java.lang.String extension)

getFileTypes

public FileType[] getFileTypes()

mergeWithDefaultItemPropertyFilters

public java.lang.String[] mergeWithDefaultItemPropertyFilters(java.lang.String[] filters)
Merges the specified filters with the default item property filters configured on this VersionControlClient. Only unique filters are returned (case insensitive) and order is not preserved.

Parameters:
filters - some item property filters or null
Returns:
a new array of filters including the specified filters (if any) and the default filters, or null if the specified filters were null and there are no default filters
See Also:
getDefaultItemPropertyFilters(), setDefaultItemPropertyFilters(String[])

getWorkspaceSecurity

public SecurityNamespace getWorkspaceSecurity()


© 2015 Microsoft. All rights reserved.