info.dmtree.spi.ReadableDataSession 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.spi;
import info.dmtree.DmtData;
import info.dmtree.DmtException;
import info.dmtree.MetaNode;
import java.util.Date;
/**
* Provides read-only access to the part of the tree handled by the plugin that
* created this session.
*
* Since the {@link ReadWriteDataSession} and {@link TransactionalDataSession}
* interfaces inherit from this interface, some of the method descriptions do
* not apply for an instance that is only a ReadableDataSession.
* For example, the {@link #close} method description also contains information
* about its behaviour when invoked as part of a transactional session.
*
* The nodePath parameters appearing in this interface always
* contain an array of path segments identifying a node in the subtree of this
* plugin. This parameter contains an absolute path, so the first segment is
* always ".". Special characters appear escaped in the segments.
*
* Error handling
*
* When a tree access command is called on the DmtAdmin service, it must perform
* an extensive set of checks on the parameters and the authority of the caller
* before delegating the call to a plugin. Therefore plugins can take certain
* circumstances for granted: that the path is valid and is within the subtree
* of the plugin and the session, the command can be applied to the given node
* (e.g. the target of getChildNodeNames is an interior node), etc.
* All errors described by the error codes {@link DmtException#INVALID_URI},
* {@link DmtException#URI_TOO_LONG}, {@link DmtException#PERMISSION_DENIED},
* {@link DmtException#COMMAND_NOT_ALLOWED} and
* {@link DmtException#TRANSACTION_ERROR} are fully filtered out before control
* reaches the plugin.
*
* If the plugin provides meta-data for a node, the DmtAdmin service must also
* check the constraints specified by it, as described in {@link MetaNode}. If
* the plugin does not provide meta-data, it must perform the necessary checks
* for itself and use the {@link DmtException#METADATA_MISMATCH} error code to
* indicate such discrepancies.
*
* The DmtAdmin also ensures that the targeted nodes exist before calling the
* plugin (except, of course, before the isNodeUri call). However,
* some small amount of time elapses between the check and the call, so in case
* of plugins where the node structure can change independantly from the DMT,
* the target node might disappear in that time. For example, a whole subtree
* can disappear when a Monitorable application is unregistered, which might
* happen in the middle of a DMT session accessing it. Plugins managing such
* nodes always need to check whether they still exist and throw
* {@link DmtException#NODE_NOT_FOUND} as necessary, but for more static
* subtrees there is no need for the plugin to use this error code.
*
* The plugin can use the remaining error codes as needed. If an error does not
* fit into any other category, the {@link DmtException#COMMAND_FAILED} code
* should be used.
*
* @version $Revision: 5673 $
*/
public interface ReadableDataSession {
/**
* Notifies the plugin that the given node has changed outside the scope of
* the plugin, therefore the Version and Timestamp properties must be
* updated (if supported). This method is needed because the ACL property of
* a node is managed by the DmtAdmin instead of the plugin. The DmtAdmin
* must call this method whenever the ACL property of a node changes.
*
* @param nodePath the absolute path of the node that has changed
* @throws DmtException with the following possible error codes:
*
* NODE_NOT_FOUND if nodePath
* points to a non-existing node
* DATA_STORE_FAILURE if an error occurred while
* accessing the data store
* COMMAND_FAILED if some unspecified error is
* encountered while attempting to complete the command
*
*/
void nodeChanged(String[] nodePath) throws DmtException;
/**
* Closes a session. This method is always called when the session ends for
* any reason: if the session is closed, if a fatal error occurs in any
* method, or if any error occurs during commit or rollback. In case the
* session was invalidated due to an exception during commit or rollback, it
* is guaranteed that no methods are called on the plugin until it is
* closed. In case the session was invalidated due to a fatal exception in
* one of the tree manipulation methods, only the rollback method is called
* before this (and only in atomic sessions).
*
* This method should not perform any data manipulation, only cleanup
* operations. In non-atomic read-write sessions the data manipulation
* should be done instantly during each tree operation, while in atomic
* sessions the DmtAdmin always calls
* {@link TransactionalDataSession#commit} automatically before the session
* is actually closed.
*
* @throws DmtException with the error code COMMAND_FAILED if
* the plugin failed to close for any reason
*/
void close() throws DmtException;
/**
* Get the list of children names of a node. The returned array contains the
* names - not the URIs - of the immediate children nodes of the given node.
* The returned child names must be mangled ({@link info.dmtree.Uri#mangle(String)}).
* The returned array may contain null entries, but these are
* removed by the DmtAdmin before returning it to the client.
*
* @param nodePath the absolute path of the node
* @return the list of child node names as a string array or an empty string
* array if the node has no children
* @throws DmtException with the following possible error codes:
*
* NODE_NOT_FOUND if nodePath
* points to a non-existing node
* METADATA_MISMATCH if the information could
* not be retrieved because of meta-data restrictions
* DATA_STORE_FAILURE if an error occurred while
* accessing the data store
* COMMAND_FAILED if some unspecified error is
* encountered while attempting to complete the command
*
* @throws SecurityException if the caller does not have the necessary
* permissions to execute the underlying management operation
*/
String[] getChildNodeNames(String[] nodePath) throws DmtException;
/**
* Get the meta data which describes a given node. Meta data can be only
* inspected, it can not be changed.
*
* Meta data support by plugins is an optional feature. It can be used, for
* example, when a data plugin is implemented on top of a data store or
* another API that has their own metadata, such as a relational database,
* in order to avoid metadata duplication and inconsistency. The meta data
* specific to the plugin returned by this method is complemented by meta
* data from the DmtAdmin before returning it to the client. If there are
* differences in the meta data elements known by the plugin and the
* DmtAdmin then the plugin specific elements take
* precedence.
*
* Note, that a node does not have to exist for having meta-data associated
* with it. This method may provide meta-data for any node that can possibly
* exist in the tree (any node defined by the Management Object provided by
* the plugin). For nodes that are not defined, a DmtException
* may be thrown with the NODE_NOT_FOUND error code. To allow
* easier implementation of plugins that do not provide meta-data, it is
* allowed to return null for any node, regardless of whether
* it is defined or not.
*
* @param nodePath the absolute path of the node
* @return a MetaNode which describes meta data information, can be
* null if there is no meta data available for the
* given node
* @throws DmtException with the following possible error codes:
*
* NODE_NOT_FOUND if nodeUri
* points to a node that is not defined in the tree (see above)
* DATA_STORE_FAILURE if an error occurred while
* accessing the data store
* COMMAND_FAILED if some unspecified error is
* encountered while attempting to complete the command
*
* @throws SecurityException if the caller does not have the necessary
* permissions to execute the underlying management operation
*/
MetaNode getMetaNode(String[] nodePath) throws DmtException;
/**
* Get the size of the data in a leaf node. The value to return depends on
* the format of the data in the node, see the description of the
* {@link DmtData#getSize()} method for the definition of node size for each
* format.
*
* @param nodePath the absolute path of the leaf node
* @return the size of the data in the node
* @throws DmtException with the following possible error codes:
*
* NODE_NOT_FOUND if nodePath
* points to a non-existing node
* METADATA_MISMATCH if the information could
* not be retrieved because of meta-data restrictions
* FEATURE_NOT_SUPPORTED if the Size property is
* not supported by the plugin
* DATA_STORE_FAILURE if an error occurred while
* accessing the data store
* COMMAND_FAILED if some unspecified error is
* encountered while attempting to complete the command
*
* @throws SecurityException if the caller does not have the necessary
* permissions to execute the underlying management operation
* @see DmtData#getSize
*/
int getNodeSize(String[] nodePath) throws DmtException;
/**
* Get the timestamp when the node was last modified.
*
* @param nodePath the absolute path of the node
* @return the timestamp of the last modification
* @throws DmtException with the following possible error codes:
*
* NODE_NOT_FOUND if nodePath
* points to a non-existing node
* METADATA_MISMATCH if the information could
* not be retrieved because of meta-data restrictions
* FEATURE_NOT_SUPPORTED if the Timestamp
* property is not supported by the plugin
* DATA_STORE_FAILURE if an error occurred while
* accessing the data store
* COMMAND_FAILED if some unspecified error is
* encountered while attempting to complete the command
*
* @throws SecurityException if the caller does not have the necessary
* permissions to execute the underlying management operation
*/
Date getNodeTimestamp(String[] nodePath) throws DmtException;
/**
* Get the title of a node. There might be no title property set for a node.
*
* @param nodePath the absolute path of the node
* @return the title of the node, or null if the node has no
* title
* @throws DmtException with the following possible error codes:
*
* NODE_NOT_FOUND if nodePath
* points to a non-existing node
* METADATA_MISMATCH if the information could
* not be retrieved because of meta-data restrictions
* FEATURE_NOT_SUPPORTED if the Title property
* is not supported by the plugin
* DATA_STORE_FAILURE if an error occurred while
* accessing the data store
* COMMAND_FAILED if some unspecified error is
* encountered while attempting to complete the command
*
* @throws SecurityException if the caller does not have the necessary
* permissions to execute the underlying management operation
*/
String getNodeTitle(String[] nodePath) throws DmtException;
/**
* Get the type of a node. The type of leaf node is the MIME type of the
* data it contains. The type of an interior node is a URI identifying a DDF
* document; a null type means that there is no DDF document
* overriding the tree structure defined by the ancestors.
*
* @param nodePath the absolute path of the node
* @return the type of the node, can be null
* @throws DmtException with the following possible error codes:
*
* NODE_NOT_FOUND if nodePath
* points to a non-existing node
* METADATA_MISMATCH if the information could
* not be retrieved because of meta-data restrictions
* DATA_STORE_FAILURE if an error occurred while
* accessing the data store
* COMMAND_FAILED if some unspecified error is
* encountered while attempting to complete the command
*
* @throws SecurityException if the caller does not have the necessary
* permissions to execute the underlying management operation
*/
String getNodeType(String[] nodePath) throws DmtException;
/**
* Check whether the specified path corresponds to a valid node in the DMT.
*
* @param nodePath the absolute path to check
* @return true if the given node exists in the DMT
*/
boolean isNodeUri(String[] nodePath);
/**
* Tells whether a node is a leaf or an interior node of the DMT.
*
* @param nodePath the absolute path of the node
* @return true if the given node is a leaf node
* @throws DmtException with the following possible error codes:
*
* NODE_NOT_FOUND if nodePath
* points to a non-existing node
* METADATA_MISMATCH if the information could
* not be retrieved because of meta-data restrictions
* DATA_STORE_FAILURE if an error occurred while
* accessing the data store
* COMMAND_FAILED if some unspecified error is
* encountered while attempting to complete the command
*
* @throws SecurityException if the caller does not have the necessary
* permissions to execute the underlying management operation
*/
boolean isLeafNode(String[] nodePath) throws DmtException;
/**
* Get the data contained in a leaf or interior node.
*
* @param nodePath the absolute path of the node to retrieve
* @return the data of the leaf node, must not be null
* @throws DmtException with the following possible error codes:
*
* NODE_NOT_FOUND if nodePath
* points to a non-existing node
* METADATA_MISMATCH if the information could
* not be retrieved because of meta-data restrictions
* FEATURE_NOT_SUPPORTED if the specified node is
* an interior node and does not support Java object values
* DATA_STORE_FAILURE if an error occurred while
* accessing the data store
* COMMAND_FAILED if some unspecified error is
* encountered while attempting to complete the command
*
* @throws SecurityException if the caller does not have the necessary
* permissions to execute the underlying management operation
*/
DmtData getNodeValue(String[] nodePath) throws DmtException;
/**
* Get the version of a node. The version can not be set, it is calculated
* automatically by the device. It is incremented modulo 0x10000 at every
* modification of the value or any other property of the node, for both
* leaf and interior nodes. When a node is created the initial value is 0.
*
* @param nodePath the absolute path of the node
* @return the version of the node
* @throws DmtException with the following possible error codes:
*
* NODE_NOT_FOUND if nodePath
* points to a non-existing node
* METADATA_MISMATCH if the information could
* not be retrieved because of meta-data restrictions
* FEATURE_NOT_SUPPORTED if the Version property
* is not supported by the plugin
* DATA_STORE_FAILURE if an error occurred while
* accessing the data store
* COMMAND_FAILED if some unspecified error is
* encountered while attempting to complete the command
*
* @throws SecurityException if the caller does not have the necessary
* permissions to execute the underlying management operation
*/
int getNodeVersion(String[] nodePath) throws DmtException;
}