ReadWriteDataSession
Date: 2016-06-25

org.osgi.service.dmt.spi

## Interface ReadWriteDataSession

- All Superinterfaces:
    ReadableDataSession
  All Known Subinterfaces:
    TransactionalDataSession

      public interface ReadWriteDataSession
      extends ReadableDataSession

  Provides non-atomic read-write access to the part of the tree handled by the plugin that created this session.

  The `nodePath` parameters appearing in this interface always contain an array of path segments identifying a node in the subtree of this plugin. This parameter contains an absolute path, so the first segment is always ".". Special characters appear escaped in the segments.

  Error handling

  When a tree manipulation command is called on the DmtAdmin service, it must perform an extensive set of checks on the parameters and the authority of the caller before delegating the call to a plugin. Therefore plugins can take certain circumstances for granted: that the path is valid and is within the subtree of the plugin and the session, the command can be applied to the given node (e.g. the target of `setNodeValue` is a leaf node), etc. All errors described by the error codes `DmtException.INVALID_URI`, `DmtException.URI_TOO_LONG`, `DmtException.PERMISSION_DENIED`, `DmtException.COMMAND_NOT_ALLOWED` and `DmtException.TRANSACTION_ERROR` are fully filtered out before control reaches the plugin.

  If the plugin provides meta-data for a node, the DmtAdmin service must also check the constraints specified by it, as described in `MetaNode`. If the plugin does not provide meta-data, it must perform the necessary checks for itself and use the `DmtException.METADATA_MISMATCH` error code to indicate such discrepancies.

  The DmtAdmin does not check that the targeted node exists (or that it does not exist, in case of a node creation) before calling the plugin. It is the responsibility of the plugin to perform this check and to throw a `DmtException.NODE_NOT_FOUND` or `DmtException.NODE_ALREADY_EXISTS` if needed. In this case the DmtAdmin must pass through this exception to the caller of the corresponding DmtSession method.

  The plugin can use the remaining error codes as needed. If an error does not fit into any other category, the `DmtException.COMMAND_FAILED` code should be used.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `copy(java.lang.String[] nodePath, java.lang.String[] newNodePath, boolean recursive)` Create a copy of a node or a whole subtree.
    `void` | `createInteriorNode(java.lang.String[] nodePath, java.lang.String type)` Create an interior node with a given type.
    `void` | `createLeafNode(java.lang.String[] nodePath, DmtData value, java.lang.String mimeType)` Create a leaf node with a given value and MIME type.
    `void` | `deleteNode(java.lang.String[] nodePath)` Delete the given node.
    `void` | `renameNode(java.lang.String[] nodePath, java.lang.String newName)` Rename a node.
    `void` | `setNodeTitle(java.lang.String[] nodePath, java.lang.String title)` Set the title property of a node.
    `void` | `setNodeType(java.lang.String[] nodePath, java.lang.String type)` Set the type of a node.
    `void` | `setNodeValue(java.lang.String[] nodePath, DmtData data)` Set the value of a leaf or interior node.

    - ### Methods inherited from interface org.osgi.service.dmt.spi.ReadableDataSession

      `close, getChildNodeNames, getMetaNode, getNodeSize, getNodeTimestamp, getNodeTitle, getNodeType, getNodeValue, getNodeVersion, isLeafNode, isNodeUri, nodeChanged`

