info.dmtree
Interface DmtSession

public interface DmtSession

DmtSession provides concurrent access to the DMT. All DMT manipulation
commands for management applications are available on the
DmtSession interface. The session is associated with a root node
which limits the subtree in which the operations can be executed within this
session.

Most of the operations take a node URI as parameter, which can be either an
absolute URI (starting with "./") or a URI relative to the root
node of the session. The empty string as relative URI means the root URI the
session was opened with. All segments of a URI must be within the segment
length limit of the implementation, and the special characters '/' and '\'
must be escaped (preceded by a '\'). Any string can be converted to a valid
URI segment using the Uri.mangle(String) method.

If the URI specified does not correspond to a legitimate node in the tree an
exception is thrown. The only exception is the isNodeUri(String)
method which returns false in case of an invalid URI.

Each method of DmtSession that accesses the tree in any way can
throw DmtIllegalStateException if the session has been closed or
invalidated (due to timeout, fatal exceptions, or unexpectedly unregistered
plugins).

Field Summary

static int

LOCK_TYPE_ATOMICLOCK_TYPE_ATOMIC is an exclusive lock with transactional
functionality.

static int

LOCK_TYPE_EXCLUSIVELOCK_TYPE_EXCLUSIVE lock guarantees full access to the
tree, but can not be shared with any other locks.

static int

LOCK_TYPE_SHARED
Sessions created with LOCK_TYPE_SHARED lock allows
read-only access to the tree, but can be shared between multiple readers.

static int

STATE_CLOSED
The session is closed, DMT manipulation operations are not available,
they throw DmtIllegalStateException if tried.

LOCK_TYPE_EXCLUSIVE

LOCK_TYPE_ATOMIC

static final int LOCK_TYPE_ATOMIC

LOCK_TYPE_ATOMIC is an exclusive lock with transactional
functionality. Commands of an atomic session will either fail or succeed
together, if a single command fails then the whole session will be rolled
back.

STATE_CLOSED

STATE_INVALID

static final int STATE_INVALID

The session is invalid because a fatal error happened. Fatal errors
include the timeout of the session, any DmtException with the 'fatal'
flag set, or the case when a plugin service is unregistered while in use
by the session. DMT manipulation operations are not available, they throw
DmtIllegalStateException if tried.

commit

Commits a series of DMT operations issued in the current atomic session
since the last transaction boundary. Transaction boundaries are the
creation of this object that starts the session, and all subsequent
commit() and rollback() calls.

This method can fail even if all operations were successful. This can
happen due to some multi-node semantic constraints defined by a specific
implementation. For example, node A can be required to always have
children A/B, A/C and A/D. If this condition is broken when
commit() is executed, the method will fail, and throw a
METADATA_MISMATCH exception.

An error situation can arise due to the lack of a two phase commit
mechanism in the underlying plugins. As an example, if plugin A has
committed successfully but plugin B failed, the whole session must fail,
but there is no way to undo the commit performed by A. To provide
predictable behaviour, the commit operation should continue with the
remaining plugins even after detecting a failure. All exceptions received
from failed commits are aggregated into one
TRANSACTION_ERROR exception thrown by this method.

In many cases the tree is not the only way to manage a given part of the
system. It may happen that while modifying some nodes in an atomic
session, the underlying settings are modified in parallel outside the
scope of the DMT. If this is detected during commit, an exception with
the code CONCURRENT_ACCESS is thrown.

rollback

Rolls back a series of DMT operations issued in the current atomic
session since the last transaction boundary. Transaction boundaries are
the creation of this object that starts the session, and all subsequent
commit() and rollback() calls.

Throws:

DmtException - with the error code ROLLBACK_FAILED
in case the rollback did not succeed

DmtIllegalStateException - if the session was not opened using the
LOCK_TYPE_ATOMIC lock type, or if the session is
already closed or invalidated

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

close

Closes a session. If the session was opened with atomic lock mode, the
DmtSession must first persist the changes made to the DMT
by calling commit() on all (transactional) plugins
participating in the session. See the documentation of the
commit() method for details and possible errors during this
operation.

The state of the session changes to DmtSession.STATE_CLOSED
if the close operation completed successfully, otherwise it becomes
DmtSession.STATE_INVALID.

URI_TOO_LONG if nodeUri or a
segment of it is too long, or if it has too many segments

INVALID_URI if nodeUri is
null or syntactically invalid

NODE_NOT_FOUND if the node does not exist and
the plugin does not allow executing unexisting nodes

PERMISSION_DENIED if the session is
associated with a principal and the ACL of the node does not
allow the Execute operation for the associated
principal

METADATA_MISMATCH if the node cannot be
executed according to the meta-data (does not have
MetaNode.CMD_EXECUTE access type)

DATA_STORE_FAILURE if an error occurred while
accessing the data store

COMMAND_FAILED if the URI is not within the
current session's subtree, if no DmtExecPlugin is associated with
the node and the DmtAdmin can not execute the node, or if some
unspecified error is encountered while attempting to complete the
command

DmtIllegalStateException - if the session was opened using the
LOCK_TYPE_SHARED lock type, or if the session is
already closed or invalidated

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the node with the Exec action
present

execute

Executes a node, also specifying a correlation ID for use in response
notifications. This operation corresponds to the EXEC command in OMA DM.
This method cannot be called in a read-only session.

The semantics of an execute operation and the data parameter it takes
depends on the definition of the managed object on which the command is
issued. If a correlation ID is specified, it should be used as the
correlator parameter for notifications sent in response to this
execute operation.

Parameters:

nodeUri - the node on which the execute operation is issued

correlator - an identifier to associate this operation with any
notifications sent in response to it, can be null if not
needed

URI_TOO_LONG if nodeUri or a
segment of it is too long, or if it has too many segments

INVALID_URI if nodeUri is
null or syntactically invalid

NODE_NOT_FOUND if the node does not exist and
the plugin does not allow executing unexisting nodes

PERMISSION_DENIED if the session is
associated with a principal and the ACL of the node does not
allow the Execute operation for the associated
principal

METADATA_MISMATCH if the node cannot be
executed according to the meta-data (does not have
MetaNode.CMD_EXECUTE access type)

DATA_STORE_FAILURE if an error occurred while
accessing the data store

COMMAND_FAILED if the URI is not within the
current session's subtree, if no DmtExecPlugin is associated with
the node, or if some unspecified error is encountered while
attempting to complete the command

DmtIllegalStateException - if the session was opened using the
LOCK_TYPE_SHARED lock type, or if the session is
already closed or invalidated

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the node with the Exec action
present

getEffectiveNodeAcl

Gives the Access Control List in effect for a given node. The returned
Acl takes inheritance into account, that is if there is no
ACL defined for the node, it will be derived from the closest ancestor
having an ACL defined.

setNodeAcl

Set the Access Control List associated with a given node. To perform this
operation, the caller needs to have replace rights (Acl.REPLACE
or the corresponding Java permission depending on the session type) as
described below:

if nodeUri specifies a leaf node, replace rights are
needed on the parent of the node

if nodeUri specifies an interior node, replace rights
on either the node or its parent are sufficient

If the given acl is null or an empty ACL
(not specifying any permissions for any principals), then the ACL of the
node is deleted, and the node will inherit the ACL from its parent node.

copy

Create a copy of a node or a whole subtree. Beside the structure and
values of the nodes, most properties are also copied, with the exception
of the ACL (Access Control List), Timestamp and Version properties.

The copy method is essentially a convenience method that could be
substituted with a sequence of retrieval and update operations. This
determines the permissions required for copying. However, some
optimization can be possible if the source and target nodes are all
handled by DmtAdmin or by the same plugin. In this case, the handler
might be able to perform the underlying management operation more
efficiently: for example, a configuration table can be copied at once
instead of reading each node for each entry and creating it in the new
tree.

URI_TOO_LONG if nodeUri or
newNodeUri or any segment of them is too long, or
if they have too many segments

INVALID_URI if nodeUri or
newNodeUri is null or syntactically
invalid

NODE_NOT_FOUND if nodeUri
points to a non-existing node, or if newNodeUri
points to a node that cannot exist in the tree according to the
meta-data (see getMetaNode(String))

NODE_ALREADY_EXISTS if
newNodeUri points to a node that already exists

PERMISSION_DENIED if the session is
associated with a principal and the ACL of the copied node(s)
does not allow the Get operation, or the ACL of
the parent of the target node does not allow the Add
operation for the associated principal

COMMAND_NOT_ALLOWED if nodeUri
is an ancestor of newNodeUri, or if any of the
implied retrieval or update operations are not allowed

METADATA_MISMATCH if any of the meta-data
constraints of the implied retrieval or update operations are
violated

TRANSACTION_ERROR in an atomic session if the
underlying plugin is read-only or does not support atomic writing

DATA_STORE_FAILURE if an error occurred while
accessing the data store

COMMAND_FAILED if either URI is not within
the current session's subtree, or if some unspecified error is
encountered while attempting to complete the command

DmtIllegalStateException - if the session was opened using the
LOCK_TYPE_SHARED lock type, or if the session is
already closed or invalidated

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the copied node(s) with the Get
action present, or for the parent of the target node with the Add
action

createInteriorNode

Create an interior node. If the parent node does not exist, it is created
automatically, as if this method were called for the parent URI. This way
all missing ancestor nodes leading to the specified node are created. Any
exceptions encountered while creating the ancestors are propagated to the
caller of this method, these are not explicitly listed in the error
descriptions below.

If meta-data is available for the node, several checks are made before
creating it. The node must have MetaNode.CMD_ADD access
type, it must be defined as a non-permanent interior node, the node name
must conform to the valid names, and the creation of the new node must
not cause the maximum occurrence number to be exceeded.

If the meta-data cannot be retrieved because the given node cannot
possibly exist in the tree (it is not defined in the specification), the
NODE_NOT_FOUND error code is returned (see
getMetaNode(String)).

URI_TOO_LONG if nodeUri or a
segment of it is too long, or if it has too many segments

INVALID_URI if nodeUri is
null or syntactically invalid

NODE_NOT_FOUND if nodeUri
points to a node that cannot exist in the tree (see above)

NODE_ALREADY_EXISTS if nodeUri
points to a node that already exists

PERMISSION_DENIED if the session is
associated with a principal and the ACL of the parent node does
not allow the Add operation for the associated
principal

COMMAND_NOT_ALLOWED if the parent node is not
an interior node, or in non-atomic sessions if the underlying
plugin is read-only or does not support non-atomic writing

METADATA_MISMATCH if the node could not be
created because of meta-data restrictions (see above)

TRANSACTION_ERROR in an atomic session if the
underlying plugin is read-only or does not support atomic writing

DATA_STORE_FAILURE if an error occurred while
accessing the data store

COMMAND_FAILED if the URI is not within the
current session's subtree, or if some unspecified error is
encountered while attempting to complete the command

DmtIllegalStateException - if the session was opened using the
LOCK_TYPE_SHARED lock type, or if the session is
already closed or invalidated

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the parent node with the Add
action present

createInteriorNode

Create an interior node with a given type. The type of interior node, if
specified, is a URI identifying a DDF document. If the parent node does
not exist, it is created automatically, as if
createInteriorNode(String) were called for the parent URI. This
way all missing ancestor nodes leading to the specified node are created.
Any exceptions encountered while creating the ancestors are propagated to
the caller of this method, these are not explicitly listed in the error
descriptions below.

If meta-data is available for the node, several checks are made before
creating it. The node must have MetaNode.CMD_ADD access
type, it must be defined as a non-permanent interior node, the node name
must conform to the valid names, and the creation of the new node must
not cause the maximum occurrence number to be exceeded.

If the meta-data cannot be retrieved because the given node cannot
possibly exist in the tree (it is not defined in the specification), the
NODE_NOT_FOUND error code is returned (see
getMetaNode(String)).

Interior node type identifiers must follow the format defined in section
7.7.7.2 of the OMA Device Management Tree and Description document.
Checking the validity of the type string does not have to be done by the
DmtAdmin, this can be left to the plugin handling the node (if any), to
avoid unnecessary double-checks.

Parameters:

nodeUri - the URI of the node to create

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

URI_TOO_LONG if nodeUri or a
segment of it is too long, or if it has too many segments

INVALID_URI if nodeUri is
null or syntactically invalid

NODE_NOT_FOUND if nodeUri
points to a node that cannot exist in the tree (see above)

NODE_ALREADY_EXISTS if nodeUri
points to a node that already exists

PERMISSION_DENIED if the session is
associated with a principal and the ACL of the parent node does
not allow the Add operation for the associated
principal

COMMAND_NOT_ALLOWED if the parent node is not
an interior node, or in non-atomic sessions if the underlying
plugin is read-only or does not support non-atomic writing

METADATA_MISMATCH if the node could not be
created because of meta-data restrictions (see above)

TRANSACTION_ERROR in an atomic session if the
underlying plugin is read-only or does not support atomic writing

DATA_STORE_FAILURE if an error occurred while
accessing the data store

COMMAND_FAILED if the URI is not within the
current session's subtree, if the type string is invalid (see
above), or if some unspecified error is encountered while
attempting to complete the command

