Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*
   * 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.spi;
 
 import java.util.Date;
Provides read-only access to the part of the tree handled by the plugin that created this session.

Since the ReadWriteDataSession and 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 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 org.osgi.service.dmt.DmtException.INVALID_URI, org.osgi.service.dmt.DmtException.URI_TOO_LONG, org.osgi.service.dmt.DmtException.PERMISSION_DENIED, org.osgi.service.dmt.DmtException.COMMAND_NOT_ALLOWED and org.osgi.service.dmt.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 org.osgi.service.dmt.MetaNode. If the plugin does not provide meta-data, it must perform the necessary checks for itself and use the org.osgi.service.dmt.DmtException.METADATA_MISMATCH error code to indicate such discrepancies.

The DmtAdmin does not check that the targeted node exists before calling the plugin. It is the responsibility of the plugin to perform this check and to throw a org.osgi.service.dmt.DmtException.NODE_NOT_FOUND if needed. In this case the DmtAdmin must pass through this exception to the caller of the corresponding DmtSession method.

The plugin can use the remaining error codes as needed. If an error does not fit into any other category, the org.osgi.service.dmt.DmtException.COMMAND_FAILED code should be used.

Author(s):
$Id: 127f2bfbfa19d4bafbddfb1c8c6b8fb76138ef5f $
 
 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.

Parameters:
nodePath the absolute path of the node that has changed
Throws:
org.osgi.service.dmt.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[] nodePaththrows 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 TransactionalDataSession.commit() automatically before the session is actually closed.

Throws:
org.osgi.service.dmt.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 array may contain null entries, but these are removed by the DmtAdmin before returning it to the client.

Parameters:
nodePath the absolute path of the node
Returns:
the list of child node names as a string array or an empty string array if the node has no children
Throws:
org.osgi.service.dmt.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
java.lang.SecurityException if the caller does not have the necessary permissions to execute the underlying management operation
	String[] getChildNodeNames(String[] nodePaththrows 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.

Parameters:
nodePath the absolute path of the node
Returns:
a MetaNode which describes meta data information, can be null if there is no meta data available for the given node
Throws:
org.osgi.service.dmt.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
java.lang.SecurityException if the caller does not have the necessary permissions to execute the underlying management operation
	MetaNode getMetaNode(String[] nodePaththrows 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 org.osgi.service.dmt.DmtData.getSize() method for the definition of node size for each format.

Parameters:
nodePath the absolute path of the leaf node
Returns:
the size of the data in the node
Throws:
org.osgi.service.dmt.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
java.lang.SecurityException if the caller does not have the necessary permissions to execute the underlying management operation
See also:
org.osgi.service.dmt.DmtData.getSize()
	int getNodeSize(String[] nodePaththrows DmtException;

Get the timestamp when the node was last modified.

Parameters:
nodePath the absolute path of the node
Returns:
the timestamp of the last modification
Throws:
org.osgi.service.dmt.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
java.lang.SecurityException if the caller does not have the necessary permissions to execute the underlying management operation
	Date getNodeTimestamp(String[] nodePaththrows DmtException;

Get the title of a node. There might be no title property set for a node.

Parameters:
nodePath the absolute path of the node
Returns:
the title of the node, or null if the node has no title
Throws:
org.osgi.service.dmt.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
java.lang.SecurityException if the caller does not have the necessary permissions to execute the underlying management operation
	String getNodeTitle(String[] nodePaththrows 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.

Parameters:
nodePath the absolute path of the node
Returns:
the type of the node, can be null
Throws:
org.osgi.service.dmt.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
java.lang.SecurityException if the caller does not have the necessary permissions to execute the underlying management operation
	String getNodeType(String[] nodePaththrows DmtException;

Check whether the specified path corresponds to a valid node in the DMT.

Parameters:
nodePath the absolute path to check
Returns:
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.

Parameters:
nodePath the absolute path of the node
Returns:
true if the given node is a leaf node
Throws:
org.osgi.service.dmt.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
java.lang.SecurityException if the caller does not have the necessary permissions to execute the underlying management operation
	boolean isLeafNode(String[] nodePaththrows DmtException;

Get the data contained in a leaf or interior node.

Parameters:
nodePath the absolute path of the node to retrieve
Returns:
the data of the leaf node, must not be null
Throws:
org.osgi.service.dmt.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
java.lang.SecurityException if the caller does not have the necessary permissions to execute the underlying management operation
	DmtData getNodeValue(String[] nodePaththrows 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.

Parameters:
nodePath the absolute path of the node
Returns:
the version of the node
Throws:
org.osgi.service.dmt.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
java.lang.SecurityException if the caller does not have the necessary permissions to execute the underlying management operation
	int getNodeVersion(String[] nodePaththrows DmtException;
New to GrepCode? Check out our FAQ X