info.dmtree.spi
Interface ReadWriteDataSession

All Superinterfaces:

ReadableDataSession

All Known Subinterfaces:

TransactionalDataSession

public interface ReadWriteDataSession
extends ReadableDataSession

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 also ensures that the targeted nodes exist before calling the plugin (or that they do not exist, in case of node creation). However, some small amount of time elapses between the check and the call, so in case of plugins where the node structure can change independantly from the DMT, the target node might appear/disappear in that time. For example, a whole subtree can disappear when a Monitorable application is unregistered, which might happen in the middle of a DMT session accessing it. Plugins managing such nodes always need to check the existance or non-existance of nodes and throw DmtException.NODE_NOT_FOUND or DmtException.NODE_ALREADY_EXISTS as necessary, but for more static subtrees there is no need for the plugin to use these error codes.

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

void	copy(java.lang.String[] nodePath, java.lang.String[] newNodePath, boolean recursive) Create a copy of a node or a whole subtree.
void	createInteriorNode(java.lang.String[] nodePath, java.lang.String type) Create an interior node with a given type.
void	createLeafNode(java.lang.String[] nodePath, DmtData value, java.lang.String mimeType) Create a leaf node with a given value and MIME type.
void	deleteNode(java.lang.String[] nodePath) Delete the given node.
void	renameNode(java.lang.String[] nodePath, java.lang.String newName) Rename a node.
void	setNodeTitle(java.lang.String[] nodePath, java.lang.String title) Set the title property of a node.
void	setNodeType(java.lang.String[] nodePath, java.lang.String type) Set the type of a node.
void	setNodeValue(java.lang.String[] nodePath, DmtData data) Set the value of a leaf or interior node.

Methods inherited from interface info.dmtree.spi.ReadableDataSession

close, getChildNodeNames, getMetaNode, getNodeSize, getNodeTimestamp, getNodeTitle, getNodeType, getNodeValue, getNodeVersion, isLeafNode, isNodeUri, nodeChanged

Method Detail

copy

void copy(java.lang.String[] nodePath,
          java.lang.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 - an absolute path specifying the node or the root of a subtree to be copied

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

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

Throws:

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

java.lang.SecurityException - if the caller does not have the necessary permissions to execute the underlying management operation

See Also:

DmtSession.copy(String, String, boolean)

createInteriorNode

void createInteriorNode(java.lang.String[] nodePath,
                        java.lang.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 - the absolute path of the node to create

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

Throws:

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

java.lang.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)

createLeafNode

void createLeafNode(java.lang.String[] nodePath,
                    DmtData value,
                    java.lang.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 - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.

Parameters:

nodePath - the absolute path of the node to create

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

mimeType the new node,aken.