Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep
Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> java >> [ net overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of java.net.URI JAVADOC | Sourc code of java.net.URI SOURCE | Download java.net.URI DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

java.net
Class URI  view URI download URI.java

java.lang.Object
  extended byjava.net.URI
All Implemented Interfaces:
java.lang.Comparable, java.io.Serializable
public final class URI
extends java.lang.Object
implements java.lang.Comparable, java.io.Serializable

A URI instance represents that defined by RFC3986, with some deviations.

At its highest level, a URI consists of:

[scheme:]scheme-specific-part [#fragment]

where # and : are literal characters, and those parts enclosed in square brackets are optional.

There are two main types of URI. An opaque URI is one which just consists of the above three parts, and is not further defined. An example of such a URI would be mailto: URI. In contrast, hierarchical URIs give further definition to the scheme-specific part, so as represent some part of a hierarchical structure.

[//authority][path] [?query]

with / and ? being literal characters. When server-based, the authority section is further subdivided into:

[user-info@]host [:port]

with @ and : as literal characters. Authority sections that are not server-based are said to be registry-based.

Hierarchical URIs can be either relative or absolute. Absolute URIs always start with a `/', while relative URIs don't specify a scheme. Opaque URIs are always absolute.

Each part of the URI may have one of three states: undefined, empty or containing some content. The former two of these are represented by null and the empty string in Java, respectively. The scheme-specific part may never be undefined. It also follows from this that the path sub-part may also not be undefined, so as to ensure the former.

Character Escaping and Quoting

The characters that can be used within a valid URI are restricted. There are two main classes of characters which can't be used as is within the URI:

  1. Characters outside the US-ASCII character set. These have to be escaped in order to create an RFC-compliant URI; this means replacing the character with the appropriate hexadecimal value, preceded by a `%'.
  2. Illegal characters (e.g. space characters, control characters) are quoted, which results in them being encoded in the same way as non-US-ASCII characters.

The set of valid characters differs depending on the section of the URI:

These definitions reference the following sets of characters:

The constructors and accessor methods allow the use and retrieval of URI components which contain non-US-ASCII characters directly. They are only escaped when the toASCIIString() method is used. In contrast, illegal characters are always quoted, with the exception of the return values of the non-raw accessors.

Since:
1.4

Field Summary
private  java.lang.String authority
           
private static int AUTHORITY_GROUP
          Index of authority component in parsed URI.
private static int AUTHORITY_HOST_GROUP
          Index of host component in parsed authority section.
private static java.util.regex.Pattern AUTHORITY_PATTERN
          The compiled version of the authority regular expression.
private static int AUTHORITY_PORT_GROUP
          Index of port component in parsed authority section.
private static java.lang.String AUTHORITY_REGEXP
          Regular expression for parsing the authority segment.
private static int AUTHORITY_USERINFO_GROUP
          Index of userinfo component in parsed authority section.
private  java.lang.String fragment
           
private static int FRAGMENT_GROUP
          Index of fragment component in parsed URI.
private static java.lang.String HEX
          The set of valid hexadecimal characters.
private  java.lang.String host
           
private  java.lang.String path
           
private static int PATH_GROUP
          Index of path component in parsed URI.
private  int port
           
private  java.lang.String query
           
private static int QUERY_GROUP
          Index of query component in parsed URI.
private  java.lang.String rawAuthority
           
private  java.lang.String rawFragment
           
private  java.lang.String rawHost
           
private  java.lang.String rawPath
           
private  java.lang.String rawQuery
           
private  java.lang.String rawSchemeSpecificPart
           
private  java.lang.String rawUserInfo
           
private static java.lang.String RFC2396_ALPHA
           
private static java.lang.String RFC2396_ALPHANUM
           
private static java.lang.String RFC2396_DIGIT
          Valid characters (taken from rfc2396/3986)
private static java.lang.String RFC2396_LOWALPHA
           
private static java.lang.String RFC2396_UPALPHA
           
private static java.lang.String RFC3986_HOST
           
private static java.lang.String RFC3986_PATH_SEGMENTS
           
private static java.lang.String RFC3986_PCHAR
           
private static java.lang.String RFC3986_REG_NAME
           
private static java.lang.String RFC3986_SEGMENT
           
private static java.lang.String RFC3986_SSP
           
private static java.lang.String RFC3986_SUBDELIMS
           
private static java.lang.String RFC3986_UNRESERVED
           
private static java.lang.String RFC3986_USERINFO
           
private  java.lang.String scheme
           
private static int SCHEME_GROUP
          Index of scheme component in parsed URI.
private static int SCHEME_SPEC_PART_GROUP
          Index of scheme-specific-part in parsed URI.
private  java.lang.String schemeSpecificPart
           
(package private) static long serialVersionUID
          For serialization compatability.
private  java.lang.String string
           
private static java.util.regex.Pattern URI_PATTERN
          The compiled version of the URI regular expression.
private static java.lang.String URI_REGEXP
          Regular expression for parsing URIs.
private  java.lang.String userInfo
           
 
Constructor Summary
URI(java.lang.String str)
          Creates an URI from the given string
URI(java.lang.String scheme, java.lang.String ssp, java.lang.String fragment)
          Create an URI from the given components
URI(java.lang.String scheme, java.lang.String userInfo, java.lang.String host, int port, java.lang.String path, java.lang.String query, java.lang.String fragment)
          Create an URI from the given components
URI(java.lang.String scheme, java.lang.String host, java.lang.String path, java.lang.String fragment)
          Create an URI from the given components
URI(java.lang.String scheme, java.lang.String authority, java.lang.String path, java.lang.String query, java.lang.String fragment)
          Create an URI from the given components
 
Method Summary
private  int compareFragments(URI uri)
          Compares the fragment of this URI with that of the supplied URI.
 int compareTo(java.lang.Object obj)
          Compare the URI with another object that must also be a URI.
static URI create(java.lang.String str)
          Create an URI from the given string
 boolean equals(java.lang.Object obj)
           Compares the URI with the given object for equality.
private static java.lang.String escapeCharacters(java.lang.String str)
          Converts the non-ASCII characters in the supplied string to their equivalent percent-encoded representations.
 java.lang.String getAuthority()
          Returns the decoded authority part of this URI
 java.lang.String getFragment()
          Returns the fragment of the URI
 java.lang.String getHost()
          Returns the hostname of the URI
 java.lang.String getPath()
          Returns the path of the URI
 int getPort()
          Returns the port number of the URI
 java.lang.String getQuery()
          Returns the query of the URI
 java.lang.String getRawAuthority()
          Returns the raw authority part of this URI
 java.lang.String getRawFragment()
          Return the raw fragment part of this URI
 java.lang.String getRawPath()
          Returns the raw path part of this URI
 java.lang.String getRawQuery()
          Returns the raw query part of this URI
 java.lang.String getRawSchemeSpecificPart()
          Returns the raw scheme specific part of this URI.
 java.lang.String getRawUserInfo()
          Returns the raw user info part of this URI
 java.lang.String getScheme()
          Returns the scheme of the URI
 java.lang.String getSchemeSpecificPart()
          Returns the decoded scheme specific part of this URI.
private static java.lang.String getURIGroup(java.util.regex.Matcher match, int group)
           Returns the string content of the specified group of the supplied matcher.
 java.lang.String getUserInfo()
          Returns the decoded user info part of this URI
 int hashCode()
          Computes the hashcode of the URI
 boolean isAbsolute()
          Tells whether this URI is absolute or not
 boolean isOpaque()
          Tell whether this URI is opaque or not
 URI normalize()
           Returns a normalized version of the URI.
private  java.lang.String normalizePath(java.lang.String relativePath)
           Normalize the given path.
 URI parseServerAuthority()
          Attempts to parse this URI's authority component, if defined, into user-information, host, and port components.
private  void parseURI(java.lang.String str)
          Sets fields of this URI by parsing the given string.
private static java.lang.String quote(java.lang.String str)
          Quote characters illegal in URIs in given string.
private static java.lang.String quote(java.lang.String str, java.lang.String legalCharacters)
          Quotes the characters in the supplied string that are not part of the specified set of legal characters.
private static java.lang.String quoteAuthority(java.lang.String str)
          Quote characters illegal in URI authorities in given string.
private static java.lang.String quoteHost(java.lang.String str)
          Quote characters illegal in URI hosts in given string.
private static java.lang.String quotePath(java.lang.String str)
          Quote characters illegal in URI paths in given string.
private static java.lang.String quoteUserInfo(java.lang.String str)
          Quote characters illegal in URI user infos in given string.
private  void readObject(java.io.ObjectInputStream is)
           
 URI relativize(URI uri)
           Relativizes the given URI against this URI.
private  void removeLastSegment(java.lang.StringBuffer buffer)
          Removes the last segment of the path from the specified buffer.
 URI resolve(java.lang.String str)
          Resolves the given URI string against this URI
 URI resolve(URI uri)
          Resolves the given URI against this URI
 java.lang.String toASCIIString()
          Returns the URI as US-ASCII string.
 java.lang.String toString()
          Returns the URI as a String.
 URL toURL()
          Creates an URL from an URI
private static java.lang.String unquote(java.lang.String str)
          Unquote "%" + hex quotes characters
private  void writeObject(java.io.ObjectOutputStream os)
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

serialVersionUID

static final long serialVersionUID
For serialization compatability.

See Also:
Constant Field Values

URI_REGEXP

private static final java.lang.String URI_REGEXP
Regular expression for parsing URIs. Taken from RFC 2396, Appendix B. This expression doesn't parse IPv6 addresses.

See Also:
Constant Field Values

AUTHORITY_REGEXP

private static final java.lang.String AUTHORITY_REGEXP
Regular expression for parsing the authority segment.

See Also:
Constant Field Values

RFC2396_DIGIT

private static final java.lang.String RFC2396_DIGIT
Valid characters (taken from rfc2396/3986)

See Also:
Constant Field Values

RFC2396_LOWALPHA

private static final java.lang.String RFC2396_LOWALPHA
See Also:
Constant Field Values

RFC2396_UPALPHA

private static final java.lang.String RFC2396_UPALPHA
See Also:
Constant Field Values

RFC2396_ALPHA

private static final java.lang.String RFC2396_ALPHA
See Also:
Constant Field Values

RFC2396_ALPHANUM

private static final java.lang.String RFC2396_ALPHANUM
See Also:
Constant Field Values

RFC3986_UNRESERVED

private static final java.lang.String RFC3986_UNRESERVED
See Also:
Constant Field Values

RFC3986_SUBDELIMS

private static final java.lang.String RFC3986_SUBDELIMS
See Also:
Constant Field Values

RFC3986_REG_NAME

private static final java.lang.String RFC3986_REG_NAME
See Also:
Constant Field Values

RFC3986_PCHAR

private static final java.lang.String RFC3986_PCHAR
See Also:
Constant Field Values

RFC3986_SEGMENT

private static final java.lang.String RFC3986_SEGMENT
See Also:
Constant Field Values

RFC3986_PATH_SEGMENTS

private static final java.lang.String RFC3986_PATH_SEGMENTS
See Also:
Constant Field Values

RFC3986_SSP

private static final java.lang.String RFC3986_SSP
See Also:
Constant Field Values

RFC3986_HOST

private static final java.lang.String RFC3986_HOST
See Also:
Constant Field Values

RFC3986_USERINFO

private static final java.lang.String RFC3986_USERINFO
See Also:
Constant Field Values

SCHEME_GROUP

private static final int SCHEME_GROUP
Index of scheme component in parsed URI.

See Also:
Constant Field Values

SCHEME_SPEC_PART_GROUP

private static final int SCHEME_SPEC_PART_GROUP
Index of scheme-specific-part in parsed URI.

See Also:
Constant Field Values

AUTHORITY_GROUP

private static final int AUTHORITY_GROUP
Index of authority component in parsed URI.

See Also:
Constant Field Values

PATH_GROUP

private static final int PATH_GROUP
Index of path component in parsed URI.

See Also:
Constant Field Values

QUERY_GROUP

private static final int QUERY_GROUP
Index of query component in parsed URI.

See Also:
Constant Field Values

FRAGMENT_GROUP

private static final int FRAGMENT_GROUP
Index of fragment component in parsed URI.

See Also:
Constant Field Values

AUTHORITY_USERINFO_GROUP

private static final int AUTHORITY_USERINFO_GROUP
Index of userinfo component in parsed authority section.

See Also:
Constant Field Values

AUTHORITY_HOST_GROUP

private static final int AUTHORITY_HOST_GROUP
Index of host component in parsed authority section.

See Also:
Constant Field Values

AUTHORITY_PORT_GROUP

private static final int AUTHORITY_PORT_GROUP
Index of port component in parsed authority section.

See Also:
Constant Field Values

URI_PATTERN

private static final java.util.regex.Pattern URI_PATTERN
The compiled version of the URI regular expression.

AUTHORITY_PATTERN

private static final java.util.regex.Pattern AUTHORITY_PATTERN
The compiled version of the authority regular expression.

HEX

private static final java.lang.String HEX
The set of valid hexadecimal characters.

See Also:
Constant Field Values

scheme

private transient java.lang.String scheme

rawSchemeSpecificPart

private transient java.lang.String rawSchemeSpecificPart

schemeSpecificPart

private transient java.lang.String schemeSpecificPart

rawAuthority

private transient java.lang.String rawAuthority

authority

private transient java.lang.String authority

rawUserInfo

private transient java.lang.String rawUserInfo

userInfo

private transient java.lang.String userInfo

rawHost

private transient java.lang.String rawHost

host

private transient java.lang.String host

port

private transient int port

rawPath

private transient java.lang.String rawPath

path

private transient java.lang.String path

rawQuery

private transient java.lang.String rawQuery

query

private transient java.lang.String query

rawFragment

private transient java.lang.String rawFragment

fragment

private transient java.lang.String fragment

string

private java.lang.String string
Constructor Detail

URI

public URI(java.lang.String str)
    throws URISyntaxException
Creates an URI from the given string

URI

public URI(java.lang.String scheme,
           java.lang.String userInfo,
           java.lang.String host,
           int port,
           java.lang.String path,
           java.lang.String query,
           java.lang.String fragment)
    throws URISyntaxException
Create an URI from the given components

URI

public URI(java.lang.String scheme,
           java.lang.String authority,
           java.lang.String path,
           java.lang.String query,
           java.lang.String fragment)
    throws URISyntaxException
Create an URI from the given components

URI

public URI(java.lang.String scheme,
           java.lang.String host,
           java.lang.String path,
           java.lang.String fragment)
    throws URISyntaxException
Create an URI from the given components

URI

public URI(java.lang.String scheme,
           java.lang.String ssp,
           java.lang.String fragment)
    throws URISyntaxException
Create an URI from the given components

Method Detail

readObject

private void readObject(java.io.ObjectInputStream is)
                 throws java.lang.ClassNotFoundException,
                        java.io.IOException

writeObject

private void writeObject(java.io.ObjectOutputStream os)
                  throws java.io.IOException

getURIGroup

private static java.lang.String getURIGroup(java.util.regex.Matcher match,
                                            int group)

Returns the string content of the specified group of the supplied matcher. The returned value is modified according to the following:

  • If the resulting string has a length greater than 0, then that string is returned.
  • If a string of zero length, is matched, then the content of the preceding group is considered. If this is also an empty string, then null is returned to indicate an undefined value. Otherwise, the value is truly the empty string and this is the returned value.

This method is used for matching against all parts of the URI that may be either undefined or empty (i.e. all those but the scheme-specific part and the path). In each case, the preceding group is the content of the original group, along with some additional distinguishing feature. For example, the preceding group for the query includes the preceding question mark, while that of the fragment includes the hash symbol. The presence of these features enables disambiguation between the two cases of a completely unspecified value and a simple non-existant value. The scheme differs in that it will never return an empty string; the delimiter follows the scheme rather than preceding it, so it becomes part of the following section. The same is true of the user information.

parseURI

private void parseURI(java.lang.String str)
               throws URISyntaxException
Sets fields of this URI by parsing the given string.

unquote

private static java.lang.String unquote(java.lang.String str)
                                 throws URISyntaxException
Unquote "%" + hex quotes characters

quote

private static java.lang.String quote(java.lang.String str)
Quote characters illegal in URIs in given string. Replace illegal characters by encoding their UTF-8 representation as "%" + hex code for each resulting UTF-8 character.

quoteAuthority

private static java.lang.String quoteAuthority(java.lang.String str)
Quote characters illegal in URI authorities in given string. Replace illegal characters by encoding their UTF-8 representation as "%" + hex code for each resulting UTF-8 character.

quote

private static java.lang.String quote(java.lang.String str,
                                      java.lang.String legalCharacters)
Quotes the characters in the supplied string that are not part of the specified set of legal characters.

quoteHost

private static java.lang.String quoteHost(java.lang.String str)
Quote characters illegal in URI hosts in given string. Replace illegal characters by encoding their UTF-8 representation as "%" + hex code for each resulting UTF-8 character.

quotePath

private static java.lang.String quotePath(java.lang.String str)
Quote characters illegal in URI paths in given string. Replace illegal characters by encoding their UTF-8 representation as "%" + hex code for each resulting UTF-8 character.

quoteUserInfo

private static java.lang.String quoteUserInfo(java.lang.String str)
Quote characters illegal in URI user infos in given string. Replace illegal characters by encoding their UTF-8 representation as "%" + hex code for each resulting UTF-8 character.

create

public static URI create(java.lang.String str)
Create an URI from the given string

parseServerAuthority

public URI parseServerAuthority()
                         throws URISyntaxException
Attempts to parse this URI's authority component, if defined, into user-information, host, and port components. The purpose of this method was to disambiguate between some authority sections, which form invalid server-based authories, but valid registry based authorities. In the updated RFC 3986, the authority section is defined differently, with registry-based authorities part of the host section. Thus, this method is now simply an explicit way of parsing any authority section.

normalize

public URI normalize()

Returns a normalized version of the URI. If the URI is opaque, or its path is already in normal form, then this URI is simply returned. Otherwise, the following transformation of the path element takes place:

  1. All `.' segments are removed.
  2. Each `..' segment which can be paired with a prior non-`..' segment is removed along with the preceding segment.
  3. A `.' segment is added to the front if the first segment contains a colon (`:'). This is a deviation from the RFC, which prevents confusion between the path and the scheme.

The resulting URI will be free of `.' and `..' segments, barring those that were prepended or which couldn't be paired, respectively.

normalizePath

private java.lang.String normalizePath(java.lang.String relativePath)

Normalize the given path. The following transformation takes place:

  1. All `.' segments are removed.
  2. Each `..' segment which can be paired with a prior non-`..' segment is removed along with the preceding segment.
  3. A `.' segment is added to the front if the first segment contains a colon (`:'). This is a deviation from the RFC, which prevents confusion between the path and the scheme.

The resulting URI will be free of `.' and `..' segments, barring those that were prepended or which couldn't be paired, respectively.

removeLastSegment

private void removeLastSegment(java.lang.StringBuffer buffer)
Removes the last segment of the path from the specified buffer.

resolve

public URI resolve(URI uri)
Resolves the given URI against this URI

resolve

public URI resolve(java.lang.String str)
            throws java.lang.IllegalArgumentException
Resolves the given URI string against this URI

relativize

public URI relativize(URI uri)

Relativizes the given URI against this URI. The following algorithm is used:

  • If either URI is opaque, the given URI is returned.
  • If the schemes of the URIs differ, the given URI is returned.
  • If the authority components of the URIs differ, then the given URI is returned.
  • If the path of this URI is not a prefix of the supplied URI, then the given URI is returned.
  • If all the above conditions hold, a new URI is created using the query and fragment components of the given URI, along with a path computed by removing the path of this URI from the start of the path of the supplied URI.

toURL

public URL toURL()
          throws java.lang.IllegalArgumentException,
                 MalformedURLException
Creates an URL from an URI

getScheme

public java.lang.String getScheme()
Returns the scheme of the URI

isAbsolute

public boolean isAbsolute()
Tells whether this URI is absolute or not

isOpaque

public boolean isOpaque()
Tell whether this URI is opaque or not

getRawSchemeSpecificPart

public java.lang.String getRawSchemeSpecificPart()
Returns the raw scheme specific part of this URI. The scheme-specific part is never undefined, though it may be empty

getSchemeSpecificPart

public java.lang.String getSchemeSpecificPart()
Returns the decoded scheme specific part of this URI.

getRawAuthority

public java.lang.String getRawAuthority()
Returns the raw authority part of this URI

getAuthority

public java.lang.String getAuthority()
Returns the decoded authority part of this URI

getRawUserInfo

public java.lang.String getRawUserInfo()
Returns the raw user info part of this URI

getUserInfo

public java.lang.String getUserInfo()
Returns the decoded user info part of this URI

getHost

public java.lang.String getHost()
Returns the hostname of the URI

getPort

public int getPort()
Returns the port number of the URI

getRawPath

public java.lang.String getRawPath()
Returns the raw path part of this URI

getPath

public java.lang.String getPath()
Returns the path of the URI

getRawQuery

public java.lang.String getRawQuery()
Returns the raw query part of this URI

getQuery

public java.lang.String getQuery()
Returns the query of the URI

getRawFragment

public java.lang.String getRawFragment()
Return the raw fragment part of this URI

getFragment

public java.lang.String getFragment()
Returns the fragment of the URI

equals

public boolean equals(java.lang.Object obj)

Compares the URI with the given object for equality. If the object is not a URI, then the method returns false. Otherwise, the following criteria are observed:

  • The scheme of the URIs must either be null (undefined) in both cases, or equal, ignorant of case.
  • The raw fragment of the URIs must either be null (undefined) in both cases, or equal, ignorant of case.
  • Both URIs must be of the same type (opaque or hierarchial)
  • For opaque URIs:
    • The raw scheme-specific parts must be equal.
  • For hierarchical URIs:
    • The raw paths must be equal, ignorant of case.
    • The raw queries are either both undefined or both equal, ignorant of case.
    • The raw authority sections are either both undefined or:
    • For registry-based authorities:
      • they are equal.
    • For server-based authorities:
      • the hosts are equal, ignoring case
      • the ports are equal
      • the user information components are equal

hashCode

public int hashCode()
Computes the hashcode of the URI

compareTo

public int compareTo(java.lang.Object obj)
              throws java.lang.ClassCastException
Compare the URI with another object that must also be a URI. Undefined components are taken to be less than any other component. The following criteria are observed:

  • Two URIs with different schemes are compared according to their scheme, regardless of case.
  • A hierarchical URI is less than an opaque URI with the same scheme.
  • For opaque URIs:
    • URIs with differing scheme-specific parts are ordered according to the ordering of the scheme-specific part.
    • URIs with the same scheme-specific part are ordered by the raw fragment.
  • For hierarchical URIs:
    • URIs are ordered according to their raw authority sections, if they are unequal.
    • For registry-based authorities:
      • they are ordered according to the ordering of the authority component.
    • For server-based authorities:
      • URIs are ordered according to the raw user information.
      • URIs with the same user information are ordered by the host, ignoring case.
      • URIs with the same host are ordered by the port.
    • URIs with the same authority section are ordered by the raw path.
    • URIs with the same path are ordered by their raw query.
    • URIs with the same query are ordered by their raw fragments.

Specified by:
compareTo in interface java.lang.Comparable

compareFragments

private int compareFragments(URI uri)
Compares the fragment of this URI with that of the supplied URI.

toString

public java.lang.String toString()
Returns the URI as a String. If the URI was created using a constructor, then this will be the same as the original input string.

toASCIIString

public java.lang.String toASCIIString()
Returns the URI as US-ASCII string. This is the same as the result from toString() for URIs that don't contain any non-US-ASCII characters. Otherwise, the non-US-ASCII characters are replaced by their percent-encoded representations.

escapeCharacters

private static java.lang.String escapeCharacters(java.lang.String str)
Converts the non-ASCII characters in the supplied string to their equivalent percent-encoded representations. That is, they are replaced by "%" followed by their hexadecimal value.

Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> java >> [ net overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of java.net.URI JAVADOC | Sourc code of java.net.URI SOURCE | Download java.net.URI DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD