com.microsoft.tfs.core.clients.versioncontrol.path
Class ServerPath

java.lang.Object
  extended by com.microsoft.tfs.core.clients.versioncontrol.path.ServerPath

public abstract class ServerPath
extends java.lang.Object

TFS version control repository path utility functions.

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

Field Summary
static java.util.Comparator<java.lang.String> BOTTOM_UP_COMPARATOR
          Compares well-formed server path strings in a bottom-up fashion (children sort before their parents).
static int MAXIMUM_COMPONENT_LENGTH
          Longest allowable TFS directory component part
static char PREFERRED_SEPARATOR_CHARACTER
          The preferred separator character.
static java.lang.String ROOT
          All server paths begin with this string.
static java.lang.String ROOT_NAME_ONLY
          Occasionally code must format a path using the root without the slash.
static char[] SEPARATOR_CHARACTERS
          Allowed path separator characters in repository paths.
static java.util.Comparator<java.lang.String> TOP_DOWN_COMPARATOR
          Compares well-formed server path strings in a top-down fashion (parents sort before their children).
 
Constructor Summary
ServerPath()
           
 
Method Summary
static java.lang.String canonicalize(java.lang.String serverPath)
          Returns a new version of the given repository path that is fully rooted and canonicalized.
static void checkForIllegalDollarInPath(java.lang.String path)
          This method throws an InvalidPathException if there is a dollar sign ('$') that follows a path separator ('/') since no part of a path is allowed to start with a dollar sign.
static ItemValidationError checkServerItem(java.util.concurrent.atomic.AtomicReference<java.lang.String> item, java.lang.String parameterName, boolean allowNull, boolean allowWildcards, boolean allow8Dot3Paths, boolean checkReservedCharacters)
           
static ItemValidationError checkServerItem(java.util.concurrent.atomic.AtomicReference<java.lang.String> item, java.lang.String parameterName, boolean allowNull, boolean allowWildcards, boolean allow8Dot3Paths, boolean checkReservedCharacters, int maxServerPathLength)
           
static java.lang.String combine(java.lang.String parent, java.lang.String relative)
          Combines the two given paths into one path string, using Team Foundation Server's preferred path separator character.
static int compareBottomUp(java.lang.String pathA, java.lang.String pathB)
          Compares two server paths (ordinal character comparison) placing parents after their children.
static int compareTopDown(java.lang.String pathA, java.lang.String pathB)
          Compares two server paths (ordinal character comparison) placing children after their parents.
static boolean equals(java.lang.String path1, java.lang.String path2)
          Compares two repository paths.
static boolean equals(java.lang.String path1, java.lang.String path2, boolean ignoreCase)
          Compares two repository paths, optionally ignoring case.
static java.lang.String getCommonParent(java.lang.String path1, java.lang.String path2)
          Given two canonical server paths, return the farthest item from $/ that parents both items.
static java.lang.String getFileName(java.lang.String serverPath)
          Gets just the file part of the given server path, which is all of the string after the last path component.
static java.lang.String getFirstNode(java.lang.StringBuilder path)
          Takes a repository path as a StringBuilder and parses out the top node in the path and returns it as the parent.
static int getFolderDepth(java.lang.String serverPath)
          Returns the depth of the item described by path, where the root folder is depth 0, team projects are at depth 1, and so on.
static int getFolderDepth(java.lang.String serverPath, int maxDepth)
          Returns the depth of the item described by path, where the root folder is depth 0, team projects are at depth 1, "$/Proj/a" is 2, and so on.
static java.lang.String[] getHierarchy(java.lang.String serverPath)
          Returns the hierarchy leading up to this path.
static java.lang.String getParent(java.lang.String serverPath)
          Gets just the folder part of the given server path, which is all of the string up to the last component (the file part).
static java.lang.String getTeamProject(java.lang.String serverPath)
          For a passed server path, calculate the project path.
static java.lang.String getTeamProjectName(java.lang.String serverPath)
          Returns the name of the team project that the item resides in.
static java.lang.String[] getTeamProjects(java.lang.String[] serverPaths)
          Perform getTeamProject for an array of serverPaths and return an array of unique team projects that those serverPaths are in.
static int hashCode(java.lang.String path)
          Computes a hashCode from the specified server path.
