ReadableDataSession
Date: 2016-06-25

org.osgi.service.dmt.spi

## Interface ReadableDataSession

- All Known Subinterfaces:
    ReadWriteDataSession, TransactionalDataSession

      public interface ReadableDataSession

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

  Since the `ReadWriteDataSession` and `TransactionalDataSession` interfaces inherit from this interface, some of the method descriptions do not apply for an instance that is only a `ReadableDataSession`. For example, the `close()` method description also contains information about its behavior when invoked as part of a transactional 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 access 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 `getChildNodeNames` is an interior 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 before calling the plugin. It is the responsibility of the plugin to perform this check and to throw a `DmtException.NODE_NOT_FOUND` 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` | `close()` Closes a session.
    `java.lang.String[]` | `getChildNodeNames(java.lang.String[] nodePath)` Get the list of children names of a node.
    `MetaNode` | `getMetaNode(java.lang.String[] nodePath)` Get the meta data which describes a given node.
    `int` | `getNodeSize(java.lang.String[] nodePath)` Get the size of the data in a leaf node.
    `java.util.Date` | `getNodeTimestamp(java.lang.String[] nodePath)` Get the timestamp when the node was last modified.
    `java.lang.String` | `getNodeTitle(java.lang.String[] nodePath)` Get the title of a node.
    `java.lang.String` | `getNodeType(java.lang.String[] nodePath)` Get the type of a node.
    `DmtData` | `getNodeValue(java.lang.String[] nodePath)` Get the data contained in a leaf or interior node.
    `int` | `getNodeVersion(java.lang.String[] nodePath)` Get the version of a node.
    `boolean` | `isLeafNode(java.lang.String[] nodePath)` Tells whether a node is a leaf or an interior node of the DMT.
    `boolean` | `isNodeUri(java.lang.String[] nodePath)` Check whether the specified path corresponds to a valid node in the DMT.
    `void` | `nodeChanged(java.lang.String[] nodePath)` Notifies the plugin that the given node has changed outside the scope of the plugin, therefore the Version and Timestamp properties must be updated (if supported).

- - ### Method Detail

    - #### nodeChanged

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

      Notifies the plugin that the given node has changed outside the scope of the plugin, therefore the Version and Timestamp properties must be updated (if supported). This method is needed because the ACL property of a node is managed by the DmtAdmin instead of the plugin. The DmtAdmin must call this method whenever the ACL property of a node changes.
      Parameters:
        `nodePath` - the absolute path of the node that has changed
      Throws:
        `DmtException` - with the following possible error codes:
        - `NODE_NOT_FOUND` if `nodePath` points to a non-existing node
        - `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

    - #### close

          void close()
                     throws DmtException

      Closes a session. This method is always called when the session ends for any reason: if the session is closed, if a fatal error occurs in any method, or if any error occurs during commit or rollback. In case the session was invalidated due to an exception during commit or rollback, it is guaranteed that no methods are called on the plugin until it is closed. In case the session was invalidated due to a fatal exception in one of the tree manipulation methods, only the rollback method is called before this (and only in atomic sessions).

      This method should not perform any data manipulation, only cleanup operations. In non-atomic read-write sessions the data manipulation should be done instantly during each tree operation, while in atomic sessions the `DmtAdmin` always calls `TransactionalDataSession.commit()` automatically before the session is actually closed.

      Throws:
        `DmtException` - with the error code `COMMAND_FAILED` if the plugin failed to close for any reason

    - #### getChildNodeNames

          java.lang.String[] getChildNodeNames(java.lang.String[] nodePath)
                                               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 returned array may contain `null` entries, but these are removed by the DmtAdmin before returning it to the client.
      Parameters:
        `nodePath` - the absolute path 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:
        - `NODE_NOT_FOUND` if `nodePath` points to a non-existing node
        - `METADATA_MISMATCH` if the information could not be retrieved 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

    - #### getMetaNode

          MetaNode getMetaNode(java.lang.String[] nodePath)
                               throws DmtException

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

      Meta data support by plugins is an optional feature. It can be used, for example, when a data plugin is implemented on top of a data store or another API that has their own metadata, such as a relational database, in order to avoid metadata duplication and inconsistency. The meta data specific to the plugin returned by this method is complemented by meta data from the DmtAdmin before returning it to the client. 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 by the Management Object provided by the plugin). For nodes that are not defined, a `DmtException` may be thrown with the `NODE_NOT_FOUND` error code. 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:
        `nodePath` - the absolute path 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:
        - `NODE_NOT_FOUND` if `nodeUri` points to a node that is not defined in the tree (see above)
        - `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

    - #### getNodeSize

          int getNodeSize(java.lang.String[] nodePath)
                          throws DmtException

      Get the size of the data in a leaf node. The value to return 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:
        `nodePath` - the absolute path of the leaf node
      Returns:
        the size of the data in the node
      Throws:
        `DmtException` - with the following possible error codes:
        - `NODE_NOT_FOUND` if `nodePath` points to a non-existing node
        - `METADATA_MISMATCH` if the information could not be retrieved because of meta-data restrictions
        - `FEATURE_NOT_SUPPORTED` if the Size 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:
        `DmtData.getSize()`

    - #### getNodeTimestamp

          java.util.Date getNodeTimestamp(java.lang.String[] nodePath)
                                          throws DmtException

      Get the timestamp when the node was last modified.
      Parameters:
        `nodePath` - the absolute path of the node
      Returns:
        the timestamp of the last modification
      Throws:
        `DmtException` - with the following possible error codes:
        - `NODE_NOT_FOUND` if `nodePath` points to a non-existing node
        - `METADATA_MISMATCH` if the information could not be retrieved because of meta-data restrictions
        - `FEATURE_NOT_SUPPORTED` if the Timestamp 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

    - #### getNodeTitle

          java.lang.String getNodeTitle(java.lang.String[] nodePath)
                                        throws DmtException

      Get the title of a node. There might be no title property set for a node.
      Parameters:
        `nodePath` - the absolute path 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:
        - `NODE_NOT_FOUND` if `nodePath` points to a non-existing node
        - `METADATA_MISMATCH` if the information could not be retrieved 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

    - #### getNodeType

          java.lang.String getNodeType(java.lang.String[] nodePath)
                                       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:
        `nodePath` - the absolute path of the node
      Returns:
        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 information could not be retrieved 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

    - #### isNodeUri

          boolean isNodeUri(java.lang.String[] nodePath)

      Check whether the specified path corresponds to a valid node in the DMT.
      Parameters:
        `nodePath` - the absolute path to check
      Returns:
        true if the given node exists in the DMT

    - #### isLeafNode

          boolean isLeafNode(java.lang.String[] nodePath)
                             throws DmtException

      Tells whether a node is a leaf or an interior node of the DMT.
      Parameters:
        `nodePath` - the absolute path of the node
      Returns:
        true if the given node is a leaf node
      Throws:
        `DmtException` - with the following possible error codes:
        - `NODE_NOT_FOUND` if `nodePath` points to a non-existing node
        - `METADATA_MISMATCH` if the information could not be retrieved 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

    - #### getNodeValue

          DmtData getNodeValue(java.lang.String[] nodePath)
                               throws DmtException

      Get the data contained in a leaf or interior node.
      Parameters:
        `nodePath` - the absolute path of the node to retrieve
      Returns:
        the data of the leaf node, must not 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 information could not be retrieved 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

    - #### getNodeVersion

          int getNodeVersion(java.lang.String[] nodePath)
                             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:
        `nodePath` - the absolute path of the node
      Returns:
        the version of the node
      Throws:
        `DmtException` - with the following possible error codes:
        - `NODE_NOT_FOUND` if `nodePath` points to a non-existing node
        - `METADATA_MISMATCH` if the information could not be retrieved because of meta-data restrictions
        - `FEATURE_NOT_SUPPORTED` if the Version 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