info.dmtree.DmtAdmin Maven / Gradle / Ivy
/*
* Copyright (c) OSGi Alliance (2004, 2008). All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package info.dmtree;
/**
* 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 '\'). Any string can be converted to a valid URI
* segment using the {@link Uri#mangle(String)} method.
*
* It is possible to specify a lock mode when opening the session (see lock type
* constants in {@link 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.
*
* 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 $
*/
public interface DmtAdmin {
/**
* Opens a 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.
*
* @param subtreeUri the subtree on which DMT manipulations can be performed
* within the returned session
* @return a DmtSession object for the requested subtree
* @throws DmtException with the following possible error codes:
*
* URI_TOO_LONG if subtreeUri or
* a segment of it is too long, or if it has too many segments
* INVALID_URI if subtreeUri is
* syntactically invalid
* 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
*
* @throws SecurityException if the caller does not have
* DmtPermission for the given root node with the Get
* action present
*/
DmtSession getSession(String subtreeUri) throws DmtException;
/**
* Opens a 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.
*
* @param subtreeUri the subtree on which DMT manipulations can be performed
* within the returned session
* @param lockMode one of the lock modes specified in
* DmtSession
* @return a DmtSession object for the requested subtree
* @throws DmtException with the following possible error codes:
*
* URI_TOO_LONG if subtreeUri or
* a segment of it is too long, or if it has too many segments
* INVALID_URI if subtreeUri is
* syntactically invalid
* 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
*
* @throws SecurityException if the caller does not have
* DmtPermission for the given root node with the Get
* action present
*/
DmtSession getSession(String subtreeUri, int lockMode) throws DmtException;
/**
* Opens a 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.
*
* @param principal the identifier of the remote server on whose behalf the
* data manipulation is performed, or null for local
* sessions
* @param subtreeUri the subtree on which DMT manipulations can be performed
* within the returned session
* @param lockMode one of the lock modes specified in
* DmtSession
* @return a DmtSession object for the requested subtree
* @throws DmtException with the following possible error codes:
*
* URI_TOO_LONG if subtreeUri or
* a segment of it is too long, or if it has too many segments
* INVALID_URI if subtreeUri is
* syntactically invalid
* 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
*
* @throws 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
*/
DmtSession getSession(String principal, String subtreeUri, int lockMode)
throws DmtException;
/**
* 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
* {@link info.dmtree.security.DmtPermission}.
*
* If the specified listener was already registered, calling
* this method will update the registration.
*
* @param type a bitmask of event types the caller is interested in
* @param uri the URI of the root node of a subtree, must not be
* null
* @param listener the listener to be registered, must not be
* null
* @throws SecurityException if the caller doesn't have the necessary GET
* DmtPermission for the given URI
* @throws NullPointerException if the uri or
* listener parameter is null
* @throws IllegalArgumentException if the type parameter
* contains invalid bits (not corresponding to any event type
* defined in DmtEvent), or if the uri
* parameter is invalid (is not an absolute URI or is syntactically
* incorrect)
*/
void addEventListener(int type, 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.
*
* @param principal the management server identity the caller is acting on
* behalf of, must not be null
* @param type a bitmask of event types the caller is interested in
* @param uri the URI of the root node of a subtree, must not be
* null
* @param listener the listener to be registered, must not be
* null
* @throws SecurityException if the caller doesn't have the necessary
* DmtPrincipalPermission to use the specified
* principal
* @throws NullPointerException if the principal,
* uri or listener parameter is
* null
* @throws IllegalArgumentException if the type parameter
* contains invalid bits (not corresponding to any event type
* defined in DmtEvent), or if the uri
* parameter is invalid (is not an absolute URI or is syntactically
* incorrect)
*/
void addEventListener(String principal, int type, String uri,
DmtEventListener listener);
/**
* Remove a previously registered listener. After this call, the listener
* will not receive change notifications.
*
* @param listener the listener to be unregistered, must not be
* null
* @throws NullPointerException if the listener parameter is
* null
*/
void removeEventListener(DmtEventListener listener);
}