OSGi 8.1.0 · org.osgi.service.dmt.spi.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.

Modifier and Type	Method and Description
public void	close() Closes a session.
public String[]	Returns: the list of child node names as a string array or an empty string array if the node has no children getChildNodeNames(String[] the absolute path of the node nodePath) Get the list of children names of a node.
public MetaNode	Returns: a MetaNode which describes meta data information, can be `null` if there is no meta data available for the given node getMetaNode(String[] the absolute path of the node nodePath) Get the meta data which describes a given node.
public int	Returns: the size of the data in the node getNodeSize(String[] the absolute path of the leaf node nodePath) Get the size of the data in a leaf node.
public Date	Returns: the timestamp of the last modification getNodeTimestamp(String[] the absolute path of the node nodePath) Get the timestamp when the node was last modified.
public String	Returns: the title of the node, or `null` if the node has no title getNodeTitle(String[] the absolute path of the node nodePath) Get the title of a node.
public String	Returns: the type of the node, can be `null` getNodeType(String[] the absolute path of the node nodePath) Get the type of a node.
public DmtData	Returns: the data of the leaf node, must not be `null` getNodeValue(String[] the absolute path of the node to retrieve nodePath) Get the data contained in a leaf or interior node.
public int	Returns: the version of the node getNodeVersion(String[] the absolute path of the node nodePath) Get the version of a node.
public boolean	Returns: true if the given node is a leaf node isLeafNode(String[] the absolute path of the node nodePath) Tells whether a node is a leaf or an interior node of the DMT.
public boolean	Returns: true if the given node exists in the DMT isNodeUri(String[] the absolute path to check nodePath) Check whether the specified path corresponds to a valid node in the DMT.
public void	nodeChanged(String[] the absolute path of the node that has changed 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

close back to summary

close	back to summary
public 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. Exceptions DmtException: with the error code `COMMAND_FAILED` if the plugin failed to close for any reason

public 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.

Exceptions

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

getChildNodeNames back to summary

getChildNodeNames	back to summary
public String[] getChildNodeNames(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:String[] the absolute path of the node Returns:String[] the list of child node names as a string array or an empty string array if the node has no children Exceptions 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 SecurityException: if the caller does not have the necessary permissions to execute the underlying management operation

public String[] getChildNodeNames(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:String[]: the absolute path of the node

Returns:String[]

the list of child node names as a string array or an empty string array if the node has no children

Exceptions

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

SecurityException:

if the caller does not have the necessary permissions to execute the underlying management operation

getMetaNode back to summary

getMetaNode	back to summary
public MetaNode getMetaNode(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:String[] the absolute path of the node Returns:MetaNode a MetaNode which describes meta data information, can be `null` if there is no meta data available for the given node Exceptions 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 SecurityException: if the caller does not have the necessary permissions to execute the underlying management operation

public MetaNode getMetaNode(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:String[]: the absolute path of the node

Returns:MetaNode

a MetaNode which describes meta data information, can be null if there is no meta data available for the given node

Exceptions

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

SecurityException:

if the caller does not have the necessary permissions to execute the underlying management operation

getNodeSize back to summary

getNodeSize	back to summary
public int getNodeSize(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:String[] the absolute path of the leaf node Returns:int the size of the data in the node Exceptions 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 SecurityException: if the caller does not have the necessary permissions to execute the underlying management operation See Also `DmtData#getSize()`

public int getNodeSize(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:String[]: the absolute path of the leaf node

Returns:int

the size of the data in the node

Exceptions

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

SecurityException:

if the caller does not have the necessary permissions to execute the underlying management operation

See Also

DmtData#getSize()

getNodeTimestamp back to summary

getNodeTimestamp	back to summary
public Date getNodeTimestamp(String[] nodePath) throws DmtException Get the timestamp when the node was last modified. Parameters nodePath:String[] the absolute path of the node Returns:Date the timestamp of the last modification Exceptions 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 SecurityException: if the caller does not have the necessary permissions to execute the underlying management operation

public Date getNodeTimestamp(String[] nodePath) throws DmtException

Get the timestamp when the node was last modified.

Parameters

nodePath:String[]: the absolute path of the node

Returns:Date

the timestamp of the last modification

Exceptions

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

SecurityException:

if the caller does not have the necessary permissions to execute the underlying management operation

getNodeTitle back to summary

getNodeTitle	back to summary
public String getNodeTitle(String[] nodePath) throws DmtException Get the title of a node. There might be no title property set for a node. Parameters nodePath:String[] the absolute path of the node Returns:String the title of the node, or `null` if the node has no title Exceptions 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 SecurityException: if the caller does not have the necessary permissions to execute the underlying management operation

public String getNodeTitle(String[] nodePath) throws DmtException

Get the title of a node. There might be no title property set for a node.

Parameters

nodePath:String[]: the absolute path of the node

Returns:String

the title of the node, or null if the node has no title

Exceptions

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

SecurityException:

if the caller does not have the necessary permissions to execute the underlying management operation

getNodeType back to summary

getNodeType	back to summary
public String getNodeType(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:String[] the absolute path of the node Returns:String the type of the node, can be `null` Exceptions 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 SecurityException: if the caller does not have the necessary permissions to execute the underlying management operation

public String getNodeType(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:String[]: the absolute path of the node

Returns:String

the type of the node, can be null

Exceptions

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

SecurityException:

if the caller does not have the necessary permissions to execute the underlying management operation

getNodeValue back to summary

getNodeValue	back to summary
public DmtData getNodeValue(String[] nodePath) throws DmtException Get the data contained in a leaf or interior node. Parameters nodePath:String[] the absolute path of the node to retrieve Returns:DmtData the data of the leaf node, must not be `null` Exceptions 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 SecurityException: if the caller does not have the necessary permissions to execute the underlying management operation

public DmtData getNodeValue(String[] nodePath) throws DmtException

Get the data contained in a leaf or interior node.

Parameters

nodePath:String[]: the absolute path of the node to retrieve

Returns:DmtData

the data of the leaf node, must not be null

Exceptions

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

SecurityException:

if the caller does not have the necessary permissions to execute the underlying management operation

getNodeVersion back to summary

getNodeVersion	back to summary
public int getNodeVersion(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:String[] the absolute path of the node Returns:int the version of the node Exceptions 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 SecurityException: if the caller does not have the necessary permissions to execute the underlying management operation

public int getNodeVersion(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:String[]: the absolute path of the node

Returns:int

the version of the node

Exceptions

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

SecurityException:

if the caller does not have the necessary permissions to execute the underlying management operation

isLeafNode back to summary

isLeafNode	back to summary
public boolean isLeafNode(String[] nodePath) throws DmtException Tells whether a node is a leaf or an interior node of the DMT. Parameters nodePath:String[] the absolute path of the node Returns:boolean true if the given node is a leaf node Exceptions 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 SecurityException: if the caller does not have the necessary permissions to execute the underlying management operation

public boolean isLeafNode(String[] nodePath) throws DmtException

Tells whether a node is a leaf or an interior node of the DMT.

Parameters

nodePath:String[]: the absolute path of the node

Returns:boolean

true if the given node is a leaf node

Exceptions

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

SecurityException:

if the caller does not have the necessary permissions to execute the underlying management operation

isNodeUri	back to summary
public boolean isNodeUri(String[] nodePath) Check whether the specified path corresponds to a valid node in the DMT. Parameters nodePath:String[] the absolute path to check Returns:boolean true if the given node exists in the DMT

isNodeUri

back to summary

public boolean isNodeUri(String[] nodePath)

Check whether the specified path corresponds to a valid node in the DMT.

Parameters

nodePath:String[]: the absolute path to check

Returns:boolean

true if the given node exists in the DMT

nodeChanged back to summary

nodeChanged	back to summary
public void nodeChanged(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:String[] the absolute path of the node that has changed Exceptions 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

public void nodeChanged(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:String[]: the absolute path of the node that has changed

Exceptions

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

public Interface ReadableDataSession

Method Summary

Method Detail