public final class URI extends Object implements Comparable<URI>, Serializable
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 or relative
.
http://android.com/robots.txt
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(java.net.URI)
to compute the referenced absolute URI. Symmetrically, you can use
relativize(java.net.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 or hierarchical
. Relative
URIs are always hierarchical.
http://android.com/robots.txt
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 part | robots@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.
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 part | 0-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" |
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.
Constructor and Description |
---|
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.
|
Modifier and Type | Method and Description |
---|---|
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.
|
int |
getEffectivePort() |
static int |
getEffectivePort(String scheme,
int specifiedPort)
|
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.
|
public URI(String spec) throws URISyntaxException
spec
.spec
- a URI whose illegal characters have all been encoded.URISyntaxException
public URI(String scheme, String schemeSpecificPart, String fragment) throws URISyntaxException
scheme
- the URI scheme, or null for a non-absolute URI.URISyntaxException
public URI(String scheme, String userInfo, String host, int port, String path, String query, String fragment) throws URISyntaxException
scheme
- the URI scheme, or null for a non-absolute URI.URISyntaxException
public URI(String scheme, String host, String path, String fragment) throws URISyntaxException
scheme
- the URI scheme, or null for a non-absolute URI.URISyntaxException
public URI(String scheme, String authority, String path, String query, String fragment) throws URISyntaxException
scheme
- the URI scheme, or null for a non-absolute URI.URISyntaxException
public int compareTo(URI uri)
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.compareTo
in interface Comparable<URI>
uri
- the URI this instance has to compare with.public static URI create(String uri)
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)
Object
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 Object.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.
equals
in class Object
o
- the object to compare this instance with.true
if the specified object is equal to this Object
; false
otherwise.Object.hashCode()
public String getScheme()
public String getSchemeSpecificPart()
public String getRawSchemeSpecificPart()
public String getAuthority()
public String getRawAuthority()
public String getUserInfo()
public String getRawUserInfo()
public String getHost()
public int getPort()
-1
if this URI has no
explicit port.public int getEffectivePort()
public static int getEffectivePort(String scheme, int specifiedPort)
public String getPath()
public String getRawPath()
public String getQuery()
public String getRawQuery()
public String getFragment()
public String getRawFragment()
public int hashCode()
Object
Object.equals(java.lang.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.
hashCode
in class Object
Object.equals(java.lang.Object)
public boolean isAbsolute()
public boolean isOpaque()
public URI normalize()
public URI parseServerAuthority() throws URISyntaxException
URISyntaxException
- if the authority part could not be parsed as a server-based
authority.public URI relativize(URI relative)
relative
to a relative URI against the URI
represented by this instance.relative
- the URI which has to be relativized against this URI.public URI resolve(URI relative)
relative
against the URI represented by
this instance.relative
- the URI which has to be resolved against this URI.public URI resolve(String relative)
relative
and resolves the created URI against the URI represented by this
instance.relative
- the given string to create the new URI instance which has to
be resolved later on.public String toASCIIString()
public String toString()
public URL toURL() throws MalformedURLException
MalformedURLException
- if an error occurs while creating the URL or no protocol
handler could be found.