Package com.globalmentor.net

Class URIs

java.lang.Object

com.globalmentor.net.URIs

public class URIs
extends Object

Various URI manipulating functions for working with URIs as defined in RFC 3986, "Uniform Resource Identifiers (URI): Generic Syntax".

For file URIs Java incorrectly uses the form file:/mnt/sdcard/... instead of file:///mnt/sdcard/..., but these utilities use the former for consistency.

See Also:

• URI
• RFC 3986: Uniform Resource Identifiers (URI): Generic Syntax

Field Summary

Fields

Modifier and Type	Field	Description
static final Characters	ALPHA_CHARACTERS	Alphabetic characters as defined by RFC 2396.
static final String	AUTHORITY_PREFIX	The prefix string that introduces an authority.
static final String	CURRENT_LEVEL_PATH	The collection path "./" representing the current hierarchical level of a hierarchical URI.
static final String	CURRENT_LEVEL_PATH_SEGMENT	The path segment "." representing the current hierarchical level of a hierarchical URI.
static final URI	CURRENT_LEVEL_PATH_URI	The URI collection path of "./" representing the current hierarchical level of a hierarchical URI.
static final Characters	DIGIT_CHARACTERS	Digit characters as defined by RFC 2396.
static final URI	EMPTY_PATH_URI	A shared URI constant equal to creating a URI from an empty path.
static final char	ESCAPE_CHAR	The character to use for escaping URI data as defined by RFC 2396.
static final Characters	EXTRA_CHARACTERS	Extra characters as defined by RFC 2396.
static final String	FILE_SCHEME	The file scheme identifier.
static final String	FILE_URI_PATH_ROOT_PREFIX	The sequence "//" which is supposed to be present in file URIs (e.g.
static final char	FRAGMENT_SEPARATOR	The pound character ('#') that separates a fragment from the rest of a URI.
static final String	FTP_SCHEME	The FTP scheme identifier.
static final Characters	GEN_DELIM_CHARACTERS	General delimiter characters defined by RFC 3986.
static final String	INFO_SCHEME	The info scheme identifier.
static final char	INFO_SCHEME_NAMESPACE_DELIMITER	The delimiter separating the info scheme namespace from the rest of the info scheme-specific part.
static final String	MAILTO_SCHEME	The email address scheme identifier.
static final char	MAILTO_USERNAME_DOMAIN_SEPARATOR	The character separating a mailto URI username from the domain.
static final int	MICROSOFT_INTERNET_EXPLORER_MAXIMUM_URI_LENGTH	The maximum URL length allowed by Microsoft Internet Explorer for HTTP GET.
static final URI[]	NO_URIS	The shared static empty array of URIs.
static final Characters	NORMAL_CHARACTERS	Characters that can appear in a URI path with no escape sequences.
static final String	PARENT_LEVEL_PATH	The collection path "../" representing the parent hierarchical level of a hierarchical URI.
static final String	PARENT_LEVEL_PATH_SEGMENT	The path segment ".." representing the parent hierarchical level of a hierarchical URI.
static final URI	PARENT_LEVEL_PATH_URI	The URI collection path "../" representing the parent hierarchical level of a hierarchical URI.
static final Characters	PATH_CHARACTERS	Path characters defined by RFC 3986.
static final String	PATH_SCHEME	The path scheme identifier for representing relative and absolute URI paths.
static final Characters	PATH_SEGMENT_CHARACTERS	Path segment characters defined by RFC 3986.
static final char	PATH_SEPARATOR	The slash character ('/') that separates components in a URI path.
static final Characters	PLAIN_ENCODE_CHARACTERS	The characters that are allowed in a URI plain encoding.
protected static final Characters	PLAIN_ENCODE_INITIAL_UNRESERVED_CHARACTERS	The characters that, at least initially, should not be encoded.
static final char	PLAIN_ENCODING_ESCAPE_CHAR	The character used for escaping characters in a URI plain encoding.
static final char	PLAIN_ENCODING_REPLACE_CHAR	The character used for replacing certain characters in a URI plain encoding.
static final char	PORT_SEPARATOR	The colon character (':') that separates a host from a port.
static final char	QUERY_NAME_VALUE_ASSIGNMENT	The character that represents assigning a value to a name in a query.
static final char	QUERY_NAME_VALUE_PAIR_DELIMITER	The character that separates each name-value pair in a query.
static final char	QUERY_SEPARATOR	The character that separates the query from the rest of a URI.
static final Characters	RESERVED_CHARACTERS	Reserved characters as defined by RFC 2396.
static final String	RESOURCE_SCHEME	The resource scheme identifier "resource".
static final String	ROOT_PATH	The path to root, consisting of a single path separator ("/").
static final String	ROOT_PATH_PARENT_LEVEL	The path Java returns when it tries to resolve .. to the root path.
static final URI	ROOT_PATH_URI	A URI consisting only of a single path separator ("/").
static final Characters	SAFE_CHARACTERS	Safe characters as defined by RFC 2396.
static final char	SCHEME_SEPARATOR	The colon character (':') that separates a URI schema from the rest of the URI.
static final Characters	SUB_DELIM_CHARACTERS	Subdelimiter characters defined by RFC 3986.
static final String	TEL_SCHEME	The telephone scheme identifier.
static final Characters	UNRESERVED_CHARACTERS	Unreserved characters defined by RFC 3986.
static final Characters	URI_CHARACTERS	Characters that can appear in a URI as defined by RFC 2396.
static final MediaType	URI_LIST_MEDIA_TYPE	A text/uri-list content type as defined in RFC 2483 § 5.
static final String	URN_SCHEME	The URN scheme identifier "urn".
static final Pattern	URN_SSP_PATTERN	The pattern to match the scheme-specific part of a URN.
static final int	URN_SSP_PATTERN_NID_MATCHING_GROUP	The matching group to retrieve the URN namespace identifier.
static final int	URN_SSP_PATTERN_NSS_MATCHING_GROUP	The matching group to retrieve the URN-namespace-specific part.
static final char	USER_INFO_SEPARATOR	The at sign ('@') that separates user information from a host in a URI.
static final String	WINDOWS_UNC_PATH_URI_SSP_PREFIX	The prefix used in the scheme-specific part by Java for Windows UNC paths in file URIs.

Constructor Summary

Constructors

Constructor	Description
URIs()

Method Summary

Modifier and Type	Method	Description
static URI	addRawNameExtension(URI uri, String extension)	Adds the given extension to a URI name and returns the new URI with the new extension.
static URI	appendQueryParameter(URI uri, String paramName, String paramValue)	Constructs a query string for a URI with a single name/value parameter, and appends it to the query of the given URI, if any.
static String	appendQueryParameters(String query, URIQueryParameter... params)	Constructs a query string for a URI and appends it to the given query, if any.
static URI	appendQueryParameters(URI uri, URIQueryParameter... params)	Constructs a query string for a URI and appends it to the query of the given URI, if any.
static URI	appendRawNameBase(URI uri, CharSequence charSequence)	Appends a given string to the end of the URI's raw name before the extension, if any.
static URI	appendRawQuery(URI uri, String rawQuery)	Appends a query string to a URI.
static URI	canonicalize(URI uri)	Ensures that the given URI is in canonical form.
static URI	changeBase(URI uri, URI oldBaseURI, URI newBaseURI)	Changes a URI from one base to another.
static URI	changeHost(URI uri, String newHost)	Creates a new URI identical to the supplied URI with a different host.
static String	changeName(String path, String name)	Deprecated. to be removed in favor of changePathName(String, String)
static URI	changeName(URI uri, String name)	Changes the name of the path of the given URI to the given name.
static URI	changePath(URI uri, URIPath path)	Creates a new URI identical to the supplied URI with a different path.
static String	changePathName(String path, String name)	Changes the name of the path of the given URI to the given name.
static URI	changeRawName(URI uri, String rawName)	Changes the raw name of the path of the given URI to the given raw name.
static URI	changeRawNameBase(URI uri, String base)	Changes the base of a URI name, preserving the extension(s), if any.
static URI	changeRawNameExtension(URI uri, String extension)	Changes the extension of a URI name and returns a new URI with the new name extension.
static URI	changeRawPath(URI uri, String newRawPath)	Creates a new URI identical to the supplied URI with a different raw path.
static URI	changeRawSchemeSpecificPart(URI uri, String newRawSSP)	Creates a new URI identical to the supplied URI with a different raw scheme-specific part.
static URI	changeScheme(URI uri, String newScheme)	Creates a new URI identical to the supplied URI with a different scheme.
static URI	checkAbsolute(URI uri)	Checks to see if a given URI is absolute.
static String	checkCollectionPath(String path)	Checks to see if a given path represents a canonical collection, that is, it has a path that ends with a slash ('/').
static URI	checkCollectionURI(URI uri)	Checks to see if a given URI represents a canonical collection, that is, it has a path that ends with a slash ('/').
static final URI	checkInfoNamespace(URI uri, String infoNamespace)	Verifies that the given URI is an "info" scheme URI with the given namespace.
static String	checkNotCollectionPath(String path)	Checks to see if a given path does not represents a canonical collection, that is, it does not have a path that ends with a slash ('/').
static URI	checkNotCollectionURI(URI uri)	Checks to see if a given URI does not represents a canonical collection, that is, it does not have a path that ends with a slash ('/').
static String	checkPath(String path)	Checks to see if a given path is only a path and not a URI with a scheme and/or authority.
static URI	checkPathURI(URI uri)	Checks to see if a given URI is only a path and not a URI with a scheme, authority, query, and/or fragment.
static URI	checkPlainURI(URI uri)	Checks to see if a given URI is plain, i.e.
static String	checkRelativePath(String path)	Checks to see if a given path is only a relative path and not a URI with a scheme and/or authority.
static URI	checkRoot(URI uri)	Checks to see if a given URI has the root path.
static final URI	checkScheme(URI uri, String scheme)	Verifies that the given URI has the indicated scheme.
static String	compress(URI uri)	Compresses a URI into a shorter string representation.
static String	constructPath(boolean absolute, boolean collection, String... pathElements)	Constructs an absolute path from the given elements in the form: /element1/element2.
static String	constructQuery(URIQueryParameter... params)	Constructs a query string for a URI by URI-encoding each name-value pair, separating them with '&', and prepending the entire string (if there is at least one parameter) with '?', if there are no parameters, it doesn't do anything.
static String	constructQuery(String params)	Deprecated.
static String	constructQueryParameters(URIQueryParameter... params)	Constructs a query string for a URI by URI-encoding each name-value pair, separating them with '&'.
static URI	createInfoURI(String namespace, String rawIdentifier)	Creates an "info" URI with the given info namespace and identifier with no fragment.
static URI	createInfoURI(String namespace, String rawIdentifier, String rawFragment)	Creates an "info" URI with the given info namespace, identifier, and optional fragment.
static URI	createMailtoURI(String username, String domain)	Creates a "mailto" URI in the form mailto:username@domain.
static URI	createPathURI(String path)	Creates a URI from the given path, verifying that the string contains only a path.
static URI	createURI(Object contextObject, String string)	Deprecated. because this ancient code doesn't have an obvious utility, is confusing, and jumbles various types, many of them legacy.
static URI	createURI(String scheme, String rawSchemeSpecificPart)	Returns a URI constructed from the given parts, any of which can be null.
static URI	createURI(String scheme, String rawSchemeSpecificPart, String rawFragment)	Returns a URI constructed from the given parts, any of which can be null.
static URI	createURI(String scheme, String rawUserInfo, String host, int port, URIPath path, String rawQuery, String rawFragment)	Returns a URI constructed from the given parts, any of which can be null.
static URI	createURI(String scheme, String rawUserInfo, String host, int port, String rawPath, String rawQuery, String rawFragment)	Returns a URI constructed from the given parts, any of which can be null.
static String	createURIList(URI... uris)	Creates a string of type text/uri-list as defined in RFC 2483, "URI Resolution Services Necessary for URN Resolution".
static URI	createURN(String nid, String nss)	Creates a URN in the form urn:nid:nss.
static String	decode(CharSequence uri)	Decodes the escaped characters in the character iterator according to the URI encoding rules in RFC 2396, "Uniform Resource Identifiers (URI): Generic Syntax", using the URI escape character, '%'.
static String	decode(CharSequence uri, char escapeChar)	Decodes the escaped ('%') characters in the character iterator according to the URI encoding rules in RFC 2396, "Uniform Resource Identifiers (URI): Generic Syntax".
static URI	decompress(String string)	Decompresses a URI from a shorter string representation.
static String	encode(String string)	Encodes all URI reserved characters in the string according to the URI encoding rules in RFC 3986, "Uniform Resource Identifiers (URI): Generic Syntax" using the URI escape character, '%'.
static String	encode(String string, char escapeChar)	Encodes all URI reserved characters in the string according to the URI encoding rules in RFC 3986, "Uniform Resource Identifiers (URI): Generic Syntax".
static String	encode(URI uri)	Encodes all non-ASCII and URI reserved characters in the URI according to the URI encoding rules in RFC 3986, "Uniform Resource Identifiers (URI): Generic Syntax" using the URI escape character, '%'.
static String	encode(URI uri, char escapeChar)	Encodes all non-ASCII and URI reserved characters in the URI according to the URI encoding rules in RFC 3986, "Uniform Resource Identifiers (URI): Generic Syntax".
static Optional<String>	findName(URI uri)	Returns the decoded name of the resource at the given URI's path, which will be the decoded name of the last path component.
static Optional<String>	findNameExtension(URI uri)	Extracts the extension from a URI's name.
static Optional<String>	findRawName(URI uri)	Returns the raw name of the resource at the given URI's path, which will be the raw name of the last path component.
static Optional<String>	findRawNameExtension(URI uri)	Extracts the raw, encoded extension from a URI's name.
static Optional<URI>	findRelativeChildPath(URI parentURI, URI childURI)	Returns a URI relative to the given parent URI.
static Optional<URI>	findRelativePath(URI sourceURI, URI targetURI)	Returns the path of a target URI relative to some source URI, which may be a sibling URI or even a child URI.
static Optional<URIPath>	findURIPath(URI uri)	Returns a path object to represent the path of the URI, if it has one.
static URI	getCurrentLevel(URI uri)	Determines the current level of a hierarchical URI.
static URL	getDirectoryURL(URL url)	Returns a URL representing the directory of the given file URL.
static Host	getHost(URI uri)	Returns the unencoded host and optional port of the given URI.
static final String	getInfoIdentifier(URI uri)	Determines the info identifier of the given "info" scheme URI.
static final String	getInfoNamespace(URI uri)	Determines the info namespace of the given "info" scheme URI.
static final String	getInfoRawIdentifier(URI uri)	Determines the raw, encoded info identifier of the given "info" scheme URI.
static String	getName(String path)	Returns the name of the resource at the given path, which will be the name of the last path component.
static String	getName(URI uri)	Deprecated. to be removed in favor of findName(URI).
static String	getNameExtension(URI uri)	Deprecated. to be removed in favor of findNameExtension(URI).
static CollectionMap<String,String,List<String>>	getParameterMap(URI uri)	Retrieves the parameters from the query of a URI, if present.
static NameValuePair<String,String>[]	getParameters(String query)	Retrieves the parameters from a URI query.
static NameValuePair<String,String>[]	getParameters(URI uri)	Retrieves the query parameters from a URI.
static URI	getParentLevel(URI uri)	Determines the parent level of a hierarchical URI.
static URI	getParentURI(URI uri)	Determines the parent collection of a hierarchical URI.
static URIPath	getPath(URI uri)	Deprecated. to remove in favor of findURIPath(URI)
static final String	getPathRawPath(URI uri)	Determines the raw, encoded path of the given "path" scheme URI.
static final URIPath	getPathURIPath(URI uri)	Returns the path of the given "path" scheme URI as a URIPath.
static URI	getPlainURI(URI uri)	Creates a new URI identical to the supplied URI with no query or fragment.
static String	getRawName(URI uri)	Deprecated. to be removed in favor of findRawName(URI).
static String	getRawNameExtension(URI uri)	Deprecated. to be removed in favor of findRawNameExtension(URI).
static String	getRawPathQueryFragment(URI uri)	Returns the unencoded path, optional unencoded query, and optional unencoded fragment of the given URI.
static String	getRelativePath(String absolutePath)	Determines the relative path of the given absolute path by removing the root path '/' character from the beginning of the path.
static URI	getRootURI(URI uri)	Determines the canonical root URI of a URI.
static URI	guessAbsoluteURI(String string)	Creates an absolute URI from the given string, guessing what the string represents.
static boolean	hasAbsolutePath(URI uri)	Determines whether the path of the URI (which may or may not be absolute) is absolute.
static boolean	hasPath(URI uri)	Determines whether the URI has a path.
static boolean	hasSubPath(URI uri)	Determines whether the path of the URI is a relative path that does not backtrack to a higher level.
static boolean	isChild(URI baseURI, URI uri)	Determines whether the given URI is a child relative to the given base URI.
static boolean	isCollectionPath(String path)	Determines whether the given path is a canonical collection path.
static boolean	isCollectionURI(URI uri)	Determines whether the URI represents a canonical collection, that is, it has a path that ends with a slash ('/').
static boolean	isHost(URI uri)	Determines whether the URI contains only a host and optional port.
static final boolean	isInfoNamespace(URI uri, String infoNamespace)	Determines whether the given URI is an "info" scheme URI with the given namespace.
static boolean	isPath(String path)	Determines if a given path is only a path and not a URI with a scheme and/or authority.
static boolean	isPathAbsolute(String path)	Determines whether the given path is absolute.
static boolean	isPathURI(URI uri)	Determines if a given URI contains only a path and does not have a scheme, authority, query, and/or fragment.
static boolean	isPlainURI(URI uri)	Determines if a given URI is plain, i.e.
static boolean	isUNCFileURI(URI uri)	Determines whether the given URI is a UNC file path URI in the form file:////server/file.ext.
static URI	normalize(URI uri)	Normalizes a URI.
static String	normalizePath(String path)	Normalizes the given path by resolving the . and .. path segments.
static URI	plainDecode(CharSequence charSequence)	Decodes a plain-encoded URI.
static String	plainEncode(URI uri)	Encodes an absolute URI into a plain string that is safe to be used in the path of another URI, for example.
static URI	relativizeChildPath(URI parentURI, URI childURI)	Returns a URI relative to the given parent URI.
static URI	relativizePath(URI sourceURI, URI targetURI)	Returns the path of a target URI relative to some source URI, which may be a sibling URI or even a child URI.
static URI	removeFragment(URI uri)	Returns a URI with its fragment, if any, removed.
static URI	removeRawNameExtension(URI uri)	Removes the extension, if any, of a URI name and returns a new URI with no extension.
static URI	replaceRawFragment(URI uri, String newRawFragment)	Returns a URI with its fragment, if any, replaced.
static URI	resolve(URI baseURI, URIPath path)	Resolves a URI path against a base URI.
static URI	resolve(URI baseURI, String childURI)	Resolves a string against a base URI with added functionality and bug fixes over URI.resolve(String), following RFC 3986.
static URI	resolve(URI baseURI, URI childURI)	Resolves a relative URI against a base URI with added functionality and bug fixes over URI.resolve(URI), following RFC 3986.
static URI	resolve(URI baseURI, URI childURI, boolean deep)	Resolves a relative URI against a base URI with added functionality and bug fixes over URI.resolve(URI), following RFC 3986.
static URI	resolveFragment(URI uri, String fragment)	Returns a URI constructed from a given URI and a fragment identifier.
static URI	resolveRawFragment(URI uri, String rawFragment)	Returns a URI constructed from a given URI and a raw fragment identifier.
static URI	setRawNameExtension(URI uri, String extension)	Adds the extension, if any, to a name and returns the new URI.
static URI	toCollectionURI(URI uri)	Forces a URI to represent a collection by appending a trailing path separator to the URI path, if any.
static URL	toValidURL(URI uri)	Creates a URL from a URI.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

NO_URIS

public static final URI[] NO_URIS

The shared static empty array of URIs.

EMPTY_PATH_URI

public static final URI EMPTY_PATH_URI

A shared URI constant equal to creating a URI from an empty path.

API Note:

This constant is useful for detecting a URI relativized against itself, for example.

FILE_SCHEME

public static final String FILE_SCHEME

The file scheme identifier.

See Also:

• Constant Field Values

FTP_SCHEME

public static final String FTP_SCHEME

The FTP scheme identifier.

See Also:

• Constant Field Values

MAILTO_SCHEME

public static final String MAILTO_SCHEME

The email address scheme identifier.

See Also:

• Constant Field Values

INFO_SCHEME

public static final String INFO_SCHEME

The info scheme identifier.

See Also:

• Constant Field Values

INFO_SCHEME_NAMESPACE_DELIMITER

public static final char INFO_SCHEME_NAMESPACE_DELIMITER

The delimiter separating the info scheme namespace from the rest of the info scheme-specific part.

See Also:

• Constant Field Values

PATH_SCHEME

public static final String PATH_SCHEME

The path scheme identifier for representing relative and absolute URI paths.

See Also:

• Constant Field Values

RESOURCE_SCHEME

public static final String RESOURCE_SCHEME

The resource scheme identifier "resource".

See Also:

• Constant Field Values

TEL_SCHEME

public static final String TEL_SCHEME

The telephone scheme identifier.

See Also:

• Constant Field Values

URN_SCHEME

public static final String URN_SCHEME

The URN scheme identifier "urn".

See Also:

• Constant Field Values

SCHEME_SEPARATOR

public static final char SCHEME_SEPARATOR

The colon character (':') that separates a URI schema from the rest of the URI.

See Also:

• Constant Field Values

URN_SSP_PATTERN

public static final Pattern URN_SSP_PATTERN

The pattern to match the scheme-specific part of a URN.

This pattern is not currently meant to be a vigorous validation of URN format, but rather a means to easily discover the components of a URN.

URN_SSP_PATTERN_NID_MATCHING_GROUP

public static final int URN_SSP_PATTERN_NID_MATCHING_GROUP

The matching group to retrieve the URN namespace identifier.

See Also:

• Constant Field Values

URN_SSP_PATTERN_NSS_MATCHING_GROUP

public static final int URN_SSP_PATTERN_NSS_MATCHING_GROUP

The matching group to retrieve the URN-namespace-specific part.

See Also:

• Constant Field Values

AUTHORITY_PREFIX

public static final String AUTHORITY_PREFIX

The prefix string that introduces an authority.

See Also:

• Constant Field Values

USER_INFO_SEPARATOR

public static final char USER_INFO_SEPARATOR

The at sign ('@') that separates user information from a host in a URI.

See Also:

• Constant Field Values

PORT_SEPARATOR

public static final char PORT_SEPARATOR

The colon character (':') that separates a host from a port.

See Also:

• Constant Field Values

PATH_SEPARATOR

public static final char PATH_SEPARATOR

The slash character ('/') that separates components in a URI path.

See Also:

• Constant Field Values

CURRENT_LEVEL_PATH_SEGMENT

public static final String CURRENT_LEVEL_PATH_SEGMENT

The path segment "." representing the current hierarchical level of a hierarchical URI.

See Also:

• Constant Field Values

CURRENT_LEVEL_PATH

public static final String CURRENT_LEVEL_PATH

The collection path "./" representing the current hierarchical level of a hierarchical URI.

See Also:

• Constant Field Values

CURRENT_LEVEL_PATH_URI

public static final URI CURRENT_LEVEL_PATH_URI

The URI collection path of "./" representing the current hierarchical level of a hierarchical URI.

PARENT_LEVEL_PATH_SEGMENT

public static final String PARENT_LEVEL_PATH_SEGMENT

The path segment ".." representing the parent hierarchical level of a hierarchical URI.

See Also:

• Constant Field Values

PARENT_LEVEL_PATH

public static final String PARENT_LEVEL_PATH

The collection path "../" representing the parent hierarchical level of a hierarchical URI.

See Also:

• Constant Field Values

PARENT_LEVEL_PATH_URI

public static final URI PARENT_LEVEL_PATH_URI

The URI collection path "../" representing the parent hierarchical level of a hierarchical URI.

QUERY_SEPARATOR

public static final char QUERY_SEPARATOR

The character that separates the query from the rest of a URI.

See Also:

• Constant Field Values

QUERY_NAME_VALUE_PAIR_DELIMITER

public static final char QUERY_NAME_VALUE_PAIR_DELIMITER

The character that separates each name-value pair in a query.

See Also:

• Constant Field Values

QUERY_NAME_VALUE_ASSIGNMENT

public static final char QUERY_NAME_VALUE_ASSIGNMENT

The character that represents assigning a value to a name in a query.

See Also:

• Constant Field Values

FRAGMENT_SEPARATOR

public static final char FRAGMENT_SEPARATOR

The pound character ('#') that separates a fragment from the rest of a URI.

See Also:

• Constant Field Values

ROOT_PATH

public static final String ROOT_PATH

The path to root, consisting of a single path separator ("/").

ROOT_PATH_URI

public static final URI ROOT_PATH_URI

A URI consisting only of a single path separator ("/").

ROOT_PATH_PARENT_LEVEL

public static final String ROOT_PATH_PARENT_LEVEL

The path Java returns when it tries to resolve .. to the root path.

MAILTO_USERNAME_DOMAIN_SEPARATOR

public static final char MAILTO_USERNAME_DOMAIN_SEPARATOR

The character separating a mailto URI username from the domain.

See Also:

• Constant Field Values

ALPHA_CHARACTERS

public static final Characters ALPHA_CHARACTERS

Alphabetic characters as defined by RFC 2396.

DIGIT_CHARACTERS

public static final Characters DIGIT_CHARACTERS

Digit characters as defined by RFC 2396.

SAFE_CHARACTERS

public static final Characters SAFE_CHARACTERS

Safe characters as defined by RFC 2396.

EXTRA_CHARACTERS

public static final Characters EXTRA_CHARACTERS

Extra characters as defined by RFC 2396.

ESCAPE_CHAR

public static final char ESCAPE_CHAR

The character to use for escaping URI data as defined by RFC 2396.

See Also:

• Constant Field Values

RESERVED_CHARACTERS

public static final Characters RESERVED_CHARACTERS

Reserved characters as defined by RFC 2396.

URI_CHARACTERS

public static final Characters URI_CHARACTERS

Characters that can appear in a URI as defined by RFC 2396.

NORMAL_CHARACTERS

public static final Characters NORMAL_CHARACTERS

Characters that can appear in a URI path with no escape sequences.

UNRESERVED_CHARACTERS

public static final Characters UNRESERVED_CHARACTERS

Unreserved characters defined by RFC 3986.

GEN_DELIM_CHARACTERS

public static final Characters GEN_DELIM_CHARACTERS

General delimiter characters defined by RFC 3986.

SUB_DELIM_CHARACTERS

public static final Characters SUB_DELIM_CHARACTERS

Subdelimiter characters defined by RFC 3986.

PATH_SEGMENT_CHARACTERS

public static final Characters PATH_SEGMENT_CHARACTERS

Path segment characters defined by RFC 3986.

PATH_CHARACTERS

public static final Characters PATH_CHARACTERS

Path characters defined by RFC 3986.

FILE_URI_PATH_ROOT_PREFIX

public static final String FILE_URI_PATH_ROOT_PREFIX

The sequence "//" which is supposed to be present in file URIs (e.g. file:///mnt/sdcard/...) but which isn't present in Java file URIs.

See Also:

• File URIs in Windows.

MICROSOFT_INTERNET_EXPLORER_MAXIMUM_URI_LENGTH

public static final int MICROSOFT_INTERNET_EXPLORER_MAXIMUM_URI_LENGTH

The maximum URL length allowed by Microsoft Internet Explorer for HTTP GET.

See Also:

• Maximum URL length is 2,083 characters in Internet Explorer
• Constant Field Values

URI_LIST_MEDIA_TYPE

public static final MediaType URI_LIST_MEDIA_TYPE

A text/uri-list content type as defined in RFC 2483 § 5. The text/uri-list Internet Media Type.

See Also:

• RFC 2483: URI Resolution Services Necessary for URN Resolution

WINDOWS_UNC_PATH_URI_SSP_PREFIX

public static final String WINDOWS_UNC_PATH_URI_SSP_PREFIX

The prefix used in the scheme-specific part by Java for Windows UNC paths in file URIs.

PLAIN_ENCODING_ESCAPE_CHAR

public static final char PLAIN_ENCODING_ESCAPE_CHAR

The character used for escaping characters in a URI plain encoding.

See Also:

• plainEncode(URI)
• Constant Field Values

PLAIN_ENCODING_REPLACE_CHAR

public static final char PLAIN_ENCODING_REPLACE_CHAR

The character used for replacing certain characters in a URI plain encoding.

See Also:

• plainEncode(URI)
• Constant Field Values

PLAIN_ENCODE_INITIAL_UNRESERVED_CHARACTERS

protected static final Characters PLAIN_ENCODE_INITIAL_UNRESERVED_CHARACTERS

The characters that, at least initially, should not be encoded. Path separators will be replaced with '-'.

PLAIN_ENCODE_CHARACTERS

public static final Characters PLAIN_ENCODE_CHARACTERS

The characters that are allowed in a URI plain encoding.

Constructor Details

URIs

public URIs()

Method Details

createURIList

public static String createURIList(URI... uris)

Creates a string of type text/uri-list as defined in RFC 2483, "URI Resolution Services Necessary for URN Resolution".

Parameters:

uris - The URIs to include in the list.

Returns:

A URI list string.

See Also:

• RFC 2483: URI Resolution Services Necessary for URN Resolution

checkScheme

public static final URI checkScheme(URI uri,
 String scheme)

Verifies that the given URI has the indicated scheme.

Parameters:

uri - The URI to check.

scheme - The scheme to match for the URI.

Returns:

The given URI.

Throws:

NullPointerException - if the given URI and/or scheme is null.

IllegalArgumentException - if the scheme of the given URI does not match the given scheme.

changeScheme

public static URI changeScheme(URI uri,
 String newScheme)

Creates a new URI identical to the supplied URI with a different scheme.

Parameters:

uri - The URI to change.

newScheme - The new scheme information.

Returns:

A new URI with the new scheme information.

Throws:

NullPointerException - if the given URI and/or new scheme is null.

IllegalArgumentException - if the given URI has no scheme or if the given scheme results in an invalid URI.

checkInfoNamespace

public static final URI checkInfoNamespace(URI uri,
 String infoNamespace)

Verifies that the given URI is an "info" scheme URI with the given namespace.

Parameters:

uri - The URI to check.

infoNamespace - The info namespace to match for the URI.

Returns:

The given URI.

Throws:

NullPointerException - if the given URI and/or info namespace is null.

IllegalArgumentException - if the scheme of the given URI is not "info" and/or the info namespace does not match the given info namespace.

getInfoNamespace

public static final String getInfoNamespace(URI uri)

Determines the info namespace of the given "info" scheme URI.

Parameters:

uri - The URI from which the info namespace should be retrieved.

Returns:

The info namespace of the given info URI.

Throws:

NullPointerException - if the given URI is null.

IllegalArgumentException - if the given URI is not a valid "info" scheme URI.

getInfoIdentifier

public static final String getInfoIdentifier(URI uri)

Determines the info identifier of the given "info" scheme URI.

Parameters:

uri - The URI from which the info identifier should be retrieved.

Returns:

The decoded info identifier of the given info URI.

Throws:

NullPointerException - if the given URI is null.

IllegalArgumentException - if the given URI is not a valid "info" scheme URI.

getInfoRawIdentifier

public static final String getInfoRawIdentifier(URI uri)

Determines the raw, encoded info identifier of the given "info" scheme URI.

Parameters:

uri - The URI from which the info identifier should be retrieved.

Returns:

The raw, encoded info identifier of the given info URI.

Throws:

NullPointerException - if the given URI is null.

IllegalArgumentException - if the given URI is not a valid "info" scheme URI.

isInfoNamespace

public static final boolean isInfoNamespace(URI uri,
 String infoNamespace)

Determines whether the given URI is an "info" scheme URI with the given namespace.

Parameters:

uri - The URI to check.

infoNamespace - The info namespace to match for the URI.

Returns:

The true if the given URI has a scheme of "info" and has the indicated info namespace.

Throws:

NullPointerException - if the given URI and/or info namespace is null.

getPathRawPath

public static final String getPathRawPath(URI uri)

Determines the raw, encoded path of the given "path" scheme URI. The path will never be null; the empty relative path path: will return the empty string. Any query or fragment is ignored.

API Note:

This method is needed because the URI.getRawPath() method does not recognize relative paths for the "path" scheme.

Parameters:

uri - The path URI from which the path should be retrieved.

Returns:

The raw, encoded path of the given path URI.

Throws:

NullPointerException - if the given URI is null.

IllegalArgumentException - if the given URI is not a valid "path" scheme URI.

getPathURIPath

public static final URIPath getPathURIPath(URI uri)

Returns the path of the given "path" scheme URI as a URIPath.

Parameters:

uri - The path URI from which the path should be retrieved.

Returns:

A URI path object representing the path of the given path URI.

Throws:

NullPointerException - if the given URI is null.

IllegalArgumentException - if the given URI is not a valid "path" scheme URI.

changePath

public static URI changePath(URI uri,
 URIPath path)

Creates a new URI identical to the supplied URI with a different path.

Parameters:

uri - The URI to change.

path - The path, or null if there should be no path.

Returns:

A new URI with the new path.

Throws:

NullPointerException - if the given URI is null.

IllegalArgumentException - if the given path results in an invalid URI.

changeRawPath

public static URI changeRawPath(URI uri,
 String newRawPath)

Creates a new URI identical to the supplied URI with a different raw path.

Parameters:

uri - The URI to change.

newRawPath - The raw, escaped path, or null if there should be no path.

Returns:

A new URI with the new raw path information.

Throws:

NullPointerException - if the given URI is null.

IllegalArgumentException - if the given path results in an invalid URI.

changeHost

public static URI changeHost(URI uri,
 String newHost)

Creates a new URI identical to the supplied URI with a different host.

Parameters:

uri - The URI to change.

newHost - The new host information.

Returns:

A new URI with the new host information.

Throws:

NullPointerException - if the given URI and/or new host is null.

IllegalArgumentException - if the given URI has no host or if the given host results in an invalid URI.

changeRawSchemeSpecificPart

public static URI changeRawSchemeSpecificPart(URI uri,
 String newRawSSP)

Creates a new URI identical to the supplied URI with a different raw scheme-specific part.

Parameters:

uri - The URI to change.

newRawSSP - The raw, escaped scheme-specific part.

Returns:

A new URI with the new raw scheme-specific part information.

Throws:

NullPointerException - if the given URI or the scheme-specific part is null.

IllegalArgumentException - if the given scheme-specific part results in an invalid URI.

toCollectionURI

public static URI toCollectionURI(URI uri)

Forces a URI to represent a collection by appending a trailing path separator to the URI path, if any. If the URI has no path, no change is made.

API Note:

This method is most useful for working with file systems that are imprecise about distinguishing between collection and non-collection nodes.

Parameters:

uri - The URI to represent a collection.

Returns:

A form of the URI representing a collection.

Throws:

NullPointerException - if the given URI is null.

findURIPath

public static Optional<URIPath> findURIPath(@Nonnull
 URI uri)

Returns a path object to represent the path of the URI, if it has one.

Parameters:

uri - The URI for which a path object should be returned.

Returns:

An object representing the path if any.

getPath

@Deprecated
public static URIPath getPath(URI uri)

Deprecated.

to remove in favor of findURIPath(URI)

Returns a path object to represent the path of the URI.

Parameters:

uri - The URI for which a path object should be returned.

Returns:

An object representing the path, or null if the URI has no path.

findRawName

public static Optional<String> findRawName(@Nonnull
 URI uri)

Returns the raw name of the resource at the given URI's path, which will be the raw name of the last path component. If the path is a collection (i.e. it ends with slash), the component before the last slash will be returned. As examples, "/path/name.ext" and "name.ext" will return "name.ext". "/path/", "path/", and "path" will all return "path". A empty path will return "", while the root path will return "/".

API Note:

The return value of "/" for http://example.com indicates that it is a special resource that doesn't have a name, but still distinguishes between that case and the resource http://example.com, which has an empty relative path and is not equivalent to the root. Thus "" and "/" should be considered special values indicating certain conditions, not actual names.

Implementation Specification:

This method correctly handles "info" URIs., This implementation calls getName(String).

Parameters:

uri - The URI the path of which will be examined.

Returns:

The name of the last last path component, the empty string if the path is the empty string, "/" if the path is the root path, or empty if the URI has no path.

Throws:

NullPointerException - if the given URI is null.

getRawName

@Deprecated
public static String getRawName(URI uri)

Deprecated.

to be removed in favor of findRawName(URI).

Returns the raw name of the resource at the given URI's path, which will be the raw name of the last path component. If the path is a collection (i.e. it ends with slash), the component before the last slash will be returned. As examples, "/path/name.ext" and "name.ext" will return "name.ext". "/path/", "path/", and "path" will all return "path".

API Note:

The return value of "/" for http://example.com indicates that it is a special resource that doesn't have a name, but still distinguishes between that case and the resource http://example.com, which has an empty relative path and is not equivalent to the root. Thus "" and "/" should be considered special values indicating certain conditions, not actual names.

Implementation Specification:

This method correctly handles "info" URIs.

Parameters:

uri - The URI the path of which will be examined.

Returns:

The name of the last last path component, the empty string if the path is the empty string, "/" if the path is the root path, or null if the URI has no path.

Throws:

NullPointerException - if the given URI is null.

findName

public static Optional<String> findName(URI uri)

Returns the decoded name of the resource at the given URI's path, which will be the decoded name of the last path component. If the path is a collection (i.e. it ends with slash), the component before the last slash will be returned. As examples, "/path/name.ext" and "name.ext" will return "name.ext". "/path/", "path/", and "path" will all return "path". The path name is first extracted from the URI's raw path and then decoded so that encoded '/' characters will not prevent correct parsing.

API Note:

The return value of "/" for http://example.com indicates that it is a special resource that doesn't have a name, but still distinguishes between that case and the resource http://example.com, which has an empty relative path and is not equivalent to the root. Thus "" and "/" should be considered special values indicating certain conditions, not actual names.

Implementation Specification:

This method correctly handles "info" URIs.

Parameters:

uri - The URI the path of which will be examined.

Returns:

The name of the last path component, the empty string if the path is the empty string, "/" if the path is the root path, or empty if the URI has no path.

Throws:

NullPointerException - if the given URI is null.

getName

@Deprecated
public static String getName(URI uri)

Deprecated.

to be removed in favor of findName(URI).

Returns the decoded name of the resource at the given URI's path, which will be the decoded name of the last path component. If the path is a collection (i.e. it ends with slash), the component before the last slash will be returned. As examples, "/path/name.ext" and "name.ext" will return "name.ext". "/path/", "path/", and "path" will all return "path". The path name is first extracted from the URI's raw path and then decoded so that encoded '/' characters will not prevent correct parsing.

API Note:

The return value of "/" for http://example.com indicates that it is a special resource that doesn't have a name, but still distinguishes between that case and the resource http://example.com, which has an empty relative path and is not equivalent to the root. Thus "" and "/" should be considered special values indicating certain conditions, not actual names.

Implementation Specification:

This method correctly handles "info" URIs.

Parameters:

uri - The URI the path of which will be examined.

Returns:

The name of the last path component, the empty string if the path is the empty string, "/" if the path is the root path, or null if the URI has no path.

Throws:

NullPointerException - if the given URI is null.

changePathName

public static String changePathName(String path,
 String name)

Changes the name of the path of the given URI to the given name. If the path is a collection (i.e. it ends with slash), the name is the last component before the last slash. As examples, "/path/name.ext" and "name.ext" will change "name.ext". "/path/", "path/", and "path" will all change "path". For a requested name of "name", a path of "" will return "name", and a path of "/" will return "/name/".

API Note:

Neither an empty path or the root path are considered to have names, and thus are not allowed to have their names changed.

Parameters:

path - The path, which should be encoded if '/' characters are present.

name - The new name of the path.

Returns:

A new path with the name changed to the given name.

Throws:

NullPointerException - if the given path and/or name is null.

IllegalArgumentException - if the given path is the empty string or is the root path.

See Also:

• getName(String)

changeName

@Deprecated
public static String changeName(String path,
 String name)

Deprecated.

to be removed in favor of changePathName(String, String)

Changes the name of the path of the given URI to the given name. If the path is a collection (i.e. it ends with slash), the name is the last component before the last slash. As examples, "/path/name.ext" and "name.ext" will change "name.ext". "/path/", "path/", and "path" will all change "path". For a requested name of "name", a path of "" will return "name", and a path of "/" will return "/name/".

API Note:

Neither an empty path or the root path are considered to have names, and thus are not allowed to have their names changed.

Parameters:

path - The path, which should be encoded if '/' characters are present.

name - The new name of the path.

Returns:

A new path with the name changed to the given name.

Throws:

NullPointerException - if the given path and/or name is null.

IllegalArgumentException - if the given path is the empty string or is the root path.

See Also:

• getName(String)

changeRawName

public static URI changeRawName(URI uri,
 String rawName)

Changes the raw name of the path of the given URI to the given raw name. If the path is a collection (i.e. it ends with slash), the name is the last component before the last slash. As examples, "/path/name.ext" and "name.ext" will change "name.ext". "/path/", "path/", and "path" will all change "path". For a requested name of "name", a path of "" will return "name", and a path of "/" will return "/name/".

API Note:

Neither an empty path or the root path are considered to have names, and thus are not allowed to have their names changed.

Implementation Specification:

This method correctly handles "info" URIs.

Parameters:

uri - The URI the raw name of which to change.

rawName - The new raw name of the URI.

Returns:

A new URI with the raw name changed to the given raw name.

Throws:

NullPointerException - if the given URI and/or name is null.

IllegalArgumentException - if the given URI has no path, if the path is empty, or if the path is just a "/".

See Also:

• findRawName(URI)

changeName

public static URI changeName(URI uri,
 String name)

Changes the name of the path of the given URI to the given name. If the path is a collection (i.e. it ends with slash), the name is the last component before the last slash. As examples, "/path/name.ext" and "name.ext" will change "name.ext". "/path/", "path/", and "path" will all change "path". For a requested name of "name", a path of "" will return "name", and a path of "/" will return "/name/".

API Note:

Neither an empty path or the root path are considered to have names, and thus are not allowed to have their names changed.

Implementation Specification:

This method correctly handles "info" URIs.

Parameters:

uri - The URI the name of which to change.

name - The new unencoded name of the URI, which will be encoded.

Returns:

A new URI with the name changed to the given name.

Throws:

NullPointerException - if the given URI and/or name is null.

IllegalArgumentException - if the given URI has no path, if the path is empty, or if the path is just a "/".

See Also:

• URIPath.encodeSegment(String)
• findName(URI)

appendRawNameBase

public static URI appendRawNameBase(@Nonnull
 URI uri,
 @Nonnull
 CharSequence charSequence)

Appends a given string to the end of the URI's raw name before the extension, if any.

API Note:

This is useful for forming a locale-aware name, such as test_fr.txt from test.txt., Here "base name" refers to the name with all extensions removed. That is both example.bar and example.foo.bar would result in a base name of example.

Implementation Specification:

This implementation delegates to Filenames.appendBase(String, CharSequence).

Parameters:

uri - The URI to examine.

charSequence - The characters to append to the raw name.

Returns:

A URI with the given character sequence appended before the name extension, if any.

Throws:

IllegalArgumentException - if the given URI has no raw name.

changeRawNameBase

public static URI changeRawNameBase(@Nonnull
 URI uri,
 @Nonnull
 String base)

Changes the base of a URI name, preserving the extension(s), if any.

API Note:

Here "base name" refers to the filename with all extensions removed. That is both example.bar and example.foo.bar would result in a base name of example.

Implementation Specification:

This implementation delegates to Filenames.changeBase(String, String).

Parameters:

uri - The URI to examine.

base - The new base to set.

Returns:

A URI with a raw name with the new base.

Throws:

NullPointerException - if the given URI's raw name and/or the new base is null.

IllegalArgumentException - if the given URI's raw name and/or the new base is empty.

addRawNameExtension

public static URI addRawNameExtension(URI uri,
 String extension)

Adds the given extension to a URI name and returns the new URI with the new extension. The URI name is not checked to see if it currently has an extension.

Parameters:

uri - The URI the name of which an extension should be added.

extension - The raw, encoded extension to add.

Returns:

The URI with the new extension.

Throws:

NullPointerException - if the given extension is null.

IllegalArgumentException - if the given URI has no path, if the path is empty, or if the path is just a "/".

findNameExtension

public static Optional<String> findNameExtension(@Nonnull
 URI uri)

Extracts the extension from a URI's name.

API Note:

This this the preferred method for extracting an extension from a URI, as this method correctly parses the raw form of the URI path to find the extension before decoding.

Parameters:

uri - The URI to examine.

Returns:

The extension of the URI's name (not including '.'), which may not be present.

See Also:

• findName(URI)

getNameExtension

@Deprecated
public static String getNameExtension(@Nonnull
 URI uri)

Deprecated.

to be removed in favor of findNameExtension(URI).

Extracts the extension from a URI's name. This this the preferred method for extracting an extension from a URI, as this method correctly parses the raw form of the URI path to find the extension before decoding.

Parameters:

uri - The URI to examine.

Returns:

The extension of the URI's name (not including '.'), or null if no extension is present.

findRawNameExtension

public static Optional<String> findRawNameExtension(@Nonnull
 URI uri)

Extracts the raw, encoded extension from a URI's name.

Parameters:

uri - The URI to examine.

Returns:

The raw, encoded extension of the URI's name (not including '.'), which may not be present.

See Also:

• findRawName(URI)

getRawNameExtension

@Deprecated
public static String getRawNameExtension(@Nonnull
 URI uri)

Deprecated.

to be removed in favor of findRawNameExtension(URI).

Extracts the raw, encoded extension from a URI's name.

Parameters:

uri - The URI to examine.

Returns:

The raw, encoded extension of the URI's name (not including '.'), or null if no extension is present.

changeRawNameExtension

public static URI changeRawNameExtension(URI uri,
 String extension)

Changes the extension of a URI name and returns a new URI with the new name extension. If the URI name does not currently have an extension, one will be added.

Parameters:

uri - The URI to examine.

extension - The raw extension to set, or null if the extension should be removed.

Returns:

A URI with a raw name with the new extension.

Throws:

IllegalArgumentException - if the given URI has no path, if the path is empty, or if the path is just a "/".

setRawNameExtension

public static URI setRawNameExtension(URI uri,
 String extension)

Adds the extension, if any, to a name and returns the new URI. This is a convenience method that delegates to addRawNameExtension(URI, String) if a non-null extension is given.

Parameters:

uri - The URI to examine.

extension - The raw, encoded extension to add, or null if no extension should be added.

Returns:

A URI with a raw name with the new extension, if any.

removeRawNameExtension

public static URI removeRawNameExtension(URI uri)

Removes the extension, if any, of a URI name and returns a new URI with no extension. This is a convenience method that delegates to changeRawNameExtension(URI, String).

Parameters:

uri - The URI to examine.

Returns:

The URI with no extension.

getPlainURI

public static URI getPlainURI(URI uri)

Creates a new URI identical to the supplied URI with no query or fragment.

Parameters:

uri - The URI from which to remove the query and fragment, if any.

Returns:

A new URI with no query or fragment.

constructQuery

public static String constructQuery(URIQueryParameter... params)

Constructs a query string for a URI by URI-encoding each name-value pair, separating them with '&', and prepending the entire string (if there is at least one parameter) with '?', if there are no parameters, it doesn't do anything.

Parameters:

params - The name-value pairs representing the query parameters.

Returns:

A string representing the constructed query, or the empty string if there were no parameters.

constructQuery

@Deprecated
public static String constructQuery(String params)

Deprecated.

Constructs a query string for a URI by prepending the given query string, if it is not the empty string, with '?'.

Parameters:

params - The string representing the query parameters.

Returns:

A string representing the constructed query, or the empty string if there were no parameters.

appendRawQuery

public static URI appendRawQuery(URI uri,
 String rawQuery)

Appends a query string to a URI.

Parameters:

uri - The existing URI.

rawQuery - The encoded query information, without a beginning query separator.

Returns:

A URI representing the URI with the appended query parameters.

Throws:

NullPointerException - if the given URI and/or query is null.

appendQueryParameter

public static URI appendQueryParameter(URI uri,
 String paramName,
 String paramValue)

Constructs a query string for a URI with a single name/value parameter, and appends it to the query of the given URI, if any.

Parameters:

uri - The existing URI.

paramName - The name of the parameter.

paramValue - The value of the parameter.

Returns:

A URI representing the URI with the appended query parameter.

Throws:

NullPointerException - if the given URI, param name, and/or param value is null.

appendQueryParameters

public static URI appendQueryParameters(URI uri,
 URIQueryParameter... params)

Constructs a query string for a URI and appends it to the query of the given URI, if any.

Parameters:

uri - The existing URI.

params - The name-value pairs representing the query parameters.

Returns:

A URI representing the URI with the appended query parameters.

Throws:

NullPointerException - if the given URI and/or params is null.

appendQueryParameters

public static String appendQueryParameters(String query,
 URIQueryParameter... params)

Constructs a query string for a URI and appends it to the given query, if any.

Parameters:

query - The existing query parameters, or null or the empty string if there is no query.

params - The name-value pairs representing the query parameters.

Returns:

A string representing the query with the appended parameters, or the empty string if there was no query and there were no parameters.

constructQueryParameters

public static String constructQueryParameters(URIQueryParameter... params)

Constructs a query string for a URI by URI-encoding each name-value pair, separating them with '&'. Parameters are allowed to have null values, in which case no '=' delimiter will be used.

Parameters:

params - The name-value pairs representing the query parameters.

Returns:

A string representing the constructed query, or the empty string if there were no parameters.

getParameterMap

public static CollectionMap<String,String,List<String>> getParameterMap(URI uri)

Retrieves the parameters from the query of a URI, if present.

Parameters:

uri - The URI from which to extract parameters.

Returns:

An array of parameters.

getParameters

public static NameValuePair<String,String>[] getParameters(URI uri)

Retrieves the query parameters from a URI.

Parameters:

uri - The URI which may contain a query.

Returns:

An array of parameters represented by the URI query, or null if the given URI does not contain a query.

getParameters

public static NameValuePair<String,String>[] getParameters(String query)

Retrieves the parameters from a URI query. An empty string query will return an empty array of name/value pairs.

Parameters:

query - The string containing URI query parameters (without the '?' prefix), or null.

Returns:

An array of parameters represented by the query, or null if the given query is null.

createPathURI

public static URI createPathURI(String path)

Creates a URI from the given path, verifying that the string contains only a path.

Parameters:

path - The string version of a path to convert to a URI form of that same path.

Returns:

The URI constructed.

Throws:

NullPointerException - if the given path is null.

IllegalArgumentException - if the provided path specifies a URI scheme (i.e. the URI is absolute) and/or authority.

See Also:

• isPathURI(URI)

checkRoot

public static URI checkRoot(URI uri)
                     throws IllegalArgumentException

Checks to see if a given URI has the root path. If the given URI does not have the root path, i.e., if it's missing or if it's not composed only by the root path, an exception is thrown.

Parameters:

uri - The URI to check to see if it has the root path.

Returns:

The given root URI.

Throws:

NullPointerException - if the given URI is null.

IllegalArgumentException - if the given URI does not have the root path.

See Also:

• URI.getPath()
• ROOT_PATH

checkAbsolute

public static URI checkAbsolute(URI uri)
                         throws IllegalArgumentException

Checks to see if a given URI is absolute. If the given URI is not absolute, an exception is thrown.

Parameters:

uri - The URI to check to see if it is absolute.

Returns:

The given absolute URI.

Throws:

NullPointerException - if the given URI is null.

IllegalArgumentException - if the given URI is not absolute.

See Also:

• URI.isAbsolute()

isPathURI

public static boolean isPathURI(URI uri)

Determines if a given URI contains only a path and does not have a scheme, authority, query, and/or fragment.

Parameters:

uri - The URI to check to for path status.

Returns:

true if the URI has a path and does not specify a scheme (i.e. the URI is not absolute), authority, query, or fragment.

Throws:

NullPointerException - if the given URI is null.

checkPathURI

public static URI checkPathURI(URI uri)

Checks to see if a given URI is only a path and not a URI with a scheme, authority, query, and/or fragment. If the given URI is not a path, an exception is thrown.

Parameters:

uri - The URI to check to for path status.

Returns:

The given path URI.

Throws:

NullPointerException - if the given URI is null.

IllegalArgumentException - if the provided URI specifies a URI scheme (i.e. the URI is absolute), authority, query, and/or fragment.

IllegalArgumentException - if the given URI is not a path.

See Also:

• isPath(String)

isPlainURI

public static boolean isPlainURI(URI uri)

Determines if a given URI is plain, i.e. it does not contain a query or a fragment.

Parameters:

uri - The URI to check to for plainness.

Returns:

true if the URI has no query or fragment.

Throws:

NullPointerException - if the given URI is null.

checkPlainURI

public static URI checkPlainURI(URI uri)

Checks to see if a given URI is plain, i.e. it does not contain a query or a fragment. If the given URI is not a plain URI, an exception is thrown.

Parameters:

uri - The URI to check to for plainness.

Returns:

The given plain URI.

Throws:

NullPointerException - if the given URI is null.

IllegalArgumentException - if the provided URI specifies a query and/or fragment.

See Also:

• isPlainURI(URI)

getCurrentLevel

public static URI getCurrentLevel(URI uri)

Determines the current level of a hierarchical URI. This is equivalent to resolving the path "." to the URI.

Parameters:

uri - The URI to examine.

Returns:

A URI representing the current hierarchical level of a hierarchical URI.

getParentLevel

public static URI getParentLevel(URI uri)

Determines the parent level of a hierarchical URI. This is equivalent to resolving the path ".." to the URI for all non-root paths.

Parameters:

uri - The URI to examine.

Returns:

A URI representing the parent hierarchical level of a hierarchical URI, or null if the given URI's path equates to the root path.

getParentURI

public static URI getParentURI(URI uri)

Determines the parent collection of a hierarchical URI.

Non-normalized collection paths (e.g. ending with /.) are not supported.

Parameters:

uri - The URI to examine.

Returns:

A URI representing the parent collection of a hierarchical URI; if the URI ends in '/', equivalent to resolving the path ".." to the URI; if the URI does not end in '/', equivalent to resolving the path "." to the URI; or null if the given URI's path equates to the root path.

Throws:

IllegalArgumentException - if the URI does not have a path component.

See Also:

• isCollectionURI(URI)
• getParentLevel(URI)
• getCurrentLevel(URI)

getRootURI

public static URI getRootURI(URI uri)

Determines the canonical root URI of a URI.

Parameters:

uri - The URI to examine.

Returns:

A URI representing the URI with no path and no query or fragment.

relativizeChildPath

public static URI relativizeChildPath(URI parentURI,
 URI childURI)

Returns a URI relative to the given parent URI. A collection URI relativized against itself will return an empty URI.

This method does not support backtracking, that is, creating a path to a parent or child path. For that functionality use findRelativePath(URI, URI) instead.

API Note:

This method differs from URI.relativize(URI) in that the parent URI must be a collection URI (i.e. end with a slash) for a relative child path to be found.

Implementation Specification:

This method delegates to findRelativeChildPath(URI, URI)

Parameters:

parentURI - The URI to which the child URI is relative.

childURI - The URI that will be relativized against the parent URI.

Returns:

The URI representing path of the child URI to the parent URI, or the child URI if the given child URI is not a child of the given parent URI.

See Also:

• normalize(URI)

findRelativeChildPath

public static Optional<URI> findRelativeChildPath(@Nonnull
 URI parentURI,
 @Nonnull
 URI childURI)

Returns a URI relative to the given parent URI. A collection URI relativized against itself will return an empty URI.

This method does not support backtracking, that is, creating a path to a parent or child path. For that functionality use findRelativePath(URI, URI) instead.

API Note:

This method differs from URI.relativize(URI) in that the parent URI must be a collection URI (i.e. end with a slash) for a relative child path to be found.

Implementation Specification:

This method first normalizes both URIs.

Parameters:

parentURI - The URI to which the child URI is relative.

childURI - The URI that will be relativized against the parent URI.

Returns:

The URI representing path of the child URI to the parent URI, which will not be present if the given child URI is not a child of the given parent URI.

See Also:

• normalize(URI)

relativizePath

public static URI relativizePath(@Nonnull
 URI sourceURI,
 @Nonnull
 URI targetURI)

Returns the path of a target URI relative to some source URI, which may be a sibling URI or even a child URI. A collection URI relativized against itself will return an empty URI. A non-collection URI relativized against its parent will return ./. Otherwise if the source URI is not a parent of (or the same URI as) the target URI, the path will backtrack using .. path segments as appropriate.

Implementation Specification:

This method delegates to findRelativePath(URI, URI)

Implementation Note:

This implementation properly relativizes URIs that require backtracking, such as siblings, unlike Java URI relativization methods; see JDK-6226081., This method differs from URI.relativize(URI), which would return an empty URI when relativizing foo/bar against foo/. This method instead would return ./, compliant with browser relative resolution behavior and with RFC 3986, as discussed at Is Java's URI.resolve incompatible with RFC 3986 when the relative URI contains an empty path?.

Parameters:

sourceURI - The URI to which the other URI will be relativized.

targetURI - The URI that will be relativized against the base URI.

Returns:

The relative path of the source URI to the target URI, or the target URI if the two URIs have no base in common.

See Also:

• normalize(URI)

findRelativePath

public static Optional<URI> findRelativePath(@Nonnull
 URI sourceURI,
 @Nonnull
 URI targetURI)

Returns the path of a target URI relative to some source URI, which may be a sibling URI or even a child URI. A collection URI relativized against itself will return an empty URI. A non-collection URI relativized against its parent will return ./. Otherwise if the source URI is not a parent of (or the same URI as) the target URI, the path will backtrack using .. path segments as appropriate.

Implementation Specification:

This method first normalizes both URIs.

Implementation Note:

This implementation properly relativizes URIs that require backtracking, such as siblings, unlike Java URI relativization methods; see JDK-6226081., This method differs from URI.relativize(URI), which would return an empty URI when relativizing foo/bar against foo/. This method instead would return ./, compliant with browser relative resolution behavior and with RFC 3986, as discussed at Is Java's URI.resolve incompatible with RFC 3986 when the relative URI contains an empty path?.

Parameters:

sourceURI - The URI to which the other URI will be relativized.

targetURI - The URI that will be relativized against the base URI.

Returns:

The relative path of the source URI to the target URI, which will not be present if the two URIs have no base in common.

Throws:

IllegalArgumentException - if the two URIs have no base URI in common.

See Also:

• normalize(URI)

createURN

public static URI createURN(String nid,
 String nss)

Creates a URN in the form urn:nid:nss.

Parameters:

nid - The namespace identifier.

nss - The namespace-specific string.

Returns:

A URN based upon the given parameters.

Throws:

IllegalArgumentException - if the resulting string violates RFC 2396.

See Also:

• RFC 2141

createInfoURI

public static URI createInfoURI(String namespace,
 String rawIdentifier)

Creates an "info" URI with the given info namespace and identifier with no fragment.

Parameters:

namespace - The info namespace.

rawIdentifier - The raw, encoded info identifier.

Returns:

An info URI based upon the given parameters.

Throws:

NullPointerException - if the given namespace and/or identifier is null.

IllegalArgumentException - if the given namespace, and/or identifier result in an invalid URI.

See Also:

• RFC 4452

createInfoURI

public static URI createInfoURI(String namespace,
 String rawIdentifier,
 String rawFragment)

Creates an "info" URI with the given info namespace, identifier, and optional fragment.

Parameters:

namespace - The info namespace.

rawIdentifier - The raw, encoded info identifier.

rawFragment - The raw, encoded fragment, or null if there should be no fragment

Returns:

An info URI based upon the given parameters.

Throws:

NullPointerException - if the given namespace and/or identifier is null.

IllegalArgumentException - if the given namespace, identifier, and/or fragment result in an invalid URI.

See Also:

• RFC 4452

createMailtoURI

public static URI createMailtoURI(String username,
 String domain)

Creates a "mailto" URI in the form mailto:username@domain. The username and domain will be URI-encoded.

Parameters:

username - The mail username.

domain - The mail domain.

Returns:

A mailto URI based upon the given parameters.

Throws:

NullPointerException - if the given username and/or domain is null.

See Also:

• RFC 2368

createURI

@Deprecated
public static URI createURI(Object contextObject,
 String string)
                     throws URISyntaxException

Deprecated.

because this ancient code doesn't have an obvious utility, is confusing, and jumbles various types, many of them legacy.

Creates a URI from the given URI string relative to the given context object.

Parameters:

contextObject - The source context, such as a URL, a URI, a File, or null if the filename should not be referenced from any object.

string - The string version of a URI, either relative or absolute, or a URI fragment beginning with "#".

Returns:

A URI constructed from the URI string and context object.

Throws:

URISyntaxException - Thrown if the context object and string cannot be used to create a valid URI.

See Also:

• File
• URI
• URL

guessAbsoluteURI

public static URI guessAbsoluteURI(String string)

Creates an absolute URI from the given string, guessing what the string represents.

If the string is not a valid URL (e.g. it contains a space), this method assumes that a file was intended and a file URI is constructed.

This method is convenient for creating URIs based upon user input.

Parameters:

string - The string to convert to a URI.

Returns:

A URI representing the contents of the string, interpreted in a lenient fashion.

getDirectoryURL

public static URL getDirectoryURL(URL url)
                           throws MalformedURLException

Returns a URL representing the directory of the given file URL. (It is assumed that the given URL represents a file.)

Parameters:

url - The URL of a file.

Returns:

A URL of the file's directory, ending with '/'.

Throws:

MalformedURLException - Thrown if a directory URL cannot be created.

getHost

public static Host getHost(URI uri)

Returns the unencoded host and optional port of the given URI.

Parameters:

uri - The URI from which to extract the host and optional port.

Returns:

The host name and optional port of the given URI, or null if there is no host specified in the given URI.

getRawPathQueryFragment

public static String getRawPathQueryFragment(URI uri)

Returns the unencoded path, optional unencoded query, and optional unencoded fragment of the given URI.

Parameters:

uri - The URI from which to extract the path, optional query, and optional fragment.

Returns:

An unencoded path in the form [path][?query][#fragment], or null if none of those components are present in the given URI.

getRelativePath

public static String getRelativePath(String absolutePath)

Determines the relative path of the given absolute path by removing the root path '/' character from the beginning of the path.

Parameters:

absolutePath - The absolute path to convert to a relative path.

Returns:

A relative path from the root of the absolute path.

Throws:

IllegalArgumentException - if the given path is not absolute.

isCollectionURI

public static boolean isCollectionURI(URI uri)

Determines whether the URI represents a canonical collection, that is, it has a path that ends with a slash ('/'). This method returns false for URIs with no path component.

Parameters:

uri - The URI the raw path of which to examine.

Returns:

true if the given URI has a path that ends with a slash ('/').

See Also:

• isCollectionPath(String)

checkCollectionURI

public static URI checkCollectionURI(URI uri)

Checks to see if a given URI represents a canonical collection, that is, it has a path that ends with a slash ('/'). If the given URI is not a collection URI, an exception is thrown.

Parameters:

uri - The URI to check to for a collection.

Returns:

The given collection URI.

Throws:

NullPointerException - if the given URI is null.

IllegalArgumentException - if the provided URI does not have a path that ends with a slash ('/').

See Also:

• isCollectionURI(URI)

checkNotCollectionURI

public static URI checkNotCollectionURI(URI uri)

Checks to see if a given URI does not represents a canonical collection, that is, it does not have a path that ends with a slash ('/'). If the given URI is not a collection URI, an exception is thrown.

Parameters:

uri - The URI to check to for a collection.

Returns:

The given non-collection URI.

Throws:

NullPointerException - if the given URI is null.

IllegalArgumentException - if the provided URI has path that ends with a slash ('/').

See Also:

• isCollectionURI(URI)

hasPath

public static boolean hasPath(@Nonnull
 URI uri)

Determines whether the URI has a path. This is a convenience method that delegates to URI.getRawPath().

Parameters:

uri - The URI which should be checked for a path.

Returns:

true if the given URI has a path.

hasAbsolutePath

public static boolean hasAbsolutePath(@Nonnull
 URI uri)

Determines whether the path of the URI (which may or may not be absolute) is absolute.

Parameters:

uri - The URI the path of which to examine.

Returns:

true if the URI has a path that begins with a slash ('/').

See Also:

• hasPath(URI)
• isPathAbsolute(String)

hasSubPath

public static boolean hasSubPath(@Nonnull
 URI uri)

Determines whether the path of the URI is a relative path that does not backtrack to a higher level. This method considers a URI referring to the current level as a "subpath".

Implementation Specification:

This method first normalizes the URI using URI.normalize() and then checks to see if the path is ".." or begins with a backtrack "../" path segment.

Parameters:

uri - The URI the path of which to examine.

Returns:

true if the URI has a relative path that, when normalized, refers to a location at a higher relative level; that is, when normalized it begins with a backtrack ".." path segment.

See Also:

• hasPath(URI)
• PARENT_LEVEL_PATH_SEGMENT

isHost

public static boolean isHost(URI uri)

Determines whether the URI contains only a host and optional port.

Parameters:

uri - The URI the path of which to examine.

Returns:

true if the URI contains only a host and optionally a port.

toValidURL

public static URL toValidURL(URI uri)

Creates a URL from a URI. If a valid URL cannot be formed, null is returned.

Parameters:

uri - The URI to convert to a URL, or null if no URI is available (in which case null will be returned).

Returns:

The URL form of the URI, or null if the URI cannot be converted to a valid URL.

isUNCFileURI

public static boolean isUNCFileURI(URI uri)

Determines whether the given URI is a UNC file path URI in the form file:////server/file.ext.

Strangely, the Java URI form of a UNC path will contain a path prefixed with //, but the entire scheme-specific part will be prefixed with ////.

Parameters:

uri - The URI to test.

Returns:

true if the given URI has a scheme of "file" and its scheme-specific part begins with four slashes.

See Also:

• WINDOWS_UNC_PATH_URI_SSP_PREFIX

normalize

public static URI normalize(URI uri)

Normalizes a URI.

API Note:

This method has the same semantics as URI.normalize(), except that this method has improvements and bug fixes. For example, a UNC path such as file:////server/file.ext will retain its correct path, unlike URI.normalize(), which would reduce this to file:/server/file.ext.

Parameters:

uri - The URI to normalize.

Returns:

The normalized URI.

See Also:

• isUNCFileURI(URI)
• Java Bug ID: 4723726

resolve

public static URI resolve(URI baseURI,
 String childURI)

Resolves a string against a base URI with added functionality and bug fixes over URI.resolve(String), following RFC 3986.

This method correctly resolves fragment URIs against opaque base URIs.

This method corrects Java's erroneous collapsing of slashes in UNC paths, so that for example file:////server/file.ext can successfully be resolved against.

API Note:

This method follows differs from URI.resolve(URI), which would resolve the empty path "" as if it were ., following RFC 2396. That is, http://example.com/foo/bar resolved against "" would return http://example.com/foo/. This method instead follows RFC 3986, as discussed at Is Java's URI.resolve incompatible with RFC 3986 when the relative URI contains an empty path?, and returns the URI itself, e.g. http://example.com/foo/bar.

Implementation Specification:

This method creates a URI from the child URI using URI.create(String) and then delegates to resolve(URI, URI).

Parameters:

baseURI - The URI against which the child URI should be resolved.

childURI - The URI to resolve against the base URI.

Returns:

The child URI resolved against the base URI.

Throws:

NullPointerException - if the base URI and/or the child URI is null.

See Also:

• RFC 3986: Uniform Resource Identifier (URI): Generic Syntax
• RDF/XML Syntax Specification (Revised) 5.3 Resolving URIs
• isUNCFileURI(URI)

resolve

public static URI resolve(URI baseURI,
 URI childURI)

Resolves a relative URI against a base URI with added functionality and bug fixes over URI.resolve(URI), following RFC 3986.

This method correctly resolves fragment URIs against opaque base URIs.

This method corrects Java's erroneous collapsing of slashes in UNC paths in URI.resolve(URI), so that for example file:////server/file.ext can successfully be resolved against.

API Note:

This method follows differs from URI.resolve(URI), which would resolve the empty path "" as if it were ., following RFC 2396. That is, http://example.com/foo/bar resolved against "" would return http://example.com/foo/. This method instead follows RFC 3986, as discussed at Is Java's URI.resolve incompatible with RFC 3986 when the relative URI contains an empty path?, and returns the URI itself, e.g. http://example.com/foo/bar.

Parameters:

baseURI - The URI against which the child URI should be resolved.

childURI - The URI to resolve against the base URI.

Returns:

The child URI resolved against the base URI.

Throws:

NullPointerException - if the base URI and/or the child URI is null.

See Also:

• RFC 3986: Uniform Resource Identifier (URI): Generic Syntax
• RDF/XML Syntax Specification (Revised) 5.3 Resolving URIs
• isUNCFileURI(URI)

resolve

public static URI resolve(URI baseURI,
 URI childURI,
 boolean deep)

Resolves a relative URI against a base URI with added functionality and bug fixes over URI.resolve(URI), following RFC 3986. If a deep resolution is requested, a URI's contents will be further resolved if possible, even if the URI itself is already absolute. For example, a deep resolution of file:/foo/bar.txt against file:///C:/test would yield file:///C:/test/foo/bar.txt.

This implementation supports deep resolution of the following URI schemes:

• Files"file"

This method correctly resolves fragment URIs against opaque base URIs.

This method corrects Java's erroneous collapsing of slashes in UNC paths in URI.resolve(URI), so that for example file:////server/file.ext can successfully be resolved against.

API Note:

This method follows differs from URI.resolve(URI), which would resolve the empty path "" as if it were ., following RFC 2396. That is, http://example.com/foo/bar resolved against "" would return http://example.com/foo/. This method instead follows RFC 3986, as discussed at Is Java's URI.resolve incompatible with RFC 3986 when the relative URI contains an empty path?, and returns the URI itself, e.g. http://example.com/foo/bar.

Parameters:

baseURI - The URI against which the child URI should be resolved.

childURI - The URI to resolve against the base URI.

deep - Whether the relative contents of the URI should also be resolved, even if the URI itself is absolute.

Returns:

The child URI resolved against the base URI.

Throws:

NullPointerException - if the base URI and/or the child URI is null.

See Also:

• RFC 3986: Uniform Resource Identifier (URI): Generic Syntax
• RDF/XML Syntax Specification (Revised) 5.3 Resolving URIs
• isUNCFileURI(URI)

resolve

public static URI resolve(URI baseURI,
 URIPath path)

Resolves a URI path against a base URI.

Parameters:

baseURI - The base URI against which the path should be resolved.

path - The path to resolve against the base URI.

Returns:

A URI that represents the path resolved against the base URI.

Throws:

NullPointerException - if the given base URI and/or path is null.

resolveFragment

public static URI resolveFragment(URI uri,
 String fragment)
                           throws IllegalArgumentException

Returns a URI constructed from a given URI and a fragment identifier. The fragment will first be URI-encoded.

If no URI is provided, a URI is created from the fragment itself.

Parameters:

uri - The URI to which to add a fragment identifier, or null if a URI should be created from just the fragment.

fragment - The unencoded fragment to add to the end of the URI.

Returns:

The URI constructed.

Throws:

IllegalArgumentException - if the a URI cannot be constructed from the given information.

See Also:

• encode(String)
• URI.create(String)

resolveRawFragment

public static URI resolveRawFragment(URI uri,
 String rawFragment)
                              throws IllegalArgumentException

Returns a URI constructed from a given URI and a raw fragment identifier.

If the URI is not syntactically correct, an IllegalArgumentExceptionwill be thrown.

This method should normally only be used when the format of the string is known to be a syntactically correct URI.

If no URI is provided, a URI is created from the fragment itself.

Parameters:

uri - The URI to which to add a fragment identifier, or null if a URI should be created from just the fragment.

rawFragment - The raw, encoded fragment to add to the end of the URI.

Returns:

The URI constructed.

Throws:

IllegalArgumentException - if the a URI cannot be constructed from the given information.

See Also:

• URI.create(String)

removeFragment

public static URI removeFragment(URI uri)

Returns a URI with its fragment, if any, removed.

Parameters:

uri - The URI from which a fragment should be removed.

Returns:

The URI with the fragment, if any, removed.

Throws:

NullPointerException - if the given URI is null.

See Also:

• replaceRawFragment(URI, String)

replaceRawFragment

public static URI replaceRawFragment(URI uri,
 String newRawFragment)

Returns a URI with its fragment, if any, replaced.

Parameters:

uri - The URI from which a fragment should be removed.

newRawFragment - The new encoded fragment, or null if the URI should have no fragment.

Returns:

The URI with the fragment, if any, removed and replaced with the given raw fragment, if any.

Throws:

NullPointerException - if the given URI is null.

createURI

public static URI createURI(String scheme,
 String rawSchemeSpecificPart)
                     throws IllegalArgumentException

Returns a URI constructed from the given parts, any of which can be null.

This method should normally only be used when the format of the string is known to be a syntactically correct URI.

Parameters:

scheme - The name of the URI scheme.

rawSchemeSpecificPart - The raw, encoded scheme-specific part, or null if there is no scheme-specific part.

Returns:

The URI constructed.

Throws:

IllegalArgumentException - if the a URI cannot be constructed from the given strings.

createURI

public static URI createURI(String scheme,
 String rawSchemeSpecificPart,
 String rawFragment)
                     throws IllegalArgumentException

Returns a URI constructed from the given parts, any of which can be null.

This method should normally only be used when the format of the string is known to be a syntactically correct URI.

Parameters:

scheme - The name of the URI scheme.

rawSchemeSpecificPart - The raw, encoded scheme-specific part, or null if there is no scheme-specific part.

rawFragment - The raw, encoded fragment at the end of the URI, or null if there is no fragment.

Returns:

The URI constructed.

Throws:

IllegalArgumentException - if the a URI cannot be constructed from the given strings.

createURI

public static URI createURI(String scheme,
 String rawUserInfo,
 String host,
 int port,
 URIPath path,
 String rawQuery,
 String rawFragment)
                     throws IllegalArgumentException

Returns a URI constructed from the given parts, any of which can be null.

This method should normally only be used when the format of the string is known to be a syntactically correct URI.

Parameters:

scheme - The name of the URI scheme.

rawUserInfo - The raw, encoded user information, or null if there is no user information.

host - The host information, or null if there is no host.

port - The port number, or -1 for no defined port.

path - The path, or null if there is no path.

rawQuery - The raw, encoded URI query, or null if there is no query.

rawFragment - The raw, encoded fragment at the end of the URI, or null if there is no fragment.

Returns:

The URI constructed.

Throws:

IllegalArgumentException - if the a URI cannot be constructed from the given strings.

createURI

public static URI createURI(String scheme,
 String rawUserInfo,
 String host,
 int port,
 String rawPath,
 String rawQuery,
 String rawFragment)
                     throws IllegalArgumentException

Returns a URI constructed from the given parts, any of which can be null.

This method should normally only be used when the format of the string is known to be a syntactically correct URI.

Parameters:

scheme - The name of the URI scheme.

rawUserInfo - The raw, encoded user information, or null if there is no user information.

host - The host information, or null if there is no host.

port - The port number, or -1 for no defined port.

rawPath - The raw, encoded path, or null if there is no path.

rawQuery - The raw, encoded URI query, or null if there is no query.

rawFragment - The raw, encoded fragment at the end of the URI, or null if there is no fragment.

Returns:

The URI constructed.

Throws:

IllegalArgumentException - if the a URI cannot be constructed from the given strings.

encode

public static String encode(URI uri)

Encodes all non-ASCII and URI reserved characters in the URI according to the URI encoding rules in RFC 3986, "Uniform Resource Identifiers (URI): Generic Syntax" using the URI escape character, '%'.

Parameters:

uri - The URI to URI-encode.

Returns:

A string containing the escaped data.

See Also:

• ESCAPE_CHAR

encode

public static String encode(URI uri,
 char escapeChar)

Encodes all non-ASCII and URI reserved characters in the URI according to the URI encoding rules in RFC 3986, "Uniform Resource Identifiers (URI): Generic Syntax".

Parameters:

uri - The URI to URI-encode.

escapeChar - The escape character to use, which will always be escaped.

Returns:

A string containing the escaped data.

encode

public static String encode(String string)

Encodes all URI reserved characters in the string according to the URI encoding rules in RFC 3986, "Uniform Resource Identifiers (URI): Generic Syntax" using the URI escape character, '%'.

Parameters:

string - The data to URI-encode.

Returns:

A string containing the escaped data.

See Also:

• ESCAPE_CHAR

encode

public static String encode(String string,
 char escapeChar)

Encodes all URI reserved characters in the string according to the URI encoding rules in RFC 3986, "Uniform Resource Identifiers (URI): Generic Syntax".

Parameters:

string - The data to URI-encode.

escapeChar - The escape character to use, which will always be escaped.

Returns:

A string containing the escaped data.

decode

public static String decode(CharSequence uri)

Decodes the escaped characters in the character iterator according to the URI encoding rules in RFC 2396, "Uniform Resource Identifiers (URI): Generic Syntax", using the URI escape character, '%'.

Parameters:

uri - The data to URI-decode.

Returns:

A character sequence containing the encoded URI data.

Throws:

IllegalArgumentException - if the given URI string contains a character greater than U+00FF.

IllegalArgumentException - if a given escape character is not followed by a two-digit escape sequence.

See Also:

• ESCAPE_CHAR

decode

public static String decode(CharSequence uri,
 char escapeChar)

Decodes the escaped ('%') characters in the character iterator according to the URI encoding rules in RFC 2396, "Uniform Resource Identifiers (URI): Generic Syntax".

Parameters:

uri - The data to URI-decode.

escapeChar - The escape character.

Returns:

A character sequence containing the encoded URI data.

Throws:

IllegalArgumentException - if the given URI string contains a character greater than U+00FF.

IllegalArgumentException - if a given escape character is not followed by a two-digit escape sequence.

canonicalize

public static URI canonicalize(URI uri)

Ensures that the given URI is in canonical form.

This implementation, following the recommendation of RFC 3986, ensures that all hexadecimal escape codes are in uppercase.

API Note:

This method should be distinguished from normalize(URI), which normalizes the hierarchy of path segments.

Implementation Note:

This implementation does not currently encode any non-ASCII or reserved characters.

Parameters:

uri - The URI to be returned in canonical form.

Returns:

The canonical form of the given URI.

Throws:

NullPointerException - if the given URI is null.

IllegalArgumentException - if the given URI has an invalid escape sequence.

changeBase

public static URI changeBase(URI uri,
 URI oldBaseURI,
 URI newBaseURI)

Changes a URI from one base to another. For example, http://example.com/base1/test.txt changed from base http://example.com/base1/ to base http://example.com/base2/level2/ yields http://example.com/base2/level2/test.txt. If the old and new base URIs are the same, a URI equal to given URI is returned.

Parameters:

uri - The URI the base of which to change.

oldBaseURI - The current base URI.

newBaseURI - The base URI of the new URI to construct.

Returns:

A new URI constructed by relativizing the URI to the old base URI and resolving the resulting URI against the new base URI.

Throws:

IllegalArgumentException - if the old base URI is is not a base URI of the given URI.

See Also:

• isUNCFileURI(URI)
• URI.relativize(URI)
• resolve(URI, URI)

isChild

public static boolean isChild(URI baseURI,
 URI uri)

Determines whether the given URI is a child relative to the given base URI. The base URI is considered a child of itself. This for the base URI http://www.example.com/base/, the URIs http://www.example.com/base/ and http://www.example.com/base/child/ are considered child URIs, while http://www.example.com/ and http://www.example.com/other/ are not.

Implementation Note:

This implementation relies on the behavior of URI.relativize(URI) not to relativize URIs that require backtracking, such as siblings, as described in JDK-6226081.

Parameters:

baseURI - The assumed base URI.

uri - The URI which may be relative to the given base URI.

Returns:

true if the given URI can be made relative to the given base URI resulting in a non-absolute form.

Throws:

NullPointerException - if the given base URI and/or URI is null.

compress

public static String compress(URI uri)

Compresses a URI into a shorter string representation.

Parameters:

uri - The URI to compress.

Returns:

A compressed string representation of the URI.

decompress

public static URI decompress(String string)
                      throws SyntaxException

Decompresses a URI from a shorter string representation.

Parameters:

string - The alphanumeric string.

Returns:

An uncompressed URI from the alphanumeric string.

Throws:

SyntaxException - Thrown if the given string is not correctly encoded.

plainEncode

public static String plainEncode(URI uri)

Encodes an absolute URI into a plain string that is safe to be used in the path of another URI, for example. The resulting string will only contain PLAIN_ENCODE_CHARACTERS, making it also be a valid XML name.

1. The scheme separator character ':' is replaced with '-'.
2. Every instance of the slash character '/' is replaced with '-'.
3. The characters '-', '_', and all other non-URI characters are escaped using '_' as the escape character.

This implementation ensures that all hexadecimal escape codes are in lowercase.

Implementation Note:

The implementation encodes all non-ASCII characters.

Parameters:

uri - The URI to encode

Returns:

A string representing the plain encoding of the URI.

Throws:

IllegalArgumentException - if the given URI is not absolute.

See Also:

• PLAIN_ENCODE_CHARACTERS

plainDecode

public static URI plainDecode(CharSequence charSequence)

Decodes a plain-encoded URI.

Parameters:

charSequence - The string containing the plain-encoded URI.

Returns:

The decoded URI.

Throws:

IllegalArgumentException - if the given string is not a plain-encoded URI.

checkCollectionPath

public static String checkCollectionPath(@Nonnull
 String path)

Checks to see if a given path represents a canonical collection, that is, it has a path that ends with a slash ('/'). If the given path is not a collection path, an exception is thrown.

Parameters:

path - The raw path to examine.

Returns:

The given collection path.

Throws:

NullPointerException - if the given path is null.

IllegalArgumentException - if the provided path does not end with a slash ('/').

See Also:

• isCollectionPath(String)

checkNotCollectionPath

public static String checkNotCollectionPath(String path)

Checks to see if a given path does not represents a canonical collection, that is, it does not have a path that ends with a slash ('/'). If the given path is not a collection path, an exception is thrown.

Parameters:

path - The raw path to examine.

Returns:

The given non-collection path.

Throws:

NullPointerException - if the given path is null.

IllegalArgumentException - if the provided path ends with a slash ('/').

See Also:

• isCollectionPath(String)

checkPath

public static String checkPath(String path)
                        throws IllegalArgumentException

Checks to see if a given path is only a path and not a URI with a scheme and/or authority. If the given string is not a path, an exception is thrown.

Parameters:

path - The string version of a path to determine if it is indeed only a path.

Returns:

The given path.

Throws:

NullPointerException - if the given path is null.

IllegalArgumentException - if the given string is not a path.

See Also:

• isPath(String)

checkRelativePath

public static String checkRelativePath(String path)
                                throws IllegalArgumentException

Checks to see if a given path is only a relative path and not a URI with a scheme and/or authority. If the given string is not a relative path, an exception is thrown.

Parameters:

path - The string version of a path to determine if it is indeed only a relative path.

Returns:

The given relative path.

Throws:

NullPointerException - if the given path is null.

IllegalArgumentException - if the given string is not a path or the path is not relative.

See Also:

• isPath(String)

constructPath

public static String constructPath(boolean absolute,
 boolean collection,
 String... pathElements)

Constructs an absolute path from the given elements in the form: /element1/element2. Each element in the path is URI-encoded using UTF-8.

Parameters:

absolute - true if the path should be absolute and therefore should begin with '/'.

collection - true if the path should be a collection and therefore end with `/`.

pathElements - true if the path represents a collection and therefore should end with '/'.

Returns:

A path constructed according to the given rules.

Throws:

IllegalArgumentException - if there are no path elements and an absolute non-collection or non-absolute collection is requested.

See Also:

• encode(String)

getName

public static String getName(String path)

Returns the name of the resource at the given path, which will be the name of the last path component. If the path is a collection (i.e. it ends with slash), the component before the last slash will be returned. As examples, "/path/name.ext" and "name.ext" will return "name.ext". "/path/", "path/", and "path" will all return "path".

Parameters:

path - The path, which should be encoded if '/' characters are present within a path component.

Returns:

The name of the last last path component, the empty string if the path is the empty string, or "/" if the path is the root path.

Throws:

NullPointerException - if the given path is null.

isCollectionPath

public static boolean isCollectionPath(@Nonnull
 String path)

Determines whether the given path is a canonical collection path.

Non-normalized collection paths (e.g. ending with /.) are not supported.

Parameters:

path - The raw path to examine.

Returns:

true if the path ends with a slash ('/').

Throws:

NullPointerException - if the given path is null.

isPath

public static boolean isPath(String path)

Determines if a given path is only a path and not a URI with a scheme and/or authority.

Parameters:

path - The string version of a path to determine if it.

Returns:

true if the path is a path and does not specify a scheme (i.e. the URI is not absolute) or authority.

Throws:

NullPointerException - if the given path is null.

See Also:

• isPathURI(URI)

isPathAbsolute

public static boolean isPathAbsolute(@Nonnull
 String path)

Determines whether the given path is absolute.

Parameters:

path - The path to examine.

Returns:

true if the path begins with a slash ('/').

Throws:

NullPointerException - if the path is null.

normalizePath

public static String normalizePath(String path)

Normalizes the given path by resolving the . and .. path segments.

Parameters:

path - The path to normalize.

Returns:

The normalized form of the given path.

Throws:

NullPointerException - if the given path is null.

IllegalArgumentException - if the provided path specifies a URI scheme (i.e. the URI is absolute) and/or authority.

See Also:

• normalize(URI)