Uri
Date: 2016-06-25

org.osgi.service.dmt

## Class Uri

- java.lang.Object
- - org.osgi.service.dmt.Uri

-     public final class Uri
      extends java.lang.Object

  This class contains static utility methods to manipulate DMT URIs.

  Syntax of valid DMT URIs:

  - A slash (`'/'` \u002F) is the separator of the node names. Slashes used in node name must therefore be escaped using a backslash slash ( `"\/"`). The backslash must be escaped with a double backslash sequence. A backslash found must be ignored when it is not followed by a slash or backslash.
  - The node name can be constructed using full Unicode character set (except the Supplementary code, not being supported by CLDC/CDC). However, using the full Unicode character set for node names is discouraged because the encoding in the underlying storage as well as the encoding needed in communications can create significant performance and memory usage overhead. Names that are restricted to the URI set `[-a-zA-Z0-9_.!~*'()]` are most efficient.
  - URIs used in the DMT must be treated and interpreted as case sensitive.
  - No End Slash: URI must not end with the delimiter slash (`'/'` \u002F). This implies that the root node must be denoted as `"."` and not `"./"`.
  - No parent denotation: URI must not be constructed using the character sequence `"../"` to traverse the tree upwards.
  - Single Root: The character sequence `"./"` must not be used anywhere else but in the beginning of a URI.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `PATH_SEPARATOR` This constant stands for a string identifying the path separator in the DmTree ("/").
    `static char` | `PATH_SEPARATOR_CHAR` This constant stands for a char identifying the path separator in the DmTree ('/').
    `static java.lang.String` | `ROOT_NODE` This constant stands for a string identifying the root of the DmTree (".").
    `static char` | `ROOT_NODE_CHAR` This constant stands for a char identifying the root of the DmTree ('.').

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.String` | `decode(java.lang.String nodeName)` Decode the node name so that back slash and forward slash are unescaped from a back slash.
    `static java.lang.String` | `encode(java.lang.String nodeName)` Encode the node name so that back slash and forward slash are escaped with a back slash.
    `static boolean` | `isAbsoluteUri(java.lang.String uri)` Checks whether the specified URI is an absolute URI.
    `static boolean` | `isValidUri(java.lang.String uri)` Checks whether the specified URI is valid.
    `static java.lang.String` | `mangle(java.lang.String nodeName)` Returns a node name that is valid for the tree operation methods, based on the given node name.
    `static java.lang.String[]` | `toPath(java.lang.String uri)` Split the specified URI along the path separator '/' characters and return an array of URI segments.
    `static java.lang.String` | `toUri(java.lang.String[] path)` Construct a URI from the specified URI segments.

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

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

- - ### Field Detail

    - #### ROOT_NODE

          public static final java.lang.String ROOT_NODE

      This constant stands for a string identifying the root of the DmTree (".").
      Since:
        2.0
      See Also:
        Constant Field Values

    - #### ROOT_NODE_CHAR

          public static final char ROOT_NODE_CHAR

      This constant stands for a char identifying the root of the DmTree ('.').
      Since:
        2.0
      See Also:
        Constant Field Values

    - #### PATH_SEPARATOR

          public static final java.lang.String PATH_SEPARATOR

      This constant stands for a string identifying the path separator in the DmTree ("/").
      Since:
        2.0
      See Also:
        Constant Field Values

    - #### PATH_SEPARATOR_CHAR

          public static final char PATH_SEPARATOR_CHAR

      This constant stands for a char identifying the path separator in the DmTree ('/').
      Since:
        2.0
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### mangle

          public static java.lang.String mangle(java.lang.String nodeName)

      Returns a node name that is valid for the tree operation methods, based on the given node name. This transformation is not idempotent, so it must not be called with a parameter that is the result of a previous `mangle` method call.

      Node name mangling is needed in the following cases:

      - if the name contains '/' or '\' characters

      A node name that does not suffer from either of these problems is guaranteed to remain unchanged by this method. Therefore the client may skip the mangling if the node name is known to be valid (though it is always safe to call this method).

      The method returns the normalized `nodeName` as described below. Invalid node names are normalized in different ways, depending on the cause. If the name contains '/' or '\' characters, then these are simply escaped by inserting an additional '\' before each occurrence. If the length of the name does exceed the limit, the following mechanism is used to normalize it:

      - the SHA 1 digest of the name is calculated
      - the digest is encoded with the base 64 algorithm
      - all '/' characters in the encoded digest are replaced with '_'
      - trailing '=' signs are removed
      Parameters:
        `nodeName` - the node name to be mangled (if necessary), must not be `null` or empty
      Returns:
        the normalized node name that is valid for tree operations
      Throws:
        `java.lang.NullPointerException` - if `nodeName` is `null`
        `java.lang.IllegalArgumentException` - if `nodeName` is empty

    - #### toUri

          public static java.lang.String toUri(java.lang.String[] path)

      Construct a URI from the specified URI segments. The segments must already be mangled.

      If the specified path is an empty array then an empty URI (`""`) is returned.

      Parameters:
        `path` - a possibly empty array of URI segments, must not be `null`
      Returns:
        the URI created from the specified segments
      Throws:
        `java.lang.NullPointerException` - if the specified path or any of its segments are `null`
        `java.lang.IllegalArgumentException` - if the specified path contains too many or malformed segments or the resulting URI is too long

    - #### toPath

          public static java.lang.String[] toPath(java.lang.String uri)

      Split the specified URI along the path separator '/' characters and return an array of URI segments. Special characters in the returned segments are escaped. The returned array may be empty if the specified URI was empty.
      Parameters:
        `uri` - the URI to be split, must not be `null`
      Returns:
        an array of URI segments created by splitting the specified URI
      Throws:
        `java.lang.NullPointerException` - if the specified URI is `null`
        `java.lang.IllegalArgumentException` - if the specified URI is malformed

    - #### isAbsoluteUri

          public static boolean isAbsoluteUri(java.lang.String uri)

      Checks whether the specified URI is an absolute URI. An absolute URI contains the complete path to a node in the DMT starting from the DMT root (".").
      Parameters:
        `uri` - the URI to be checked, must not be `null` and must contain a valid URI
      Returns:
        whether the specified URI is absolute
      Throws:
        `java.lang.NullPointerException` - if the specified URI is `null`
        `java.lang.IllegalArgumentException` - if the specified URI is malformed

    - #### encode

          public static java.lang.String encode(java.lang.String nodeName)

      Encode the node name so that back slash and forward slash are escaped with a back slash. This method is the reverse of `decode(String)`.
      Parameters:
        `nodeName` - the node name to be encoded
      Returns:
        the encoded node name
      Since:
        2.0

    - #### decode

          public static java.lang.String decode(java.lang.String nodeName)

      Decode the node name so that back slash and forward slash are unescaped from a back slash.
      Parameters:
        `nodeName` - the node name to be decoded
      Returns:
        the decoded node name
      Since:
        2.0

    - #### isValidUri

          public static boolean isValidUri(java.lang.String uri)

      Checks whether the specified URI is valid. A URI is considered valid if it meets the following constraints:
      - the URI is not `null`;
      - the URI follows the syntax defined for valid DMT URIs;
      The exact definition of the length of a URI and its segments is given in the descriptions of the `getMaxUriLength()` and `getMaxSegmentNameLength()` methods.
      Parameters:
        `uri` - the URI to be validated
      Returns:
        whether the specified URI is valid