Class Uri


  • public class Uri
    extends Object
    This class implements an immutable Uri as defined by RFC 2396.

    Character encoding is employed as defined by RFC 3986, see RFC 3986 section 2.1, while multibyte unicode characters are preserved in encoded parts.

         1 [scheme:]scheme-specific-part[#fragment]
         2 [scheme:][//authority]path[?query][#fragment]
         3 [scheme:][//[user-info@]host[:port]]path[?query][#fragment]
    
            scheme-specific-part: [//authority]path[?query]
            authority:            [user-info@]host[:port]
     

    RFC 3986 section 2.2 Reserved Characters (January 2005)

    ! * ' ( ) ; : @ & = + $ , / ? # [ ]

    RFC 3986 section 2.3 Unreserved Characters (January 2005)

    A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
    a b c d e f g h i j k l m n o p q r s t u v w x y z
    0 1 2 3 4 5 6 7 8 9 - _ . ~

    Other characters in a Uri must be percent encoded.

    Since:
    2.2.1
    • Field Detail

      • UNRESERVED

        public static final String UNRESERVED
        RFC 3986 section 2.3 Unreserved Characters (January 2005)

        "_-.~" + alphanum

        See Also:
        Constant Field Values
      • RESERVED

        public static final String RESERVED
        RFC 3986 section 2.2 Reserved Characters (January 2005)

        ",;:$&+=!*\'()@/?#[]" + alphanum

        See Also:
        Constant Field Values
      • USERINFO_LEGAL

        public static final String USERINFO_LEGAL
        Valid charset for RFC 2396 authority's user-info, additional to legal alphanum characters.

        "_-.~,;:$&+=" + alphanum

        See Also:
        Constant Field Values
      • AUTHORITY_LEGAL

        public static final String AUTHORITY_LEGAL
        Valid charset for RFC 2396 authority, additional to legal alphanum characters.

        "@[]_-.~,;:$&+=" + alphanum

        See Also:
        Constant Field Values
      • PATH_LEGAL

        public static final String PATH_LEGAL
        Valid charset for RFC 2396 path, additional to legal alphanum characters.

        "/!_-.~" + alphanum

        See Also:
        Constant Field Values
      • QUERY_LEGAL

        public static final String QUERY_LEGAL
        Valid charset for RFC 2396 query, additional to legal alphanum characters.

        "_-.~,;:$&+=!*\'()@/?[]\\\"" + alphanum

        See Also:
        Constant Field Values
      • SSP_LEGAL

        public static final String SSP_LEGAL
        Valid charset for RFC 2396 scheme-specific-part, additional to legal alphanum characters.

        "_-.~,;:$&+=!*\'()@/?[]\\\"" + alphanum

        See Also:
        Constant Field Values
      • FRAG_LEGAL

        public static final String FRAG_LEGAL
        Valid charset for RFC 2396 fragment, additional to legal alphanum characters.

        "_-.~,;:$&+=!*\'()@/?#[]" + alphanum

        See Also:
        Constant Field Values
      • JAR_SCHEME_SEPARATOR

        public static final char JAR_SCHEME_SEPARATOR
        A JAR sub-protocol is separated from the JAR entry w/ this separator 33. Even if no class is specified '!/' must follow!.
        See Also:
        Constant Field Values
      • input

        public final Uri.Encoded input
        Encoded input string used at construction, never null.
      • scheme

        public final Uri.Encoded scheme
        Encoded scheme, null if undefined.
      • schemeSpecificPart

        public final Uri.Encoded schemeSpecificPart
        Encoded scheme-specific-part, never null.
      • path

        public final Uri.Encoded path
        Encoded path part of scheme-specific-part, never null.
      • hasAuthority

        public final boolean hasAuthority
        Indicating whether authority part is defined or not.
      • authority

        public final Uri.Encoded authority
        Encoded authority part of scheme-specific-part, null if undefined.
      • userInfo

        public final Uri.Encoded userInfo
        Encoded userinfo part of authority and scheme-specific-part, null if undefined.
      • host

        public final Uri.Encoded host
        Encoded host part of authority and scheme-specific-part, null if undefined.
      • port

        public final int port
        Encoded port part of authority and scheme-specific-part, -1 if undefined.
      • query

        public final Uri.Encoded query
        Encoded query part of scheme-specific-part, null if undefined.
      • fragment

        public final Uri.Encoded fragment
        Encoded fragment, null if undefined.
      • absolute

        public final boolean absolute
        Indicating whether this Uri is absolute, i.e. has a scheme and hence an absolute scheme-specific-part.
      • opaque

        public final boolean opaque
        Indicating whether this Uri is opaque, i.e. non-hierarchical scheme-specific-part.

        An opaque Uri has no scheme-specific-part being parsed, i.e. path, query and authority are null.

    • Constructor Detail

      • Uri

        public Uri​(Uri.Encoded uri)
            throws URISyntaxException
        Creates a new Uri instance according to the given encoded string uri.
        Parameters:
        uri - the RFC3986 encoded RFC2396 Uri representation to be parsed into a Uri object
        Throws:
        URISyntaxException - if the given string uri doesn't fit to the specification RFC2396 and RFC3986 or could not be parsed correctly.
    • Method Detail

      • encode

        public static String encode​(String vanilla,
                                    String legal)
        All characters are encoded into their hexadecimal value prepended by '%', except:
        1. letters ('a'..'z', 'A'..'Z')
        2. numbers ('0'..'9')
        3. characters in the legal-set parameter
        4. others (unicode characters that are not in US-ASCII set, and are not ISO Control or are not ISO Space characters)

        Use encodeToASCIIString(String) for US-ASCII encoding.

        Consider using Encoded(String, String) in APIs to distinguish encoded from unencoded data by type.

        Parameters:
        vanilla - the string to be encoded
        legal - extended character set, allowed to be preserved in the vanilla string
        Returns:
        java.lang.String the converted string
      • encodeToASCIIString

        public static String encodeToASCIIString​(String unicode)
        Other characters, which are Unicode chars that are not US-ASCII, and are not ISO Control or are not ISO Space chars are not preserved and encoded into their hexidecimal value prepended by '%'.

        For example: Euro currency symbol -> "%E2%82%AC".

        Consider using ASCIIEncoded(String) in APIs to distinguish encoded from unencoded data by type.

        Parameters:
        unicode - string to be converted
        Returns:
        java.lang.String the converted string
      • decode

        public static String decode​(String encoded)
        Decodes the string argument which is assumed to be encoded in the x-www-form-urlencoded MIME content type using the UTF-8 encoding scheme.

        '%' and two following hex digit characters are converted to the equivalent byte value. All other characters are passed through unmodified.

        e.g. "A%20B%20C %24%25" -> "A B C $%"

        Parameters:
        encoded - The encoded string.
        Returns:
        java.lang.String The decoded version.
      • create

        public static Uri create​(String scheme,
                                 String ssp,
                                 String fragment)
                          throws URISyntaxException
        Creates a new Uri instance using the given unencoded arguments.

        This constructor first creates a temporary Uri string from the given unencoded components. This string will be parsed later on to create the Uri instance.

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

        host and port may be undefined or invalid within scheme-specific-part.

        Parameters:
        scheme - the unencoded scheme part of the Uri.
        ssp - the unencoded scheme-specific-part of the Uri.
        fragment - the unencoded fragment part of the Uri.
        Throws:
        URISyntaxException - if the temporary created string doesn't fit to the specification RFC2396 or could not be parsed correctly.
      • create

        public static Uri create​(Uri.Encoded scheme,
                                 Uri.Encoded ssp,
                                 Uri.Encoded fragment)
                          throws URISyntaxException
        Creates a new Uri instance using the given encoded arguments.

        This constructor first creates a temporary Uri string from the given encoded components. This string will be parsed later on to create the Uri instance.

        The given encoded components are taken as-is, i.e. no re-encoding will be performed! However, Uri parsing will re-evaluate encoding of the resulting components.

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

        host and port may be undefined or invalid within scheme-specific-part.

        Parameters:
        scheme - the encoded scheme part of the Uri.
        ssp - the encoded scheme-specific-part of the Uri.
        fragment - the encoded fragment part of the Uri.
        Throws:
        URISyntaxException - if the temporary created string doesn't fit to the specification RFC2396 or could not be parsed correctly.
      • create

        public static Uri create​(String scheme,
                                 String userinfo,
                                 String host,
                                 int port,
                                 String path,
                                 String query,
                                 String fragment)
                          throws URISyntaxException
        Creates a new Uri instance using the given unencoded arguments.

        This constructor first creates a temporary Uri string from the given unencoded components. This string will be parsed later on to create the Uri instance.

        [scheme:][user-info@]host[:port][path][?query][#fragment]

        host and port must be defined and valid, if any authority components are defined, i.e. user-info, host or port.

        Parameters:
        scheme - the unencoded scheme part of the Uri.
        userinfo - the unencoded user information of the Uri for authentication and authorization, null for undefined.
        host - the unencoded host name of the Uri, null for undefined.
        port - the port number of the Uri, -1 for undefined.
        path - the unencoded path to the resource on the host.
        query - the unencoded query part of the Uri to specify parameters for the resource.
        fragment - the unencoded fragment part of the Uri.
        Throws:
        URISyntaxException - if the temporary created string doesn't fit to the specification RFC2396 or could not be parsed correctly.
      • create

        public static Uri create​(Uri.Encoded scheme,
                                 Uri.Encoded userinfo,
                                 Uri.Encoded host,
                                 int port,
                                 Uri.Encoded path,
                                 Uri.Encoded query,
                                 Uri.Encoded fragment)
                          throws URISyntaxException
        Creates a new Uri instance using the given encoded arguments.

        This constructor first creates a temporary Uri string from the given encoded components. This string will be parsed later on to create the Uri instance.

        The given encoded components are taken as-is, i.e. no re-encoding will be performed! However, Uri parsing will re-evaluate encoding of the resulting components.

        [scheme:][user-info@]host[:port][path][?query][#fragment]

        host and port must be defined and valid, if any authority components are defined, i.e. user-info, host or port.

        Parameters:
        scheme - the encoded scheme part of the Uri.
        userinfo - the encoded user information of the Uri for authentication and authorization, null for undefined.
        host - the encoded host name of the Uri, null for undefined.
        port - the port number of the Uri, -1 for undefined.
        path - the encoded path to the resource on the host.
        query - the encoded query part of the Uri to specify parameters for the resource.
        fragment - the encoded fragment part of the Uri.
        Throws:
        URISyntaxException - if the temporary created string doesn't fit to the specification RFC2396 or could not be parsed correctly.
      • create

        public static Uri create​(String scheme,
                                 String host,
                                 String path,
                                 String fragment)
                          throws URISyntaxException
        Creates a new Uri instance using the given unencoded arguments.

        This constructor first creates a temporary Uri string from the given unencoded components. This string will be parsed later on to create the Uri instance.

        [scheme:]host[path][#fragment]

        host must be valid, if defined.

        Parameters:
        scheme - the unencoded scheme part of the Uri.
        host - the unencoded host name of the Uri.
        path - the unencoded path to the resource on the host.
        fragment - the unencoded fragment part of the Uri.
        Throws:
        URISyntaxException - if the temporary created string doesn't fit to the specification RFC2396 or could not be parsed correctly.
      • create

        public static Uri create​(Uri.Encoded scheme,
                                 Uri.Encoded host,
                                 Uri.Encoded path,
                                 Uri.Encoded fragment)
                          throws URISyntaxException
        Creates a new Uri instance using the given encoded arguments.

        This constructor first creates a temporary Uri string from the given encoded components. This string will be parsed later on to create the Uri instance.

        The given encoded components are taken as-is, i.e. no re-encoding will be performed! However, Uri parsing will re-evaluate encoding of the resulting components.

        [scheme:]host[path][#fragment]

        host must be valid, if defined.

        Parameters:
        scheme - the encoded scheme part of the Uri.
        host - the encoded host name of the Uri.
        path - the encoded path to the resource on the host.
        fragment - the encoded fragment part of the Uri.
        Throws:
        URISyntaxException - if the temporary created string doesn't fit to the specification RFC2396 or could not be parsed correctly.
      • create

        public static Uri create​(String scheme,
                                 String authority,
                                 String path,
                                 String query,
                                 String fragment)
                          throws URISyntaxException
        Creates a new Uri instance using the given unencoded arguments.

        This constructor first creates a temporary Uri string from the given unencoded components. This string will be parsed later on to create the Uri instance.

        [scheme:][//authority][path][?query][#fragment]

        host and port may be undefined or invalid, in the optional authority.

        Parameters:
        scheme - the unencoded scheme part of the Uri.
        authority - the unencoded authority part of the Uri.
        path - the unencoded path to the resource on the host.
        query - the unencoded query part of the Uri to specify parameters for the resource.
        fragment - the unencoded fragment part of the Uri.
        Throws:
        URISyntaxException - if the temporary created string doesn't fit to the specification RFC2396 or could not be parsed correctly.
      • create

        public static Uri create​(Uri.Encoded scheme,
                                 Uri.Encoded authority,
                                 Uri.Encoded path,
                                 Uri.Encoded query,
                                 Uri.Encoded fragment)
                          throws URISyntaxException
        Creates a new Uri instance using the given encoded arguments.

        This constructor first creates a temporary Uri string from the given encoded encoded components. This string will be parsed later on to create the Uri instance.

        The given encoded components are taken as-is, i.e. no re-encoding will be performed! However, Uri parsing will re-evaluate encoding of the resulting components.

        [scheme:][//authority][path][?query][#fragment]

        host and port may be undefined or invalid, in the optional authority.

        Parameters:
        scheme - the encoded scheme part of the Uri.
        authority - the encoded authority part of the Uri.
        path - the encoded path to the resource on the host.
        query - the encoded query part of the Uri to specify parameters for the resource.
        fragment - the encoded fragment part of the Uri.
        Throws:
        URISyntaxException - if the temporary created string doesn't fit to the specification RFC2396 or could not be parsed correctly.
      • valueOfFilepath

        public static Uri valueOfFilepath​(String path)
                                   throws URISyntaxException
        Creates a new Uri instance using the given file-path argument.

        This constructor first creates a temporary Uri string from the given components. This string will be parsed later on to create the Uri instance.

        file:path

        Parameters:
        path - the unencoded path of the file schema.
        Throws:
        URISyntaxException - if the temporary created string doesn't fit to the specification RFC2396 or could not be parsed correctly.
      • valueOf

        public static Uri valueOf​(File file)
                           throws URISyntaxException
        Creates a new Uri instance using the given File instance.

        This constructor first creates a temporary Uri string from the given components. This string will be parsed later on to create the Uri instance.

        file:path

        Parameters:
        file - using slashified absolute-path for the path of the file schema, utilizing valueOfFilepath(String).
        Throws:
        URISyntaxException - if the temporary created string doesn't fit to the specification RFC2396 or could not be parsed correctly.
      • valueOf

        public static Uri valueOf​(URI uri)
                           throws URISyntaxException
        Creates a new Uri instance using the given URI instance.

        Re-encoding will be performed if the given URI is not opaque.

        See PARSE_HINT_FIX_PATH for issues of injecting opaque URLs.

        Parameters:
        uri - A given URI instance
        Throws:
        URISyntaxException - if the temporary created string doesn't fit to the specification RFC2396 or could not be parsed correctly.
      • valueOf

        public static Uri valueOf​(URL url)
                           throws URISyntaxException
        Creates a new Uri instance using the given URL instance, convenient wrapper for valueOf(URI) and URL#toURI().

        Re-encoding will be performed if the given URL is not opaque, see valueOf(URI).

        See PARSE_HINT_FIX_PATH for issues of injecting opaque URLs.

        Parameters:
        url - A given URL instance
        Throws:
        URISyntaxException - if the temporary created string doesn't fit to the specification RFC2396 or could not be parsed correctly.
      • isFileScheme

        public final boolean isFileScheme()
        Returns true, if this instance is a file scheme, otherwise false.
      • isJarScheme

        public final boolean isJarScheme()
        Returns true, if this instance is a jar scheme, otherwise false.
        Since:
        2.3.2
      • getEncoded

        public final Uri.Encoded getEncoded()
        Returns the encoded input, never null.
      • toURI

        public final URI toURI()
        Returns a new URI instance using the encoded input string, new URI(uri.input), i.e. no re-encoding will be performed.
        See Also:
        #toURIReencoded(boolean), valueOf(URI)
      • toURIReencoded

        public final URI toURIReencoded()
                                 throws URISyntaxException
        Returns a new URI instance based upon this instance.

        All Uri parts of this instance will be decoded and encoded by the URI constructor, i.e. re-encoding will be performed.

        Throws:
        URISyntaxException - if the given string uri doesn't fit to the specification RFC2396 or could not be parsed correctly.
        See Also:
        toURI(), valueOf(URI)
      • toURL

        public final URL toURL()
                        throws MalformedURLException
        Returns a new URL instance using the encoded input string, new URL(uri.input), i.e. no re-encoding will be performed.
        Throws:
        MalformedURLException - if an error occurs while creating the URL or no protocol handler could be found.
      • toFile

        public final File toFile()
        If this instance is a file scheme, implementation decodes [ "//"+authority ] + path,
        then it processes the result if File.separatorChar == '\\' as follows:
        • slash -> backslash
        • drop a starting single backslash, preserving windows UNC
        and returns the resulting new File instance.

        Otherwise implementation returns null.

      • getContainedUri

        public final Uri getContainedUri()
                                  throws URISyntaxException
        If this instance's schemeSpecificPart contains a Uri itself, a sub-Uri, return schemeSpecificPart + # fragment via it's own new Uri instance.

        In case this Uri is a jar-scheme, the query is omitted, since it shall be invalid for jar-schemes anyway.

        Otherwise method returns null.

         Example 1:
             This instance: jar:scheme2:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class
             Returned Uri:  scheme2:/some/path/gluegen-rt.jar
        
         Example 2:
             This instance: jar:scheme2:/some/path/gluegen-rt.jar!/com/jogamp/common/GlueGenVersion.class?lala=01#fragment
             Returned Uri:  scheme2:/some/path/gluegen-rt.jar#fragment
        
         Example 3:
             This instance: scheme1:scheme2:/some/path/gluegen-rt.jar!/?lala=01#fragment
             Returned Uri:  scheme2:/some/path/gluegen-rt.jar?lala=01#fragment
         
        Throws:
        URISyntaxException - if this Uri is a container Uri and does not comply with the container spec, i.e. a JAR Uri
      • getNormalized

        public final Uri getNormalized()
        Normalizes this Uri's path and return the normalized form if it differs, otherwise this instance.

         Example-1:
             This instance  : jar:http://some/path/../gluegen-rt.jar!/com/Test.class?arg=1#frag
             Normalized     : jar:http://some/gluegen-rt.jar!/com/Test.class?arg=1#frag
        
         Example-2:
             This instance  : http://some/path/../gluegen-rt.jar?arg=1#frag
             Normalized     : http://some/gluegen-rt.jar?arg=1#frag
         

      • getDirectory

        public Uri getDirectory()
        Returns this Uri's directory Uri.

        This Uri path will be normalized before returning the directory.

        If this Uri's directory cannot be found, or already denotes a directory, method returns this instance.

         Example-1:
             this-uri: http:/some/path/gluegen-rt.jar?arg=1#frag
             result:   http:/some/path/?arg=1#frag
        
         Example-2:
             this-uri: file:/some/path/
             result:   file:/some/path/
        
         Example-3:
             this-uri: file:/some/path/lala/lili/../../hello.txt
             result:   file:/some/path/
         

        Throws:
        URISyntaxException - if the new string uri doesn't fit to the specification RFC2396 and RFC3986 or could not be parsed correctly.
      • getParent

        public final Uri getParent()
        Returns this Uri's parent directory Uri..

        This Uri path will be normalized before traversing up one directory.

        If a parent folder cannot be found, method returns null.

         Example-1:
             This instance  : jar:http://some/path/gluegen-rt.jar!/com/Test.class?arg=1#frag
             Returned Uri #1: jar:http://some/path/gluegen-rt.jar!/com/?arg=1#frag
             Returned Uri #2: jar:http://some/path/gluegen-rt.jar!/?arg=1#frag
             Returned Uri #3: null
        
         Example-2:
             This instance  : http://some/path/gluegen-rt.jar?arg=1#frag
             Returned Uri #1: http://some/path/?arg=1#frag
             Returned Uri #2: http://some/?arg=1#frag
             Returned Uri #2: null
        
         Example-3:
             This instance  : http://some/path/../gluegen-rt.jar?arg=1#frag
             Returned Uri #1: http://some/?arg=1#frag
             Returned Uri #2: null
         

      • getRelativeOf

        public Uri getRelativeOf​(Uri.Encoded appendPath)
                          throws URISyntaxException
        Returns a new Uri appending the given appendPath to this instance's directory.

        If appendPath is empty, method behaves like getNormalized().

        This resulting path will be normalized.

         Example-1:
             append: null
             this-uri: http:/some/path/gluegen-rt.jar
             result:   http:/some/path/gluegen-rt.jar
        
         Example-2:
             append: test.txt
             this-uri: file:/some/path/gluegen-rt.jar
             result:   file:/some/path/test.txt
        
         Example-3:
             append: test.txt
             this-uri: file:/some/path/lala/lili/../../hello.txt
             result:   file:/some/path/test.txt
         

        Parameters:
        appendPath - denotes a relative path to be appended to this Uri's directory
        Throws:
        URISyntaxException - if the resulting uri doesn't fit to the specification RFC2396 and RFC3986 or could not be parsed correctly.
      • getNewQuery

        public final Uri getNewQuery​(Uri.Encoded newQuery)
                              throws URISyntaxException
        Returns a new Uri instance w/ the given new query newQuery.
        Throws:
        URISyntaxException - if this Uri is opaque or if the new string uri doesn't fit to the specification RFC2396 and RFC3986 or could not be parsed correctly.
      • equals

        public final boolean equals​(Object o)

        Compares this Uri instance with the given argument o and determines if both are equal. Two Uri instances are equal if all single parts are identical in their meaning.

        Overrides:
        equals in class Object
        Parameters:
        o - the Uri this instance has to be compared with.
        Returns:
        true if both Uri instances point to the same resource, false otherwise.
      • hashCode

        public final int hashCode()

        Gets the hashcode value of this Uri instance.

        Overrides:
        hashCode in class Object