Package 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

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method 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