DmtIllegalStateException - if the session was opened using the
LOCK_TYPE_SHARED lock type, or if the session is
already closed or invalidated

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the parent node with the Add
action present

createLeafNode

Create a leaf node with default value and MIME type. If a node does not
have a default value or MIME type, this method will throw a
DmtException with error code
METADATA_MISMATCH. Note that a node might have a default
value or MIME type even if there is no meta-data for the node or its
meta-data does not specify the default.

If the parent node does not exist, it is created automatically, as if
createInteriorNode(String) were called for the parent URI. This
way all missing ancestor nodes leading to the specified node are created.
Any exceptions encountered while creating the ancestors are propagated to
the caller of this method, these are not explicitly listed in the error
descriptions below.

If meta-data is available for a node, several checks are made before
creating it. The node must have MetaNode.CMD_ADD access
type, it must be defined as a non-permanent leaf node, the node name must
conform to the valid names, and the creation of the new node must not
cause the maximum occurrence number to be exceeded.

If the meta-data cannot be retrieved because the given node cannot
possibly exist in the tree (it is not defined in the specification), the
NODE_NOT_FOUND error code is returned (see
getMetaNode(String)).

URI_TOO_LONG if nodeUri or a
segment of it is too long, or if it has too many segments

INVALID_URI if nodeUri is
null or syntactically invalid

