Package java.net

Class URI

java.lang.Object
java.net.URI
All Implemented Interfaces:
Serializable, Comparable<URI>
public final class URI
extends Object
implements Comparable<URI>, Serializable
A Uniform Resource Identifier that identifies an abstract or physical resource, as specified by RFC 2396.

Parts of a URI

A URI is composed of many parts. This class can both parse URI strings into parts and compose URI strings from parts. For example, consider the parts of this URI: 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 vs. Relative URIs

URIs are either absolute or relative.
  • Absolute: http://android.com/robots.txt
  • Relative: 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 vs. Hierarchical URIs

Absolute URIs are either opaque or hierarchical. Relative URIs are always hierarchical.
  • Hierarchical: http://android.com/robots.txt
  • Opaque: 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 partrobots@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.

Encoding and Decoding URI Components

Each component of a URI permits a limited set of legal characters. Other characters must first be encoded before they can be embedded in a URI. To recover the original characters from a URI, they may be decoded. Contrary to what you might expect, this class uses the term raw to refer to encoded strings. The non-raw accessors return decoded strings. For example, consider how this URI is decoded: 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 part0-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"
A URI's host, port and scheme are not eligible for encoding and must not contain illegal characters.

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.

See Also:
Serialized Form

  • Constructor Summary

    Constructors
    Constructor 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.

  • Method Summary

    Modifier and Type Method 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)
    Returns the port to use for scheme connections will use when getPort() returns 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.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

  • Method Details

    • compareTo

      public int compareTo​(URI uri)
      Compares this URI with the given argument 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.
      Specified by:
      compareTo in interface Comparable<URI>
      Parameters:
      uri - the URI this instance has to compare with.
      Returns:
      the value representing the order of the two instances.

    • create

      public static URI create​(String uri)
      Returns the URI formed by parsing 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.

    • equals

      public boolean equals​(Object o)
      Description copied from class: Object
      Compares this instance with the specified object and indicates if they are equal. In order to be equal, 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.

      Overrides:
      equals in class Object
      Parameters:
      o - the object to compare this instance with.
      Returns:
      true if the specified object is equal to this Object; false otherwise.
      See Also:
      Object.hashCode()

    • getScheme

      public String getScheme()
      Returns the scheme of this URI, or null if this URI has no scheme. This is also known as the protocol.

    • getSchemeSpecificPart

      public String getSchemeSpecificPart()
      Returns the decoded scheme-specific part of this URI, or null if this URI has no scheme-specific part.

    • getRawSchemeSpecificPart

      public String getRawSchemeSpecificPart()
      Returns the encoded scheme-specific part of this URI, or null if this URI has no scheme-specific part.

    • getAuthority

      public String getAuthority()
      Returns the decoded authority part of this URI, or null if this URI has no authority.

    • getRawAuthority

      public String getRawAuthority()
      Returns the encoded authority of this URI, or null if this URI has no authority.

    • getUserInfo

      public String getUserInfo()
      Returns the decoded user info of this URI, or null if this URI has no user info.

    • getRawUserInfo

      public String getRawUserInfo()
      Returns the encoded user info of this URI, or null if this URI has no user info.

    • getHost

      public String getHost()
      Returns the host of this URI, or null if this URI has no host.

    • getPort

      public int getPort()
      Returns the port number of this URI, or -1 if this URI has no explicit port.

    • getEffectivePort

      public int getEffectivePort()

    • getEffectivePort

      public static int getEffectivePort​(String scheme, int specifiedPort)
      Returns the port to use for scheme connections will use when getPort() returns specifiedPort.

    • getPath

      public String getPath()
      Returns the decoded path of this URI, or null if this URI has no path.

    • getRawPath

      public String getRawPath()
      Returns the encoded path of this URI, or null if this URI has no path.

    • getQuery

      public String getQuery()
      Returns the decoded query of this URI, or null if this URI has no query.

    • getRawQuery

      public String getRawQuery()
      Returns the encoded query of this URI, or null if this URI has no query.

    • getFragment

      public String getFragment()
      Returns the decoded fragment of this URI, or null if this URI has no fragment.

    • getRawFragment

      public String getRawFragment()
      Gets the encoded fragment of this URI, or null if this URI has no fragment.

    • hashCode

      public int hashCode()
      Description copied from class: Object
      Returns an integer hash code for this object. By contract, any two objects for which 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.

      Overrides:
      hashCode in class Object
      Returns:
      this object's hash code.
      See Also:
      Object.equals(java.lang.Object)

    • isAbsolute

      public boolean isAbsolute()
      Returns true if this URI is absolute, which means that a scheme is defined.

    • isOpaque

      public boolean isOpaque()
      Returns true if this URI is opaque. Opaque URIs are absolute and have a scheme-specific part that does not start with a slash character. All parts except scheme, scheme-specific and fragment are undefined.

    • normalize

      public URI normalize()
      Normalizes the path part of this URI.
      Returns:
      an URI object which represents this instance with a normalized path.

    • parseServerAuthority

      public URI parseServerAuthority() throws URISyntaxException
      Tries to parse the authority component of this URI to divide it into the host, port, and user-info. If this URI is already determined as a ServerAuthority this instance will be returned without changes.
      Returns:
      this instance with the components of the parsed server authority.
      Throws:
      URISyntaxException - if the authority part could not be parsed as a server-based authority.

    • relativize

      public URI relativize​(URI relative)
      Makes the given URI relative to a relative URI against the URI represented by this instance.
      Parameters:
      relative - the URI which has to be relativized against this URI.
      Returns:
      the relative URI.

    • resolve

      public URI resolve​(URI relative)
      Resolves the given URI relative against the URI represented by this instance.
      Parameters:
      relative - the URI which has to be resolved against this URI.
      Returns:
      the resolved URI.

    • resolve

      public 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.
      Parameters:
      relative - the given string to create the new URI instance which has to be resolved later on.
      Returns:
      the created and resolved URI.

    • toASCIIString

      public String toASCIIString()
      Returns the textual string representation of this URI instance using the US-ASCII encoding.
      Returns:
      the US-ASCII string representation of this URI.

    • toString

      public String toString()
      Returns the encoded URI.
      Overrides:
      toString in class Object
      Returns:
      a printable representation of this object.

    • toURL

      public URL toURL() throws MalformedURLException
      Converts this URI instance to a URL.
      Returns:
      the created URL representing the same resource as this URI.
      Throws:
      MalformedURLException - if an error occurs while creating the URL or no protocol handler could be found.