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.

Author:

$Id: 6d3a6a20d1f1f993740ed1ce8387c4c1eaa7e9b3 $

Method Summary

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