NODE_NOT_FOUND if nodeUri
points to a node that cannot exist in the tree (see above)

NODE_ALREADY_EXISTS if nodeUri
points to a node that already exists

PERMISSION_DENIED if the session is
associated with a principal and the ACL of the parent node does
not allow the Add operation for the associated
principal

COMMAND_NOT_ALLOWED if the parent node is not
an interior node, or in non-atomic sessions if the underlying
plugin is read-only or does not support non-atomic writing

METADATA_MISMATCH if the node could not be
created because of meta-data restrictions (see above)

TRANSACTION_ERROR in an atomic session if the
underlying plugin is read-only or does not support atomic writing

DATA_STORE_FAILURE if an error occurred while
accessing the data store

COMMAND_FAILED if the URI is not within the
current session's subtree, or if some unspecified error is
encountered while attempting to complete the command

DmtIllegalStateException - if the session was opened using the
LOCK_TYPE_SHARED lock type, or if the session is
already closed or invalidated

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the parent node with the Add
action present

createLeafNode

Create a leaf node with a given value and the default MIME type. If the
specified value is null, the default value is taken. If
the node does not have a default MIME type or value (if needed), this
method will throw a DmtException with error code
METADATA_MISMATCH. Note that a node might have a default
value or MIME type even if there is no meta-data for the node or its
meta-data does not specify the default.

