java.net

Class URI

public final class URI extends Object implements Comparable<URI>, Serializable

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:

  1. 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 `%'.
  2. 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:

These definitions reference the following sets of characters:

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
intcompareTo(URI uri)
Compare the URI with another URI.
static URIcreate(String str)
Create an URI from the given string
booleanequals(Object obj)

Compares the URI with the given object for equality.

StringgetAuthority()
Returns the decoded authority part of this URI
StringgetFragment()
Returns the fragment of the URI
StringgetHost()
Returns the hostname of the URI
StringgetPath()
Returns the path of the URI
intgetPort()
Returns the port number of the URI
StringgetQuery()
Returns the query of the URI
StringgetRawAuthority()
Returns the raw authority part of this URI
StringgetRawFragment()
Return the raw fragment part of this URI
StringgetRawPath()
Returns the raw path part of this URI
StringgetRawQuery()
Returns the raw query part of this URI
StringgetRawSchemeSpecificPart()
Returns the raw scheme specific part of this URI.
StringgetRawUserInfo()
Returns the raw user info part of this URI
StringgetScheme()
Returns the scheme of the URI
StringgetSchemeSpecificPart()
Returns the decoded scheme specific part of this URI.
StringgetUserInfo()
Returns the decoded user info part of this URI
inthashCode()
Computes the hashcode of the URI
booleanisAbsolute()
Tells whether this URI is absolute or not
booleanisOpaque()
Tell whether this URI is opaque or not
URInormalize()

Returns a normalized version of the URI.

URIparseServerAuthority()
Attempts to parse this URI's authority component, if defined, into user-information, host, and port components.
URIrelativize(URI uri)

Relativizes the given URI against this URI.

URIresolve(URI uri)
Resolves the given URI against this URI
URIresolve(String str)
Resolves the given URI string against this URI
StringtoASCIIString()
Returns the URI as US-ASCII string.
StringtoString()
Returns the URI as a String.
URLtoURL()
Creates an URL from an URI

Constructor Detail

URI

public URI(String str)
Creates an URI from the given string

Parameters: str The string to create the URI from

Throws: URISyntaxException If the given string violates RFC 2396 NullPointerException If str is null

URI

public URI(String scheme, String userInfo, String host, int port, String path, String query, String fragment)
Create an URI from the given components

Parameters: scheme The scheme name userInfo The username and authorization info host The hostname port The port number path The path query The query fragment The fragment

Throws: URISyntaxException If the given string violates RFC 2396

URI

public URI(String scheme, String authority, String path, String query, String fragment)
Create an URI from the given components

Parameters: scheme The scheme name authority The authority path The apth query The query fragment The fragment

Throws: URISyntaxException If the given string violates RFC 2396

URI

public URI(String scheme, String host, String path, String fragment)
Create an URI from the given components

Parameters: scheme The scheme name host The hostname path The path fragment The fragment

Throws: URISyntaxException If the given string violates RFC 2396

URI

public URI(String scheme, String ssp, String fragment)
Create an URI from the given components

Parameters: scheme The scheme name ssp The scheme specific part fragment The fragment

Throws: URISyntaxException If the given string violates RFC 2396

Method Detail

compareTo

public int compareTo(URI uri)
Compare the URI with another URI. Undefined components are taken to be less than any other component. The following criteria are observed:

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

public static URI create(String str)
Create an URI from the given string

Parameters: str The string to create the URI from

Throws: IllegalArgumentException If the given string violates RFC 2396 NullPointerException If str is null

equals

public boolean equals(Object obj)

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:

Parameters: obj the obj to compare the URI with.

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

getAuthority

public String getAuthority()
Returns the decoded authority part of this URI

getFragment

public String getFragment()
Returns the fragment of the URI

getHost

public String getHost()
Returns the hostname of the URI

getPath

public String getPath()
Returns the path of the URI

getPort

public int getPort()
Returns the port number of the URI

getQuery

public String getQuery()
Returns the query of the URI

getRawAuthority

public String getRawAuthority()
Returns the raw authority part of this URI

getRawFragment

public String getRawFragment()
Return the raw fragment part of this URI

getRawPath

public String getRawPath()
Returns the raw path part of this URI

getRawQuery

public String getRawQuery()
Returns the raw query part of this URI

getRawSchemeSpecificPart

public String getRawSchemeSpecificPart()
Returns the raw scheme specific part of this URI. The scheme-specific part is never undefined, though it may be empty

getRawUserInfo

public String getRawUserInfo()
Returns the raw user info part of this URI

getScheme

public String getScheme()
Returns the scheme of the URI

getSchemeSpecificPart

public String getSchemeSpecificPart()
Returns the decoded scheme specific part of this URI.

getUserInfo

public String getUserInfo()
Returns the decoded user info part of this URI

hashCode

public int hashCode()
Computes the hashcode of the URI

isAbsolute

public boolean isAbsolute()
Tells whether this URI is absolute or not

isOpaque

public boolean isOpaque()
Tell whether this URI is opaque or not

normalize

public URI normalize()

Returns a normalized version of the URI. If the URI is opaque, or its path is already in normal form, then this URI is simply returned. Otherwise, the following transformation of the path element takes place:

  1. All `.' segments are removed.
  2. Each `..' segment which can be paired with a prior non-`..' segment is removed along with the preceding segment.
  3. A `.' segment is added to the front if the first segment contains a colon (`:'). This is a deviation from the RFC, which prevents confusion between the path and the scheme.

The resulting URI will be free of `.' and `..' segments, barring those that were prepended or which couldn't be paired, respectively.

Returns: the normalized URI.

parseServerAuthority

public URI parseServerAuthority()
Attempts to parse this URI's authority component, if defined, into user-information, host, and port components. The purpose of this method was to disambiguate between some authority sections, which form invalid server-based authories, but valid registry based authorities. In the updated RFC 3986, the authority section is defined differently, with registry-based authorities part of the host section. Thus, this method is now simply an explicit way of parsing any authority section.

Returns: the URI, with the authority section parsed into user information, host and port components.

Throws: URISyntaxException if the given string violates RFC 2396

relativize

public URI relativize(URI uri)

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

Parameters: uri the URI to relativize agsint this URI

Returns: the resulting URI

Throws: NullPointerException if the uri is null

resolve

public URI resolve(URI uri)
Resolves the given URI against this URI

Parameters: uri The URI to resolve against this URI

Returns: The resulting URI, or null when it couldn't be resolved for some reason.

Throws: NullPointerException if uri is null

resolve

public URI resolve(String str)
Resolves the given URI string against this URI

Parameters: str The URI as string to resolve against this URI

Returns: The resulting URI

Throws: IllegalArgumentException If the given URI string violates RFC 2396 NullPointerException If uri is null

toASCIIString

public String toASCIIString()
Returns the URI as US-ASCII string. This is the same as the result from toString() for URIs that don't contain any non-US-ASCII characters. Otherwise, the non-US-ASCII characters are replaced by their percent-encoded representations.

Returns: a string representation of the URI, containing only US-ASCII characters.

toString

public String toString()
Returns the URI as a String. If the URI was created using a constructor, then this will be the same as the original input string.

Returns: a string representation of the URI.

toURL

public URL toURL()
Creates an URL from an URI

Throws: MalformedURLException If a protocol handler for the URL could not be found, or if some other error occurred while constructing the URL IllegalArgumentException If the URI is not absolute