DmtSession
Date: 2016-06-25

org.osgi.service.dmt

## Interface DmtSession

-     public interface DmtSession

  DmtSession provides concurrent access to the DMT. All DMT manipulation commands for management applications are available on the `DmtSession` interface. The session is associated with a root node which limits the subtree in which the operations can be executed within this session.

  Most of the operations take a node URI as parameter, which can be either an absolute URI (starting with "./") or a URI relative to the root node of the session. The empty string as relative URI means the root URI the session was opened with. All segments of a 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.

  If the URI specified does not correspond to a legitimate node in the tree an exception is thrown. The only exception is the `isNodeUri(String)` method which returns `false` in case of an invalid URI.

  Each method of `DmtSession` that accesses the tree in any way can throw `DmtIllegalStateException` if the session has been closed or invalidated (due to timeout, fatal exceptions, or unexpectedly unregistered plugins).

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `LOCK_TYPE_ATOMIC` `LOCK_TYPE_ATOMIC` is an exclusive lock with transactional functionality.
    `static int` | `LOCK_TYPE_EXCLUSIVE` `LOCK_TYPE_EXCLUSIVE` lock guarantees full access to the tree, but can not be shared with any other locks.
    `static int` | `LOCK_TYPE_SHARED` Sessions created with `LOCK_TYPE_SHARED` lock allows read-only access to the tree, but can be shared between multiple readers.
    `static int` | `STATE_CLOSED` The session is closed, DMT manipulation operations are not available, they throw `DmtIllegalStateException` if tried.
    `static int` | `STATE_INVALID` The session is invalid because a fatal error happened.
    `static int` | `STATE_OPEN` The session is open, all session operations are available.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes a session.
    `void` | `commit()` Commits a series of DMT operations issued in the current atomic session since the last transaction boundary.
    `void` | `copy(java.lang.String nodeUri, java.lang.String newNodeUri, boolean recursive)` Create a copy of a node or a whole subtree.
    `void` | `createInteriorNode(java.lang.String nodeUri)` Create an interior node.
    `void` | `createInteriorNode(java.lang.String nodeUri, java.lang.String type)` Create an interior node with a given type.
    `void` | `createLeafNode(java.lang.String nodeUri)` Create a leaf node with default value and MIME type.
    `void` | `createLeafNode(java.lang.String nodeUri, DmtData value)` Create a leaf node with a given value and the default MIME type.
    `void` | `createLeafNode(java.lang.String nodeUri, DmtData value, java.lang.String mimeType)` Create a leaf node with a given value and MIME type.
    `void` | `deleteNode(java.lang.String nodeUri)` Delete the given node.
    `void` | `execute(java.lang.String nodeUri, java.lang.String data)` Executes a node.
    `void` | `execute(java.lang.String nodeUri, java.lang.String correlator, java.lang.String data)` Executes a node, also specifying a correlation ID for use in response notifications.
    `java.lang.String[]` | `getChildNodeNames(java.lang.String nodeUri)` Get the list of children names of a node.
    `Acl` | `getEffectiveNodeAcl(java.lang.String nodeUri)` Gives the Access Control List in effect for a given node.
    `int` | `getLockType()` Gives the type of lock the session has.
    `MetaNode` | `getMetaNode(java.lang.String nodeUri)` Get the meta data which describes a given node.
    `Acl` | `getNodeAcl(java.lang.String nodeUri)` Get the Access Control List associated with a given node.
    `int` | `getNodeSize(java.lang.String nodeUri)` Get the size of the data in a leaf node.
    `java.util.Date` | `getNodeTimestamp(java.lang.String nodeUri)` Get the timestamp when the node was created or last modified.
    `java.lang.String` | `getNodeTitle(java.lang.String nodeUri)` Get the title of a node.
    `java.lang.String` | `getNodeType(java.lang.String nodeUri)` Get the type of a node.
    `DmtData` | `getNodeValue(java.lang.String nodeUri)` Get the data contained in a leaf or interior node.
    `int` | `getNodeVersion(java.lang.String nodeUri)` Get the version of a node.
    `java.lang.String` | `getPrincipal()` Gives the name of the principal on whose behalf the session was created.
    `java.lang.String` | `getRootUri()` Get the root URI associated with this session.
    `int` | `getSessionId()` The unique identifier of the session.
    `int` | `getState()` Get the current state of this session.
    `boolean` | `isLeafNode(java.lang.String nodeUri)` Tells whether a node is a leaf or an interior node of the DMT.
    `boolean` | `isNodeUri(java.lang.String nodeUri)` Check whether the specified URI corresponds to a valid node in the DMT.
    `void` | `renameNode(java.lang.String nodeUri, java.lang.String newName)` Rename a node.
    `void` | `rollback()` Rolls back a series of DMT operations issued in the current atomic session since the last transaction boundary.
    `void` | `setDefaultNodeValue(java.lang.String nodeUri)` Set the value of a leaf or interior node to its default.
    `void` | `setNodeAcl(java.lang.String nodeUri, Acl acl)` Set the Access Control List associated with a given node.
    `void` | `setNodeTitle(java.lang.String nodeUri, java.lang.String title)` Set the title property of a node.
    `void` | `setNodeType(java.lang.String nodeUri, java.lang.String type)` Set the type of a node.
    `void` | `setNodeValue(java.lang.String nodeUri, DmtData data)` Set the value of a leaf or interior node.