If the parent node does not exist, it is created automatically, as if
createInteriorNode(String) were called for the parent URI. This
way all missing ancestor nodes leading to the specified node are created.
Any exceptions encountered while creating the ancestors are propagated to
the caller of this method, these are not explicitly listed in the error
descriptions below.

If meta-data is available for a node, several checks are made before
creating it. The node must have MetaNode.CMD_ADD access
type, it must be defined as a non-permanent leaf node, the node name must
conform to the valid names, the node value must conform to the value
constraints, and the creation of the new node must not cause the maximum
occurrence number to be exceeded.

If the meta-data cannot be retrieved because the given node cannot
possibly exist in the tree (it is not defined in the specification), the
NODE_NOT_FOUND error code is returned (see
getMetaNode(String)).

URI_TOO_LONG if nodeUri or a
segment of it is too long, or if it has too many segments

INVALID_URI if nodeUri is
null or syntactically invalid

NODE_NOT_FOUND if nodeUri
points to a node that cannot exist in the tree (see above)

NODE_ALREADY_EXISTS if nodeUri
points to a node that already exists

PERMISSION_DENIED if the session is
associated with a principal and the ACL of the parent node does
not allow the Add operation for the associated
principal

COMMAND_NOT_ALLOWED if the parent node is not
an interior node, or in non-atomic sessions if the underlying
plugin is read-only or does not support non-atomic writing

