Package java.net

Class 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

      All Methods Static Methods Instance Methods Concrete Methods 
      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.

    • Method Detail

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