Skip to content

Most visited

Recently visited

navigation
Added in API level 1

URI

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

java.lang.Object
   ↳ java.net.URI


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 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.

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.

Inherited methods

From class java.lang.Object
From interface java.lang.Comparable

Public constructors

URI

Added in API level 1
URI (String spec)

Creates a new URI instance by parsing spec.

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

URI

Added in API level 1
URI (String scheme, 
                String schemeSpecificPart, 
                String fragment)

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

Parameters
scheme String: the URI scheme, or null for a non-absolute URI.
schemeSpecificPart String
fragment String
Throws
URISyntaxException

URI

Added in API level 1
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.

Parameters
scheme String: the URI scheme, or null for a non-absolute URI.
userInfo String
host String
port int
path String
query String
fragment String
Throws
URISyntaxException

URI

Added in API level 1
URI (String scheme, 
                String host, 
                String path, 
                String fragment)

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

Parameters
scheme String: the URI scheme, or null for a non-absolute URI.
host String
path String
fragment String
Throws
URISyntaxException

URI

Added in API level 1
URI (String scheme, 
                String authority, 
                String path, 
                String query, 
                String fragment)

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

Parameters
scheme String: the URI scheme, or null for a non-absolute URI.
authority String
path String
query String
fragment String
Throws
URISyntaxException

Public methods

compareTo

Added in API level 1
int compareTo (URI uri)

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 URI: the URI this instance has to compare with.
Returns
int the value representing the order of the two instances.

create

Added in API level 1
URI create (String uri)

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.

Parameters
uri String
Returns
URI

equals

Added in API level 1
boolean equals (Object o)

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 Object: the object to compare this instance with.
Returns
boolean true if the specified object is equal to this Object; false otherwise.

getAuthority

Added in API level 1
String getAuthority ()

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

Returns
String

getFragment

Added in API level 1
String getFragment ()

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

Returns
String

getHost

Added in API level 1
String getHost ()

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

Returns
String

getPath

Added in API level 1
String getPath ()

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

Returns
String

getPort

Added in API level 1
int getPort ()

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

Returns
int

getQuery

Added in API level 1
String getQuery ()

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

Returns
String

getRawAuthority

Added in API level 1
String getRawAuthority ()

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

Returns
String

getRawFragment

Added in API level 1
String getRawFragment ()

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

Returns
String

getRawPath

Added in API level 1
String getRawPath ()

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

Returns
String

getRawQuery

Added in API level 1
String getRawQuery ()

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

Returns
String

getRawSchemeSpecificPart

Added in API level 1
String getRawSchemeSpecificPart ()

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

Returns
String

getRawUserInfo

Added in API level 1
String getRawUserInfo ()

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

Returns
String

getScheme

Added in API level 1
String getScheme ()

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

Returns
String

getSchemeSpecificPart

Added in API level 1
String getSchemeSpecificPart ()

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

Returns
String

getUserInfo

Added in API level 1
String getUserInfo ()

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

Returns
String

hashCode

Added in API level 1
int hashCode ()

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
int this object's hash code.

isAbsolute

Added in API level 1
boolean isAbsolute ()

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

Returns
boolean

isOpaque

Added in API level 1
boolean isOpaque ()

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.

Returns
boolean

normalize

Added in API level 1
URI normalize ()

Normalizes the path part of this URI.

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

parseServerAuthority

Added in API level 1
URI parseServerAuthority ()

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
URI 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.

relativize

Added in API level 1
URI relativize (URI relative)

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

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

resolve

Added in API level 1
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.

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

resolve

Added in API level 1
URI resolve (URI relative)

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

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

toASCIIString

Added in API level 1
String toASCIIString ()

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

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

toString

Added in API level 1
String toString ()

Returns the encoded URI.

Returns
String a printable representation of this object.

toURL

Added in API level 1
URL toURL ()

Converts this URI instance to a URL.

Returns
URL 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.
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.