| /* |
| * $Header: /cvshome/build/info.dmtree/src/info/dmtree/spi/DataPlugin.java,v 1.4 2006/06/16 16:31:59 hargrave 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.spi; |
| |
| import info.dmtree.DmtException; |
| import info.dmtree.DmtSession; |
| |
| /** |
| * An implementation of this interface takes the responsibility of handling data |
| * requests in a subtree of the DMT. |
| * <p> |
| * In an OSGi environment such implementations should be registered at the OSGi |
| * service registry specifying the list of root node URIs in a |
| * <code>String</code> array in the <code>dataRootURIs</code> registration |
| * parameter. |
| * <p> |
| * When the first reference in a session is made to a node handled by this |
| * plugin, the DmtAdmin calls one of the <code>open...</code> methods to |
| * retrieve a plugin session object for processing the request. The called |
| * method depends on the lock type of the current session. In case of |
| * {@link #openReadWriteSession(String[], DmtSession)} and |
| * {@link #openAtomicSession(String[], DmtSession)}, the plugin may return |
| * <code>null</code> to indicate that the specified lock type is not |
| * supported. In this case the DmtAdmin may call |
| * {@link #openReadOnlySession(String[], DmtSession)} to start a read-only |
| * plugin session, which can be used as long as there are no write operations on |
| * the nodes handled by this plugin. |
| * <p> |
| * The <code>sessionRoot</code> parameter of each method is a String array |
| * containing the segments of the URI pointing to the root of the session. This |
| * is an absolute path, so the first segment is always ".". Special |
| * characters appear escaped in the segments. |
| * <p> |
| */ |
| public interface DataPlugin { |
| |
| /** |
| * This method is called to signal the start of a read-only session when the |
| * first reference is made within a <code>DmtSession</code> to a node |
| * which is handled by this plugin. Session information is given as it is |
| * needed for sending alerts back from the plugin. |
| * <p> |
| * The plugin can assume that there are no writing sessions open on any |
| * subtree that has any overlap with the subtree of this session. |
| * |
| * @param sessionRoot the path to the subtree which is accessed in the |
| * current session, must not be <code>null</code> |
| * @param session the session from which this plugin instance is accessed, |
| * must not be <code>null</code> |
| * @return a plugin session capable of executing read operations |
| * @throws DmtException with the following possible error codes: |
| * <ul> |
| * <li><code>NODE_NOT_FOUND</code> if <code>sessionRoot</code> |
| * points to a non-existing node |
| * <li><code>COMMAND_FAILED</code> if some unspecified error is |
| * encountered while attempting to complete the command |
| * </ul> |
| * @throws SecurityException if some underlying operation failed because of |
| * lack of permissions |
| */ |
| ReadableDataSession openReadOnlySession(String[] sessionRoot, |
| DmtSession session) throws DmtException; |
| |
| /** |
| * This method is called to signal the start of a non-atomic read-write |
| * session when the first reference is made within a <code>DmtSession</code> |
| * to a node which is handled by this plugin. Session information is given |
| * as it is needed for sending alerts back from the plugin. |
| * <p> |
| * The plugin can assume that there are no other sessions open on any |
| * subtree that has any overlap with the subtree of this session. |
| * |
| * @param sessionRoot the path to the subtree which is locked in the current |
| * session, must not be <code>null</code> |
| * @param session the session from which this plugin instance is accessed, |
| * must not be <code>null</code> |
| * @return a plugin session capable of executing read-write operations, or |
| * <code>null</code> if the plugin does not support non-atomic |
| * read-write sessions |
| * @throws DmtException with the following possible error codes: |
| * <ul> |
| * <li><code>NODE_NOT_FOUND</code> if <code>sessionRoot</code> |
| * points to a non-existing node |
| * <li><code>COMMAND_FAILED</code> if some unspecified error is |
| * encountered while attempting to complete the command |
| * </ul> |
| * @throws SecurityException if some underlying operation failed because of |
| * lack of permissions |
| */ |
| ReadWriteDataSession openReadWriteSession(String[] sessionRoot, |
| DmtSession session) throws DmtException; |
| |
| /** |
| * This method is called to signal the start of an atomic read-write session |
| * when the first reference is made within a <code>DmtSession</code> to a |
| * node which is handled by this plugin. Session information is given as it |
| * is needed for sending alerts back from the plugin. |
| * <p> |
| * The plugin can assume that there are no other sessions open on any |
| * subtree that has any overlap with the subtree of this session. |
| * |
| * @param sessionRoot the path to the subtree which is locked in the current |
| * session, must not be <code>null</code> |
| * @param session the session from which this plugin instance is accessed, |
| * must not be <code>null</code> |
| * @return a plugin session capable of executing read-write operations in an |
| * atomic block, or <code>null</code> if the plugin does not |
| * support atomic read-write sessions |
| * @throws DmtException with the following possible error codes: |
| * <ul> |
| * <li><code>NODE_NOT_FOUND</code> if <code>sessionRoot</code> |
| * points to a non-existing node |
| * <li><code>COMMAND_FAILED</code> if some unspecified error is |
| * encountered while attempting to complete the command |
| * </ul> |
| * @throws SecurityException if some underlying operation failed because of |
| * lack of permissions |
| */ |
| TransactionalDataSession openAtomicSession(String[] sessionRoot, |
| DmtSession session) throws DmtException; |
| } |