com.microsoft.tfs.core.util
Class URIUtils

java.lang.Object
  extended by com.microsoft.tfs.core.util.URIUtils

public class URIUtils
extends java.lang.Object

Static utility methods for working with URIs.

See Also:
URI

Constructor Summary
URIUtils()
           
 
Method Summary
static java.net.URI addQueryParameters(java.net.URI parent, java.util.Map<java.lang.String,java.lang.String> queryParameters)
           Appends the specified parent URI with provided query parameters.
static java.lang.String combinePartiallyEncodedPaths(java.lang.String path1, java.lang.String path2)
          Combine two partial URI paths to create a single path.
static java.lang.String combinePaths(java.lang.String path1, java.lang.String path2)
          Combine two partial URI paths to create a single path.
static java.lang.String combinePaths(java.lang.String path1, java.lang.String path2, boolean encodeRelativePath)
          Combine two partial URI paths to create a single path.
static java.lang.String decodeForDisplay(java.lang.String asciiURIString)
          Returns a URI string string for display to the user, decoding escaped ASCII characters into Unicode.
static java.lang.String decodeForDisplay(java.net.URI uri)
          Returns a URI string for display to the user, decoding escaped ASCII characters into Unicode.
static java.lang.String encodeQueryIgnoringPercentCharacters(java.lang.String partiallyEncoded)
          Encodes a URI query string which might already be encoded, or partially encoded, by encoding all characters that would normally need encoded in a query string except for the percent sign (which is left aloen).
static java.net.URI ensurePathHasTrailingSlash(java.net.URI uri)
           Ensures that the specified URI's path component ends with a slash character (/).
static java.net.URI newURI(java.lang.String uri)
           Constructs a new URI from a string representation of the URI.
static java.net.URI newURI(java.lang.String scheme, java.lang.String authority, java.lang.String path, java.lang.String query, java.lang.String fragment)
           Constructs a new URI from the string components of the URI.
static java.net.URI removePathAndQueryParts(java.net.URI uri)
          Returns a new URI containing only the scheme, user info, host, and port of the given URI.
static java.net.URI removeQueryParts(java.net.URI uri)
          Returns a new URI containing only the scheme, user info, host, port, and path of the given URI.
static java.net.URI removeTrailingSlash(java.net.URI uri)
          Ensures that the specified URI has any trailing slashes REMOVED.
static java.net.URI resolve(java.lang.String parent, java.lang.String child)
           Resolves the specified child string against the specified parent URI, returning a new URI as the result.
static java.net.URI resolve(java.net.URI parent, java.lang.String child)
           Resolves the specified child string against the specified URI, returning a new URI as the result.
static java.net.URI resolve(java.net.URI parent, java.net.URI child)
           Resolves the specified child URI against the specified URI, returning a URI as the result.
static java.lang.String safeGetHost(java.net.URI uri)
           If a URI is successfully constructed but contains invalid characters in the hostname (notably, underscores), the URI.getHost() method returns null.
static java.net.URI toLowerCase(java.net.URI uri)
           Ensures that all the components of the URI are in lower-case.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

URIUtils

public URIUtils()
Method Detail

ensurePathHasTrailingSlash

public static java.net.URI ensurePathHasTrailingSlash(java.net.URI uri)

Ensures that the specified URI's path component ends with a slash character (/).

URIs that will be resolved against should always have a trailing slash in their path component. For more information, see Sun Java bug 4666701 (http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4666701).

If the specified URI is opaque, it is returned. If the specified URI is hierarchical and its path component already ends in a slash, it is returned. Otherwise, a new URI is returned that is identical to the specified URI except in its path component, which will have a slash appended on.

Parameters:
uri - a URI to check (must not be null)
Returns:
a URI as described above (never null)

toLowerCase

public static java.net.URI toLowerCase(java.net.URI uri)

Ensures that all the components of the URI are in lower-case.

If the specified URI is opaque, it is returned. Otherwise, a new URI is returned that is identical to the specified URI except that the components (scheme, hostname, path) are converted to their lower case equivalents (in a generic locale.)

Parameters:
uri - a URI to check (must not be null)
Returns:
a URI as described above (never null)

