java.net

Class URI

Implemented Interfaces:
Comparable, Serializable

public final class URI
extends Object
implements Comparable, 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

See Also:
Serialized Form

Constructor Summary

URI(String str)
Creates an URI from the given string
URI(String scheme, String ssp, String fragment)
Create an URI from the given components
URI(String scheme, String userInfo, String host, int port, String path, String query, String fragment)
Create an URI from the given components
URI(String scheme, String host, String path, String fragment)
Create an URI from the given components
URI(String scheme, String authority, String path, String query, String fragment)
Create an URI from the given components

Method Summary

int
compareTo(Object obj)
Compare the URI with another object that must also be a URI.
static URI
create(String str)
Create an URI from the given string
boolean
equals(Object obj)
Compares the URI with the given object for equality.
String
getAuthority()
Returns the decoded authority part of this URI
String
getFragment()
Returns the fragment of the URI
String
getHost()
Returns the hostname of the URI
String
getPath()
Returns the path of the URI
int
getPort()
Returns the port number of the URI
String
getQuery()
Returns the query of the URI
String
getRawAuthority()
Returns the raw authority part of this URI
String
getRawFragment()
Return the raw fragment part of this URI
String
getRawPath()
Returns the raw path part of this URI
String
getRawQuery()
Returns the raw query part of this URI
String
getRawSchemeSpecificPart()
Returns the raw scheme specific part of this URI.
String
getRawUserInfo()
Returns the raw user info part of this URI
String
getScheme()
Returns the scheme of the URI
String
getSchemeSpecificPart()
Returns the decoded scheme specific part of this URI.
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.
URI
parseServerAuthority()
Attempts to parse this URI's authority component, if defined, into user-information, host, and port components.
URI
relativize(URI uri)
Relativizes the given URI against this URI.
URI
resolve(String str)
Resolves the given URI string against this URI
URI
resolve(URI uri)
Resolves the given URI against this URI
String
toASCIIString()
Returns the URI as US-ASCII string.
String
toString()
Returns the URI as a String.
URL
toURL()
Creates an URL from an URI

Methods inherited from class java.lang.Object

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

Constructor Details

URI

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

Parameters:
str - The string to create the URI from

Throws:
URISyntaxException - If the given string violates RFC 2396
NullPointerException - If str is null


URI

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

Parameters:
scheme - The scheme name
ssp - The scheme specific part
fragment - The fragment

Throws:
URISyntaxException - If the given string violates RFC 2396


URI

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

Parameters:
scheme - The scheme name
userInfo - The username and authorization info
host - The hostname
port - The port number
path - The path
query - The query
fragment - The fragment

Throws:
URISyntaxException - If the given string violates RFC 2396


URI

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

Parameters:
scheme - The scheme name
host - The hostname
path - The path
fragment - The fragment

Throws:
URISyntaxException - If the given string violates RFC 2396


URI

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

Parameters:
scheme - The scheme name
authority - The authority
path - The apth
query - The query
fragment - The fragment

Throws:
URISyntaxException - If the given string violates RFC 2396

Method Details

compareTo

public int compareTo(Object obj)
            throws 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 Comparable

    Parameters:
    obj - This object to compare this URI with

    Returns:
    a negative integer, zero or a positive integer depending on whether this URI is less than, equal to or greater than that supplied, respectively.

    Throws:
    ClassCastException - if the given object is not a URI


    create

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

    Parameters:
    str - The string to create the URI from

    Throws:
    IllegalArgumentException - If the given string violates RFC 2396
    NullPointerException - If str is null


    equals

    public boolean equals(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
    Overrides:
    equals in interface Object

    Parameters:
    obj - the obj to compare the URI with.

    Returns:
    true if the objects are equal, according to the specification above.


    getAuthority

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


    getFragment

    public String getFragment()
    Returns the fragment of the URI


    getHost

    public String getHost()
    Returns the hostname of the URI


    getPath

    public String getPath()
    Returns the path of the URI


    getPort

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


    getQuery

    public String getQuery()
    Returns the query of the URI


    getRawAuthority

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


    getRawFragment

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


    getRawPath

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


    getRawQuery

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


    getRawSchemeSpecificPart

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


    getRawUserInfo

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


    getScheme

    public String getScheme()
    Returns the scheme of the URI


    getSchemeSpecificPart

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


    getUserInfo

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


    hashCode

    public int hashCode()
    Computes the hashcode of the URI
    Overrides:
    hashCode in interface Object


    isAbsolute

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


    isOpaque

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


    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.

    Returns:
    the normalized URI.


    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.

    Returns:
    the URI, with the authority section parsed into user information, host and port components.

    Throws:
    URISyntaxException - if the given string violates RFC 2396


    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.

    Parameters:
    uri - the URI to relativize agsint this URI

    Returns:
    the resulting URI

    Throws:
    NullPointerException - if the uri is null


    resolve

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

    Parameters:
    str - The URI as string to resolve against this URI

    Returns:
    The resulting URI

    Throws:
    IllegalArgumentException - If the given URI string violates RFC 2396
    NullPointerException - If uri is null


    resolve

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

    Parameters:
    uri - The URI to resolve against this URI

    Returns:
    The resulting URI, or null when it couldn't be resolved for some reason.

    Throws:
    NullPointerException - if uri is null


    toASCIIString

    public 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.

    Returns:
    a string representation of the URI, containing only US-ASCII characters.


    toString

    public 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.
    Overrides:
    toString in interface Object

    Returns:
    a string representation of the URI.


    toURL

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

    Throws:
    MalformedURLException - If a protocol handler for the URL could not be found, or if some other error occurred while constructing the URL
    IllegalArgumentException - If the URI is not absolute


    URI.java -- An URI class Copyright (C) 2002, 2004, 2005 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.