OSGi 8.1.0 · org.osgi.service.dmt.spi.DataPlugin · APIdia, the JavaDoc alternative

An implementation of this interface takes the responsibility of handling data requests in a subtree of the DMT.

In an OSGi environment such implementations should be registered at the OSGi service registry specifying the list of root node URIs in a String array or in case of a single value as String in the dataRootURIs registration parameter.

When the first reference in a session is made to a node handled by this plugin, the DmtAdmin calls one of the open... 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 openReadWriteSession(String[], DmtSession) and openAtomicSession(String[], DmtSession), the plugin may return null to indicate that the specified lock type is not supported. In this case the DmtAdmin may call 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.

The sessionRoot 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.

Field Summary

Modifier and Type	Field and Description
public static final String	DATA_ROOT_URIS The string to be used as key for the "dataRootURIs" property when an DataPlugin is registered.
public static final String	MOUNT_POINTS The string to be used as key for the mount points property when a DataPlugin is registered with mount points.

Method Summary

Modifier and Type	Method and Description
public TransactionalDataSession	Returns: a plugin session capable of executing read-write operations in an atomic block, or `null` if the plugin does not support atomic read-write sessions openAtomicSession(String[] the path to the subtree which is locked in the current session, must not be `null` sessionRoot, DmtSession the session from which this plugin instance is accessed, must not be `null` session) This method is called to signal the start of an atomic read-write session when the first reference is made within a `DmtSession` to a node which is handled by this plugin.
public ReadableDataSession	Returns: a plugin session capable of executing read operations openReadOnlySession(String[] the path to the subtree which is accessed in the current session, must not be `null` sessionRoot, DmtSession the session from which this plugin instance is accessed, must not be `null` session) This method is called to signal the start of a read-only session when the first reference is made within a `DmtSession` to a node which is handled by this plugin.
public ReadWriteDataSession	Returns: a plugin session capable of executing read-write operations, or `null` if the plugin does not support non-atomic read-write sessions openReadWriteSession(String[] the path to the subtree which is locked in the current session, must not be `null` sessionRoot, DmtSession the session from which this plugin instance is accessed, must not be `null` session) This method is called to signal the start of a non-atomic read-write session when the first reference is made within a `DmtSession` to a node which is handled by this plugin.

Field Detail

DATA_ROOT_URIS	back to summary
public static final String DATA_ROOT_URIS The string to be used as key for the "dataRootURIs" property when an DataPlugin is registered. Since 2.0

DATA_ROOT_URIS

back to summary

public static final String DATA_ROOT_URIS

The string to be used as key for the "dataRootURIs" property when an DataPlugin is registered.

Since: 2.0

MOUNT_POINTS	back to summary
public static final String MOUNT_POINTS The string to be used as key for the mount points property when a DataPlugin is registered with mount points.

Method Detail

openAtomicSession back to summary