removeTrailingSlash

public static java.net.URI removeTrailingSlash(java.net.URI uri)
Ensures that the specified URI has any trailing slashes REMOVED. VisualStudio uses server URIs that lack trailing slashes, this is for compatibility. However, a path of only / will be maintained.

Parameters:
uri - a URI to check (must not be null)
Returns:
a URI as described above (never null)

removeQueryParts

public static java.net.URI removeQueryParts(java.net.URI uri)
Returns a new URI containing only the scheme, user info, host, port, and path of the given URI.

Parameters:
uri - the URI to remove the query parts from (must not be null)
Returns:
a new URI containing only the scheme, user info, host, port, and path of the given URI

removePathAndQueryParts

public static java.net.URI removePathAndQueryParts(java.net.URI uri)
Returns a new URI containing only the scheme, user info, host, and port of the given URI.

Parameters:
uri - the URI to remove the path and query parts from (must not be null)
Returns:
a new URI containing only the scheme, user info, host, and port of the given URI

newURI

public static java.net.URI newURI(java.lang.String uri)

Constructs a new URI from a string representation of the URI. Any characters in the string that are illegal for URIs will be quoted. This method is an alternative to the single-argument URI constructor, which requires that all illegal characters must already be quoted.

For example, the following code fails with a URISyntaxException because the path component contains a space character, which is illegal:

 URI uri = new URI("http://example.com/path/a file.txt");
 
Instead, do this:
 URI uri = URIUtils.newURI("http://example.com/path/a file.txt");
 

Parameters:
uri - the String representation of the URI (must not be null)
Returns:
a new URI (never null)

newURI

public static java.net.URI newURI(java.lang.String scheme,
                                  java.lang.String authority,
                                  java.lang.String path,
                                  java.lang.String query,
                                  java.lang.String fragment)

Constructs a new URI from the string components of the URI. Any characters in the components that are illegal for URIs will be quoted. This method is an alternative to the corresponding URI constructor which does encode some characters, but not all necessary characters like the URIUtil class does (some RTL Unicode characters remain unescaped in the URI constructor which cause problems in HTTP requests).

Parameters:
scheme - Unencoded URI scheme
authority - Unencoded URI authority
path - Unencoded URI path
query - Unencoded URI query
fragment - Unencoded URI fragment
Returns:
the new URI

addQueryParameters

public static java.net.URI addQueryParameters(java.net.URI parent,
                                              java.util.Map<java.lang.String,java.lang.String> queryParameters)

Appends the specified parent URI with provided query parameters.

Old query parameters and/or fragments in the specified parent URI (if any) are discarded.

Parameters:
parent - a base URI (must not be null)
Returns:
a new URI as described above (never null)

resolve

public static java.net.URI resolve(java.net.URI parent,
                                   java.net.URI child)

Resolves the specified child URI against the specified URI, returning a URI as the result.

This method behaves differently than calling URI.resolve(URI). This method first uses the ensurePathHasTrailingSlash(URI) method to ensure that the specified parent URI's path has a trailing slash. See the documentation of ensurePathHasTrailingSlash(URI) method for a reason why this is necessary.

Parameters:
parent - a base URI to resolve against (must not be null)
child - a relative path to resolve (must not be null)
Returns:
a new URI as described above (never null)

resolve

public static java.net.URI resolve(java.lang.String parent,
                                   java.lang.String child)

Resolves the specified child string against the specified parent URI, returning a new URI as the result.

This method behaves differently than creating a new URI and calling URI.resolve(String). It first creates intermediate parent and child URIs using the newURI(String) method. Doing this ensures that any characters in the specified parent and child strings that are not legal URI characters are properly quoted. This method then uses the ensurePathHasTrailingSlash(URI) method to ensure that the specified parent URI's path has a trailing slash. See the documentation of ensurePathHasTrailingSlash(URI) method for a reason why this is necessary.

Parameters:
parent - a base URI to resolve against (must not be null)
child - a relative path to resolve (must not be null)
Returns:
a new URI as described above (never null)
Throws:
java.lang.IllegalArgumentException - if the URI string computed from the given child string violates RFC 2396

