|
OSGi™ Service Platform Residential Specification Release 4 Version 4.3 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface ReadWriteDataSession
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.
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 org.osgi.service.dmt.spi.ReadableDataSession |
---|
close, getChildNodeNames, getMetaNode, getNodeSize, getNodeTimestamp, getNodeTitle, getNodeType, getNodeValue, getNodeVersion, isLeafNode, isNodeUri, nodeChanged |
Method Detail |
---|
void copy(java.lang.String[] nodePath, java.lang.String[] newNodePath, boolean recursive) throws DmtException
nodePath
- an absolute path specifying the node or the root of a
subtree to be copiednewNodePath
- the absolute path of the new node or root of a subtreerecursive
- false
if only a single node is copied,
true
if the whole subtree is copied
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 operationDmtSession.copy(String, String, boolean)
void createInteriorNode(java.lang.String[] nodePath, java.lang.String type) throws DmtException
nodePath
- the absolute path of the node to createtype
- the type URI of the interior node, can be null
if no
node type is defined
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 operationDmtSession.createInteriorNode(String)
,
DmtSession.createInteriorNode(String, String)
void createLeafNode(java.lang.String[] nodePath, DmtData value, java.lang.String mimeType) throws DmtException
null
, their default values must be taken.
nodePath
- the absolute path of the node to createvalue
- the value to be given to the new node, can be null
mimeType
- the MIME type to be given to the new node, can be
null
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
java.lang.SecurityException
- if the caller does not have the necessary
permissions to execute the underlying management operationDmtSession.createLeafNode(String)
,
DmtSession.createLeafNode(String, DmtData)
,
DmtSession.createLeafNode(String, DmtData, String)
void deleteNode(java.lang.String[] nodePath) throws DmtException
nodePath
- the absolute path of the node to delete
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
java.lang.SecurityException
- if the caller does not have the necessary
permissions to execute the underlying management operationDmtSession.deleteNode(String)
void renameNode(java.lang.String[] nodePath, java.lang.String newName) throws DmtException
nodePath
- the absolute path of the node to renamenewName
- the new name property of the node
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
java.lang.SecurityException
- if the caller does not have the necessary
permissions to execute the underlying management operationDmtSession.renameNode(String, String)
void setNodeTitle(java.lang.String[] nodePath, java.lang.String title) throws DmtException
nodePath
- the absolute path of the nodetitle
- the title text of the node, can be null
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
java.lang.SecurityException
- if the caller does not have the necessary
permissions to execute the underlying management operationDmtSession.setNodeTitle(String, String)
void setNodeType(java.lang.String[] nodePath, java.lang.String type) throws DmtException
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.
nodePath
- the absolute path of the nodetype
- the type of the node, can be null
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
java.lang.SecurityException
- if the caller does not have the necessary
permissions to execute the underlying management operationDmtSession.setNodeType(String, String)
void setNodeValue(java.lang.String[] nodePath, DmtData data) throws DmtException
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.
nodePath
- the absolute path of the nodedata
- the data to be set, can be null
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
java.lang.SecurityException
- if the caller does not have the necessary
permissions to execute the underlying management operationDmtSession.setNodeValue(String, DmtData)
|
OSGi™ Service Platform Residential Specification Release 4 Version 4.3 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |