Class Uri

Method Details

• 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(Uri.Encoded encoded)

  Safe Uri.Encoded.decode() call on optional encoded instance.

  Parameters:

  encoded - Uri.Encoded instance to be decoded, may be null.

  Returns:

  the decoded String or null if encoded was null.

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

• cast

  public static Uri cast(String encodedUri) throws URISyntaxException

  Casts the given encoded String to a new Encoded instance used to create the resulting Uri instance via Uri(Encoded).

  No encoding will be performed on the given encodedUri, use with care.

  Throws:

  URISyntaxException

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

• toString

  public final String toString()

  Returns the encoded input as String, never null, same as getEncoded().

  Overrides:

  toString in class Object

• toASCIIString

  public Uri.ASCIIEncoded toASCIIString()

  Returns the encoded input encoded in US-ASCII.

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

• concat

  public final Uri concat(Uri.Encoded suffix) throws URISyntaxException

  Concatenates the given encoded string to the encoded uri of this instance and returns a new Uri instance with the result.

  Throws:

  URISyntaxException - if the concatenated string 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