METADATA_MISMATCH if the node could not be
created because of meta-data restrictions (see above)

TRANSACTION_ERROR in an atomic session if the
underlying plugin is read-only or does not support atomic writing

DATA_STORE_FAILURE if an error occurred while
accessing the data store

COMMAND_FAILED if the URI is not within the
current session's subtree, or if some unspecified error is
encountered while attempting to complete the command

DmtIllegalStateException - if the session was opened using the
LOCK_TYPE_SHARED lock type, or if the session is
already closed or invalidated

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the parent node with the Add
action present

createLeafNode

Create a leaf node with a given value and MIME type. If the specified
value or MIME type is null, their default values are
taken. If the node does not have the necessary defaults, this method will
throw a DmtException with error code
METADATA_MISMATCH. Note that a node might have a default
value or MIME type even if there is no meta-data for the node or its
meta-data does not specify the default.

If the parent node does not exist, it is created automatically, as if
createInteriorNode(String) were called for the parent URI. This
way all missing ancestor nodes leading to the specified node are created.
Any exceptions encountered while creating the ancestors are propagated to
the caller of this method, these are not explicitly listed in the error
descriptions below.

If meta-data is available for a node, several checks are made before
creating it. The node must have MetaNode.CMD_ADD access
type, it must be defined as a non-permanent leaf node, the node name must
conform to the valid names, the node value must conform to the value
constraints, the MIME type must be among the listed types, and the
creation of the new node must not cause the maximum occurrence number to
be exceeded.

If the meta-data cannot be retrieved because the given node cannot
possibly exist in the tree (it is not defined in the specification), the
NODE_NOT_FOUND error code is returned (see
getMetaNode(String)).

The MIME type string must conform to the definition in RFC 2045. Checking
its validity does not have to be done by the DmtAdmin, this can be left
to the plugin handling the node (if any), to avoid unnecessary
double-checks.

URI_TOO_LONG if nodeUri or a
segment of it is too long, or if it has too many segments

INVALID_URI if nodeUri is
null or syntactically invalid

NODE_NOT_FOUND if nodeUri
points to a node that cannot exist in the tree (see above)

NODE_ALREADY_EXISTS if nodeUri
points to a node that already exists

PERMISSION_DENIED if the session is
associated with a principal and the ACL of the parent node does
not allow the Add operation for the associated
principal

