public final class

URI

extends Object
implements Serializable Comparable<T>
java.lang.Object
   ↳ java.net.URI

Class Overview

A Uniform Resource Identifier that identifies an abstract or physical resource, as specified by RFC 2396.

Parts of a URI

A URI is composed of many parts. This class can both parse URI strings into parts and compose URI strings from parts. For example, consider the parts of this URI: http://username:password@host:8080/directory/file?query#fragment
Component Example value Also known as
Scheme http protocol
Scheme-specific part//username:password@host:8080/directory/file?query#fragment
Authority username:password@host:8080
User Info username:password
Host host
Port 8080
Path /directory/file
Query query
Fragment fragment ref

Absolute vs. Relative URIs

URIs are either absolute or relative.
  • Absolute: http://android.com/robots.txt
  • Relative: robots.txt

Absolute URIs always have a scheme. If its scheme is supported by URL, you can use toURL() to convert an absolute URI to a URL.

Relative URIs do not have a scheme and cannot be converted to URLs. If you have the absolute URI that a relative URI is relative to, you can use resolve(String) to compute the referenced absolute URI. Symmetrically, you can use relativize(URI) to compute the relative URI from one URI to another. 

   URI absolute = new URI("http://android.com/");
   URI relative = new URI("robots.txt");
   URI resolved = new URI("http://android.com/robots.txt");
   // print "http://android.com/robots.txt"
   System.out.println(absolute.resolve(relative));
   // print "robots.txt"
   System.out.println(absolute.relativize(resolved));

Opaque vs. Hierarchical URIs

Absolute URIs are either opaque or hierarchical. Relative URIs are always hierarchical.
  • Hierarchical: http://android.com/robots.txt
  • Opaque: mailto:robots@example.com

Opaque URIs have both a scheme and a scheme-specific part that does not begin with the slash character: /. The contents of the scheme-specific part of an opaque URI is not parsed so an opaque URI never has an authority, user info, host, port, path or query. An opaque URIs may have a fragment, however. A typical opaque URI is mailto:robots@example.com.

Component Example value
Scheme mailto
Scheme-specific partrobots@example.com
Fragment

Hierarchical URIs may have values for any URL component. They always have a non-null path, though that path may be the empty string.

Encoding and Decoding URI Components

Each component of a URI permits a limited set of legal characters. Other characters must first be encoded before they can be embedded in a URI. To recover the original characters from a URI, they may be decoded. Contrary to what you might expect, this class uses the term raw to refer to encoded strings. The non-raw accessors return decoded strings. For example, consider how this URI is decoded: http://user:pa55w%3Frd@host:80/doc%7Csearch?q=green%20robots#over%206%22
Component Legal Characters Other Constraints Raw Value Value
Scheme 0-9, a-z, A-Z, +-. First character must be in a-z, A-Z http
Scheme-specific part0-9, a-z, A-Z, _-!.~'()*,;:$&+=?/[]@Non-ASCII characters okay //user:pa55w%3Frd@host:80/doc%7Csearch?q=green%20robots//user:pa55w?rd@host:80/doc|search?q=green robots
Authority 0-9, a-z, A-Z, _-!.~'()*,;:$&+=@[] Non-ASCII characters okay user:pa55w%3Frd@host:80 user:pa55w?rd@host:80
User Info 0-9, a-z, A-Z, _-!.~'()*,;:$&+= Non-ASCII characters okay user:pa55w%3Frd user:pa55w?rd
Host 0-9, a-z, A-Z, -.[] Domain name, IPv4 address or [IPv6 address] host
Port 0-9 80
Path 0-9, a-z, A-Z, _-!.~'()*,;:$&+=/@ Non-ASCII characters okay /doc%7Csearch /doc|search
Query 0-9, a-z, A-Z, _-!.~'()*,;:$&+=?/[]@Non-ASCII characters okay q=green%20robots q=green robots
Fragment 0-9, a-z, A-Z, _-!.~'()*,;:$&+=?/[]@Non-ASCII characters okay over%206%22 over 6"
A URI's host, port and scheme are not eligible for encoding and must not contain illegal characters.

To encode a URI, invoke any of the multiple-parameter constructors of this class. These constructors accept your original strings and encode them into their raw form.

To decode a URI, invoke the single-string constructor, and then use the appropriate accessor methods to get the decoded components.

The URL class can be used to retrieve resources by their URI.

Summary