openAtomicSession	back to summary
public TransactionalDataSession openAtomicSession(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 `DmtSession` to a node which is handled by this plugin. Session information is given as it is needed for sending alerts back from the plugin. The plugin can assume that there are no other sessions open on any subtree that has any overlap with the subtree of this session. Parameters sessionRoot:String[] the path to the subtree which is locked in the current session, must not be `null` session:DmtSession the session from which this plugin instance is accessed, must not be `null` Returns:TransactionalDataSession a plugin session capable of executing read-write operations in an atomic block, or `null` if the plugin does not support atomic read-write sessions Exceptions DmtException: with the following possible error codes: `NODE_NOT_FOUND` if `sessionRoot` points to a non-existing node `COMMAND_FAILED` if some unspecified error is encountered while attempting to complete the command SecurityException: if some underlying operation failed because of lack of permissions

public TransactionalDataSession openAtomicSession(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 DmtSession to a node which is handled by this plugin. Session information is given as it is needed for sending alerts back from the plugin.

The plugin can assume that there are no other sessions open on any subtree that has any overlap with the subtree of this session.

Parameters

sessionRoot:String[]: the path to the subtree which is locked in the current session, must not be null
session:DmtSession: the session from which this plugin instance is accessed, must not be null

Returns:TransactionalDataSession

a plugin session capable of executing read-write operations in an atomic block, or null if the plugin does not support atomic read-write sessions

Exceptions

DmtException:

with the following possible error codes:

NODE_NOT_FOUND if sessionRoot points to a non-existing node
COMMAND_FAILED if some unspecified error is encountered while attempting to complete the command

SecurityException:

if some underlying operation failed because of lack of permissions

openReadOnlySession back to summary

openReadOnlySession	back to summary
public ReadableDataSession openReadOnlySession(String[] sessionRoot, DmtSession session) throws DmtException This method is called to signal the start of a read-only session when the first reference is made within a `DmtSession` to a node which is handled by this plugin. Session information is given as it is needed for sending alerts back from the plugin. The plugin can assume that there are no writing sessions open on any subtree that has any overlap with the subtree of this session. Parameters sessionRoot:String[] the path to the subtree which is accessed in the current session, must not be `null` session:DmtSession the session from which this plugin instance is accessed, must not be `null` Returns:ReadableDataSession a plugin session capable of executing read operations Exceptions DmtException: with the following possible error codes: `NODE_NOT_FOUND` if `sessionRoot` points to a non-existing node `COMMAND_FAILED` if some unspecified error is encountered while attempting to complete the command SecurityException: if some underlying operation failed because of lack of permissions

public ReadableDataSession openReadOnlySession(String[] sessionRoot, DmtSession session) throws DmtException

This method is called to signal the start of a read-only session when the first reference is made within a DmtSession to a node which is handled by this plugin. Session information is given as it is needed for sending alerts back from the plugin.

The plugin can assume that there are no writing sessions open on any subtree that has any overlap with the subtree of this session.

Parameters

sessionRoot:String[]: the path to the subtree which is accessed in the current session, must not be null
session:DmtSession: the session from which this plugin instance is accessed, must not be null

Returns:ReadableDataSession

a plugin session capable of executing read operations

Exceptions

DmtException:

with the following possible error codes:

NODE_NOT_FOUND if sessionRoot points to a non-existing node
COMMAND_FAILED if some unspecified error is encountered while attempting to complete the command

SecurityException:

if some underlying operation failed because of lack of permissions

openReadWriteSession back to summary

openReadWriteSession	back to summary
public ReadWriteDataSession openReadWriteSession(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 `DmtSession` to a node which is handled by this plugin. Session information is given as it is needed for sending alerts back from the plugin. The plugin can assume that there are no other sessions open on any subtree that has any overlap with the subtree of this session. Parameters sessionRoot:String[] the path to the subtree which is locked in the current session, must not be `null` session:DmtSession the session from which this plugin instance is accessed, must not be `null` Returns:ReadWriteDataSession a plugin session capable of executing read-write operations, or `null` if the plugin does not support non-atomic read-write sessions Exceptions DmtException: with the following possible error codes: `NODE_NOT_FOUND` if `sessionRoot` points to a non-existing node `COMMAND_FAILED` if some unspecified error is encountered while attempting to complete the command SecurityException: if some underlying operation failed because of lack of permissions

public ReadWriteDataSession openReadWriteSession(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 DmtSession to a node which is handled by this plugin. Session information is given as it is needed for sending alerts back from the plugin.

The plugin can assume that there are no other sessions open on any subtree that has any overlap with the subtree of this session.

Parameters

sessionRoot:String[]: the path to the subtree which is locked in the current session, must not be null
session:DmtSession: the session from which this plugin instance is accessed, must not be null

Returns:ReadWriteDataSession

a plugin session capable of executing read-write operations, or null if the plugin does not support non-atomic read-write sessions

Exceptions

DmtException:

with the following possible error codes:

NODE_NOT_FOUND if sessionRoot points to a non-existing node
COMMAND_FAILED if some unspecified error is encountered while attempting to complete the command

SecurityException:

if some underlying operation failed because of lack of permissions

public Interface DataPlugin

Field Summary

Method Summary

Field Detail

Method Detail