COMMAND_NOT_ALLOWED if the parent node is not
an interior node, or in non-atomic sessions if the underlying
plugin is read-only or does not support non-atomic writing

METADATA_MISMATCH if the node could not be
created because of meta-data restrictions (see above)

TRANSACTION_ERROR in an atomic session if the
underlying plugin is read-only or does not support atomic writing

DATA_STORE_FAILURE if an error occurred while
accessing the data store

COMMAND_FAILED if the URI is not within the
current session's subtree, if mimeType is not a
proper MIME type string (see above), or if some unspecified error
is encountered while attempting to complete the command

DmtIllegalStateException - if the session was opened using the
LOCK_TYPE_SHARED lock type, or if the session is
already closed or invalidated

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the parent node with the Add
action present

deleteNode

Delete the given node. Deleting interior nodes is recursive, the whole
subtree under the given node is deleted. It is not allowed to delete
the root node of the session.

If meta-data is available for a node, several checks are made before
deleting it. The node must be non-permanent, it must have the
MetaNode.CMD_DELETE access type, and if zero occurrences
of the node are not allowed, it must not be the last one.

URI_TOO_LONG if nodeUri or a
segment of it is too long, or if it has too many segments

INVALID_URI if nodeUri is
null or syntactically invalid

NODE_NOT_FOUND if nodeUri
points to a non-existing node

PERMISSION_DENIED if the session is
associated with a principal and the ACL of the node does not
allow the Delete operation for the associated
principal

COMMAND_NOT_ALLOWED if the target node is the
root of the session, or in non-atomic sessions if the underlying
plugin is read-only or does not support non-atomic writing

METADATA_MISMATCH if the node could not be
deleted because of meta-data restrictions (see above)

TRANSACTION_ERROR in an atomic session if the
underlying plugin is read-only or does not support atomic writing

DATA_STORE_FAILURE if an error occurred while
accessing the data store

COMMAND_FAILED if the URI is not within the
current session's subtree, or if some unspecified error is
encountered while attempting to complete the command

DmtIllegalStateException - if the session was opened using the
LOCK_TYPE_SHARED lock type, or if the session is
already closed or invalidated

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the node with the Delete action
present

renameNode

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 URI is constructed from the base of the old URI and
the given name. It is not allowed to rename the root node of the session.

If available, the meta-data of the original and the new nodes are checked
before performing the rename operation. Neither node can be permanent,
their leaf/interior property must match, and the name change must not
violate any of the cardinality constraints. The original node must have
the MetaNode.CMD_REPLACE access type, and the name of the
new node must conform to the valid names.

URI_TOO_LONG if nodeUri or a
segment of it is too long, if nodeUri has too many
segments, or if newName is too long

INVALID_URI if nodeUri or
newName is null or syntactically
invalid

NODE_NOT_FOUND if nodeUri
points to a non-existing node, or if the new node is not defined
in the tree according to the meta-data (see
getMetaNode(String))

NODE_ALREADY_EXISTS if there already exists a
sibling of nodeUri with the name
newName

PERMISSION_DENIED if the session is
associated with a principal and the ACL of the node does not
allow the Replace operation for the associated
principal

COMMAND_NOT_ALLOWED if the target node is the
root of the session, or in non-atomic sessions if the underlying
plugin is read-only or does not support non-atomic writing

METADATA_MISMATCH if the node could not be
renamed because of meta-data restrictions (see above)

TRANSACTION_ERROR in an atomic session if the
underlying plugin is read-only or does not support atomic writing

DATA_STORE_FAILURE if an error occurred while
accessing the data store

COMMAND_FAILED if the URI is not within the
current session's subtree, or if some unspecified error is
encountered while attempting to complete the command

DmtIllegalStateException - if the session was opened using the
LOCK_TYPE_SHARED lock type, or if the session is
already closed or invalidated

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the node with the Replace action
present

URI_TOO_LONG if nodeUri or a
segment of it is too long, or if it has too many segments

