FELIX-514 Updated compendium bundle to R4.1 OSGi API
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@681945 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/org.osgi.compendium/src/main/java/info/dmtree/DmtAdmin.java b/org.osgi.compendium/src/main/java/info/dmtree/DmtAdmin.java
new file mode 100644
index 0000000..abfcc6f
--- /dev/null
+++ b/org.osgi.compendium/src/main/java/info/dmtree/DmtAdmin.java
@@ -0,0 +1,281 @@
+/*
+ * $Header: /cvshome/build/info.dmtree/src/info/dmtree/DmtAdmin.java,v 1.9 2006/07/11 16:59:41 tszeredi Exp $
+ *
+ * Copyright (c) OSGi Alliance (2004, 2006). 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 <code>DmtAdmin</code> should register itself in the OSGi
+ * service registry as a service. <code>DmtAdmin</code> is the entry point for
+ * applications to use the DMT API.
+ * <p>
+ * The <code>getSession</code> methods are used to open a session on a
+ * specified subtree of the DMT. A typical way of usage:
+ * <pre>
+ * serviceRef = context.getServiceReference(DmtAdmin.class.getName());
+ * DmtAdmin admin = (DmtAdmin) context.getService(serviceRef);
+ * DmtSession session = admin.getSession("./OSGi/Configuration");
+ * session.createInteriorNode("./OSGi/Configuration/my.table");
+ * </pre>
+ * <p>
+ * 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.
+ * <p>
+ * 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</code> 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.
+ * <p>
+ * This interface also contains methods for manipulating the set of
+ * <code>DmtEventListener</code> 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.
+ */
+public interface DmtAdmin {
+ /**
+ * Opens a <code>DmtSession</code> 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)</code>
+ * <p>
+ * The <code>subtreeUri</code> parameter must contain an absolute URI. It
+ * can also be <code>null</code>, in this case the session is opened with
+ * the default session root, ".", that gives access to the whole
+ * tree.
+ * <p>
+ * To perform this operation the caller must have <code>DmtPermission</code>
+ * for the <code>subtreeUri</code> 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</code> object for the requested subtree
+ * @throws DmtException with the following possible error codes:
+ * <ul>
+ * <li><code>URI_TOO_LONG</code> if <code>subtreeUri</code> or
+ * a segment of it is too long, or if it has too many segments
+ * <li><code>INVALID_URI</code> if <code>subtreeUri</code> is
+ * syntactically invalid
+ * <li><code>NODE_NOT_FOUND</code> if <code>subtreeUri</code>
+ * specifies a non-existing node
+ * <li><code>SESSION_CREATION_TIMEOUT</code> if the operation
+ * timed out because of another ongoing session
+ * <li><code>COMMAND_FAILED</code> if <code>subtreeUri</code>
+ * specifies a relative URI, or some unspecified error is
+ * encountered while attempting to complete the command
+ * </ul>
+ * @throws SecurityException if the caller does not have
+ * <code>DmtPermission</code> for the given root node with the Get
+ * action present
+ */
+ DmtSession getSession(String subtreeUri) throws DmtException;
+
+ /**
+ * Opens a <code>DmtSession</code> 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)</code>
+ * <p>
+ * The <code>subtreeUri</code> parameter must contain an absolute URI. It
+ * can also be <code>null</code>, in this case the session is opened with
+ * the default session root, ".", that gives access to the whole
+ * tree.
+ * <p>
+ * To perform this operation the caller must have <code>DmtPermission</code>
+ * for the <code>subtreeUri</code> 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</code>
+ * @return a <code>DmtSession</code> object for the requested subtree
+ * @throws DmtException with the following possible error codes:
+ * <ul>
+ * <li><code>URI_TOO_LONG</code> if <code>subtreeUri</code> or
+ * a segment of it is too long, or if it has too many segments
+ * <li><code>INVALID_URI</code> if <code>subtreeUri</code> is
+ * syntactically invalid
+ * <li><code>NODE_NOT_FOUND</code> if <code>subtreeUri</code>
+ * specifies a non-existing node
+ * <li><code>FEATURE_NOT_SUPPORTED</code> if atomic sessions are
+ * not supported by the implementation and <code>lockMode</code>
+ * requests an atomic session
+ * <li><code>SESSION_CREATION_TIMEOUT</code> if the operation
+ * timed out because of another ongoing session
+ * <li><code>COMMAND_FAILED</code> if <code>subtreeUri</code>
+ * specifies a relative URI, if <code>lockMode</code> is unknown,
+ * or some unspecified error is encountered while attempting to
+ * complete the command
+ * </ul>
+ * @throws SecurityException if the caller does not have
+ * <code>DmtPermission</code> for the given root node with the Get
+ * action present
+ */
+ DmtSession getSession(String subtreeUri, int lockMode) throws DmtException;
+
+ /**
+ * Opens a <code>DmtSession</code> 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</code> as the first parameter. Alternatively they can use
+ * other forms of this method without providing a principal string.
+ * <p>
+ * The <code>subtreeUri</code> parameter must contain an absolute URI. It
+ * can also be <code>null</code>, in this case the session is opened with
+ * the default session root, ".", that gives access to the whole
+ * tree.
+ * <p>
+ * This method is guarded by <code>DmtPrincipalPermission</code> in case of
+ * remote sessions. In addition, the caller must have Get access rights
+ * (ACL in case of remote sessions, <code>DmtPermission</code> in case of
+ * local sessions) on the <code>subtreeUri</code> node to perform this
+ * operation.
+ *
+ * @param principal the identifier of the remote server on whose behalf the
+ * data manipulation is performed, or <code>null</code> 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</code>
+ * @return a <code>DmtSession</code> object for the requested subtree
+ * @throws DmtException with the following possible error codes:
+ * <ul>
+ * <li><code>URI_TOO_LONG</code> if <code>subtreeUri</code> or
+ * a segment of it is too long, or if it has too many segments
+ * <li><code>INVALID_URI</code> if <code>subtreeUri</code> is
+ * syntactically invalid
+ * <li><code>NODE_NOT_FOUND</code> if <code>subtreeUri</code>
+ * specifies a non-existing node
+ * <li><code>PERMISSION_DENIED</code> if <code>principal</code> is
+ * not <code>null</code> and the ACL of the node does not allow the
+ * <code>Get</code> operation for the principal on the given root
+ * node
+ * <li><code>FEATURE_NOT_SUPPORTED</code> if atomic sessions are
+ * not supported by the implementation and <code>lockMode</code>
+ * requests an atomic session
+ * <li><code>SESSION_CREATION_TIMEOUT</code> if the operation
+ * timed out because of another ongoing session
+ * <li><code>COMMAND_FAILED</code> if <code>subtreeUri</code>
+ * specifies a relative URI, if <code>lockMode</code> is unknown,
+ * or some unspecified error is encountered while attempting to
+ * complete the command
+ * </ul>
+ * @throws SecurityException in case of remote sessions, if the caller does
+ * not have the required <code>DmtPrincipalPermission</code> with a
+ * target matching the <code>principal</code> parameter, or in case
+ * of local sessions, if the caller does not have
+ * <code>DmtPermission</code> 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.
+ * <code>DmtEvent.ADDED | DmtEvent.REPLACED | DmtEvent.SESSION_CLOSED</code>).
+ * Only event types included in the bitmask will be delivered to the
+ * listener.
+ * <p>
+ * The listener will only receive the change notifications of nodes for
+ * which the registering application has the appropriate GET
+ * {@link info.dmtree.security.DmtPermission}.
+ * <p>
+ * If the specified <code>listener</code> 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
+ * <code>null</code>
+ * @param listener the listener to be registered, must not be
+ * <code>null</code>
+ * @throws SecurityException if the caller doesn't have the necessary GET
+ * <code>DmtPermission</code> for the given URI
+ * @throws NullPointerException if the <code>uri</code> or
+ * <code>listener</code> parameter is <code>null</code>
+ * @throws IllegalArgumentException if the <code>type</code> parameter
+ * contains invalid bits (not corresponding to any event type
+ * defined in <code>DmtEvent</code>), or if the <code>uri</code>
+ * 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.
+ * <code>DmtEvent.ADDED | DmtEvent.REPLACED | DmtEvent.SESSION_CLOSED</code>).
+ * Only event types included in the bitmask will be delivered to the
+ * listener.
+ * <p>
+ * The listener will only receive the change notifications of nodes for
+ * which the node ACL grants GET access to the specified principal.
+ * <p>
+ * If the specified <code>listener</code> 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 <code>null</code>
+ * @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
+ * <code>null</code>
+ * @param listener the listener to be registered, must not be
+ * <code>null</code>
+ * @throws SecurityException if the caller doesn't have the necessary
+ * <code>DmtPrincipalPermission</code> to use the specified
+ * principal
+ * @throws NullPointerException if the <code>principal</code>,
+ * <code>uri</code> or <code>listener</code> parameter is
+ * <code>null</code>
+ * @throws IllegalArgumentException if the <code>type</code> parameter
+ * contains invalid bits (not corresponding to any event type
+ * defined in <code>DmtEvent</code>), or if the <code>uri</code>
+ * 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
+ * <code>null</code>
+ * @throws NullPointerException if the <code>listener</code> parameter is
+ * <code>null</code>
+ */
+ void removeEventListener(DmtEventListener listener);
+}