static boolean isCanonicalizedPath(java.lang.String serverItem, boolean allowSemicolon)
          Returns true if the path is canonicalized.
static boolean isChild(java.lang.String parentPath, java.lang.String possibleChild)
           Tests the given paths for a parent-child relationship.
static boolean isDirectChild(java.lang.String serverFolderPath, java.lang.String serverPossibleChild)
          Tests whether one path is a direct child of another path (which would be the parent).
static boolean isRootFolder(java.lang.String path)
           
static boolean isSeparator(char c)
          Tests whether the given character is a valid repository path separator character (as defined by SEPARATOR_CHARACTERS).
static boolean isServerPath(java.lang.String path)
          Tests whether the path supplied is a server path (not local path).
static boolean isTeamProject(java.lang.String serverFolder)
          Return whether the passed server item is a team project ($/proja, $/projb, not $/proja/b nor $/).
static boolean isValidPathCharacter(char c)
          Tests whether the given character is valid in a repository path component (file/folder name).
static boolean isWildcard(java.lang.String serverPath)
          Tests whether the given server path contains wildcard characters in its final path element.
static java.lang.String makeLocal(java.lang.String serverPath, java.lang.String relativeToServerPath, java.lang.String localRoot)
           Maps a server path to a local path, given a parent server path of the path to be mapped, and a local path that corresponds to the parent.
static java.lang.String makeRelative(java.lang.String serverPath, java.lang.String relativeTo)
           Returns a new string describing the first given path made relative to the second given path.
static boolean matchesWildcard(java.lang.String firstItemPath, java.lang.String secondItemFolderPath, java.lang.String secondItemWildcardPattern, boolean recursive)
           Matches one item against a wildcard tuple (item path and wildcard pattern to apply to that item path), optionally allowing recursive matches.
static java.lang.String[] split(java.lang.String serverPath)
          Splits the given server path into its components.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ROOT_NAME_ONLY

public static final java.lang.String ROOT_NAME_ONLY
Occasionally code must format a path using the root without the slash.

Constant Field Value:
"$"
See Also:
Constant Field Values

ROOT

public static final java.lang.String ROOT
All server paths begin with this string. The slash is important (the server seems to always reject access to "$").

Constant Field Value:
"$/"
See Also:
Constant Field Values

SEPARATOR_CHARACTERS

public static final char[] SEPARATOR_CHARACTERS
Allowed path separator characters in repository paths. All characters are equivalent. Forward slash ('/') is the preferred character.


PREFERRED_SEPARATOR_CHARACTER

public static final char PREFERRED_SEPARATOR_CHARACTER
The preferred separator character.

Constant Field Value:
47
See Also:
Constant Field Values

MAXIMUM_COMPONENT_LENGTH

public static final int MAXIMUM_COMPONENT_LENGTH
Longest allowable TFS directory component part

Constant Field Value:
256
See Also:
Constant Field Values

TOP_DOWN_COMPARATOR

public static final java.util.Comparator<java.lang.String> TOP_DOWN_COMPARATOR
Compares well-formed server path strings in a top-down fashion (parents sort before their children).


BOTTOM_UP_COMPARATOR

public static final java.util.Comparator<java.lang.String> BOTTOM_UP_COMPARATOR
Compares well-formed server path strings in a bottom-up fashion (children sort before their parents).

Constructor Detail

ServerPath

public ServerPath()
Method Detail

equals

public static final boolean equals(java.lang.String path1,
                                   java.lang.String path2)
Compares two repository paths. Case is ignored. null values are not permitted.

Parameters:
path1 - the first repository path (must not be null)
path2 - the second repository path (must not be null)
Returns:
true if the paths are equal, false if not.

hashCode

public static final int hashCode(java.lang.String path)
Computes a hashCode from the specified server path. NOTE: This version of hashCode only pairs with the equals method that takes two strings and should not be used in conjunction with it.

Parameters:
path - the server path to compute a hash code for.
Returns:
a hash code

equals

public static final boolean equals(java.lang.String path1,
                                   java.lang.String path2,
                                   boolean ignoreCase)
Compares two repository paths, optionally ignoring case. null values are not permitted.

