Android APIs
public abstract class

Uri

extends Object
implements Parcelable Comparable<T>
java.lang.Object
   ↳ android.net.Uri

Class Overview

Immutable URI reference. A URI reference includes a URI and a fragment, the component of the URI following a '#'. Builds and parses URI references which conform to RFC 2396.

In the interest of performance, this class performs little to no validation. Behavior is undefined for invalid input. This class is very forgiving--in the face of invalid input, it will return garbage rather than throw an exception unless otherwise specified.

Summary

Nested Classes
class Uri.Builder Helper class for building or manipulating URI references. 
[Expand]
Inherited Constants
From interface android.os.Parcelable
Fields
public static final Creator<Uri> CREATOR Reads Uris from Parcels.
public static final Uri EMPTY The empty URI, equivalent to "".
Public Methods
abstract Uri.Builder buildUpon()
Constructs a new builder, copying the attributes from this Uri.
int compareTo(Uri other)
Compares the string representation of this Uri with that of another.
static String decode(String s)
Decodes '%'-escaped octets in the given string using the UTF-8 scheme.
static String encode(String s, String allow)
Encodes characters in the given string as '%'-escaped octets using the UTF-8 scheme.
static String encode(String s)
Encodes characters in the given string as '%'-escaped octets using the UTF-8 scheme.
boolean equals(Object o)
Compares this Uri to another object for equality.
static Uri fromFile(File file)
Creates a Uri from a file.
static Uri fromParts(String scheme, String ssp, String fragment)
Creates an opaque Uri from the given components.
abstract String getAuthority()
Gets the decoded authority part of this URI.
boolean getBooleanQueryParameter(String key, boolean defaultValue)
Searches the query string for the first value with the given key and interprets it as a boolean value.
abstract String getEncodedAuthority()
Gets the encoded authority part of this URI.
abstract String getEncodedFragment()
Gets the encoded fragment part of this URI, everything after the '#'.
abstract String getEncodedPath()
Gets the encoded path.
abstract String getEncodedQuery()
Gets the encoded query component from this URI.
abstract String getEncodedSchemeSpecificPart()
Gets the scheme-specific part of this URI, i.e.
abstract String getEncodedUserInfo()
Gets the encoded user information from the authority.
abstract String getFragment()
Gets the decoded fragment part of this URI, everything after the '#'.
abstract String getHost()
Gets the encoded host from the authority for this URI.
abstract String getLastPathSegment()
Gets the decoded last segment in the path.
abstract String getPath()
Gets the decoded path.
abstract List<String> getPathSegments()
Gets the decoded path segments.
abstract int getPort()
Gets the port from the authority for this URI.
abstract String getQuery()
Gets the decoded query component from this URI.
String getQueryParameter(String key)
Searches the query string for the first value with the given key.
Set<String> getQueryParameterNames()
Returns a set of the unique names of all query parameters.
List<String> getQueryParameters(String key)
Searches the query string for parameter values with the given key.
abstract String getScheme()
Gets the scheme of this URI.
abstract String getSchemeSpecificPart()
Gets the scheme-specific part of this URI, i.e.
abstract String getUserInfo()
Gets the decoded user information from the authority.
int hashCode()
Hashes the encoded string represention of this Uri consistently with equals(Object).
boolean isAbsolute()
Returns true if this URI is absolute, i.e.
abstract boolean isHierarchical()
Returns true if this URI is hierarchical like "http://google.com".
boolean isOpaque()
Returns true if this URI is opaque like "mailto:nobody@google.com".
abstract boolean isRelative()
Returns true if this URI is relative, i.e.
Uri normalizeScheme()
Return an equivalent URI with a lowercase scheme component.
static Uri parse(String uriString)
Creates a Uri which parses the given encoded URI string.
abstract String toString()
Returns the encoded string representation of this URI.
static Uri withAppendedPath(Uri baseUri, String pathSegment)
Creates a new Uri by appending an already-encoded path segment to a base Uri.
static void writeToParcel(Parcel out, Uri uri)
Writes a Uri to a Parcel.
[Expand]
Inherited Methods
From class java.lang.Object
From interface android.os.Parcelable
From interface java.lang.Comparable

Fields

public static final Creator<Uri> CREATOR

Added in API level 1

Reads Uris from Parcels.

public static final Uri EMPTY

Added in API level 1

The empty URI, equivalent to "".

Public Methods

public abstract Uri.Builder buildUpon ()

Added in API level 1

Constructs a new builder, copying the attributes from this Uri.

public int compareTo (Uri other)

Added in API level 1

Compares the string representation of this Uri with that of another.

public static String decode (String s)

Added in API level 1

Decodes '%'-escaped octets in the given string using the UTF-8 scheme. Replaces invalid octets with the unicode replacement character ("\\uFFFD").

