net.rim.device.api.io
Class URI

java.lang.Object
  net.rim.device.api.io.URI

public class URI
extends Object

A class to represent and manipulate URI-references as defined in RFC3986. The terms "URI", "URI-reference", "relative-reference", "scheme", "authority", "path", "query", and "fragment" used in this class and associated documentation are used as defined in RFC3986. The reference-transformation algorithm used in this class is "strict" as per the usage in section 5.2.2. This class does not provide any mechanism for scheme- or protocol-based normalization. Instances of this class are immutable after creation.

This class also provides convenience methods to do IDNA-encoding of internationalized hostnames. If this functionality is desired independently of URI processing, please use the IDNA class instead.

Since:

BlackBerry API 5.0.0

Method Summary
static URI	create(String uri) Creates a new URI object from the given string.
static URI	create(String baseUri, String uriReference) Creates a new URI object from the given base URI and URI-reference.
static URI	create(URI baseUri, String uriReference) Creates a new URI object from the given base URI and URI-reference.
boolean	equals(Object other) Compares two URI-references for equality.
String	getAuthority() Get the authority component of the URI-reference.
static String	getFile(String path) Convenience method to extract the filename from the path component of a hierarchical URI-reference.
String	getFragment() Get the fragment component of the URI-reference.
String	getHost() Get the host sub-component of the URI-reference.
String	getPath() Get the path component of the URI-reference.
String	getPort() Get the port sub-component of the URI-reference.
String	getQuery() Get the query component of the URI-reference.
String	getScheme() Get the scheme component of the URI-reference.
String	getUserinfo() Get the userinfo sub-component of the URI-reference.
int	hashCode() Returns a hash code for this object.
boolean	isAbsolute() Tests if the URI-reference represented by this object is an absolute URI or a relative-reference.
String	toIDNAString() Get a string representation of the normalized URI-reference after having the IDNA algorithm applied as per RFC3490.
String	toIRIString() Get a string representation of the normalized URI-reference as per RFC3986 and RFC3987.
String	toString() Get a string representation of the normalized URI-reference as per RFC3986.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Detail

create

public static URI create(String uri)
                  throws IllegalArgumentException,
                         MalformedURIException

Creates a new URI object from the given string. This method will parse and normalize the string, and return a URI object created from the component parts of the string.

Parameters:

uri - The string to be parsed and normalized.

Returns:

A URI object. This will not be null.

Throws:

IllegalArgumentException - If uri is null.

MalformedURIException - If uri represents an invalid URI as per the syntax in RFC3986.

Since:

BlackBerry API 5.0.0

create

public static URI create(URI baseUri,
                         String uriReference)
                  throws NullPointerException,
                         IllegalArgumentException,
                         MalformedURIException

Creates a new URI object from the given base URI and URI-reference. This method will parse and normalize the URI-reference, then resolve it against the base URI, and return the resulting URI object. Note that if the uriReference parameter represents an absolute URI, then resolving it against baseUri will have no effect.

Parameters:

baseUri - The URI object that serves as the base URI.

uriReference - The URI-reference to be parsed and resolved.

Returns:

A URI object. This will not be null.

Throws:

NullPointerException - If baseUri is null.

IllegalArgumentException - If uriReference is null, or if the baseUri is not an absolute URI.

MalformedURIException - If uriReference represents an invalid URI-reference as per the syntax in RFC3986.

Since:

BlackBerry API 5.0.0

create

public static URI create(String baseUri,
                         String uriReference)
                  throws IllegalArgumentException,
                         MalformedURIException

Creates a new URI object from the given base URI and URI-reference. This method will parse and normalize the base URI, then parse and normalize the URI-reference, then resolve the URI-reference against the base URI, and return the resulting URI object. Note that if the uriReference parameter represents an absolute URI, then resolving it against baseUri will have no effect. However, since baseUri is parsed and normalized regardless, exceptions may be thrown even if uriReference represents a valid absolute URI. This is by design, so that the cases where uriReference is absolute or relative are handled consistently.

Parameters:

baseUri - The base URI to be parsed and normalized.

uriReference - The URI-reference to be parsed and resolved.

Returns:

A URI object. This will not be null.

Throws:

IllegalArgumentException - If either baseUri or uriReference is null, or if the baseUri does not represent an absolute URI.

MalformedURIException - If either baseUri or uriReference represent an invalid URI-reference as per the syntax in RFC3986.

Since:

BlackBerry API 5.0.0

getFile

public static String getFile(String path)

Convenience method to extract the filename from the path component of a hierarchical URI-reference. This method basically identifies the last forward-slash character (U+002F) in the path, and returns everything following, but not including, that character. If there is no forward-slash character, the entire path is returned. Note that filenames are not specified in RFC3986; this method is provided as a convenience method only as many users of this class may need to extract the filename component of a hierarchical path.

Parameters:

path - The path component from which the filename should be extracted.

Returns:

The filename as described above. This will not be null, although it may have a zero length.

Throws:

NullPointerException - If path is null.

Since:

BlackBerry API 5.0.0

isAbsolute

public boolean isAbsolute()

Tests if the URI-reference represented by this object is an absolute URI or a relative-reference.

Returns:

true if the URI-reference is an absolute URI (i.e. there is a scheme specified), and false otherwise.

Since:

BlackBerry API 5.0.0

getScheme

public String getScheme()

Get the scheme component of the URI-reference.

Returns:

A String containing the scheme component of the URI-reference represented by this URI object. This may be null if this URI object represents a relative-reference.

Since:

BlackBerry API 5.0.0

getAuthority

public String getAuthority()

Get the authority component of the URI-reference.

Returns:

