Interface DmtAdmin
-
public interface DmtAdmin
An interface providing methods to open sessions and register listeners. The implementation ofDmtAdmin
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 '\'). Any string can be converted to a valid URI segment using the
Uri.mangle(String)
method.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 ofDmtAdmin
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.This interface also contains methods for manipulating the set of
DmtEventListener
objects that are called when the structure or content of the tree is changed. These methods are not needed in an OSGi environment, clients should register listeners through the Event Admin service.- Version:
- $Revision: 5673 $
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
addEventListener(int type, java.lang.String uri, DmtEventListener listener)
Registers an event listener on behalf of a local application.void
addEventListener(java.lang.String principal, int type, java.lang.String uri, DmtEventListener listener)
Registers an event listener on behalf of a remote principal.DmtSession
getSession(java.lang.String subtreeUri)
Opens aDmtSession
for local usage on a given subtree of the DMT with non transactional write lock.DmtSession
getSession(java.lang.String subtreeUri, int lockMode)
Opens aDmtSession
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 aDmtSession
on a specific DMT subtree using a specific lock mode on behalf of a remote principal.void
removeEventListener(DmtEventListener listener)
Remove a previously registered listener.
-
-
-
Method Detail
-
getSession
DmtSession getSession(java.lang.String subtreeUri) throws DmtException
Opens aDmtSession
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 benull
, 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 thesubtreeUri
node with the Get action present.- Parameters:
subtreeUri
- the subtree on which DMT manipulations can be performed within the returned session- Returns:
- a
DmtSession
object for the requested subtree - Throws:
DmtException
- with the following possible error codes:URI_TOO_LONG
ifsubtreeUri
or a segment of it is too long, or if it has too many segmentsINVALID_URI
ifsubtreeUri
is syntactically invalidNODE_NOT_FOUND
ifsubtreeUri
specifies a non-existing nodeSESSION_CREATION_TIMEOUT
if the operation timed out because of another ongoing sessionCOMMAND_FAILED
ifsubtreeUri
specifies a relative URI, or some unspecified error is encountered while attempting to complete the command
java.lang.SecurityException
- if the caller does not haveDmtPermission
for the given root node with the Get action present
-
getSession
DmtSession getSession(java.lang.String subtreeUri, int lockMode) throws DmtException
Opens aDmtSession
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 benull
, 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 thesubtreeUri
node with the Get action present.- Parameters:
subtreeUri
- the subtree on which DMT manipulations can be performed within the returned sessionlockMode
- one of the lock modes specified inDmtSession
- Returns:
- a
DmtSession
object for the requested subtree - Throws:
DmtException
- with the following possible error codes:URI_TOO_LONG
ifsubtreeUri
or a segment of it is too long, or if it has too many segmentsINVALID_URI
ifsubtreeUri
is syntactically invalidNODE_NOT_FOUND
ifsubtreeUri
specifies a non-existing nodeFEATURE_NOT_SUPPORTED
if atomic sessions are not supported by the implementation andlockMode
requests an atomic sessionSESSION_CREATION_TIMEOUT
if the operation timed out because of another ongoing sessionCOMMAND_FAILED
ifsubtreeUri
specifies a relative URI, iflockMode
is unknown, or some unspecified error is encountered while attempting to complete the command
java.lang.SecurityException
- if the caller does not haveDmtPermission
for the given root node with the Get action present
-
getSession
DmtSession getSession(java.lang.String principal, java.lang.String subtreeUri, int lockMode) throws DmtException
Opens aDmtSession
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 providenull
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 benull
, 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 thesubtreeUri
node to perform this operation.- Parameters:
principal
- the identifier of the remote server on whose behalf the data manipulation is performed, ornull
for local sessionssubtreeUri
- the subtree on which DMT manipulations can be performed within the returned sessionlockMode
- one of the lock modes specified inDmtSession
- Returns:
- a
DmtSession
object for the requested subtree - Throws:
DmtException
- with the following possible error codes:URI_TOO_LONG
ifsubtreeUri
or a segment of it is too long, or if it has too many segmentsINVALID_URI
ifsubtreeUri
is syntactically invalidNODE_NOT_FOUND
ifsubtreeUri
specifies a non-existing nodePERMISSION_DENIED
ifprincipal
is notnull
and the ACL of the node does not allow theGet
operation for the principal on the given root nodeFEATURE_NOT_SUPPORTED
if atomic sessions are not supported by the implementation andlockMode
requests an atomic sessionSESSION_CREATION_TIMEOUT
if the operation timed out because of another ongoing sessionCOMMAND_FAILED
ifsubtreeUri
specifies a relative URI, iflockMode
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 requiredDmtPrincipalPermission
with a target matching theprincipal
parameter, or in case of local sessions, if the caller does not haveDmtPermission
for the given root node with the Get action present
-
addEventListener
void addEventListener(int type, java.lang.String uri, DmtEventListener listener)
Registers an event listener on behalf of a local application. The given listener will receive notification on all changes affecting the specified subtree. The subtree is specified by its root node URI. An event is delivered to the registered listener if at least one affected node is within this subtree. The events can also be filtered by specifying a bitmask of relevant event types (e.g.DmtEvent.ADDED | DmtEvent.REPLACED | DmtEvent.SESSION_CLOSED
). Only event types included in the bitmask will be delivered to the listener.The listener will only receive the change notifications of nodes for which the registering application has the appropriate GET
DmtPermission
.If the specified
listener
was already registered, calling this method will update the registration.- Parameters:
type
- a bitmask of event types the caller is interested inuri
- the URI of the root node of a subtree, must not benull
listener
- the listener to be registered, must not benull
- Throws:
java.lang.SecurityException
- if the caller doesn't have the necessary GETDmtPermission
for the given URIjava.lang.NullPointerException
- if theuri
orlistener
parameter isnull
java.lang.IllegalArgumentException
- if thetype
parameter contains invalid bits (not corresponding to any event type defined inDmtEvent
), or if theuri
parameter is invalid (is not an absolute URI or is syntactically incorrect)
-
addEventListener
void addEventListener(java.lang.String principal, int type, java.lang.String uri, DmtEventListener listener)
Registers an event listener on behalf of a remote principal. The given listener will receive notification on all changes affecting the specified subtree. The subtree is specified by its root node URI. An event is delivered to the registered listener if at least one affected node is within this subtree. The events can also be filtered by specifying a bitmask of relevant event types (e.g.DmtEvent.ADDED | DmtEvent.REPLACED | DmtEvent.SESSION_CLOSED
). Only event types included in the bitmask will be delivered to the listener.The listener will only receive the change notifications of nodes for which the node ACL grants GET access to the specified principal.
If the specified
listener
was already registered, calling this method will update the registration.- Parameters:
principal
- the management server identity the caller is acting on behalf of, must not benull
type
- a bitmask of event types the caller is interested inuri
- the URI of the root node of a subtree, must not benull
listener
- the listener to be registered, must not benull
- Throws:
java.lang.SecurityException
- if the caller doesn't have the necessaryDmtPrincipalPermission
to use the specified principaljava.lang.NullPointerException
- if theprincipal
,uri
orlistener
parameter isnull
java.lang.IllegalArgumentException
- if thetype
parameter contains invalid bits (not corresponding to any event type defined inDmtEvent
), or if theuri
parameter is invalid (is not an absolute URI or is syntactically incorrect)
-
removeEventListener
void removeEventListener(DmtEventListener listener)
Remove a previously registered listener. After this call, the listener will not receive change notifications.- Parameters:
listener
- the listener to be unregistered, must not benull
- Throws:
java.lang.NullPointerException
- if thelistener
parameter isnull
-
-