Parameters:
path1 - the first repository path (must not be null)
path2 - the second repository path (must not be null)
ignoreCase - true if we should ignore case
Returns:
true if the paths are equal, false if not.

checkServerItem

public static ItemValidationError checkServerItem(java.util.concurrent.atomic.AtomicReference<java.lang.String> item,
                                                  java.lang.String parameterName,
                                                  boolean allowNull,
                                                  boolean allowWildcards,
                                                  boolean allow8Dot3Paths,
                                                  boolean checkReservedCharacters)

checkServerItem

public static ItemValidationError checkServerItem(java.util.concurrent.atomic.AtomicReference<java.lang.String> item,
                                                  java.lang.String parameterName,
                                                  boolean allowNull,
                                                  boolean allowWildcards,
                                                  boolean allow8Dot3Paths,
                                                  boolean checkReservedCharacters,
                                                  int maxServerPathLength)
Parameters:
item -
parameterName -
allowNull -
allowWildcards -
allow8Dot3Paths -
checkReservedCharacters -
Returns:

isRootFolder

public static final boolean isRootFolder(java.lang.String path)
Parameters:
path - the path to test (may be null)
Returns:
true if the given path is equal to ROOT, false if it is not

isChild

public static final boolean isChild(java.lang.String parentPath,
                                    java.lang.String possibleChild)
                             throws ServerPathFormatException

Tests the given paths for a parent-child relationship. A path is a child of another if the object it describes would reside below the object described by the parent path in the TFS repository. Case is ignored.

A possible child that is equivalent to the parent path (both refer to the same object) is considered a child. This is compatible with Visual Studio's implementation.

Parameters:
parentPath - the server path to the parent item (must not be null)
possibleChild - the server path of the possible child item (must not be null)
Returns:
true if possibleChild is a child of parentPath.
Throws:
ServerPathFormatException

matchesWildcard

public static final boolean matchesWildcard(java.lang.String firstItemPath,
                                            java.lang.String secondItemFolderPath,
                                            java.lang.String secondItemWildcardPattern,
                                            boolean recursive)
                                     throws ServerPathFormatException

Matches one item against a wildcard tuple (item path and wildcard pattern to apply to that item path), optionally allowing recursive matches.

Character case is ignored during wildcard matching.

Parameters:
firstItemPath - the item to test against the wildcard pattern. This is a full path (must not be null)
secondItemFolderPath - a path where the wildcard pattern will be applied to find the item described by firstItemPath. If this parameter is a child of firstItemPath, there wildcard pattern will never match. If this parameter is a direct parent of firstItemPath, the wildcard can match. If this parameter is a grandparent (or greater), the pattern can only match if the recursive parameter is true. Not null.
secondItemWildcardPattern - the wildcard pattern to apply to secondItemFolderPath. If null, wildcards are not evaluated and the first item path is tested whether it equals or is a child of the second item folder path (depending on the recursive value).
recursive - if true, the wildcard pattern will apply to secondItemFolderPath and all its possible children. If false, the wildcard pattern will only match direct children of secondItemFolderPath.
Returns:
true if the firstItemPath matches the wildcard specification, false if it does not.
Throws:
ServerPathFormatException - if one of the supplied paths is not a valid server path.

canonicalize

public static final java.lang.String canonicalize(java.lang.String serverPath)
                                           throws ServerPathFormatException
Returns a new version of the given repository path that is fully rooted and canonicalized. Use this function to sanitize user input or to expand partial paths encountered in server data. Note: strips trailing slashes from directories, except $/.

Parameters:
serverPath - the repository path string to clean up.
Returns:
the cleaned up path.
Throws:
ServerPathFormatException - when the path cannot be cleaned up.

isCanonicalizedPath

public static boolean isCanonicalizedPath(java.lang.String serverItem,
                                          boolean allowSemicolon)
Returns true if the path is canonicalized. The path must not contain a $ at the beginning of a path part, or any illegal characters.


makeRelative

public static java.lang.String makeRelative(java.lang.String serverPath,
                                            java.lang.String relativeTo)

Returns a new string describing the first given path made relative to the second given path.

Character case is ignored during string comparison, so strings with mismatched-in-case common elements will still succeed in being made relative.

