Build 1.0_r1(from source)

android.net
Class Uri

java.lang.Object
  extended by android.net.Uri
All Implemented Interfaces:
Parcelable, Comparable<Uri>

public abstract class Uri
extends Object
implements Parcelable, Comparable<Uri>

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.


Nested Class Summary
(package private) static class Uri.AbstractPart
          Support for part implementations.
static class Uri.Builder
          Helper class for building or manipulating URI references.
(package private) static class Uri.Part
          Immutable wrapper of encoded and decoded versions of a URI part.
(package private) static class Uri.PathPart
          Immutable wrapper of encoded and decoded versions of a path part.
(package private) static class Uri.PathSegments
          Wrapper for path segment array.
(package private) static class Uri.PathSegmentsBuilder
          Builds PathSegments.
 
Nested classes/interfaces inherited from interface android.os.Parcelable
Parcelable.Creator<T>
 
Field Summary
static Parcelable.Creator<Uri> CREATOR
          Reads Uris from Parcels.
static Uri EMPTY
          The empty URI, equivalent to "".
 
Fields inherited from interface android.os.Parcelable
CONTENTS_FILE_DESCRIPTOR, PARCELABLE_WRITE_RETURN_VALUE
 
Method Summary
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)
          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.
 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.
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.
 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.
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 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, finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface android.os.Parcelable
describeContents, writeToParcel
 

Field Detail

EMPTY

public static final Uri EMPTY
The empty URI, equivalent to "".


CREATOR

public static final Parcelable.Creator<Uri> CREATOR
Reads Uris from Parcels.

Method Detail

isHierarchical

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.


isOpaque

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


isRelative

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

isAbsolute

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

getScheme

public abstract String getScheme()
Gets the scheme of this URI. Example: "http"

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

getSchemeSpecificPart

public abstract String getSchemeSpecificPart()
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

getEncodedSchemeSpecificPart

public abstract String getEncodedSchemeSpecificPart()
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

getAuthority

public abstract String getAuthority()
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

getEncodedAuthority

public abstract String getEncodedAuthority()
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

getUserInfo

public abstract String getUserInfo()
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

getEncodedUserInfo

public abstract String getEncodedUserInfo()
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

getHost

public abstract String getHost()
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

getPort

public abstract int getPort()
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

getPath

public abstract String getPath()
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

getEncodedPath

public abstract String getEncodedPath()
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

getQuery

public abstract String getQuery()
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

getEncodedQuery

public abstract String getEncodedQuery()
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

getFragment

public abstract String getFragment()
Gets the decoded fragment part of this URI, everything after the '#'.

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

getEncodedFragment

public abstract String getEncodedFragment()
Gets the encoded fragment part of this URI, everything after the '#'.

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

getPathSegments

public abstract List<String> getPathSegments()
Gets the decoded path segments.

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

getLastPathSegment

public abstract String getLastPathSegment()
Gets the decoded last segment in the path.

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

equals

public boolean equals(Object o)
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.

Overrides:
equals in class Object
Parameters:
o - Object the object to compare with this object.
Returns:
boolean true if the object is the same as this object false if it is different from this object.
See Also:
Object.hashCode()

hashCode

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

Overrides:
hashCode in class Object
Returns:
int the receiver's hash.
See Also:
Object.equals(java.lang.Object)

compareTo

public int compareTo(Uri other)
Compares the string representation of this Uri with that of another.

Specified by:
compareTo in interface Comparable<Uri>
Parameters:
other - Object an object to compare the receiver to
Returns:
int which should be <0 if="" the="" receiver="" should="" sort="" before="" the="" argument,="" 0="" if="" the="" receiver="" should="" sort="" in="" the="" same="" position="" as="" the="" argument,="" and="">0 if the receiver should sort after the argument.

toString

public abstract String toString()
Returns the encoded string representation of this URI. Example: "http://google.com/"

Overrides:
toString in class Object
Returns:
String a printable representation for the receiver.

buildUpon

public abstract Uri.Builder buildUpon()
Constructs a new builder, copying the attributes from this Uri.


parse

public static Uri parse(String uriString)
Creates a Uri which parses the given encoded URI string.

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

fromFile

public static Uri fromFile(File file)
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

fromParts

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
See Also:
if you don't want the ssp and fragment to be encoded

getQueryParameters

public List<String> 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

getQueryParameter

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

writeToParcel

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

encode

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

encode

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

decode

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

withAppendedPath

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
Throws:
NullPointerException - if baseUri is null

Build 1.0_r1(from source)

Please submit a feedback, bug or feature