Top Description Methods
org.osgi.service.dmt.spi

public Interface ReadWriteDataSession

extends ReadableDataSession
Known Direct Subinterfaces
org.osgi.service.dmt.spi.TransactionalDataSession
Imports
org.osgi.service.dmt.DmtData, .DmtException, .DmtSession, .MetaNode
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.

Author
$Id: 8237e8ee3cf4e7e5156de813f614986b808bd0f3 $

Method Summary

Modifier and TypeMethod and Description
public void
copy(String[]
an absolute path specifying the node or the root of a subtree to be copied
nodePath, String[]
the absolute path of the new node or root of a subtree
newNodePath, boolean
false if only a single node is copied, true if the whole subtree is copied
recursive)

Create a copy of a node or a whole subtree.

public void
createInteriorNode(String[]
the absolute path of the node to create
nodePath, String
the type URI of the interior node, can be null if no node type is defined
type)

Create an interior node with a given type.

public void
createLeafNode(String[]
the absolute path of the node to create
nodePath, DmtData
the value to be given to the new node, can be null
value, String
the MIME type to be given to the new node, can be null
mimeType)

Create a leaf node with a given value and MIME type.

public void
deleteNode(String[]
the absolute path of the node to delete
nodePath)

Delete the given node.

public void
renameNode(String[]
the absolute path of the node to rename
nodePath, String
the new name property of the node
newName)

Rename a node.

public void
setNodeTitle(String[]
the absolute path of the node
nodePath, String
the title text of the node, can be null
title)

Set the title property of a node.

public void
setNodeType(String[]
the absolute path of the node
nodePath, String
the type of the node, can be null
type)

Set the type of a node.

public void
setNodeValue(String[]
the absolute path of the node
nodePath, DmtData
the data to be set, can be null
data)

Set the value of a leaf or interior node.

Inherited from org.osgi.service.dmt.spi.ReadableDataSession:
closegetChildNodeNamesgetMetaNodegetNodeSizegetNodeTimestampgetNodeTitlegetNodeTypegetNodeValuegetNodeVersionisLeafNodeisNodeUrinodeChanged

Method Detail

copyback to summary
public void copy(String[] nodePath, 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:String[]

an absolute path specifying the node or the root of a subtree to be copied

newNodePath:String[]

the absolute path of the new node or root of a subtree

recursive:boolean

false if only a single node is copied, true if the whole subtree is copied

Exceptions
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
SecurityException:
if the caller does not have the necessary permissions to execute the underlying management operation
See Also
DmtSession#copy(String, String, boolean)
createInteriorNodeback to summary
public void createInteriorNode(String[] nodePath, 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:String[]

the absolute path of the node to create

type:String

the type URI of the interior node, can be null if no node type is defined

Exceptions
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
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)
createLeafNodeback to summary
public void createLeafNode(String[] nodePath, DmtData value, 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:String[]

the absolute path of the node to create

value:DmtData

the value to be given to the new node, can be null

mimeType:String

the MIME type to be given to the new node, can be null

Exceptions
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
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)
deleteNodeback to summary
public void deleteNode(String[] nodePath) throws DmtException

Delete the given node. Deleting interior nodes is recursive, the whole subtree under the given node is deleted.

Parameters
nodePath:String[]

the absolute path of the node to delete

Exceptions
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
SecurityException:
if the caller does not have the necessary permissions to execute the underlying management operation
See Also
DmtSession#deleteNode(String)
renameNodeback to summary
public void renameNode(String[] nodePath, 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:String[]

the absolute path of the node to rename

newName:String

the new name property of the node

Exceptions
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
SecurityException:
if the caller does not have the necessary permissions to execute the underlying management operation
See Also
DmtSession#renameNode(String, String)
setNodeTitleback to summary
public void setNodeTitle(String[] nodePath, 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:String[]

the absolute path of the node

title:String

the title text 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 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
SecurityException:
if the caller does not have the necessary permissions to execute the underlying management operation
See Also
DmtSession#setNodeTitle(String, String)
setNodeTypeback to summary
public void setNodeType(String[] nodePath, 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:String[]

the absolute path of the node

type: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 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
SecurityException:
if the caller does not have the necessary permissions to execute the underlying management operation
See Also
DmtSession#setNodeType(String, String)
setNodeValueback to summary
public void setNodeValue(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:String[]

the absolute path of the node

data:DmtData

the data to be set, 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 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
SecurityException:
if the caller does not have the necessary permissions to execute the underlying management operation
See Also
DmtSession#setNodeValue(String, DmtData)