URI (GNU Classpath 0.94-pre Documentation)

A URI instance represents that defined by RFC3986, with some deviations.

At its highest level, a URI consists of:

[scheme:]scheme-specific-part
 [#fragment]

where # and : are literal characters, and those parts enclosed in square brackets are optional.

There are two main types of URI. An opaque URI is one which just consists of the above three parts, and is not further defined. An example of such a URI would be mailto: URI. In contrast, hierarchical URIs give further definition to the scheme-specific part, so as represent some part of a hierarchical structure.

[//authority][path] [?query]

with / and ? being literal characters. When server-based, the authority section is further subdivided into:

[user-info@]host [:port]

with @ and : as literal characters. Authority sections that are not server-based are said to be registry-based.

Hierarchical URIs can be either relative or absolute. Absolute URIs always start with a `/', while relative URIs don't specify a scheme. Opaque URIs are always absolute.

Each part of the URI may have one of three states: undefined, empty or containing some content. The former two of these are represented by null and the empty string in Java, respectively. The scheme-specific part may never be undefined. It also follows from this that the path sub-part may also not be undefined, so as to ensure the former.

Character Escaping and Quoting

The characters that can be used within a valid URI are restricted. There are two main classes of characters which can't be used as is within the URI:

Characters outside the US-ASCII character set. These have to be escaped in order to create an RFC-compliant URI; this means replacing the character with the appropriate hexadecimal value, preceded by a `%'.
Illegal characters (e.g. space characters, control characters) are quoted, which results in them being encoded in the same way as non-US-ASCII characters.

The set of valid characters differs depending on the section of the URI:

Scheme: Must be an alphanumeric, `-', `.' or '+'.
Authority:Composed of the username, host, port, `@' and `:'.
Username: Allows unreserved or percent-encoded characters, sub-delimiters and `:'.
Host: Allows unreserved or percent-encoded characters, sub-delimiters and square brackets (`[' and `]') for IPv6 addresses.
Port: Digits only.
Path: Allows the path characters and `/'.
Query: Allows the path characters, `?' and '/'.
Fragment: Allows the path characters, `?' and '/'.

These definitions reference the following sets of characters:

Unreserved characters: The alphanumerics plus `-', `.', `_', and `~'.
Sub-delimiters: `!', `$', `&', `(', `)', `*', `+', `,', `;', `=' and the single-quote itself.
Path characters: Unreserved and percent-encoded characters and the sub-delimiters along with `@' and `:'.

The constructors and accessor methods allow the use and retrieval of URI components which contain non-US-ASCII characters directly. They are only escaped when the toASCIIString() method is used. In contrast, illegal characters are always quoted, with the exception of the return values of the non-raw accessors.

Since: 1.4

Constructor Summary
	URI(String str) Creates an URI from the given string
	URI(String scheme, String userInfo, String host, int port, String path, String query, String fragment) Create an URI from the given components
	URI(String scheme, String authority, String path, String query, String fragment) Create an URI from the given components
	URI(String scheme, String host, String path, String fragment) Create an URI from the given components
	URI(String scheme, String ssp, String fragment) Create an URI from the given components

Method Summary
int	compareTo(URI uri) Compare the URI with another URI.
static URI	create(String str) Create an URI from the given string
boolean	equals(Object obj) Compares the URI with the given object for equality.
String	getAuthority() Returns the decoded authority part of this URI
String	getFragment() Returns the fragment of the URI
String	getHost() Returns the hostname of the URI
String	getPath() Returns the path of the URI
int	getPort() Returns the port number of the URI
String	getQuery() Returns the query of the URI
String	getRawAuthority() Returns the raw authority part of this URI
String	getRawFragment() Return the raw fragment part of this URI
String	getRawPath() Returns the raw path part of this URI
String	getRawQuery() Returns the raw query part of this URI
String	getRawSchemeSpecificPart() Returns the raw scheme specific part of this URI.
String	getRawUserInfo() Returns the raw user info part of this URI
String	getScheme() Returns the scheme of the URI
String	getSchemeSpecificPart() Returns the decoded scheme specific part of this URI.
String	getUserInfo() Returns the decoded user info part of this URI
int	hashCode() Computes the hashcode of the URI
boolean	isAbsolute() Tells whether this URI is absolute or not
boolean	isOpaque() Tell whether this URI is opaque or not
URI	normalize() Returns a normalized version of the URI.
URI	parseServerAuthority() Attempts to parse this URI's authority component, if defined, into user-information, host, and port components.
URI	relativize(URI uri) Relativizes the given URI against this URI.
URI	resolve(URI uri) Resolves the given URI against this URI
URI	resolve(String str) Resolves the given URI string against this URI
String	toASCIIString() Returns the URI as US-ASCII string.
String	toString() Returns the URI as a String.
URL	toURL() Creates an URL from an URI

Compare the URI with another URI. Undefined components are taken to be less than any other component. The following criteria are observed:

Two URIs with different schemes are compared according to their scheme, regardless of case.
A hierarchical URI is less than an opaque URI with the same scheme.
For opaque URIs:

URIs with differing scheme-specific parts are ordered according to the ordering of the scheme-specific part.
URIs with the same scheme-specific part are ordered by the raw fragment.

For hierarchical URIs:

URIs are ordered according to their raw authority sections, if they are unequal.
For registry-based authorities:

they are ordered according to the ordering of the authority component.

For server-based authorities:

URIs are ordered according to the raw user information.
URIs with the same user information are ordered by the host, ignoring case.
URIs with the same host are ordered by the port.

URIs with the same authority section are ordered by the raw path.
URIs with the same path are ordered by their raw query.
URIs with the same query are ordered by their raw fragments.

Parameters: uri The other URI to compare this URI with

Returns: a negative integer, zero or a positive integer depending on whether this URI is less than, equal to or greater than that supplied, respectively.

create

equals

Compares the URI with the given object for equality. If the object is not a URI, then the method returns false. Otherwise, the following criteria are observed:

The scheme of the URIs must either be null (undefined) in both cases, or equal, ignorant of case.
The raw fragment of the URIs must either be null (undefined) in both cases, or equal, ignorant of case.
Both URIs must be of the same type (opaque or hierarchial)
For opaque URIs:

The raw scheme-specific parts must be equal.

For hierarchical URIs:

The raw paths must be equal, ignorant of case.
The raw queries are either both undefined or both equal, ignorant of case.
The raw authority sections are either both undefined or:
For registry-based authorities:

they are equal.

For server-based authorities:

the hosts are equal, ignoring case
the ports are equal
the user information components are equal

Parameters: obj the obj to compare the URI with.

Returns: true if the objects are equal, according to the specification above.

getRawSchemeSpecificPart

getRawUserInfo

getScheme

getSchemeSpecificPart

Relativizes the given URI against this URI. The following algorithm is used:

If either URI is opaque, the given URI is returned.
If the schemes of the URIs differ, the given URI is returned.
If the authority components of the URIs differ, then the given URI is returned.
If the path of this URI is not a prefix of the supplied URI, then the given URI is returned.
If all the above conditions hold, a new URI is created using the query and fragment components of the given URI, along with a path computed by removing the path of this URI from the start of the path of the supplied URI.

Parameters: uri the URI to relativize agsint this URI

Returns: the resulting URI

Throws: NullPointerException if the uri is null

Class URI

Character Escaping and Quoting