|
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 DmtAdmin
An interface providing methods to open sessions and register listeners. The
implementation of DmtAdmin
should register itself in the OSGi
service registry as a service. DmtAdmin
is the entry point for
applications to use the DMT API.
The getSession
methods are used to open a session on a specified
subtree of the DMT. A typical way of usage:
serviceRef = context.getServiceReference(DmtAdmin.class.getName()); DmtAdmin admin = (DmtAdmin) context.getService(serviceRef); DmtSession session = admin.getSession("./OSGi/Configuration"); session.createInteriorNode("./OSGi/Configuration/my.table");
The methods for opening a session take a node URI (the session root) as a parameter. All segments of the given URI must be within the segment length limit of the implementation, and the special characters '/' and '\' must be escaped (preceded by a '\').
See the Uri.encode(String)
method for support on escaping invalid
characters in a URI.
It is possible to specify a lock mode when opening the session (see lock type
constants in DmtSession
). This determines whether the session can run
in parallel with other sessions, and the kinds of operations that can be
performed in the session. All Management Objects constituting the device
management tree must support read operations on their nodes, while support
for write operations depends on the Management Object. Management Objects
supporting write access may support transactional write, non-transactional
write or both. Users of DmtAdmin
should consult the Management
Object specification and implementation for the supported update modes. If
Management Object definition permits, implementations are encouraged to
support both update modes.
Method Summary | |
---|---|
DmtSession |
getSession(java.lang.String subtreeUri)
Opens a DmtSession for local usage on a given subtree of
the DMT with non transactional write lock. |
DmtSession |
getSession(java.lang.String subtreeUri,
int lockMode)
Opens a DmtSession for local usage on a specific DMT
subtree with a given lock mode. |
DmtSession |
getSession(java.lang.String principal,
java.lang.String subtreeUri,
int lockMode)
Opens a DmtSession on a specific DMT subtree using a
specific lock mode on behalf of a remote principal. |
Method Detail |
---|
DmtSession getSession(java.lang.String subtreeUri) throws DmtException
DmtSession
for local usage on a given subtree of
the DMT with non transactional write lock. This call is equivalent to the
following:
getSession(null, subtreeUri, DmtSession.LOCK_TYPE_EXCLUSIVE)
The subtreeUri
parameter must contain an absolute URI. It
can also be null
, in this case the session is opened with
the default session root, ".", that gives access to the whole
tree.
To perform this operation the caller must have DmtPermission
for the subtreeUri
node with the Get action present.
subtreeUri
- the subtree on which DMT manipulations can be performed
within the returned session
DmtSession
object for the requested subtree
DmtException
- with the following possible error codes:
INVALID_URI
if subtreeUri
is
syntactically invalid
URI_TOO_LONG
if subtreeUri
is longer
than accepted by the DmtAdmin
implementation
(especially on systems with limited resources)
NODE_NOT_FOUND
if subtreeUri
specifies a non-existing node
SESSION_CREATION_TIMEOUT
if the operation
timed out because of another ongoing session
COMMAND_FAILED
if subtreeUri
specifies a relative URI, or some unspecified error is
encountered while attempting to complete the command
java.lang.SecurityException
- if the caller does not have
DmtPermission
for the given root node with the Get
action presentDmtSession getSession(java.lang.String subtreeUri, int lockMode) throws DmtException
DmtSession
for local usage on a specific DMT
subtree with a given lock mode. This call is equivalent to the
following: getSession(null, subtreeUri, lockMode)
The subtreeUri
parameter must contain an absolute URI. It
can also be null
, in this case the session is opened with
the default session root, ".", that gives access to the whole
tree.
To perform this operation the caller must have DmtPermission
for the subtreeUri
node with the Get action present.
subtreeUri
- the subtree on which DMT manipulations can be performed
within the returned sessionlockMode
- one of the lock modes specified in
DmtSession
DmtSession
object for the requested subtree
DmtException
- with the following possible error codes:
INVALID_URI
if subtreeUri
is
syntactically invalid
URI_TOO_LONG
if subtreeUri
is longer
than accepted by the DmtAdmin
implementation
(especially on systems with limited resources)
NODE_NOT_FOUND
if subtreeUri
specifies a non-existing node
FEATURE_NOT_SUPPORTED
if atomic sessions are
not supported by the implementation and lockMode
requests an atomic session
SESSION_CREATION_TIMEOUT
if the operation
timed out because of another ongoing session
COMMAND_FAILED
if subtreeUri
specifies a relative URI, if lockMode
is unknown,
or some unspecified error is encountered while attempting to
complete the command
java.lang.SecurityException
- if the caller does not have
DmtPermission
for the given root node with the Get
action presentDmtSession getSession(java.lang.String principal, java.lang.String subtreeUri, int lockMode) throws DmtException
DmtSession
on a specific DMT subtree using a
specific lock mode on behalf of a remote principal. If local management
applications are using this method then they should provide
null
as the first parameter. Alternatively they can use
other forms of this method without providing a principal string.
The subtreeUri
parameter must contain an absolute URI. It
can also be null
, in this case the session is opened with
the default session root, ".", that gives access to the whole
tree.
This method is guarded by DmtPrincipalPermission
in case of
remote sessions. In addition, the caller must have Get access rights
(ACL in case of remote sessions, DmtPermission
in case of
local sessions) on the subtreeUri
node to perform this
operation.
principal
- the identifier of the remote server on whose behalf the
data manipulation is performed, or null
for local
sessionssubtreeUri
- the subtree on which DMT manipulations can be performed
within the returned sessionlockMode
- one of the lock modes specified in
DmtSession
DmtSession
object for the requested subtree
DmtException
- with the following possible error codes:
INVALID_URI
if subtreeUri
is
syntactically invalid
URI_TOO_LONG
if subtreeUri
is longer
than accepted by the DmtAdmin
implementation
(especially on systems with limited resources)
NODE_NOT_FOUND
if subtreeUri
specifies a non-existing node
PERMISSION_DENIED
if principal
is
not null
and the ACL of the node does not allow the
Get
operation for the principal on the given root
node
FEATURE_NOT_SUPPORTED
if atomic sessions are
not supported by the implementation and lockMode
requests an atomic session
SESSION_CREATION_TIMEOUT
if the operation
timed out because of another ongoing session
COMMAND_FAILED
if subtreeUri
specifies a relative URI, if lockMode
is unknown,
or some unspecified error is encountered while attempting to
complete the command
java.lang.SecurityException
- in case of remote sessions, if the caller does
not have the required DmtPrincipalPermission
with a
target matching the principal
parameter, or in case
of local sessions, if the caller does not have
DmtPermission
for the given root node with the Get
action present
|
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 |