Android - An Open Handset Alliance Project

android.net
public abstract class

android.net.Uri

java.lang.Object
	android.net.Uri	Parcelable Comparable

This class allows you to create, decode, parse, and examine immutable URI reference objects that conform to RFC 2396. The class also includes public utility methods for encoding and decoding Strings. All encoding is done in UTF-8, with special characters encoded in '%'-escaped hexadecimal values (all characters other than alphanumeric or '.' (dot), '-' (hyphen), '*' (star), and '_' (underscore) characters). Spaces are also substituted by '+'. To encode with charset other than UTF-8, see URLEncoder.

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.

Nested Classes

Uri.Builder Helper class for building or manipulating URI references.

Summary

Constants

			Value
Creator	CREATOR	Reads Uris from Parcels.
Uri	EMPTY	The empty URI, equivalent to "".

Public Methods

abstract		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 `other`.
	static	String	decode(String s)
			Decodes '%'-escaped octets in the given string using the UTF-8 scheme.
	static	String	encode(String s)
			Encodes characters in the given string as '%'-escaped octets 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, except those that are given in `allow`.
		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 component of this URI.
abstract		String	getEncodedAuthority()
			Gets the encoded authority component of this URI.
abstract		String	getEncodedFragment()
			Gets the encoded fragment part of this URI, everything after the '#'.
abstract		String	getEncodedPath()
			Gets the encoded path component of this URI.
abstract		String	getEncodedQuery()
			Gets the encoded query component of this URI.
abstract		String	getEncodedSchemeSpecificPart()
			Gets the encoded scheme-specific part of this URI.
abstract		String	getEncodedUserInfo()
			Gets the encoded user information from the authority component.
abstract		String	getFragment()
			Gets the decoded fragment part of this URI, everything after the '#'.
abstract		String	getHost()
			Gets the encoded host from the authority component of this URI.
abstract		String	getLastPathSegment()
			Gets the decoded last segment path of this URI.
abstract		String	getPath()
			Gets the decoded path component of this URI.
abstract		List	getPathSegments()
			Gets each of the decoded path segments of this URI.
abstract		int	getPort()
			Gets the port number from the authority component of this URI.
abstract		String	getQuery()
			Gets the decoded query component of this URI.
		String	getQueryParameter(String key)
			Searches the query string for the first value with the given key.
		List	getQueryParameters(String key)
			Searches the query string for parameter values with the given key.
abstract		String	getScheme()
			Gets the scheme of this URI, such as "http".
abstract		String	getSchemeSpecificPart()
			Gets the decoded scheme-specific part of this URI.
abstract		String	getUserInfo()
			Gets the decoded user information from the authority component.
		int	hashCode()
			Hashes the encoded string represention of this Uri consistently with equals(Object).
		boolean	isAbsolute()
			Returns true if this URI is absolute.
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.
	static	Uri	parse(String uriString)
			Creates a Uri object from 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 encoding and appending a path segment to a base Uri.
	static	void	writeToParcel(Parcel out, Uri uri)
			Writes a Uri to a Parcel.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

	Object	clone()
		Answers a new instance of the same class as the receiver, whose slots have been filled in with the values in the slots of the receiver.
	boolean	equals(Object o)
		Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison.
	void	finalize()
		Called by the virtual machine when there are no longer any (non-weak) references to the receiver.
final	Class	getClass()
		Answers the unique instance of java.lang.Class which represents the class of the receiver.
	int	hashCode()
		Answers an integer hash code for the receiver.
final	void	notify()
		Causes one thread which is `wait` ing on the receiver to be made ready to run.
final	void	notifyAll()
		Causes all threads which are `wait` ing on the receiver to be made ready to run.
	String	toString()
		Answers a string containing a concise, human-readable description of the receiver.
final	void	wait(long time, int frac)
		Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by `notify` or `notifyAll`) or the expiration of the timeout.
final	void	wait(long time)
		Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by `notify` or `notifyAll`) or the expiration of the timeout.
final	void	wait()
		Causes the thread which sent this message to be made not ready to run pending some change in the receiver (as indicated by `notify` or `notifyAll`).

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface android.os.Parcelable

writeToParcel

Details

Constants

public static final Creator CREATOR

Reads Uris from Parcels.

public static final Uri EMPTY

The empty URI, equivalent to "".

Public Methods

public abstract Builder buildUpon()

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

public int compareTo(Uri other)

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

Parameters

other	a Uri object to be compared to this one, on the basis of the String values.

Returns

the value 0 if this Uri's string representation is equal to that of other; a value less than 0 if this Uri's string representation is lexicographically less than that of other; or a value greater than 0 if this Uri's string representation is lexicographically greater than that of other.

public static String decode(String s)

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)

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 static String encode(String s, String allow)

Encodes characters in the given string as '%'-escaped octets using the UTF-8 scheme, except those that are given in allow. 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 boolean equals(Object o)

Compares this Uri to another object for equality. This is case-sensitive. 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	object to compare to this Uri, which must be an instance of a Uri object.

Returns

true if the encoded string representations of this Uri and that of the given Uri instance are equal.

public static Uri fromFile(File file)

Creates a Uri from a File. The Uri's string representation 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)

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()

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

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

Any '%'-escaped octets are decoded. Invalid octets are replaced with the unicode replacement character ("\\uFFFD").

Returns

the authority for this URI or null if not present