Public Constructors
URI(String spec)
Creates a new URI instance by parsing spec.
URI(String scheme, String schemeSpecificPart, String fragment)
Creates a new URI instance of the given unencoded component parts.
URI(String scheme, String userInfo, String host, int port, String path, String query, String fragment)
Creates a new URI instance of the given unencoded component parts.
URI(String scheme, String host, String path, String fragment)
Creates a new URI instance of the given unencoded component parts.
URI(String scheme, String authority, String path, String query, String fragment)
Creates a new URI instance of the given unencoded component parts.
Public Methods
int compareTo(URI uri)
Compares this URI with the given argument uri.
static URI create(String uri)
Returns the URI formed by parsing uri.
boolean equals(Object o)
Compares this instance with the specified object and indicates if they are equal.
String getAuthority()
Returns the decoded authority part of this URI, or null if this URI has no authority.
String getFragment()
Returns the decoded fragment of this URI, or null if this URI has no fragment.
String getHost()
Returns the host of this URI, or null if this URI has no host.
String getPath()
Returns the decoded path of this URI, or null if this URI has no path.
int getPort()
Returns the port number of this URI, or -1 if this URI has no explicit port.
String getQuery()
Returns the decoded query of this URI, or null if this URI has no query.
String getRawAuthority()
Returns the encoded authority of this URI, or null if this URI has no authority.
String getRawFragment()
Gets the encoded fragment of this URI, or null if this URI has no fragment.
String getRawPath()
Returns the encoded path of this URI, or null if this URI has no path.
String getRawQuery()
Returns the encoded query of this URI, or null if this URI has no query.
String getRawSchemeSpecificPart()
Returns the encoded scheme-specific part of this URI, or null if this URI has no scheme-specific part.
String getRawUserInfo()
Returns the encoded user info of this URI, or null if this URI has no user info.
String getScheme()
Returns the scheme of this URI, or null if this URI has no scheme.
String getSchemeSpecificPart()
Returns the decoded scheme-specific part of this URI, or null if this URI has no scheme-specific part.
String getUserInfo()
Returns the decoded user info of this URI, or null if this URI has no user info.
int hashCode()
Returns an integer hash code for this object.
boolean isAbsolute()
Returns true if this URI is absolute, which means that a scheme is defined.
boolean isOpaque()
Returns true if this URI is opaque.
URI normalize()
Normalizes the path part of this URI.
URI parseServerAuthority()
Tries to parse the authority component of this URI to divide it into the host, port, and user-info.
URI relativize(URI relative)
Makes the given URI relative to a relative URI against the URI represented by this instance.
URI resolve(String relative)
Creates a new URI instance by parsing the given string relative and resolves the created URI against the URI represented by this instance.
URI resolve(URI relative)
Resolves the given URI relative against the URI represented by this instance.
String toASCIIString()
Returns the textual string representation of this URI instance using the US-ASCII encoding.
String toString()
Returns the encoded URI.
URL toURL()
Converts this URI instance to a URL.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.lang.Comparable

Public Constructors

public URI (String spec)

Since: API Level 1

Creates a new URI instance by parsing spec.

Parameters
spec a URI whose illegal characters have all been encoded.
Throws
URISyntaxException

public URI (String scheme, String schemeSpecificPart, String fragment)

Since: API Level 1

Creates a new URI instance of the given unencoded component parts.

Parameters
scheme the URI scheme, or null for a non-absolute URI.
Throws
URISyntaxException

public URI (String scheme, String userInfo, String host, int port, String path, String query, String fragment)

Since: API Level 1

Creates a new URI instance of the given unencoded component parts.

Parameters
scheme the URI scheme, or null for a non-absolute URI.
Throws
URISyntaxException

public URI (String scheme, String host, String path, String fragment)

Since: API Level 1

Creates a new URI instance of the given unencoded component parts.

Parameters
scheme the URI scheme, or null for a non-absolute URI.
Throws
URISyntaxException

public URI (String scheme, String authority, String path, String query, String fragment)

Since: API Level 1

Creates a new URI instance of the given unencoded component parts.

Parameters
scheme the URI scheme, or null for a non-absolute URI.
Throws
URISyntaxException

Public Methods

public int compareTo (URI uri)

Since: API Level 1

Compares this URI with the given argument uri. This method will return a negative value if this URI instance is less than the given argument and a positive value if this URI instance is greater than the given argument. The return value 0 indicates that the two instances represent the same URI. To define the order the single parts of the URI are compared with each other. String components will be ordered in the natural case-sensitive way. A hierarchical URI is less than an opaque URI and if one part is null the URI with the undefined part is less than the other one.

Parameters
uri the URI this instance has to compare with.
Returns
  • the value representing the order of the two instances.

public static URI create (String uri)

Since: API Level 1

Returns the URI formed by parsing uri. This method behaves identically to the string constructor but throws a different exception on failure. The constructor fails with a checked URISyntaxException; this method fails with an unchecked IllegalArgumentException.

public boolean equals (Object o)

Since: API Level 1