- - ### Field Detail

    - #### LOCK_TYPE_SHARED

          static final int LOCK_TYPE_SHARED

      Sessions created with `LOCK_TYPE_SHARED` lock allows read-only access to the tree, but can be shared between multiple readers.
      See Also:
        Constant Field Values

    - #### LOCK_TYPE_EXCLUSIVE

          static final int LOCK_TYPE_EXCLUSIVE

      `LOCK_TYPE_EXCLUSIVE` lock guarantees full access to the tree, but can not be shared with any other locks.
      See Also:
        Constant Field Values

    - #### LOCK_TYPE_ATOMIC

          static final int LOCK_TYPE_ATOMIC

      `LOCK_TYPE_ATOMIC` is an exclusive lock with transactional functionality. Commands of an atomic session will either fail or succeed together, if a single command fails then the whole session will be rolled back.
      See Also:
        Constant Field Values

    - #### STATE_OPEN

          static final int STATE_OPEN

      The session is open, all session operations are available.
      See Also:
        Constant Field Values

    - #### STATE_CLOSED

          static final int STATE_CLOSED

      The session is closed, DMT manipulation operations are not available, they throw `DmtIllegalStateException` if tried.
      See Also:
        Constant Field Values

    - #### STATE_INVALID

          static final int STATE_INVALID

      The session is invalid because a fatal error happened. Fatal errors include the timeout of the session, any DmtException with the 'fatal' flag set, or the case when a plugin service is unregistered while in use by the session. DMT manipulation operations are not available, they throw `DmtIllegalStateException` if tried.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getState

          int getState()

      Get the current state of this session.
      Returns:
        the state of the session, one of `STATE_OPEN`, `STATE_CLOSED` and `STATE_INVALID`

    - #### getLockType

          int getLockType()

      Gives the type of lock the session has.
      Returns:
        the lock type of the session, one of `LOCK_TYPE_SHARED`, `LOCK_TYPE_EXCLUSIVE` and `LOCK_TYPE_ATOMIC`

    - #### getPrincipal

          java.lang.String getPrincipal()

      Gives the name of the principal on whose behalf the session was created. Local sessions do not have an associated principal, in this case `null` is returned.
      Returns:
        the identifier of the remote server that initiated the session, or `null` for local sessions

    - #### getSessionId

          int getSessionId()

      The unique identifier of the session. The ID is generated automatically, and it is guaranteed to be unique on a machine for a specific Dmt Admin. A session id must be larger than 0.
      Returns:
        the session identification number

    - #### getRootUri

          java.lang.String getRootUri()

      Get the root URI associated with this session. Gives "`.`" if the session was created without specifying a root, which means that the target of this session is the whole DMT.
      Returns:
        the root URI

    - #### commit

          void commit()
                      throws DmtException

      Commits a series of DMT operations issued in the current atomic session since the last transaction boundary. Transaction boundaries are the creation of this object that starts the session, and all subsequent `commit()` and `rollback()` calls.

      This method can fail even if all operations were successful. This can happen due to some multi-node semantic constraints defined by a specific implementation. For example, node A can be required to always have children A/B, A/C and A/D. If this condition is broken when `commit()` is executed, the method will fail, and throw a `METADATA_MISMATCH` exception.

      An error situation can arise due to the lack of a two phase commit mechanism in the underlying plugins. As an example, if plugin A has committed successfully but plugin B failed, the whole session must fail, but there is no way to undo the commit performed by A. To provide predictable behavior, the commit operation should continue with the remaining plugins even after detecting a failure. All exceptions received from failed commits are aggregated into one `TRANSACTION_ERROR` exception thrown by this method.

      In many cases the tree is not the only way to manage a given part of the system. It may happen that while modifying some nodes in an atomic session, the underlying settings are modified in parallel outside the scope of the DMT. If this is detected during commit, an exception with the code `CONCURRENT_ACCESS` is thrown.

      Throws:
        `DmtException` - with the following possible error codes:
        - `METADATA_MISMATCH` if the operation failed because of meta-data restrictions
        - `CONCURRENT_ACCESS` if it is detected that some modification has been made outside the scope of the DMT to the nodes affected in the session's operations
        - `TRANSACTION_ERROR` if an error occurred during the commit of any of the underlying plugins
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session was not opened using the `LOCK_TYPE_ATOMIC` lock type, or if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation

    - #### rollback

          void rollback()
                        throws DmtException

      Rolls back a series of DMT operations issued in the current atomic session since the last transaction boundary. Transaction boundaries are the creation of this object that starts the session, and all subsequent `commit()` and `rollback()` calls.
      Throws:
        `DmtException` - with the error code `ROLLBACK_FAILED` in case the rollback did not succeed
        `DmtIllegalStateException` - if the session was not opened using the `LOCK_TYPE_ATOMIC` lock type, or if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation

    - #### close

          void close()
                     throws DmtException

      Closes a session. If the session was opened with atomic lock mode, the `DmtSession` must first persist the changes made to the DMT by calling `commit()` on all (transactional) plugins participating in the session. See the documentation of the `commit()` method for details and possible errors during this operation.

      The state of the session changes to `DmtSession.STATE_CLOSED` if the close operation completed successfully, otherwise it becomes `DmtSession.STATE_INVALID`.

      Throws:
        `DmtException` - with the following possible error codes:
        - `METADATA_MISMATCH` in case of atomic sessions, if the commit operation failed because of meta-data restrictions
        - `CONCURRENT_ACCESS` in case of atomic sessions, if the commit operation failed because of some modification outside the scope of the DMT to the nodes affected in the session
        - `TRANSACTION_ERROR` in case of atomic sessions, if an underlying plugin failed to commit
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if an underlying plugin failed to close, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation

    - #### execute

          void execute(java.lang.String nodeUri,
                     java.lang.String data)
                       throws DmtException

      Executes a node. This corresponds to the EXEC operation in OMA DM. This method cannot be called in a read-only session.

      The semantics of an execute operation and the data parameter it takes depends on the definition of the managed object on which the command is issued.

      Parameters:
        `nodeUri` - the node on which the execute operation is issued
        `data` - the parameter of the execute operation, can be `null`
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if the node does not exist
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node does not allow the `Execute` operation for the associated principal
        - `COMMAND_NOT_ALLOWED` if the specified node is a scaffold node
        - `METADATA_MISMATCH` if the node cannot be executed according to the meta-data (does not have `MetaNode.CMD_EXECUTE` access type)
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, if no DmtExecPlugin is associated with the node and the DmtAdmin can not execute the node, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session was opened using the `LOCK_TYPE_SHARED` lock type, or if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the node with the Exec action present
      See Also:
        `execute(String, String, String)`

    - #### execute

          void execute(java.lang.String nodeUri,
                     java.lang.String correlator,
                     java.lang.String data)
                       throws DmtException

      Executes a node, also specifying a correlation ID for use in response notifications. This operation corresponds to the EXEC command in OMA DM. This method cannot be called in a read-only session.

      The semantics of an execute operation and the data parameter it takes depends on the definition of the managed object on which the command is issued. If a correlation ID is specified, it should be used as the `correlator` parameter for notifications sent in response to this execute operation.

      Parameters:
        `nodeUri` - the node on which the execute operation is issued
        `correlator` - an identifier to associate this operation with any notifications sent in response to it, can be `null` if not needed
        `data` - the parameter of the execute operation, can be `null`
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if the node does not exist
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node does not allow the `Execute` operation for the associated principal
        - `COMMAND_NOT_ALLOWED` if the specified node is a scaffold node
        - `METADATA_MISMATCH` if the node cannot be executed according to the meta-data (does not have `MetaNode.CMD_EXECUTE` access type)
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, if no DmtExecPlugin is associated with the node, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session was opened using the `LOCK_TYPE_SHARED` lock type, or if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the node with the Exec action present
      See Also:
        `execute(String, String)`

    - #### getNodeAcl

          Acl getNodeAcl(java.lang.String nodeUri)
                         throws DmtException

      Get the Access Control List associated with a given node. The returned `Acl` object does not take inheritance into account, it gives the ACL specifically given to the node.
      Parameters:
        `nodeUri` - the URI of the node
      Returns:
        the Access Control List belonging to the node or `null` if none defined
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a non-existing node
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node does not allow the `Get` operation for the associated principal
        - `METADATA_MISMATCH` if node information cannot be retrieved according to the meta-data (the node does not have `MetaNode.CMD_GET` access type)
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session is already closed or invalidated
        `java.lang.SecurityException` - in case of local sessions, if the caller does not have `DmtPermission` for the node with the Get action present
      See Also:
        `getEffectiveNodeAcl(String)`

    - #### getEffectiveNodeAcl

          Acl getEffectiveNodeAcl(java.lang.String nodeUri)
                                  throws DmtException

      Gives the Access Control List in effect for a given node. The returned `Acl` takes inheritance into account, that is if there is no ACL defined for the node, it will be derived from the closest ancestor having an ACL defined.
      Parameters:
        `nodeUri` - the URI of the node
      Returns:
        the Access Control List belonging to the node
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a non-existing node
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node does not allow the `Get` operation for the associated principal
        - `METADATA_MISMATCH` if node information cannot be retrieved according to the meta-data (the node does not have `MetaNode.CMD_GET` access type)
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session is already closed or invalidated
        `java.lang.SecurityException` - in case of local sessions, if the caller does not have `DmtPermission` for the node with the Get action present
      See Also:
        `getNodeAcl(String)`

    - #### setNodeAcl

          void setNodeAcl(java.lang.String nodeUri,
                        Acl acl)
                          throws DmtException

      Set the Access Control List associated with a given node. To perform this operation, the caller needs to have replace rights (`Acl.REPLACE` or the corresponding Java permission depending on the session type) as described below:
      - if `nodeUri` specifies a leaf node, replace rights are needed on the parent of the node
      - if `nodeUri` specifies an interior node, replace rights on either the node or its parent are sufficient

      If the given `acl` is `null` or an empty ACL (not specifying any permissions for any principals), then the ACL of the node is deleted, and the node will inherit the ACL from its parent node.

      Parameters:
        `nodeUri` - the URI of the node
        `acl` - the Access Control List to be set on the node, can be `null`
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a non-existing node
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node or its parent (see above) does not allow the `Replace` operation for the associated principal
        - `COMMAND_NOT_ALLOWED` if the command attempts to set the ACL of the root node not to include Add rights for all principals
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session was opened using the `LOCK_TYPE_SHARED` lock type, or if the session is already closed or invalidated
        `java.lang.SecurityException` - in case of local sessions, if the caller does not have `DmtPermission` for the node or its parent (see above) with the Replace action present

    - #### copy

          void copy(java.lang.String nodeUri,
                  java.lang.String newNodeUri,
                  boolean recursive)
                    throws DmtException

      Create a copy of a node or a whole subtree. Beside the structure and values of the nodes, most properties are also copied, with the exception of the ACL (Access Control List), Timestamp and Version properties.

      The copy method is essentially a convenience method that could be substituted with a sequence of retrieval and update operations. This determines the permissions required for copying. However, some optimization can be possible if the source and target nodes are all handled by DmtAdmin or by the same plugin. In this case, the handler might be able to perform the underlying management operation more efficiently: for example, a configuration table can be copied at once instead of reading each node for each entry and creating it in the new tree.

      This method may result in any of the errors possible for the contributing operations. Most of these are collected in the exception descriptions below, but for the full list also consult the documentation of `getChildNodeNames(String)`, `isLeafNode(String)`, `getNodeValue(String)`, `getNodeType(String)`, `getNodeTitle(String)`, `setNodeTitle(String, String)`, `createLeafNode(String, DmtData, String)` and `createInteriorNode(String, String)`.

      Parameters:
        `nodeUri` - the node or root of a subtree to be copied
        `newNodeUri` - the URI of the new node or root of a subtree
        `recursive` - `false` if only a single node is copied, `true` if the whole subtree is copied
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` or `newNodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a non-existing node, or if `newNodeUri` points to a node that cannot exist in the tree according to the meta-data (see `getMetaNode(String)`)
        - `NODE_ALREADY_EXISTS` if `newNodeUri` points to a node that already exists
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the copied node(s) does not allow the `Get` operation, or the ACL of the parent of the target node does not allow the `Add` operation for the associated principal
        - `COMMAND_NOT_ALLOWED` if `nodeUri` is an ancestor of `newNodeUri`, or if any of the implied retrieval or update operations are not allowed
        - `METADATA_MISMATCH` if any of the meta-data constraints of the implied retrieval or update operations are violated
        - `TRANSACTION_ERROR` in an atomic session if the underlying plugin is read-only or does not support atomic writing
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if either URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session was opened using the `LOCK_TYPE_SHARED` lock type, or if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the copied node(s) with the Get action present, or for the parent of the target node with the Add action

    - #### createInteriorNode

          void createInteriorNode(java.lang.String nodeUri)
                                  throws DmtException

      Create an interior node. If the parent node does not exist, it is created automatically, as if this method were called for the parent URI. This way all missing ancestor nodes leading to the specified node are created. Any exceptions encountered while creating the ancestors are propagated to the caller of this method, these are not explicitly listed in the error descriptions below.

      If meta-data is available for the node, several checks are made before creating it. The node must have `MetaNode.CMD_ADD` access type, it must be defined as a non-permanent interior node, the node name must conform to the valid names, and the creation of the new node must not cause the maximum occurrence number to be exceeded.

      If the meta-data cannot be retrieved because the given node cannot possibly exist in the tree (it is not defined in the specification), the `NODE_NOT_FOUND` error code is returned (see `getMetaNode(String)`).

      Parameters:
        `nodeUri` - the URI of the node to create
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a node that cannot exist in the tree (see above)
        - `NODE_ALREADY_EXISTS` if `nodeUri` points to a node that already exists
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the parent node does not allow the `Add` operation for the associated principal
        - `COMMAND_NOT_ALLOWED` if the parent node is not an interior node, or in non-atomic sessions if the underlying plugin is read-only or does not support non-atomic writing
        - `METADATA_MISMATCH` if the node could not be created because of meta-data restrictions (see above)
        - `TRANSACTION_ERROR` in an atomic session if the underlying plugin is read-only or does not support atomic writing
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session was opened using the `LOCK_TYPE_SHARED` lock type, or if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the parent node with the Add action present

    - #### createInteriorNode

          void createInteriorNode(java.lang.String nodeUri,
                                java.lang.String type)
                                  throws DmtException

      Create an interior node with a given type. The type of interior node, if specified, is a URI identifying a DDF document. If the parent node does not exist, it is created automatically, as if `createInteriorNode(String)` were called for the parent URI. This way all missing ancestor nodes leading to the specified node are created. Any exceptions encountered while creating the ancestors are propagated to the caller of this method, these are not explicitly listed in the error descriptions below.

      If meta-data is available for the node, several checks are made before creating it. The node must have `MetaNode.CMD_ADD` access type, it must be defined as a non-permanent interior node, the node name must conform to the valid names, and the creation of the new node must not cause the maximum occurrence number to be exceeded.

      If the meta-data cannot be retrieved because the given node cannot possibly exist in the tree (it is not defined in the specification), the `NODE_NOT_FOUND` error code is returned (see `getMetaNode(String)`).

      Interior node type identifiers must follow the format defined in section 7.7.7.2 of the OMA Device Management Tree and Description document. Checking the validity of the type string does not have to be done by the DmtAdmin, this can be left to the plugin handling the node (if any), to avoid unnecessary double-checks.

      Parameters:
        `nodeUri` - the URI of the node to create
        `type` - the type URI of the interior node, can be `null` if no node type is defined
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a node that cannot exist in the tree (see above)
        - `NODE_ALREADY_EXISTS` if `nodeUri` points to a node that already exists
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the parent node does not allow the `Add` operation for the associated principal
        - `COMMAND_NOT_ALLOWED` if the parent node is not an interior node, or in non-atomic sessions if the underlying plugin is read-only or does not support non-atomic writing
        - `METADATA_MISMATCH` if the node could not be created because of meta-data restrictions (see above)
        - `TRANSACTION_ERROR` in an atomic session if the underlying plugin is read-only or does not support atomic writing
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, if the type string is invalid (see above), or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session was opened using the `LOCK_TYPE_SHARED` lock type, or if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the parent node with the Add action present
      See Also:
        `createInteriorNode(String)`, OMA Device Management Tree and Description v1.2 draft

    - #### createLeafNode

          void createLeafNode(java.lang.String nodeUri)
                              throws DmtException

      Create a leaf node with default value and MIME type. If a node does not have a default value or MIME type, this method will throw a `DmtException` with error code `METADATA_MISMATCH`. Note that a node might have a default value or MIME type even if there is no meta-data for the node or its meta-data does not specify the default.

      If the parent node does not exist, it is created automatically, as if `createInteriorNode(String)` were called for the parent URI. This way all missing ancestor nodes leading to the specified node are created. Any exceptions encountered while creating the ancestors are propagated to the caller of this method, these are not explicitly listed in the error descriptions below.

      If meta-data is available for a node, several checks are made before creating it. The node must have `MetaNode.CMD_ADD` access type, it must be defined as a non-permanent leaf node, the node name must conform to the valid names, and the creation of the new node must not cause the maximum occurrence number to be exceeded.

      If the meta-data cannot be retrieved because the given node cannot possibly exist in the tree (it is not defined in the specification), the `NODE_NOT_FOUND` error code is returned (see `getMetaNode(String)`).

      Parameters:
        `nodeUri` - the URI of the node to create
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a node that cannot exist in the tree (see above)
        - `NODE_ALREADY_EXISTS` if `nodeUri` points to a node that already exists
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the parent node does not allow the `Add` operation for the associated principal
        - `COMMAND_NOT_ALLOWED` if the parent node is not an interior node, or in non-atomic sessions if the underlying plugin is read-only or does not support non-atomic writing
        - `METADATA_MISMATCH` if the node could not be created because of meta-data restrictions (see above)
        - `TRANSACTION_ERROR` in an atomic session if the underlying plugin is read-only or does not support atomic writing
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session was opened using the `LOCK_TYPE_SHARED` lock type, or if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the parent node with the Add action present
      See Also:
        `createLeafNode(String, DmtData)`

    - #### createLeafNode

          void createLeafNode(java.lang.String nodeUri,
                            DmtData value)
                              throws DmtException

      Create a leaf node with a given value and the default MIME type. If the specified value is `null`, the default value is taken. If the node does not have a default MIME type or value (if needed), this method will throw a `DmtException` with error code `METADATA_MISMATCH`. Note that a node might have a default value or MIME type even if there is no meta-data for the node or its meta-data does not specify the default.

      If the parent node does not exist, it is created automatically, as if `createInteriorNode(String)` were called for the parent URI. This way all missing ancestor nodes leading to the specified node are created. Any exceptions encountered while creating the ancestors are propagated to the caller of this method, these are not explicitly listed in the error descriptions below.

      If meta-data is available for a node, several checks are made before creating it. The node must have `MetaNode.CMD_ADD` access type, it must be defined as a non-permanent leaf node, the node name must conform to the valid names, the node value must conform to the value constraints, and the creation of the new node must not cause the maximum occurrence number to be exceeded.

      If the meta-data cannot be retrieved because the given node cannot possibly exist in the tree (it is not defined in the specification), the `NODE_NOT_FOUND` error code is returned (see `getMetaNode(String)`).

      Nodes of `null` format can be created by using `DmtData.NULL_VALUE` as second argument.

      Parameters:
        `nodeUri` - the URI of the node to create
        `value` - the value to be given to the new node, can be `null`
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a node that cannot exist in the tree (see above)
        - `NODE_ALREADY_EXISTS` if `nodeUri` points to a node that already exists
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the parent node does not allow the `Add` operation for the associated principal
        - `COMMAND_NOT_ALLOWED` if the parent node is not an interior node, or in non-atomic sessions if the underlying plugin is read-only or does not support non-atomic writing
        - `METADATA_MISMATCH` if the node could not be created because of meta-data restrictions (see above)
        - `TRANSACTION_ERROR` in an atomic session if the underlying plugin is read-only or does not support atomic writing
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session was opened using the `LOCK_TYPE_SHARED` lock type, or if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the parent node with the Add action present

    - #### createLeafNode

          void createLeafNode(java.lang.String nodeUri,
                            DmtData value,
                            java.lang.String mimeType)
                              throws DmtException

      Create a leaf node with a given value and MIME type. If the specified value or MIME type is `null`, their default values are taken. If the node does not have the necessary defaults, this method will throw a `DmtException` with error code `METADATA_MISMATCH`. Note that a node might have a default value or MIME type even if there is no meta-data for the node or its meta-data does not specify the default.

      If the parent node does not exist, it is created automatically, as if `createInteriorNode(String)` were called for the parent URI. This way all missing ancestor nodes leading to the specified node are created. Any exceptions encountered while creating the ancestors are propagated to the caller of this method, these are not explicitly listed in the error descriptions below.

      If meta-data is available for a node, several checks are made before creating it. The node must have `MetaNode.CMD_ADD` access type, it must be defined as a non-permanent leaf node, the node name must conform to the valid names, the node value must conform to the value constraints, the MIME type must be among the listed types, and the creation of the new node must not cause the maximum occurrence number to be exceeded.

      If the meta-data cannot be retrieved because the given node cannot possibly exist in the tree (it is not defined in the specification), the `NODE_NOT_FOUND` error code is returned (see `getMetaNode(String)`).

      Nodes of `null` format can be created by using `DmtData.NULL_VALUE` as second argument.

      The MIME type string must conform to the definition in RFC 2045. Checking its validity does not have to be done by the DmtAdmin, this can be left to the plugin handling the node (if any), to avoid unnecessary double-checks.

      Parameters:
        `nodeUri` - the URI of the node to create
        `value` - the value to be given to the new node, can be `null`
        `mimeType` - the MIME type to be given to the new node, can be `null`
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a node that cannot exist in the tree (see above)
        - `NODE_ALREADY_EXISTS` if `nodeUri` points to a node that already exists
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the parent node does not allow the `Add` operation for the associated principal
        - `COMMAND_NOT_ALLOWED` if the parent node is not an interior node, or in non-atomic sessions if the underlying plugin is read-only or does not support non-atomic writing
        - `METADATA_MISMATCH` if the node could not be created because of meta-data restrictions (see above)
        - `TRANSACTION_ERROR` in an atomic session if the underlying plugin is read-only or does not support atomic writing
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, if `mimeType` is not a proper MIME type string (see above), or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session was opened using the `LOCK_TYPE_SHARED` lock type, or if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the parent node with the Add action present
      See Also:
        `createLeafNode(String, DmtData)`, RFC 2045

    - #### deleteNode

          void deleteNode(java.lang.String nodeUri)
                          throws DmtException

      Delete the given node. Deleting interior nodes is recursive, the whole subtree under the given node is deleted. It is not allowed to delete the root node of the session.

      If meta-data is available for a node, several checks are made before deleting it. The node must be non-permanent, it must have the `MetaNode.CMD_DELETE` access type, and if zero occurrences of the node are not allowed, it must not be the last one.

      Parameters:
        `nodeUri` - the URI of the node
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a non-existing node
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node does not allow the `Delete` operation for the associated principal
        - `COMMAND_NOT_ALLOWED` if the target node is the root of the session, or in non-atomic sessions if the underlying plugin is read-only or does not support non-atomic writing
        - `METADATA_MISMATCH` if the node could not be deleted because of meta-data restrictions (see above)
        - `TRANSACTION_ERROR` in an atomic session if the underlying plugin is read-only or does not support atomic writing
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session was opened using the `LOCK_TYPE_SHARED` lock type, or if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the node with the Delete action present

    - #### renameNode

          void renameNode(java.lang.String nodeUri,
                        java.lang.String newName)
                          throws DmtException

      Rename a node. This operation only changes the name of the node (updating the timestamp and version properties if they are supported), the value and the other properties are not changed. The new name of the node must be provided, the new URI is constructed from the base of the old URI and the given name. It is not allowed to rename the root node of the session.

      If available, the meta-data of the original and the new nodes are checked before performing the rename operation. Neither node can be permanent, their leaf/interior property must match, and the name change must not violate any of the cardinality constraints. The original node must have the `MetaNode.CMD_REPLACE` access type, and the name of the new node must conform to the valid names.

      Parameters:
        `nodeUri` - the URI of the node to rename
        `newName` - the new name property of the node
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` or `newName` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a non-existing node, or if the new node is not defined in the tree according to the meta-data (see `getMetaNode(String)`)
        - `NODE_ALREADY_EXISTS` if there already exists a sibling of `nodeUri` with the name `newName`
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node does not allow the `Replace` operation for the associated principal
        - `COMMAND_NOT_ALLOWED` if the target node is the root of the session, or in non-atomic sessions if the underlying plugin is read-only or does not support non-atomic writing
        - `METADATA_MISMATCH` if the node could not be renamed because of meta-data restrictions (see above)
        - `TRANSACTION_ERROR` in an atomic session if the underlying plugin is read-only or does not support atomic writing
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session was opened using the `LOCK_TYPE_SHARED` lock type, or if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the node with the Replace action present

    - #### setDefaultNodeValue

          void setDefaultNodeValue(java.lang.String nodeUri)
                                   throws DmtException

      Set the value of a leaf or interior node to its default. The default can be defined by the node's `MetaNode`. The method throws a `METADATA_MISMATCH` exception if the node does not have a default value.
      Parameters:
        `nodeUri` - the URI of the node
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a non-existing node
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node does not allow the `Replace` operation for the associated principal
        - `COMMAND_NOT_ALLOWED` in non-atomic sessions if the underlying plugin is read-only or does not support non-atomic writing
        - `METADATA_MISMATCH` if the node is permanent or cannot be modified according to the meta-data (does not have the `MetaNode.CMD_REPLACE` access type), or if there is no default value defined for this node
        - `FEATURE_NOT_SUPPORTED` if the specified node is an interior node and does not support Java object values
        - `TRANSACTION_ERROR` in an atomic session if the underlying plugin is read-only or does not support atomic writing
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session was opened using the `LOCK_TYPE_SHARED` lock type, or if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the node with the Replace action present
      See Also:
        `setNodeValue(String, DmtData)`

    - #### setNodeValue

          void setNodeValue(java.lang.String nodeUri,
                          DmtData data)
                            throws DmtException

      Set the value of a leaf or interior node. The format of the node is contained in the `DmtData` object. For interior nodes, the format must be `FORMAT_NODE`, while for leaf nodes this format must not be used.

      If the specified value is `null`, the default value is taken. In this case, if the node does not have a default value, this method will throw a `DmtException` with error code `METADATA_MISMATCH`. Nodes of `null` format can be set by using `DmtData.NULL_VALUE` as second argument.

      An Event of type REPLACE is sent out for a leaf node. A replaced interior node sends out events for each of its children in depth first order and node names sorted with Arrays.sort(String[]). When setting a value on an interior node, the values of the leaf nodes under it can change, but the structure of the subtree is not modified by the operation.

      Parameters:
        `nodeUri` - the URI of the node
        `data` - the data to be set, can be `null`
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a non-existing node
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node does not allow the `Replace` operation for the associated principal
        - `COMMAND_NOT_ALLOWED` if the given data has `FORMAT_NODE` format but the node is a leaf node (or vice versa), or in non-atomic sessions if the underlying plugin is read-only or does not support non-atomic writing
        - `METADATA_MISMATCH` if the node is permanent or cannot be modified according to the meta-data (does not have the `MetaNode.CMD_REPLACE` access type), or if the given value does not conform to the meta-data value constraints
        - `FEATURE_NOT_SUPPORTED` if the specified node is an interior node and does not support Java object values
        - `TRANSACTION_ERROR` in an atomic session if the underlying plugin is read-only or does not support atomic writing
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session was opened using the `LOCK_TYPE_SHARED` lock type, or if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the node with the Replace action present

    - #### setNodeTitle

          void setNodeTitle(java.lang.String nodeUri,
                          java.lang.String title)
                            throws DmtException

      Set the title property of a node. The length of the title string in UTF-8 encoding must not exceed 255 bytes.
      Parameters:
        `nodeUri` - the URI of the node
        `title` - the title text of the node, can be `null`
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a non-existing node
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node does not allow the `Replace` operation for the associated principal
        - `COMMAND_NOT_ALLOWED` in non-atomic sessions if the underlying plugin is read-only or does not support non-atomic writing
        - `METADATA_MISMATCH` if the node cannot be modified according to the meta-data (does not have the `MetaNode.CMD_REPLACE` access type)
        - `FEATURE_NOT_SUPPORTED` if the Title property is not supported by the DmtAdmin implementation or the underlying plugin
        - `TRANSACTION_ERROR` in an atomic session if the underlying plugin is read-only or does not support atomic writing
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the title string is too long, if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session was opened using the `LOCK_TYPE_SHARED` lock type, or if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the node with the Replace action present

    - #### setNodeType

          void setNodeType(java.lang.String nodeUri,
                         java.lang.String type)
                           throws DmtException

      Set the type of a node. The type of leaf node is the MIME type of the data it contains. The type of an interior node is a URI identifying a DDF document.

      For interior nodes, a `null` type string means that there is no DDF document overriding the tree structure defined by the ancestors. For leaf nodes, it requests that the default MIME type is used for the given node. If the node does not have a default MIME type this method will throw a `DmtException` with error code `METADATA_MISMATCH`. Note that a node might have a default MIME type even if there is no meta-data for the node or its meta-data does not specify the default.

      MIME types must conform to the definition in RFC 2045. Interior node type identifiers must follow the format defined in section 7.7.7.2 of the OMA Device Management Tree and Description document. Checking the validity of the type string does not have to be done by the DmtAdmin, this can be left to the plugin handling the node (if any), to avoid unnecessary double-checks.

      Parameters:
        `nodeUri` - the URI of the node
        `type` - the type of the node, can be `null`
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a non-existing node
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node does not allow the `Replace` operation for the associated principal
        - `COMMAND_NOT_ALLOWED` in non-atomic sessions if the underlying plugin is read-only or does not support non-atomic writing
        - `METADATA_MISMATCH` if the node is permanent or cannot be modified according to the meta-data (does not have the `MetaNode.CMD_REPLACE` access type), and in case of leaf nodes, if `null` is given and there is no default MIME type, or the given MIME type is not allowed
        - `TRANSACTION_ERROR` in an atomic session if the underlying plugin is read-only or does not support atomic writing
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, if the type string is invalid (see above), or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session was opened using the `LOCK_TYPE_SHARED` lock type, or if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the node with the Replace action present
      See Also:
        RFC 2045, OMA Device Management Tree and Description v1.2 draft

    - #### getChildNodeNames

          java.lang.String[] getChildNodeNames(java.lang.String nodeUri)
                                               throws DmtException

      Get the list of children names of a node. The returned array contains the names - not the URIs - of the immediate children nodes of the given node. The elements are in no particular order. The returned array must not contain `null` entries.
      Parameters:
        `nodeUri` - the URI of the node
      Returns:
        the list of child node names as a string array or an empty string array if the node has no children
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a non-existing node
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node does not allow the `Get` operation for the associated principal
        - `COMMAND_NOT_ALLOWED` if the specified node is not an interior node
        - `METADATA_MISMATCH` if node information cannot be retrieved according to the meta-data (it does not have `MetaNode.CMD_GET` access type)
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the node with the Get action present

    - #### getMetaNode

          MetaNode getMetaNode(java.lang.String nodeUri)
                               throws DmtException

      Get the meta data which describes a given node. Meta data can only be inspected, it can not be changed.

      The `MetaNode` object returned to the client is the combination of the meta data returned by the data plugin (if any) plus the meta data returned by the DmtAdmin. If there are differences in the meta data elements known by the plugin and the DmtAdmin then the plugin specific elements take precedence.

      Note, that a node does not have to exist for having meta-data associated with it. This method may provide meta-data for any node that can possibly exist in the tree (any node defined in the specification). For nodes that are not defined, it may throw `DmtException` with the error code `NODE_NOT_FOUND`. To allow easier implementation of plugins that do not provide meta-data, it is allowed to return `null` for any node, regardless of whether it is defined or not.

      Parameters:
        `nodeUri` - the URI of the node
      Returns:
        a MetaNode which describes meta data information, can be `null` if there is no meta data available for the given node
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a node that is not defined in the tree (see above)
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node does not allow the `Get` operation for the associated principal
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the node with the Get action present

    - #### getNodeSize

          int getNodeSize(java.lang.String nodeUri)
                          throws DmtException

      Get the size of the data in a leaf node. The returned value depends on the format of the data in the node, see the description of the `DmtData.getSize()` method for the definition of node size for each format.
      Parameters:
        `nodeUri` - the URI of the leaf node
      Returns:
        the size of the data in the node
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a non-existing node
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node does not allow the `Get` operation for the associated principal
        - `COMMAND_NOT_ALLOWED` if the specified node is not a leaf node
        - `METADATA_MISMATCH` if node information cannot be retrieved according to the meta-data (it does not have `MetaNode.CMD_GET` access type)
        - `FEATURE_NOT_SUPPORTED` if the Size property is not supported by the DmtAdmin implementation or the underlying plugin
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the node with the Get action present
      See Also:
        `DmtData.getSize()`

    - #### getNodeTimestamp

          java.util.Date getNodeTimestamp(java.lang.String nodeUri)
                                          throws DmtException

      Get the timestamp when the node was created or last modified.
      Parameters:
        `nodeUri` - the URI of the node
      Returns:
        the timestamp of the last modification
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a non-existing node
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node does not allow the `Get` operation for the associated principal
        - `METADATA_MISMATCH` if node information cannot be retrieved according to the meta-data (it does not have `MetaNode.CMD_GET` access type)
        - `FEATURE_NOT_SUPPORTED` if the Timestamp property is not supported by the DmtAdmin implementation or the underlying plugin
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the node with the Get action present

    - #### getNodeTitle

          java.lang.String getNodeTitle(java.lang.String nodeUri)
                                        throws DmtException

      Get the title of a node. There might be no title property set for a node.
      Parameters:
        `nodeUri` - the URI of the node
      Returns:
        the title of the node, or `null` if the node has no title
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a non-existing node
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node does not allow the `Get` operation for the associated principal
        - `METADATA_MISMATCH` if node information cannot be retrieved according to the meta-data (it does not have `MetaNode.CMD_GET` access type)
        - `FEATURE_NOT_SUPPORTED` if the Title property is not supported by the DmtAdmin implementation or the underlying plugin
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the node with the Get action present

    - #### getNodeType

          java.lang.String getNodeType(java.lang.String nodeUri)
                                       throws DmtException

      Get the type of a node. The type of leaf node is the MIME type of the data it contains. The type of an interior node is a URI identifying a DDF document; a `null` type means that there is no DDF document overriding the tree structure defined by the ancestors.
      Parameters:
        `nodeUri` - the URI of the node
      Returns:
        the type of the node, can be `null`
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a non-existing node
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node does not allow the `Get` operation for the associated principal
        - `METADATA_MISMATCH` if node information cannot be retrieved according to the meta-data (it does not have `MetaNode.CMD_GET` access type)
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the node with the Get action present

    - #### getNodeValue

          DmtData getNodeValue(java.lang.String nodeUri)
                               throws DmtException

      Get the data contained in a leaf or interior node. When retrieving the value associated with an interior node, the caller must have rights to read all nodes in the subtree under the given node.
      Parameters:
        `nodeUri` - the URI of the node to retrieve
      Returns:
        the data of the node, can not be `null`
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a non-existing node
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node (and the ACLs of all its descendants in case of interior nodes) do not allow the `Get` operation for the associated principal
        - `METADATA_MISMATCH` if the node value cannot be retrieved according to the meta-data (it does not have `MetaNode.CMD_GET` access type)
        - `FEATURE_NOT_SUPPORTED` if the specified node is an interior node and does not support Java object values
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the node (and all its descendants in case of interior nodes) with the Get action present

    - #### getNodeVersion

          int getNodeVersion(java.lang.String nodeUri)
                             throws DmtException

      Get the version of a node. The version can not be set, it is calculated automatically by the device. It is incremented modulo 0x10000 at every modification of the value or any other property of the node, for both leaf and interior nodes. When a node is created the initial value is 0.
      Parameters:
        `nodeUri` - the URI of the node
      Returns:
        the version of the node
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a non-existing node
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node does not allow the `Get` operation for the associated principal
        - `METADATA_MISMATCH` if node information cannot be retrieved according to the meta-data (it does not have `MetaNode.CMD_GET` access type)
        - `FEATURE_NOT_SUPPORTED` if the Version property is not supported by the DmtAdmin implementation or the underlying plugin
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the node with the Get action present

    - #### isLeafNode

          boolean isLeafNode(java.lang.String nodeUri)
                             throws DmtException

      Tells whether a node is a leaf or an interior node of the DMT.
      Parameters:
        `nodeUri` - the URI of the node
      Returns:
        true if the given node is a leaf node
      Throws:
        `DmtException` - with the following possible error codes:
        - `INVALID_URI` if `nodeUri` is `null` or syntactically invalid
        - `URI_TOO_LONG` if `nodeUri` is longer than accepted by the `DmtAdmin` implementation (especially on systems with limited resources)
        - `NODE_NOT_FOUND` if `nodeUri` points to a non-existing node
        - `PERMISSION_DENIED` if the session is associated with a principal and the ACL of the node does not allow the `Get` operation for the associated principal
        - `METADATA_MISMATCH` if node information cannot be retrieved according to the meta-data (it does not have `MetaNode.CMD_GET` access type)
        - `DATA_STORE_FAILURE` if an error occurred while accessing the data store
        - `COMMAND_FAILED` if the URI is not within the current session's subtree, or if some unspecified error is encountered while attempting to complete the command
        `DmtIllegalStateException` - if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the node with the Get action present

    - #### isNodeUri

          boolean isNodeUri(java.lang.String nodeUri)

      Check whether the specified URI corresponds to a valid node in the DMT.
      Parameters:
        `nodeUri` - the URI to check
      Returns:
        true if the given node exists in the DMT
      Throws:
        `DmtIllegalStateException` - if the session is already closed or invalidated
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation, or, in case of local sessions, if the caller does not have `DmtPermission` for the node with the Get action present