Package com.xmlmind.util

## Class URIComponent

- java.lang.Object
- - com.xmlmind.util.URIComponent

-     public final class URIComponent
      extends Object

  A collection of low-level utility functions (static methods) related to URI components (Strings, not `java.net.URI`).

  Refer to the documentation of `URI` for the definitions of quote, encode and decode.

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static String` | `decode​(String s)` | Equivalent to `decode(s, "UTF-8")`.
    `static String` | `decode​(String s, String charset)` | Decodes all `%HH` sequences.
    `static String` | `encode​(String s)` | Equivalent to `encode(s, "UTF-8")`.
    `static String` | `encode​(String s, String charset)` | Encodes non-ASCII characters, space characters (according to java.lang.Character.isSpaceChar) and control characters (according to java.lang.Character.isISOControl) as `%XX` bytes.
    `static String` | `getBaseName​(String path)` | Same as `getRawBaseName(java.lang.String)` except that the returned value is decoded using `decode(java.lang.String)`.
    `static String` | `getExtension​(String path)` | Same as `getRawExtension(java.lang.String)` except that the returned value is decoded using `decode(java.lang.String)`.
    `static String` | `getFragment​(String location)` | Same as `getRawFragment(java.lang.String)` except that the returned value is decoded using `decode(java.lang.String)`.
    `static String` | `getRawBaseName​(String path)` | Returns the base name of specified path.
    `static String` | `getRawExtension​(String path)` | Returns the extension of specified path.
    `static String` | `getRawFragment​(String location)` | Returns the fragment component (not including the '`#`' delimiter) of specified location if any; `null` otherwise.
    `static String` | `getRawParentPath​(String path)` | Equivalent to `getRawParentPath(path, true)`.
    `static String` | `getRawParentPath​(String path, boolean trailingSlash)` | Returns the parent of specified path.
    `static String` | `getRawQuery​(String location)` | Returns the query component (not including the '`?`' delimiter) of specified location if any; `null` otherwise.
    `static String` | `getRawRelativePath​(String path, String basePath)` | Returns first path as a path relative to the second path.
    `static String` | `joinQuotedComponents​(String scheme, String userName, String userPassword, String host, int port, String path, String query, String fragment)` | Joins specified URI components, without attempting to quote them.
    `static String` | `quoteFragment​(String fragment)` | Quotes specified fragment (that is, escapes ``special'' characters).
    `static String` | `quoteFullPath​(String path)` | Quotes specified path (that is, escapes ``special'' characters).
    `static void` | `quoteFullPath​(String path, StringBuilder buffer)` | Similar tp `quoteFullPath(String)` but appends quoted path to specified buffer.
    `static String` | `quotePath​(String path)` | Quotes specified path (that is, escapes ``special'' characters).
    `static String` | `quoteQuery​(String query)` | Quotes specified query (that is, escapes ``special'' characters).
    `static String` | `quoteUserInfo​(String userInfo)` | Quotes specified user info (that is, escapes ``special'' characters).
    `static String` | `setExtension​(String path, String extension)` | Same as `setRawExtension(java.lang.String, java.lang.String)` except that `extension` is quoted using `quotePath(java.lang.String)`.
    `static String` | `setFragment​(String location, String fragment)` | Same as `setRawFragment(java.lang.String, java.lang.String)` except that `fragment` is quoted using `quoteFragment(java.lang.String)`.
    `static String` | `setRawExtension​(String path, String extension)` | Changes the extension of specified path to specified extension.
    `static String` | `setRawFragment​(String location, String fragment)` | Changes the fragment component of specified location to specified fragment.
    `static String` | `setRawQuery​(String location, String query)` | Changes the query component of specified location to specified query.
    `static String` | `truncatePath​(String path, int maxLength)` | Truncates specified path to get something short enough to be displayed in the "Recently Opened Files" part of a File menu.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### getRawParentPath

          public static String getRawParentPath​(String path)

      Equivalent to `getRawParentPath(path, true)`.

    - #### getRawParentPath

          public static String getRawParentPath​(String path,
                                                boolean trailingSlash)

      Returns the parent of specified path. To make it simple, the substring before last '/'.

      Examples:

      - Returns `null` for "`/`".
      - Returns `null` for "`foo`".
      - Returns "`/`" for "`/foo`".
      - Returns "`/foo`" (or "`/foo/`") for "`/foo/bar`".
      - Returns "`/foo`" (or "`/foo/`") for "`/foo/bar/`".
      Parameters:
        `path` - relative or absolute URI path
        `trailingSlash` - if `true`, returned path ends with a trailing '/' character
      Returns:
        parent of specified path or `null` for '/' or if specified path does not contain the '/' character

    - #### getBaseName

          public static String getBaseName​(String path)

      Same as `getRawBaseName(java.lang.String)` except that the returned value is decoded using `decode(java.lang.String)`.

    - #### getRawBaseName

          public static String getRawBaseName​(String path)

      Returns the base name of specified path. To make it simple, the substring after last '/'.

      Examples:

      - Returns the empty string for "`/`".
      - Returns "`foo`" for "`foo`".
      - Returns "`bar`" for "`/foo/bar`".
      - Returns "`bar`" for "`/foo/bar/`".
      Parameters:
        `path` - relative or absolute URI path
      Returns:
        base name of specified path

    - #### getExtension

          public static String getExtension​(String path)

      Same as `getRawExtension(java.lang.String)` except that the returned value is decoded using `decode(java.lang.String)`.

    - #### getRawExtension

          public static String getRawExtension​(String path)

      Returns the extension of specified path. To make it simple, the substring after last '.', not including last '.'.
      - Returns `null` for "`/tmp/test`".
      - Returns the empty string for "`/tmp/test.`".
      - Returns `null` for "`~/.profile`".
      - Returns "`gz`" for "`/tmp/test.tar.gz`".
      Parameters:
        `path` - relative or absolute URI path possibly having an extension
      Returns:
        extension if any; `null` otherwise

    - #### setExtension

          public static String setExtension​(String path,
                                            String extension)

      Same as `setRawExtension(java.lang.String, java.lang.String)` except that `extension` is quoted using `quotePath(java.lang.String)`.

    - #### setRawExtension

          public static String setRawExtension​(String path,
                                               String extension)

      Changes the extension of specified path to specified extension. See `getRawExtension(java.lang.String)` for a description of the extension of a path.
      Parameters:
        `path` - relative or absolute URI path
        `extension` - new extension. Assumed to have been quoted using `quotePath(java.lang.String)`. May be `null` which means: remove the extension.
      Returns:
        a path identical to `path` except that its extension has been changed or removed.

        Returns same path if specified path ends with '/'.

    - #### getFragment

          public static String getFragment​(String location)

      Same as `getRawFragment(java.lang.String)` except that the returned value is decoded using `decode(java.lang.String)`.

    - #### getRawFragment

          public static String getRawFragment​(String location)

      Returns the fragment component (not including the '`#`' delimiter) of specified location if any; `null` otherwise.

    - #### setFragment

          public static String setFragment​(String location,
                                           String fragment)

      Same as `setRawFragment(java.lang.String, java.lang.String)` except that `fragment` is quoted using `quoteFragment(java.lang.String)`.

    - #### setRawFragment

          public static String setRawFragment​(String location,
                                              String fragment)

      Changes the fragment component of specified location to specified fragment.
      Parameters:
        `location` - relative or absolute location
        `fragment` - new fragment. Assumed to have been quoted using `quoteFragment(java.lang.String)`. May be `null` which means: remove the fragment.
      Returns:
        a location identical to `location` except that its fragment has been changed or removed

    - #### getRawQuery

          public static String getRawQuery​(String location)

      Returns the query component (not including the '`?`' delimiter) of specified location if any; `null` otherwise.

    - #### setRawQuery

          public static String setRawQuery​(String location,
                                           String query)

      Changes the query component of specified location to specified query.
      Parameters:
        `location` - relative or absolute location
        `query` - new query. Assumed to have been quoted using `quoteQuery(java.lang.String)`. May be `null` which means: remove the query.
      Returns:
        a location identical to `location` except that its query has been changed or removed

    - #### getRawRelativePath

          public static String getRawRelativePath​(String path,
                                                  String basePath)

      Returns first path as a path relative to the second path.

      The returned result resolved against the second path gives back first path. This means that trailing slashes "/" are significant.

      Examples:

      - Returns "`gee`" for "`gee`" relative to "`/foo/bar/wiz`".
      - Returns "`/foo/bar/gee`" for "`/foo/bar/gee`" relative to "`wiz`".
      - Returns "`foo/bar/gee`" for "`/foo/bar/gee`" relative to "`/`".
      - Returns "`bar/gee`" for "`/foo/bar/gee`" relative to "`/foo/bar`".
      - Returns "`gee`" for "`/foo/bar/gee`" relative to "`/foo/bar/wiz`".
      - Returns "`../gee`" for "`/foo/bar/gee`" relative to "`/foo/bar/wiz/`".
      - Returns "`gee/`" for "`/foo/bar/gee/`" relative to "`/foo/bar/wiz`".
      - Returns "`../gee/`" for "`/foo/bar/gee/`" relative to "`/foo/bar/wiz/`".
      - Returns "`/`" for "`/`" relative to "`/`".
      - Returns "`gee`" for "`/foo/bar/gee`" relative to "`/foo/bar/gee`".
      Parameters:
        `path` - an absolute URI path
        `basePath` - another absolute URI path
      Returns:
        first path as a path relative to the second path. Returns first path as is, if the relative path cannot be computed.

    - #### truncatePath

          public static String truncatePath​(String path,
                                            int maxLength)

      Truncates specified path to get something short enough to be displayed in the "Recently Opened Files" part of a File menu. Example: returns "/home/john/.../report1.xml" for "/home/john/docs/report1/report1.xml".
      Parameters:
        `path` - relative or absolute URI path to be truncated
        `maxLength` - maximum length for truncated (this is just a hint); typically 40
      Returns:
        truncated path

    - #### joinQuotedComponents

          public static String joinQuotedComponents​(String scheme,
                                                    String userName,
                                                    String userPassword,
                                                    String host,
                                                    int port,
                                                    String path,
                                                    String query,
                                                    String fragment)

      Joins specified URI components, without attempting to quote them. Pass `null` or -1 for missing components.
      Parameters:
        `scheme` - scheme or `null`
        `userName` - properly quoted user name or `null`
        `userPassword` - properly quoted password or `null`
        `host` - host or `null`
        `port` - port or -1
        `path` - properly quoted path or `null`
        `query` - properly quoted query (without '?') or `null`
        `fragment` - properly quoted fragment (without '#') or `null`
      Returns:
        URI spec

    - #### quoteUserInfo

          public static String quoteUserInfo​(String userInfo)

      Quotes specified user info (that is, escapes ``special'' characters).

      Use this function separately on the user name and on the user password. That is, do not use it on "name:password".

      Like all `quote` functions, the returned string may contain characters belonging to the other category (e.g. non-ASCII characters).

    - #### quotePath

          public static String quotePath​(String path)

      Quotes specified path (that is, escapes ``special'' characters).

      Use this function separately on each path segment. That is, do not use it on something like "`foo/bar/gee`".

      Like all `quote` functions, the returned string may contain characters belonging to the other category (e.g. non-ASCII characters).

      See Also:
        `quoteFullPath(String)`, `quoteFullPath(String, StringBuilder)`

    - #### quoteFullPath

          public static String quoteFullPath​(String path)

      Quotes specified path (that is, escapes ``special'' characters). Unlike `quotePath(java.lang.String)` which only works for path segments, this method can be used to quote a relative or absolute path.

      Like all `quote` functions, the returned string may contain characters belonging to the other category (e.g. non-ASCII characters).

    - #### quoteFullPath

          public static void quoteFullPath​(String path,
                                           StringBuilder buffer)

      Similar tp `quoteFullPath(String)` but appends quoted path to specified buffer.

    - #### quoteQuery

          public static String quoteQuery​(String query)

      Quotes specified query (that is, escapes ``special'' characters).

      Like all `quote` functions, the returned string may contain characters belonging to the other category (e.g. non-ASCII characters).

    - #### quoteFragment

          public static String quoteFragment​(String fragment)

      Quotes specified fragment (that is, escapes ``special'' characters).

      Returned string contains only ASCII characters.

      Like all `quote` functions, the returned string may contain characters belonging to the other category (e.g. non-ASCII characters).

    - #### decode

          public static String decode​(String s)

      Equivalent to `decode(s, "UTF-8")`.

    - #### decode

          public static String decode​(String s,
                                      String charset)

      Decodes all `%HH` sequences.

      This function should be used on individual components. For example, it can be used on "foo" and on "bar" and not on "/foo/bar" as a whole.

      `encode(String, String)` and `decode(String, String)` are not inverse operations:

      - `encode` encodes only spaces and accented characters (to make it simple).
      - `decode` replaces all `%HH` sequences by the corresponding characters.
      Parameters:
        `s` - string to be decoded
        `charset` - the encoding used for characters in the other category. A superset of US-ASCII. Examples: "ISO-8859-1" (eacute is represented as "%E9"), "UTF-8" (eacute is represented as "%C3%A9").

        For interoperability with `URI`, `charset` is required to be "UTF-8".

      Returns:
        the decoded string or `null` if `charset` is an unsupported encoding

    - #### encode

          public static String encode​(String s)

      Equivalent to `encode(s, "UTF-8")`.

    - #### encode

          public static String encode​(String s,
                                      String charset)

      Encodes non-ASCII characters, space characters (according to java.lang.Character.isSpaceChar) and control characters (according to java.lang.Character.isISOControl) as `%XX` bytes. That is, escape any character which is unambiguously illegal according to RFC2396.

      `encode(String, String)` and `decode(String, String)` are not inverse operations:

      - `encode` encodes only spaces and accented characters (to make it simple).
      - `decode` replaces all `%HH` sequences by the corresponding characters.
      Parameters:
        `s` - string to be encode
        `charset` - the encoding used for the aforementioned ``illegal'' characters. A superset of US-ASCII.

        For interoperability with `URI`, `charset` is required to be "UTF-8".

      Returns:
        the encoded string or `null` if `charset` is an unsupported encoding