Parameters
s encoded string to decode
Returns
  • the given string with escaped octets decoded, or null if s is null

public static String encode (String s, String allow)

Added in API level 1

Encodes characters in the given string as '%'-escaped octets using the UTF-8 scheme. Leaves letters ("A-Z", "a-z"), numbers ("0-9"), and unreserved characters ("_-!.~'()*") intact. Encodes all other characters with the exception of those specified in the allow argument.

Parameters
s string to encode
allow set of additional characters to allow in the encoded form, null if no characters should be skipped
Returns
  • an encoded version of s suitable for use as a URI component, or null if s is null

public static String encode (String s)

Added in API level 1

Encodes characters in the given string as '%'-escaped octets using the UTF-8 scheme. Leaves letters ("A-Z", "a-z"), numbers ("0-9"), and unreserved characters ("_-!.~'()*") intact. Encodes all other characters.

Parameters
s string to encode
Returns
  • an encoded version of s suitable for use as a URI component, or null if s is null

public boolean equals (Object o)

Added in API level 1

Compares this Uri to another object for equality. Returns true if the encoded string representations of this Uri and the given Uri are equal. Case counts. Paths are not normalized. If one Uri specifies a default port explicitly and the other leaves it implicit, they will not be considered equal.

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

public static Uri fromFile (File file)

Added in API level 1

Creates a Uri from a file. The URI has the form "file://". Encodes path characters with the exception of '/'.

Example: "file:///tmp/android.txt"

Returns
  • a Uri for the given file
Throws
NullPointerException if file is null

public static Uri fromParts (String scheme, String ssp, String fragment)

Added in API level 1

Creates an opaque Uri from the given components. Encodes the ssp which means this method cannot be used to create hierarchical URIs.

Parameters
scheme of the URI
ssp scheme-specific-part, everything between the scheme separator (':') and the fragment separator ('#'), which will get encoded
fragment fragment, everything after the '#', null if undefined, will get encoded
Returns
  • Uri composed of the given scheme, ssp, and fragment
Throws
NullPointerException if scheme or ssp is null

public abstract String getAuthority ()

Added in API level 1

Gets the decoded authority part of this URI. For server addresses, the authority is structured as follows: [ userinfo '@' ] host [ ':' port ]

Examples: "google.com", "bob@google.com:80"

Returns
  • the authority for this URI or null if not present

public boolean getBooleanQueryParameter (String key, boolean defaultValue)

Added in API level 11

Searches the query string for the first value with the given key and interprets it as a boolean value. "false" and "0" are interpreted as false, everything else is interpreted as true.

Parameters
key which will be decoded
defaultValue the default value to return if there is no query parameter for key
Returns
  • the boolean interpretation of the query parameter key

public abstract String getEncodedAuthority ()

Added in API level 1

Gets the encoded authority part of this URI. For server addresses, the authority is structured as follows: [ userinfo '@' ] host [ ':' port ]

Examples: "google.com", "bob@google.com:80"

Returns
  • the authority for this URI or null if not present

public abstract String getEncodedFragment ()

Added in API level 1

Gets the encoded fragment part of this URI, everything after the '#'.

Returns
  • the encoded fragment or null if there isn't one

public abstract String getEncodedPath ()

Added in API level 1

Gets the encoded path.

Returns
  • the encoded path, or null if this is not a hierarchical URI (like "mailto:nobody@google.com") or the URI is invalid

public abstract String getEncodedQuery ()

Added in API level 1

Gets the encoded query component from this URI. The query comes after the query separator ('?') and before the fragment separator ('#'). This method would return "q=android" for "http://www.google.com/search?q=android".

Returns
  • the encoded query or null if there isn't one

public abstract String getEncodedSchemeSpecificPart ()

Added in API level 1

Gets the scheme-specific part of this URI, i.e. everything between the scheme separator ':' and the fragment separator '#'. If this is a relative URI, this method returns the entire URI. Leaves escaped octets intact.

Example: "//www.google.com/search?q=android"

Returns
  • the decoded scheme-specific-part

public abstract String getEncodedUserInfo ()

Added in API level 1

Gets the encoded user information from the authority. For example, if the authority is "nobody@google.com", this method will return "nobody".

Returns
  • the user info for this URI or null if not present

public abstract String getFragment ()

Added in API level 1

Gets the decoded fragment part of this URI, everything after the '#'.

Returns
  • the decoded fragment or null if there isn't one

public abstract String getHost ()

Added in API level 1

Gets the encoded host from the authority for this URI. For example, if the authority is "bob@google.com", this method will return "google.com".

Returns
  • the host for this URI or null if not present

public abstract String getLastPathSegment ()

Added in API level 1

Gets the decoded last segment in the path.

Returns
  • the decoded last segment or null if the path is empty

public abstract String getPath ()

Added in API level 1

Gets the decoded path.