resolve

public static java.net.URI resolve(java.net.URI parent,
                                   java.lang.String child)

Resolves the specified child string against the specified URI, returning a new URI as the result.

This method behaves differently than calling URI.resolve(String). It first creates an intermediate child URI using the newURI(String) method. Doing this ensures that any characters in the specified child URI that are not legal URI characters are properly quoted. This method then uses the ensurePathHasTrailingSlash(URI) method to ensure that the specified parent URI's path has a trailing slash. See the documentation of ensurePathHasTrailingSlash(URI) method for a reason why this is necessary.

Parameters:
parent - a base URI to resolve against (must not be null)
child - a relative path to resolve (must not be null)
Returns:
a new URI as described above (never null)
Throws:
java.lang.IllegalArgumentException - if the URI string computed from the given child string violates RFC 2396

safeGetHost

public static java.lang.String safeGetHost(java.net.URI uri)

If a URI is successfully constructed but contains invalid characters in the hostname (notably, underscores), the URI.getHost() method returns null. This method first gets the host using that method. If null is returned, a best effort to get the original host (if any) is made by converting the URI to a URL and calling URL.getHost().

This method should only be used in the specific case when you want to try to detect and handle the above condition. For most cases, underscores in hostnames should correctly be treated as errors, and this method should not be used.

Parameters:
uri - the URI to get the host name for (must not be null)
Returns:
the host name of the URI, or null if the host name was not defined

combinePaths

public static java.lang.String combinePaths(java.lang.String path1,
                                            java.lang.String path2)
Combine two partial URI paths to create a single path.

Parameters:
path1 - The path prefix
path2 - A relative path.
Returns:
The concatenated string with and leading slashes or tildes removed from the second string.

combinePaths

public static java.lang.String combinePaths(java.lang.String path1,
                                            java.lang.String path2,
                                            boolean encodeRelativePath)
Combine two partial URI paths to create a single path.

Parameters:
path1 - The path prefix
path2 - A relative path.
encodeRelativePath - If true, URI-encode the relative path (path2) before appending
Returns:
The concatenated string with and leading slashes or tildes removed from the second string.

combinePartiallyEncodedPaths

public static java.lang.String combinePartiallyEncodedPaths(java.lang.String path1,
                                                            java.lang.String path2)
Combine two partial URI paths to create a single path. The second part of the path might already be encoded, or partially encoded. The method encodes all characters that would normally need encoded in a path except for the percent sign (which is left alone).

Parameters:
path1 - The path prefix
path2 - A relative path.
Returns:
The concatenated string with leading slashes or tildes removed from the second string.

encodeQueryIgnoringPercentCharacters

public static java.lang.String encodeQueryIgnoringPercentCharacters(java.lang.String partiallyEncoded)
Encodes a URI query string which might already be encoded, or partially encoded, by encoding all characters that would normally need encoded in a query string except for the percent sign (which is left aloen). This means that if your goal is to encode strings that might have percent signs which do need encoded, this method is not for you. This method is for a very limited set of encoding cases (specifically, TFS download URLs which are partially encoded but will never have percent signs in the parts which do need encoded).

Parameters:
partiallyEncoded - the URL query string which may already have some parts encoded with percent signs, but needs other parts encoded (not encoding any percent signs that might be in that part)
Returns:
the encoded string

decodeForDisplay

public static java.lang.String decodeForDisplay(java.net.URI uri)
Returns a URI string for display to the user, decoding escaped ASCII characters into Unicode. If the decoding fails (invalid escaped characters?) the URI's toString() value is returned instead.

Parameters:
uri - the URI to get the display string for (must not be null)
Returns:
the decoded URI string

decodeForDisplay

public static java.lang.String decodeForDisplay(java.lang.String asciiURIString)
Returns a URI string string for display to the user, decoding escaped ASCII characters into Unicode. If the decoding fails (invalid escaped characters?) the given string is returned instead.

Parameters:
asciiURIString - the URI String to get the display string for (must not be null)
Returns:
the decoded URI string


© 2015 Microsoft. All rights reserved.