public abstract String getEncodedAuthority()

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

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

Any '%'-escaped octets are intact.

Returns

the authority for this URI or null if not present

public abstract String getEncodedFragment()

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

Any '%'-escaped octets are intact.

Returns

the encoded fragment or null if there isn't one

public abstract String getEncodedPath()

Gets the encoded path component of this URI.

Any '%'-escaped octets are intact.

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()

Gets the encoded query component of 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".

Any '%'-escaped octets are intact.

Returns

the encoded query or null if there isn't one

public abstract String getEncodedSchemeSpecificPart()

Gets the encoded 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.

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

Any '%'-escaped octets are intact.

Returns

the decoded scheme-specific-part

public abstract String getEncodedUserInfo()

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

Any '%'-escaped octets are intact.

Returns

the user info for this URI or null if not present

public abstract String getFragment()

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

Any '%'-escaped octets are decoded. Invalid octets are replaced with the unicode replacement character ("\\uFFFD").

Returns

the decoded fragment or null if there isn't one

public abstract String getHost()

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

Any '%'-escaped octets are intact.

Returns

the host for this URI or null if not present

public abstract String getLastPathSegment()

Gets the decoded last segment path of this URI. For example, if the path is "foo/bar/baz/" then the returned String will be "baz".

Any '%'-escaped octets are decoded. Invalid octets are replaced with the unicode replacement character ("\\uFFFD").

Returns

the decoded last segment or null if the path is empty

public abstract String getPath()

Gets the decoded path component of this URI.

Any '%'-escaped octets are decoded. Invalid octets are replaced with the unicode replacement character ("\\uFFFD").

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 getPathSegments()

Gets each of the decoded path segments of this URI. For example, if the path is "/foo/bar/baz/" then the returned List will have entries for "foo", "bar" and "baz".

Any '%'-escaped octets are decoded. Invalid octets are replaced with the unicode replacement character ("\\uFFFD").

Returns

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

public abstract int getPort()

Gets the port number from the authority component of 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()

Gets the decoded query component of 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".

Any '%'-escaped octets are decoded. Invalid octets are replaced with the unicode replacement character ("\\uFFFD").

Returns

the decoded query or null if there isn't one

public String getQueryParameter(String key)

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

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 List getQueryParameters(String key)

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()

Gets the scheme of this URI, such as "http".

Returns

the scheme, or null if this is a relative URI

public abstract String getSchemeSpecificPart()

Gets the decoded 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.

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

Any '%'-escaped octets are decoded. Invalid octets are replaced with the unicode replacement character ("\\uFFFD").

Returns

the decoded scheme-specific-part

public abstract String getUserInfo()

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

Any '%'-escaped octets are decoded. Invalid octets are replaced with the unicode replacement character ("\\uFFFD").

Returns

the user info for this URI or null if not present

public int hashCode()

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

public boolean isAbsolute()

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()

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()

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()

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 static Uri parse(String uriString)

Creates a Uri object from the given encoded URI string. The given string must be encoded, meaning any special characters must be percent-encoded ('%'-escaped).

Parameters

uriString	an RFC 3296-compliant, encoded URI

Returns

a Uri object for this given URI string

Throws

NullPointerException	if uriString is null

public abstract String toString()

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

Any '%'-escaped octets are intact.

public static Uri withAppendedPath(Uri baseUri, String pathSegment)

Creates a new Uri by encoding and appending a path segment to a base Uri.

Parameters

baseUri	Uri to append path segment to
pathSegment	to encode and append

Returns

a new Uri based on baseUri with the given segment encoded and appended to the path

public static void writeToParcel(Parcel out, Uri uri)

Writes a Uri to a Parcel.

Parameters

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

				int	compareTo(T another)
					Answers an integer indicating the relative positions of the receiver and the argument in the natural order of elements of the receiver's class.


e.g. "intent" or "activity"

Android - An Open Handset Alliance Project

Documentation

Goodies

android.net.Uri

Nested Classes

Summary

Constants

Public Methods

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Comparable

Methods inherited from interface android.os.Parcelable

Details

Constants

public static final Creator CREATOR

public static final Uri EMPTY

Public Methods

public abstract Builder buildUpon()

public int compareTo(Uri other)

Parameters

Returns

See Also

public static String decode(String s)

Parameters

Returns

public static String encode(String s)

Parameters

Returns

public static String encode(String s, String allow)

Parameters

Returns

public boolean equals(Object o)

Parameters

Returns

See Also

public static Uri fromFile(File file)

Returns

Throws

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

Parameters

Returns

Throws

See Also

public abstract String getAuthority()

Returns

public abstract String getEncodedAuthority()

Returns

public abstract String getEncodedFragment()

Returns

public abstract String getEncodedPath()

Returns

public abstract String getEncodedQuery()

Returns

public abstract String getEncodedSchemeSpecificPart()

Returns

public abstract String getEncodedUserInfo()

Returns

public abstract String getFragment()

Returns

public abstract String getHost()

Returns

public abstract String getLastPathSegment()

Returns

public abstract String getPath()

Returns

public abstract List getPathSegments()

Returns

public abstract int getPort()

Returns

public abstract String getQuery()

Returns

public String getQueryParameter(String key)

Parameters

Returns

Throws

public List getQueryParameters(String key)

Parameters

Returns

Throws

public abstract String getScheme()

Returns