Compares this instance with the specified object and indicates if they are equal. In order to be equal, o must represent the same object as this instance using a class-specific comparison. The general contract is that this comparison should be reflexive, symmetric, and transitive. Also, no object reference other than null is equal to null.

The default implementation returns true only if this == o. See Writing a correct equals method if you intend implementing your own equals method.

The general contract for the equals and hashCode() methods is that if equals returns true for any two objects, then hashCode() must return the same value for these objects. This means that subclasses of Object usually override either both methods or neither of them.

Parameters
o the object to compare this instance with.
Returns
  • true if the specified object is equal to this Object; false otherwise.

public String getAuthority ()

Since: API Level 1

Returns the decoded authority part of this URI, or null if this URI has no authority.

public String getFragment ()

Since: API Level 1

Returns the decoded fragment of this URI, or null if this URI has no fragment.

public String getHost ()

Since: API Level 1

Returns the host of this URI, or null if this URI has no host.

public String getPath ()

Since: API Level 1

Returns the decoded path of this URI, or null if this URI has no path.

public int getPort ()

Since: API Level 1

Returns the port number of this URI, or -1 if this URI has no explicit port.

public String getQuery ()

Since: API Level 1

Returns the decoded query of this URI, or null if this URI has no query.

public String getRawAuthority ()

Since: API Level 1

Returns the encoded authority of this URI, or null if this URI has no authority.

public String getRawFragment ()

Since: API Level 1

Gets the encoded fragment of this URI, or null if this URI has no fragment.

public String getRawPath ()

Since: API Level 1

Returns the encoded path of this URI, or null if this URI has no path.

public String getRawQuery ()

Since: API Level 1

Returns the encoded query of this URI, or null if this URI has no query.

public String getRawSchemeSpecificPart ()

Since: API Level 1

Returns the encoded scheme-specific part of this URI, or null if this URI has no scheme-specific part.

public String getRawUserInfo ()

Since: API Level 1

Returns the encoded user info of this URI, or null if this URI has no user info.

public String getScheme ()

Since: API Level 1

Returns the scheme of this URI, or null if this URI has no scheme. This is also known as the protocol.

public String getSchemeSpecificPart ()

Since: API Level 1

Returns the decoded scheme-specific part of this URI, or null if this URI has no scheme-specific part.

public String getUserInfo ()

Since: API Level 1

Returns the decoded user info of this URI, or null if this URI has no user info.

public int hashCode ()

Since: API Level 1

Returns an integer hash code for this object. By contract, any two objects for which equals(Object) returns true must return the same hash code value. This means that subclasses of Object usually override both methods or neither method.

Note that hash values must not change over time unless information used in equals comparisons also changes.

See Writing a correct hashCode method if you intend implementing your own hashCode method.

Returns
  • this object's hash code.

public boolean isAbsolute ()

Since: API Level 1

Returns true if this URI is absolute, which means that a scheme is defined.

public boolean isOpaque ()

Since: API Level 1

Returns true if this URI is opaque. Opaque URIs are absolute and have a scheme-specific part that does not start with a slash character. All parts except scheme, scheme-specific and fragment are undefined.

public URI normalize ()

Since: API Level 1

Normalizes the path part of this URI.

Returns
  • an URI object which represents this instance with a normalized path.

public URI parseServerAuthority ()

Since: API Level 1

Tries to parse the authority component of this URI to divide it into the host, port, and user-info. If this URI is already determined as a ServerAuthority this instance will be returned without changes.

Returns
  • this instance with the components of the parsed server authority.
Throws
URISyntaxException if the authority part could not be parsed as a server-based authority.

public URI relativize (URI relative)

Since: API Level 1

Makes the given URI relative to a relative URI against the URI represented by this instance.

Parameters
relative the URI which has to be relativized against this URI.
Returns
  • the relative URI.

public URI resolve (String relative)

Since: API Level 1

Creates a new URI instance by parsing the given string relative and resolves the created URI against the URI represented by this instance.

Parameters
relative the given string to create the new URI instance which has to be resolved later on.
Returns
  • the created and resolved URI.

public URI resolve (URI relative)

Since: API Level 1

Resolves the given URI relative against the URI represented by this instance.

Parameters
relative the URI which has to be resolved against this URI.
Returns
  • the resolved URI.

public String toASCIIString ()

Since: API Level 1

Returns the textual string representation of this URI instance using the US-ASCII encoding.

Returns
  • the US-ASCII string representation of this URI.

public String toString ()

Since: API Level 1

Returns the encoded URI.

Returns
  • a printable representation of this object.

public URL toURL ()

Since: API Level 1

Converts this URI instance to a URL.

Returns
  • the created URL representing the same resource as this URI.
Throws
MalformedURLException if an error occurs while creating the URL or no protocol handler could be found.