Paths are not normalized (for ending separators, case, etc.). It is the caller's responsibility to make sure the relativeTo path can be matched.

Parameters:
serverPath - the path to the server item to describe (must not be null)
relativeTo - the path that the first parameter will be described relative to (must not be null)
Returns:
the relative path, or the unaltered given server path if it could not be made relative to the second path.

makeLocal

public static java.lang.String makeLocal(java.lang.String serverPath,
                                         java.lang.String relativeToServerPath,
                                         java.lang.String localRoot)

Maps a server path to a local path, given a parent server path of the path to be mapped, and a local path that corresponds to the parent.

Character case is ignored during string comparison, so strings with mismatched-in-case common elements will still succeed in being made relative.

Paths are not normalized (for ending separators, case, etc.). It is the caller's responsibility to make sure the relativeToServerPath path can be matched.

Parameters:
serverPath - the server path to convert to a local path (must not be null)
relativeToServerPath - the parent server path (must not be null and must be a parent of serverPath)
localRoot - the local path that corresponds to relativeToServerPath (must not be null)
Returns:
the corresponding local path (never null)

isValidPathCharacter

public static final boolean isValidPathCharacter(char c)
Tests whether the given character is valid in a repository path component (file/folder name).

Parameters:
c - the character to test.
Returns:
true if the character is allowed in a path component (file/folder), false if not.

isSeparator

public static final boolean isSeparator(char c)
Tests whether the given character is a valid repository path separator character (as defined by SEPARATOR_CHARACTERS).

Parameters:
c - the character to test.
Returns:
true if the character is a valid separator character, false otherwise.

isServerPath

public static final boolean isServerPath(java.lang.String path)
Tests whether the path supplied is a server path (not local path).

Parameters:
path - the path to test (must not be null)
Returns:
true if the path describes a version control server path and not a local path or some other string.

compareTopDown

public static final int compareTopDown(java.lang.String pathA,
                                       java.lang.String pathB)
Compares two server paths (ordinal character comparison) placing children after their parents.

If sorting paths for display to the user, better to use a Collator-based comparison instead of this one.

Parameters:
pathA - the first path to compare (must not be null)
pathB - the second path to compare (must not be null)
Returns:
see Object.compareTo().

compareBottomUp

public static final int compareBottomUp(java.lang.String pathA,
                                        java.lang.String pathB)
Compares two server paths (ordinal character comparison) placing parents after their children.

If sorting paths for display to the user, better to use a Collator-based comparison instead of this one.

Parameters:
pathA - the first path to compare (must not be null)
pathB - the second path to compare (must not be null)
Returns:
see Object.compareTo().

getFirstNode

public static final java.lang.String getFirstNode(java.lang.StringBuilder path)
Takes a repository path as a StringBuilder and parses out the top node in the path and returns it as the parent. The remaining path is then shortened to only include the rest of the path, minus the top node.

Parameters:
path - the path to find the top node in (must not be null)
Returns:
the first node in the path that was supplied.

isWildcard

public static boolean isWildcard(java.lang.String serverPath)
Tests whether the given server path contains wildcard characters in its final path element. Wildcards in initial path elements are ignored.

Parameters:
serverPath - the server path to test for wildcards (in last element only). Not null.
Returns:
true if the last path element contains wildcards, false otherwise.

getParent

public static java.lang.String getParent(java.lang.String serverPath)
Gets just the folder part of the given server path, which is all of the string up to the last component (the file part). If the given path describes a folder but does not end in a separator, the last folder is discarded.

Parameters:
serverPath - the server path of which to return the folder part (must not be null)
Returns:
a server path with only the folder part of the given path, ending in a separator character.

getFileName

public static java.lang.String getFileName(java.lang.String serverPath)
Gets just the file part of the given server path, which is all of the string after the last path component. If there are no separators, the entire string is returned. If the string ends in a separator, an empty string is returned.

Parameters:
serverPath - the server path from which to parse the file part (must not be null)
Returns:
the file name at the end of the given server path, or the given path if no separator characters were found, or an empty string if the given path ends with a separator.

isDirectChild

public static boolean isDirectChild(java.lang.String serverFolderPath,
                                    java.lang.String serverPossibleChild)
Tests whether one path is a direct child of another path (which would be the parent).

