org.osgi.service.dmt.DmtAdmin Maven / Gradle / Ivy
/*
* Copyright (c) OSGi Alliance (2004, 2013). 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 org.osgi.service.dmt;
/**
* An interface providing methods to open sessions and register listeners. The
* implementation of {@code DmtAdmin} should register itself in the OSGi service
* registry as a service. {@code DmtAdmin} is the entry point for applications
* to use the DMT API.
*
* The {@code 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 {@link 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 {@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 {@code 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.
*
* @author $Id: 193fb8ed85cf47cdc98b31f0fb1fb11d3bad57eb $
*/
public interface DmtAdmin {
/**
* Opens a {@code DmtSession} for local usage on a given subtree of the DMT
* with non transactional write lock. This call is equivalent to the
* following:
* {@code getSession(null, subtreeUri, DmtSession.LOCK_TYPE_EXCLUSIVE)}
*
* The {@code subtreeUri} parameter must contain an absolute URI. It can
* also be {@code 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 {@code DmtPermission} for
* the {@code subtreeUri} node with the Get action present.
*
* @param subtreeUri the subtree on which DMT manipulations can be performed
* within the returned session
* @return a {@code DmtSession} object for the requested subtree
* @throws DmtException with the following possible error codes:
*
* - {@code INVALID_URI} if {@code subtreeUri} is syntactically
* invalid
- {@code URI_TOO_LONG} if {@code subtreeUri} is
* longer than accepted by the {@code DmtAdmin} implementation
* (especially on systems with limited resources)
-
* {@code NODE_NOT_FOUND} if {@code subtreeUri} specifies a
* non-existing node
- {@code SESSION_CREATION_TIMEOUT} if
* the operation timed out because of another ongoing session
* - {@code COMMAND_FAILED} if {@code 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
* {@code DmtPermission} for the given root node with the Get action
* present
*/
DmtSession getSession(String subtreeUri) throws DmtException;
/**
* Opens a {@code DmtSession} for local usage on a specific DMT subtree with
* a given lock mode. This call is equivalent to the following:
* {@code getSession(null, subtreeUri, lockMode)}
*
* The {@code subtreeUri} parameter must contain an absolute URI. It can
* also be {@code 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 {@code DmtPermission} for
* the {@code 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 {@code DmtSession}
* @return a {@code DmtSession} object for the requested subtree
* @throws DmtException with the following possible error codes:
*
* - {@code INVALID_URI} if {@code subtreeUri} is syntactically
* invalid
- {@code URI_TOO_LONG} if {@code subtreeUri} is
* longer than accepted by the {@code DmtAdmin} implementation
* (especially on systems with limited resources)
-
* {@code NODE_NOT_FOUND} if {@code subtreeUri} specifies a
* non-existing node
- {@code FEATURE_NOT_SUPPORTED} if
* atomic sessions are not supported by the implementation and
* {@code lockMode} requests an atomic session
-
* {@code SESSION_CREATION_TIMEOUT} if the operation timed out
* because of another ongoing session
-
* {@code COMMAND_FAILED} if {@code subtreeUri} specifies a relative
* URI, if {@code lockMode} is unknown, or some unspecified error is
* encountered while attempting to complete the command
*
* @throws SecurityException if the caller does not have
* {@code DmtPermission} for the given root node with the Get action
* present
*/
DmtSession getSession(String subtreeUri, int lockMode) throws DmtException;
/**
* Opens a {@code 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 {@code null}
* as the first parameter. Alternatively they can use other forms of this
* method without providing a principal string.
*
* The {@code subtreeUri} parameter must contain an absolute URI. It can
* also be {@code 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 {@code DmtPrincipalPermission} in case of
* remote sessions. In addition, the caller must have Get access rights (ACL
* in case of remote sessions, {@code DmtPermission} in case of local
* sessions) on the {@code subtreeUri} node to perform this operation.
*
* @param principal the identifier of the remote server on whose behalf the
* data manipulation is performed, or {@code 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 {@code DmtSession}
* @return a {@code DmtSession} object for the requested subtree
* @throws DmtException with the following possible error codes:
*
* - {@code INVALID_URI} if {@code subtreeUri} is syntactically
* invalid
- {@code URI_TOO_LONG} if {@code subtreeUri} is
* longer than accepted by the {@code DmtAdmin} implementation
* (especially on systems with limited resources)
-
* {@code NODE_NOT_FOUND} if {@code subtreeUri} specifies a
* non-existing node
- {@code PERMISSION_DENIED} if
* {@code principal} is not {@code null} and the ACL of the node
* does not allow the {@code Get} operation for the principal on the
* given root node
- {@code FEATURE_NOT_SUPPORTED} if atomic
* sessions are not supported by the implementation and
* {@code lockMode} requests an atomic session
-
* {@code SESSION_CREATION_TIMEOUT} if the operation timed out
* because of another ongoing session
-
* {@code COMMAND_FAILED} if {@code subtreeUri} specifies a relative
* URI, if {@code 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 {@code DmtPrincipalPermission} with a
* target matching the {@code principal} parameter, or in case of
* local sessions, if the caller does not have {@code DmtPermission}
* for the given root node with the Get action present
*/
DmtSession getSession(String principal, String subtreeUri, int lockMode) throws DmtException;
}