A String containing the authority component of the URI-reference represented by this URI object. This may be null if there is no authority component. This may be zero-length if an empty authority component was specified (such as in "file:///a.file.ext").

Since:

BlackBerry API 5.0.0

getUserinfo

public String getUserinfo()

Get the userinfo sub-component of the URI-reference. The userinfo sub-component is the part of the authority component that precedes the '@' (U+0040) character, if there is one.

Returns:

A String containing the userinfo sub-component of the URI-reference represented by this URI object. This may be null if there is no userinfo sub-component. This may be zero-length if an empty userinfo sub-component was specified (such as in "scheme://@host/").

Since:

BlackBerry API 5.0.0

getHost

public String getHost()

Get the host sub-component of the URI-reference. The host sub-component is the part of the authority component that comes between the userinfo and port sub-components. As it is a required part of the the authority component, this will be null if and only if URI.getAuthority() also returns null. Note that the host sub-component may be an IP address, including strings in the IPvFuture production of the RFC3986 grammar. Also note that as part of the URI normalization process specified in RFC3986, the hostname will be in lowercased (except for characters in a percent-encoding).

Returns:

A String containing the host sub-component of the URI-reference represented by this URI object. This may be null if there is no authority component. This may be zero-length if an empty host sub-component was specified (such as in "file:///a.file.ext").

Since:

BlackBerry API 5.0.0

getPort

public String getPort()

Get the port sub-component of the URI-reference. The port sub-component is the part of the authority component that follows the ':' (U+003A) character following the host, if there is one. Note that the port sub-component may be removed during the URI normalization process if the port is the same as the default port of the scheme.

Returns:

A String containing the port sub-component of the URI-reference represented by this URI object. This may be null if there is no port sub-component. If not null, this will not be zero-length.

Since:

BlackBerry API 5.0.0

getPath

public String getPath()

Get the path component of the URI-reference. Note that some scheme-specific normalization may have been performed upon the path. For instance, for URI objects representing URIs with "http" and "https" schemes, a zero-length path will be changed to a single slash ("/") as they are defined to be equivalent.

Returns:

A String containing the path component of the URI-reference represented by this URI object. This will not be null, since the path component is a required component of a URI-reference.

Since:

BlackBerry API 5.0.0

getQuery

public String getQuery()

Get the query component of the URI-reference.

Returns:

A String containing the query component of the URI-reference represented by this URI object. This may be null if no query was specified.

Since:

BlackBerry API 5.0.0

getFragment

public String getFragment()

Get the fragment component of the URI-reference.

Returns:

A String containing the fragment component of the URI-reference represented by this URI object. This may be null if no fragment was specified.

Since:

BlackBerry API 5.0.0

hashCode

public int hashCode()

Returns a hash code for this object.

Overrides:

hashCode in class Object

Returns:

an integer hashcode as per the contract in hashCode.

See Also:

Object.equals(java.lang.Object), Hashtable

Since:

BlackBerry API 5.0.0

toString

public String toString()

Get a string representation of the normalized URI-reference as per RFC3986. In particular, this means that host names are NOT translated by the IDNA algorithm (RFC3490). Additionally, all non-ASCII characters will be represented by the percent-encodings of their UTF-8 octets as per RFC3986. In most cases you will really want to use toIDNAString or toIRIString.

Overrides:

toString in class Object

Returns:

a String that represents the normalized URI-reference. This will not be null.

Since:

BlackBerry API 5.0.0

toIDNAString

public String toIDNAString()
                    throws IDNAException

Get a string representation of the normalized URI-reference after having the IDNA algorithm applied as per RFC3490. Specifically, the host name will be transformed by the IDNA algorithm (or an IDNAException will be thrown on failure). Non-ASCII characters in parts of the URI other than the host component will be represented by the percent- encodings of their UTF-8 octets as per RFC3986. This string will be suitable for passing to legacy DNS resolvers and other protocol-resolution code.

Returns:

a String that represents the normalized URI-reference as per RFC3986 and RFC3490. This will not be null.

Throws:

IDNAException - If the host name could not be transformed as per RFC3490. See the toASCII method for details.

Since:

BlackBerry API 5.0.0

toIRIString

public String toIRIString()

Get a string representation of the normalized URI-reference as per RFC3986 and RFC3987. In particular, non-ASCII characters in the URI will be returned as-is. This string representation is the most suitable for display to the user, but is not appropriate for passing to lower-level protocols unless they are fully i18n compliant. Note that for URIs created with IDNA-encoded host names, this method will also decode the hostnames using the ToUnicode algorithm in RFC3490.

Returns:

a String that represents the normalized URI-reference as per RFC3986 and RFC3987. This will not be null.

Since:

BlackBerry API 5.0.0

equals

public boolean equals(Object other)

Compares two URI-references for equality. This method compares the two URI-references for equality using the comparison ladder described in RFC3986. This includes simple string comparison and syntax-normalized comparison (with case, percent-encoding, and path-segment normalizations). For some known schemes, scheme-based normalization is also performed; however, this does not happen for all schemes and cannot be relied upon. Protocol-based normalization is not supported.

Overrides:

equals in class Object

Parameters:

other - Either a String or a URI object to compare against this URI object.

Returns:

false under the following conditions: (1) this URI object represents a relative-reference; since it is not absolute, it cannot be compared for equality. (2) other is neither a String nor a URI object (this includes the case where other is null). (3) If other is a String and attempts to parse it fail. (4) If, after any parsing and normalization required of both this URI object and the provided URI-reference, the URI-references differ in one or more of their component parts. This method returns true if, after parsing and normalization, the URI-references have identical component parts.

See Also:

Boolean.hashCode(), Hashtable

Since:

BlackBerry API 5.0.0