Returns
  • the decoded path, or null if this is not a hierarchical URI (like "mailto:nobody@google.com") or the URI is invalid

public abstract List<String> getPathSegments ()

Added in API level 1

Gets the decoded path segments.

Returns
  • decoded path segments, each without a leading or trailing '/'

public abstract int getPort ()

Added in API level 1

Gets the port from the authority for this URI. For example, if the authority is "google.com:80", this method will return 80.

Returns
  • the port for this URI or -1 if invalid or not present

public abstract String getQuery ()

Added in API level 1

Gets the decoded query component from this URI. The query comes after the query separator ('?') and before the fragment separator ('#'). This method would return "q=android" for "http://www.google.com/search?q=android".

Returns
  • the decoded query or null if there isn't one

public String getQueryParameter (String key)

Added in API level 1

Searches the query string for the first value with the given key.

Warning: Prior to Ice Cream Sandwich, this decoded the '+' character as '+' rather than ' '.

Parameters
key which will be encoded
Returns
  • the decoded value or null if no parameter is found
Throws
UnsupportedOperationException if this isn't a hierarchical URI
NullPointerException if key is null

public Set<String> getQueryParameterNames ()

Added in API level 11

Returns a set of the unique names of all query parameters. Iterating over the set will return the names in order of their first occurrence.

Returns
  • a set of decoded names
Throws
UnsupportedOperationException if this isn't a hierarchical URI

public List<String> getQueryParameters (String key)

Added in API level 1

Searches the query string for parameter values with the given key.

Parameters
key which will be encoded
Returns
  • a list of decoded values
Throws
UnsupportedOperationException if this isn't a hierarchical URI
NullPointerException if key is null

public abstract String getScheme ()

Added in API level 1

Gets the scheme of this URI. Example: "http"

Returns
  • the scheme or null if this is a relative URI

public abstract String getSchemeSpecificPart ()

Added in API level 1

Gets the scheme-specific part of this URI, i.e. everything between the scheme separator ':' and the fragment separator '#'. If this is a relative URI, this method returns the entire URI. Decodes escaped octets.

Example: "//www.google.com/search?q=android"

Returns
  • the decoded scheme-specific-part

public abstract String getUserInfo ()

Added in API level 1

Gets the decoded user information from the authority. For example, if the authority is "nobody@google.com", this method will return "nobody".

Returns
  • the user info for this URI or null if not present

public int hashCode ()

Added in API level 1

Hashes the encoded string represention of this Uri consistently with equals(Object).

Returns
  • this object's hash code.

public boolean isAbsolute ()

Added in API level 1

Returns true if this URI is absolute, i.e. if it contains an explicit scheme.

Returns
  • true if this URI is absolute, false if it's relative

public abstract boolean isHierarchical ()

Added in API level 1

Returns true if this URI is hierarchical like "http://google.com". Absolute URIs are hierarchical if the scheme-specific part starts with a '/'. Relative URIs are always hierarchical.

public boolean isOpaque ()

Added in API level 1

Returns true if this URI is opaque like "mailto:nobody@google.com". The scheme-specific part of an opaque URI cannot start with a '/'.

public abstract boolean isRelative ()

Added in API level 1

Returns true if this URI is relative, i.e. if it doesn't contain an explicit scheme.

Returns
  • true if this URI is relative, false if it's absolute

public Uri normalizeScheme ()

Added in API level 16

Return an equivalent URI with a lowercase scheme component. This aligns the Uri with Android best practices for intent filtering.

For example, "HTTP://www.android.com" becomes "http://www.android.com"

All URIs received from outside Android (such as user input, or external sources like Bluetooth, NFC, or the Internet) should be normalized before they are used to create an Intent.

This method does not validate bad URI's, or 'fix' poorly formatted URI's - so do not use it for input validation. A Uri will always be returned, even if the Uri is badly formatted to begin with and a scheme component cannot be found.

Returns
  • normalized Uri (never null)

public static Uri parse (String uriString)

Added in API level 1

Creates a Uri which parses the given encoded URI string.

Parameters
uriString an RFC 2396-compliant, encoded URI
Returns
  • Uri for this given uri string
Throws
NullPointerException if uriString is null

public abstract String toString ()

Added in API level 1

Returns the encoded string representation of this URI. Example: "http://google.com/"

Returns
  • a printable representation of this object.

public static Uri withAppendedPath (Uri baseUri, String pathSegment)

Added in API level 1

Creates a new Uri by appending an already-encoded path segment to a base Uri.

Parameters
baseUri Uri to append path segment to
pathSegment encoded path segment to append
Returns
  • a new Uri based on baseUri with the given segment appended to the path
Throws
NullPointerException if baseUri is null

public static void writeToParcel (Parcel out, Uri uri)

Added in API level 1

Writes a Uri to a Parcel.

Parameters
out parcel to write to
uri to write, can be null