INVALID_URI if nodeUri is
null or syntactically invalid

NODE_NOT_FOUND if nodeUri
points to a non-existing node

PERMISSION_DENIED if the session is
associated with a principal and the ACL of the node does not
allow the Replace operation for the associated
principal

COMMAND_NOT_ALLOWED in non-atomic sessions if
the underlying plugin is read-only or does not support non-atomic
writing

METADATA_MISMATCH if the node is permanent or
cannot be modified according to the meta-data (does not have the
MetaNode.CMD_REPLACE access type), or if there is
no default value defined for this node

FEATURE_NOT_SUPPORTED if the specified node is
an interior node and does not support Java object values

TRANSACTION_ERROR in an atomic session if the
underlying plugin is read-only or does not support atomic writing

DATA_STORE_FAILURE if an error occurred while
accessing the data store

COMMAND_FAILED if the URI is not within the
current session's subtree, or if some unspecified error is
encountered while attempting to complete the command

DmtIllegalStateException - if the session was opened using the
LOCK_TYPE_SHARED lock type, or if the session is
already closed or invalidated

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the node with the Replace action
present

setNodeValue

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 must be FORMAT_NODE, while for leaf nodes this
format must not be used.

If the specified value is null, the default value is taken.
In this case, if the node does not have a default value, this method will
throw a DmtException with error code
METADATA_MISMATCH. Nodes of null format can be
set by using DmtData.NULL_VALUE as second argument.

An Event of type REPLACE is sent out for a leaf node. A replaced interior
node sends out events for each of its children in depth first order
and node names sorted with Arrays.sort(String[]). When setting a value
on an interior node, the values of the leaf nodes under it can change,
but the structure of the subtree is not modified by the operation.

URI_TOO_LONG if nodeUri or a
segment of it is too long, or if it has too many segments

INVALID_URI if nodeUri is
null or syntactically invalid

NODE_NOT_FOUND if nodeUri
points to a non-existing node

PERMISSION_DENIED if the session is
associated with a principal and the ACL of the node does not
allow the Replace operation for the associated
principal

COMMAND_NOT_ALLOWED if the given data has
FORMAT_NODE format but the node is a leaf node (or
vice versa), or in non-atomic sessions if the underlying plugin
is read-only or does not support non-atomic writing

METADATA_MISMATCH if the node is permanent or
cannot be modified according to the meta-data (does not have the
MetaNode.CMD_REPLACE access type), or if the given
value does not conform to the meta-data value constraints

FEATURE_NOT_SUPPORTED if the specified node is
an interior node and does not support Java object values

TRANSACTION_ERROR in an atomic session if the
underlying plugin is read-only or does not support atomic writing

DATA_STORE_FAILURE if an error occurred while
accessing the data store

COMMAND_FAILED if the URI is not within the
current session's subtree, or if some unspecified error is
encountered while attempting to complete the command

DmtIllegalStateException - if the session was opened using the
LOCK_TYPE_SHARED lock type, or if the session is
already closed or invalidated

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the node with the Replace action
present

URI_TOO_LONG if nodeUri or a
segment of it is too long, or if it has too many segments

INVALID_URI if nodeUri is
null or syntactically invalid

NODE_NOT_FOUND if nodeUri
points to a non-existing node

PERMISSION_DENIED if the session is
associated with a principal and the ACL of the node does not
allow the Replace operation for the associated
principal

COMMAND_NOT_ALLOWED in non-atomic sessions if
the underlying plugin is read-only or does not support non-atomic
writing

METADATA_MISMATCH if the node cannot be
modified according to the meta-data (does not have the
MetaNode.CMD_REPLACE access type)

FEATURE_NOT_SUPPORTED if the Title property
is not supported by the DmtAdmin implementation or the
underlying plugin

TRANSACTION_ERROR in an atomic session if the
underlying plugin is read-only or does not support atomic writing

DATA_STORE_FAILURE if an error occurred while
accessing the data store