- - ### Method Detail

    - #### copy

          void copy(java.lang.String[] nodePath,
                  java.lang.String[] newNodePath,
                  boolean recursive)
                    throws DmtException

      Create a copy of a node or a whole subtree. Beside the structure and values of the nodes, most properties managed by the plugin must also be copied, with the exception of the Timestamp and Version properties.
      Parameters:
        `nodePath` - an absolute path specifying the node or the root of a subtree to be copied
        `newNodePath` - the absolute path 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:
        - `NODE_NOT_FOUND` if `nodePath` points to a non-existing node, or if `newNodePath` points to a node that cannot exist in the tree
        - `NODE_ALREADY_EXISTS` if `newNodePath` points to a node that already exists
        - `METADATA_MISMATCH` if the node could not be copied because of meta-data restrictions
        - `FEATURE_NOT_SUPPORTED` if the copy operation is not supported by the plugin
        - `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
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation
      See Also:
        `DmtSession.copy(String, String, boolean)`

    - #### createInteriorNode

          void createInteriorNode(java.lang.String[] nodePath,
                                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.
      Parameters:
        `nodePath` - the absolute path 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:
        - `NODE_NOT_FOUND` if `nodePath` points to a node that cannot exist in the tree
        - `NODE_ALREADY_EXISTS` if `nodeUri` points to a node that already exists
        - `METADATA_MISMATCH` if the node could not be created because of meta-data restrictions
        - `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
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation
      See Also:
        `DmtSession.createInteriorNode(String)`, `DmtSession.createInteriorNode(String, String)`

    - #### createLeafNode

          void createLeafNode(java.lang.String[] nodePath,
                            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 must be taken.
      Parameters:
        `nodePath` - the absolute path 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:
        - `NODE_NOT_FOUND` if `nodePath` points to a node that cannot exist in the tree
        - `NODE_ALREADY_EXISTS` if `nodePath` points to a node that already exists
        - `METADATA_MISMATCH` if the node could not be created because of meta-data restrictions
        - `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
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation
      See Also:
        `DmtSession.createLeafNode(String)`, `DmtSession.createLeafNode(String, DmtData)`, `DmtSession.createLeafNode(String, DmtData, String)`

    - #### deleteNode

          void deleteNode(java.lang.String[] nodePath)
                          throws DmtException

      Delete the given node. Deleting interior nodes is recursive, the whole subtree under the given node is deleted.
      Parameters:
        `nodePath` - the absolute path of the node to delete
      Throws:
        `DmtException` - with the following possible error codes:
        - `NODE_NOT_FOUND` if `nodePath` points to a non-existing node
        - `METADATA_MISMATCH` if the node could not be deleted because of meta-data restrictions
        - `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
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation
      See Also:
        `DmtSession.deleteNode(String)`

    - #### renameNode

          void renameNode(java.lang.String[] nodePath,
                        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 path is constructed from the base of the old path and the given name.
      Parameters:
        `nodePath` - the absolute path of the node to rename
        `newName` - the new name property of the node
      Throws:
        `DmtException` - with the following possible error codes:
        - `NODE_NOT_FOUND` if `nodePath` points to a non-existing node, or if the new node is not defined in the tree
        - `NODE_ALREADY_EXISTS` if there already exists a sibling of `nodePath` with the name `newName`
        - `METADATA_MISMATCH` if the node could not be renamed because of meta-data restrictions
        - `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
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation
      See Also:
        `DmtSession.renameNode(String, String)`

    - #### setNodeTitle

          void setNodeTitle(java.lang.String[] nodePath,
                          java.lang.String title)
                            throws DmtException

      Set the title property of a node. The length of the title is guaranteed not to exceed the limit of 255 bytes in UTF-8 encoding.
      Parameters:
        `nodePath` - the absolute path of the node
        `title` - the title text of the node, can be `null`
      Throws:
        `DmtException` - with the following possible error codes:
        - `NODE_NOT_FOUND` if `nodePath` points to a non-existing node
        - `METADATA_MISMATCH` if the title could not be set because of meta-data restrictions
        - `FEATURE_NOT_SUPPORTED` if the Title property is not supported by the plugin
        - `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
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation
      See Also:
        `DmtSession.setNodeTitle(String, String)`

    - #### setNodeType

          void setNodeType(java.lang.String[] nodePath,
                         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, the `null` type should remove the reference (if any) to a 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.

      Parameters:
        `nodePath` - the absolute path of the node
        `type` - the type of the node, can be `null`
      Throws:
        `DmtException` - with the following possible error codes:
        - `NODE_NOT_FOUND` if `nodePath` points to a non-existing node
        - `METADATA_MISMATCH` if the type could not be set because of meta-data restrictions
        - `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
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation
      See Also:
        `DmtSession.setNodeType(String, String)`

    - #### setNodeValue

          void setNodeValue(java.lang.String[] nodePath,
                          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 is `FORMAT_NODE`, while for leaf nodes this format is never used.

      If the specified value is `null`, the default value must be taken; if there is no default value, a `DmtException` with error code `METADATA_MISMATCH` must be thrown.

      Parameters:
        `nodePath` - the absolute path of the node
        `data` - the data to be set, can be `null`
      Throws:
        `DmtException` - with the following possible error codes:
        - `NODE_NOT_FOUND` if `nodePath` points to a non-existing node
        - `METADATA_MISMATCH` if the value could not be set because of meta-data restrictions
        - `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 some unspecified error is encountered while attempting to complete the command
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation
      See Also:
        `DmtSession.setNodeValue(String, DmtData)`