Parameters:
serverFolderPath - the server path to the parent folder (must not be null)
serverPossibleChild - the server path of the possible child item (must not be null)
Returns:
true if the serverPossibleChild is a child of the serverFolderPath

getTeamProject

public static java.lang.String getTeamProject(java.lang.String serverPath)
For a passed server path, calculate the project path. This is currently just the first folder name with the "$/" to replicate the behaviour of the MS Client.

Parameters:
serverPath - String path of a server item (for example "$/TeamProject/MyPath/MyItem.java").
Returns:
String containing path to Team project that the serverPath resides in i.e. "$/TeamProject". If an error occured or Team Project was not part of the path, returns null.

getTeamProjects

public static java.lang.String[] getTeamProjects(java.lang.String[] serverPaths)
Perform getTeamProject for an array of serverPaths and return an array of unique team projects that those serverPaths are in.

See Also:
getTeamProject(String)

getTeamProjectName

public static java.lang.String getTeamProjectName(java.lang.String serverPath)
Returns the name of the team project that the item resides in. Currently this is just the first folder name of the item without the "$/".

Parameters:
serverPath - String path of a server item (for example "$/TeamProject/MyPath/MyItem.java").
Returns:
String containing the name of the Team Project that the item resides in i.e. "TeamProject". Null if the given server path was null or no team project name was found in the path (i.e. in the case of the root path, "$/").

isTeamProject

public static boolean isTeamProject(java.lang.String serverFolder)
Return whether the passed server item is a team project ($/proja, $/projb, not $/proja/b nor $/). The item must be in the canonical server path format for folders (no trailing slash except for the root folder).

Parameters:
serverFolder - a fully qualified server folder item (must not be null)
Returns:
true if the item is a team project (is an element directly under the server root folder), false otherwise

getFolderDepth

public static int getFolderDepth(java.lang.String serverPath)
Returns the depth of the item described by path, where the root folder is depth 0, team projects are at depth 1, and so on.

Parameters:
serverPath - the server path to test (must not be null)
Returns:
the depth from root, where root is 0, team projects are 1, etc.

getFolderDepth

public static int getFolderDepth(java.lang.String serverPath,
                                 int maxDepth)
Returns the depth of the item described by path, where the root folder is depth 0, team projects are at depth 1, "$/Proj/a" is 2, and so on.

Parameters:
serverPath - the server path to test (must not be null)
maxDepth - the maximum depth to search.
Returns:
the depth from root, where root is 0, team projects are 1, etc.

combine

public static java.lang.String combine(java.lang.String parent,
                                       java.lang.String relative)
Combines the two given paths into one path string, using Team Foundation Server's preferred path separator character. If path2 is an absolute path, it is returned as the entire return value (path1 is discarded).

Parameters:
parent - the first (left-side) path component (must not be null or empty).
relative - the second (right-side) path component (must not be null)

split

public static java.lang.String[] split(java.lang.String serverPath)
Splits the given server path into its components.

Parameters:
serverPath - The server path to split (must not be null)
Returns:
An array of the components of the path

getHierarchy

public static java.lang.String[] getHierarchy(java.lang.String serverPath)
Returns the hierarchy leading up to this path. Root path will be at index 0, full path to team project will be at index 1, etc.

Parameters:
serverPath - The server path to obtain the hierarchy for (must not be null)
Returns:
An array of strings representing the hierarchy leading up to this server path

getCommonParent

public static java.lang.String getCommonParent(java.lang.String path1,
                                               java.lang.String path2)
Given two canonical server paths, return the farthest item from $/ that parents both items. If one of the two paths is null, the other will be returned. If both paths are null, an IllegalArgumentException is thrown.

Parameters:
path1 - a server path starting with $/ (must not be null or empty)
path2 - a server path starting with $/ (must not be null or empty)
Returns:
the farthest item from $/ that parents both path1 and path2

checkForIllegalDollarInPath

public static void checkForIllegalDollarInPath(java.lang.String path)
This method throws an InvalidPathException if there is a dollar sign ('$') that follows a path separator ('/') since no part of a path is allowed to start with a dollar sign.

Parameters:
path - the path to check (path must already be canonicalized)


© 2015 Microsoft. All rights reserved.