DmtAdmin
Date: 2016-06-25

org.osgi.service.dmt

## Interface DmtAdmin

-     public interface DmtAdmin

  An interface providing methods to open sessions and register listeners. The implementation of `DmtAdmin` should register itself in the OSGi service registry as a service. `DmtAdmin` is the entry point for applications to use the DMT API.

  The `getSession` methods are used to open a session on a specified subtree of the DMT. A typical way of usage:

       serviceRef = context.getServiceReference(DmtAdmin.class.getName());
       DmtAdmin admin = (DmtAdmin) context.getService(serviceRef);
       DmtSession session = admin.getSession("./OSGi/Configuration");
       session.createInteriorNode("./OSGi/Configuration/my.table");

  The methods for opening a session take a node URI (the session root) as a parameter. All segments of the given URI must be within the segment length limit of the implementation, and the special characters '/' and '\' must be escaped (preceded by a '\').

  See the `Uri.encode(String)` method for support on escaping invalid characters in a URI.

  It is possible to specify a lock mode when opening the session (see lock type constants in `DmtSession`). This determines whether the session can run in parallel with other sessions, and the kinds of operations that can be performed in the session. All Management Objects constituting the device management tree must support read operations on their nodes, while support for write operations depends on the Management Object. Management Objects supporting write access may support transactional write, non-transactional write or both. Users of `DmtAdmin` should consult the Management Object specification and implementation for the supported update modes. If Management Object definition permits, implementations are encouraged to support both update modes.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `DmtSession` | `getSession(java.lang.String subtreeUri)` Opens a `DmtSession` for local usage on a given subtree of the DMT with non transactional write lock.
    `DmtSession` | `getSession(java.lang.String subtreeUri, int lockMode)` Opens a `DmtSession` for local usage on a specific DMT subtree with a given lock mode.
    `DmtSession` | `getSession(java.lang.String principal, java.lang.String subtreeUri, int lockMode)` Opens a `DmtSession` on a specific DMT subtree using a specific lock mode on behalf of a remote principal.

- - ### Method Detail

    - #### getSession

          DmtSession getSession(java.lang.String subtreeUri)
                                throws DmtException

      Opens a `DmtSession` for local usage on a given subtree of the DMT with non transactional write lock. This call is equivalent to the following: `getSession(null, subtreeUri, DmtSession.LOCK_TYPE_EXCLUSIVE)`

      The `subtreeUri` parameter must contain an absolute URI. It can also be `null`, in this case the session is opened with the default session root, ".", that gives access to the whole tree.

      To perform this operation the caller must have `DmtPermission` for the `subtreeUri` node with the Get action present.

      Parameters:
        `subtreeUri` - the subtree on which DMT manipulations can be performed within the returned session
      Returns:
        a `DmtSession` object for the requested subtree
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `subtreeUri` is syntactically invalid
        - `URI_TOO_LONG` if `subtreeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `subtreeUri` specifies a non-existing node
        - `SESSION_CREATION_TIMEOUT` if the operation timed out because of another ongoing session
        - `COMMAND_FAILED` if `subtreeUri` specifies a relative URI, or some unspecified error is encountered while attempting to complete the command
        `java.lang.SecurityException` - if the caller does not have `DmtPermission` for the given root node with the Get action present

    - #### getSession

          DmtSession getSession(java.lang.String subtreeUri,
                              int lockMode)
                                throws DmtException

      Opens a `DmtSession` for local usage on a specific DMT subtree with a given lock mode. This call is equivalent to the following: `getSession(null, subtreeUri, lockMode)`

      The `subtreeUri` parameter must contain an absolute URI. It can also be `null`, in this case the session is opened with the default session root, ".", that gives access to the whole tree.

      To perform this operation the caller must have `DmtPermission` for the `subtreeUri` node with the Get action present.

      Parameters:
        `subtreeUri` - the subtree on which DMT manipulations can be performed within the returned session
        `lockMode` - one of the lock modes specified in `DmtSession`
      Returns:
        a `DmtSession` object for the requested subtree
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `subtreeUri` is syntactically invalid
        - `URI_TOO_LONG` if `subtreeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `subtreeUri` specifies a non-existing node
        - `FEATURE_NOT_SUPPORTED` if atomic sessions are not supported by the implementation and `lockMode` requests an atomic session
        - `SESSION_CREATION_TIMEOUT` if the operation timed out because of another ongoing session
        - `COMMAND_FAILED` if `subtreeUri` specifies a relative URI, if `lockMode` is unknown, or some unspecified error is encountered while attempting to complete the command
        `java.lang.SecurityException` - if the caller does not have `DmtPermission` for the given root node with the Get action present

    - #### getSession

          DmtSession getSession(java.lang.String principal,
                              java.lang.String subtreeUri,
                              int lockMode)
                                throws DmtException

      Opens a `DmtSession` on a specific DMT subtree using a specific lock mode on behalf of a remote principal. If local management applications are using this method then they should provide `null` as the first parameter. Alternatively they can use other forms of this method without providing a principal string.

      The `subtreeUri` parameter must contain an absolute URI. It can also be `null`, in this case the session is opened with the default session root, ".", that gives access to the whole tree.

      This method is guarded by `DmtPrincipalPermission` in case of remote sessions. In addition, the caller must have Get access rights (ACL in case of remote sessions, `DmtPermission` in case of local sessions) on the `subtreeUri` node to perform this operation.

      Parameters:
        `principal` - the identifier of the remote server on whose behalf the data manipulation is performed, or `null` for local sessions
        `subtreeUri` - the subtree on which DMT manipulations can be performed within the returned session
        `lockMode` - one of the lock modes specified in `DmtSession`
      Returns:
        a `DmtSession` object for the requested subtree
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `subtreeUri` is syntactically invalid
        - `URI_TOO_LONG` if `subtreeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `subtreeUri` specifies a non-existing node
        - `PERMISSION_DENIED` if `principal` is not `null` and the ACL of the node does not allow the `Get` operation for the principal on the given root node
        - `FEATURE_NOT_SUPPORTED` if atomic sessions are not supported by the implementation and `lockMode` requests an atomic session
        - `SESSION_CREATION_TIMEOUT` if the operation timed out because of another ongoing session
        - `COMMAND_FAILED` if `subtreeUri` specifies a relative URI, if `lockMode` is unknown, or some unspecified error is encountered while attempting to complete the command
        `java.lang.SecurityException` - in case of remote sessions, if the caller does not have the required `DmtPrincipalPermission` with a target matching the `principal` parameter, or in case of local sessions, if the caller does not have `DmtPermission` for the given root node with the Get action present