COMMAND_FAILED if the title string is too
long, if the URI is not within the current session's subtree, or
if some unspecified error is encountered while attempting to
complete the command

DmtIllegalStateException - if the session was opened using the
LOCK_TYPE_SHARED lock type, or if the session is
already closed or invalidated

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the node with the Replace action
present

setNodeType

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, a null type string means that there is
no 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. If the node does not have a default MIME type this method
will throw a DmtException with error code
METADATA_MISMATCH. Note that a node might have a default
MIME type even if there is no meta-data for the node or its meta-data
does not specify the default.

MIME types must conform to the definition in RFC 2045. Interior node type
identifiers must follow the format defined in section 7.7.7.2 of the OMA
Device Management Tree and Description document. Checking the validity of
the type string does not have to be done by the DmtAdmin, this can be
left to the plugin handling the node (if any), to avoid unnecessary
double-checks.

URI_TOO_LONG if nodeUri or a
segment of it is too long, or if it has too many segments

INVALID_URI if nodeUri is
null or syntactically invalid

NODE_NOT_FOUND if nodeUri
points to a non-existing node

PERMISSION_DENIED if the session is
associated with a principal and the ACL of the node does not
allow the Replace operation for the associated
principal

COMMAND_NOT_ALLOWED in non-atomic sessions if
the underlying plugin is read-only or does not support non-atomic
writing

METADATA_MISMATCH if the node is permanent or
cannot be modified according to the meta-data (does not have the
MetaNode.CMD_REPLACE access type), and in case of
leaf nodes, if null is given and there is no
default MIME type, or the given MIME type is not allowed

TRANSACTION_ERROR in an atomic session if the
underlying plugin is read-only or does not support atomic writing

DATA_STORE_FAILURE if an error occurred while
accessing the data store

COMMAND_FAILED if the URI is not within the
current session's subtree, if the type string is invalid (see
above), or if some unspecified error is encountered while
attempting to complete the command

DmtIllegalStateException - if the session was opened using the
LOCK_TYPE_SHARED lock type, or if the session is
already closed or invalidated

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the node with the Replace action
present

getChildNodeNames

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 child names are mangled (Uri.mangle(String)). The elements
are in no particular order. The returned array must not contain
null entries.

Parameters:

nodeUri - the URI 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

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the node with the Get action
present

getMetaNode

Get the meta data which describes a given node. Meta data can only be
inspected, it can not be changed.

The MetaNode object returned to the client is the
combination of the meta data returned by the data plugin (if any) plus
the meta data returned by the DmtAdmin. 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 in the specification). For nodes that
are not defined, it may throw DmtException with the error
code NODE_NOT_FOUND. 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:

nodeUri - the URI 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

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the node with the Get action
present

getNodeSize

Get the size of the data in a leaf node. The returned value 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.

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the node with the Get action
present

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the node with the Get action
present

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the node with the Get action
present

getNodeType

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.

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the node with the Get action
present

URI_TOO_LONG if nodeUri or a
segment of it is too long, or if it has too many segments

INVALID_URI if nodeUri is
null or syntactically invalid

NODE_NOT_FOUND if nodeUri
points to a non-existing node

PERMISSION_DENIED if the session is
associated with a principal and the ACL of the node (and the ACLs
of all its descendants in case of interior nodes) do not allow
the Get operation for the associated principal

METADATA_MISMATCH if the node value cannot be
retrieved according to the meta-data (it does not have
MetaNode.CMD_GET access type)

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 the URI is not within the
current session's subtree, or 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, or,
in case of local sessions, if the caller does not have
DmtPermission for the node (and all its descendants
in case of interior nodes) with the Get action present

getNodeVersion

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.

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the node with the Get action
present

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the node with the Get action
present

isNodeUri

boolean isNodeUri(java.lang.String nodeUri)

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

java.lang.SecurityException - if the caller does not have the necessary
permissions to execute the underlying management operation, or,
in case of local sessions, if the caller does not have
DmtPermission for the node with the Get action
present