DataPlugin
Date: 2016-06-25

org.osgi.service.dmt.spi

## Interface DataPlugin

-     public interface DataPlugin

  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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `DATA_ROOT_URIS` The string to be used as key for the “dataRootURIs” property when an DataPlugin is registered.
    `static java.lang.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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `TransactionalDataSession` | `openAtomicSession(java.lang.String[] sessionRoot, DmtSession 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.
    `ReadableDataSession` | `openReadOnlySession(java.lang.String[] sessionRoot, DmtSession 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.
    `ReadWriteDataSession` | `openReadWriteSession(java.lang.String[] sessionRoot, DmtSession 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

    - #### MOUNT_POINTS

          static final java.lang.String MOUNT_POINTS

      The string to be used as key for the mount points property when a DataPlugin is registered with mount points.
      See Also:
        Constant Field Values

    - #### DATA_ROOT_URIS

          static final java.lang.String DATA_ROOT_URIS

      The string to be used as key for the “dataRootURIs” property when an DataPlugin is registered.
      Since:
        2.0
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### openReadOnlySession

          ReadableDataSession openReadOnlySession(java.lang.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` - the path to the subtree which is accessed in the current session, must not be `null`
        `session` - the session from which this plugin instance is accessed, must not be `null`
      Returns:
        a plugin session capable of executing read operations
      Throws:
        `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
        `java.lang.SecurityException` - if some underlying operation failed because of lack of permissions

    - #### openReadWriteSession

          ReadWriteDataSession openReadWriteSession(java.lang.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` - the path to the subtree which is locked in the current session, must not be `null`
        `session` - the session from which this plugin instance is accessed, must not be `null`
      Returns:
        a plugin session capable of executing read-write operations, or `null` if the plugin does not support non-atomic read-write sessions
      Throws:
        `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
        `java.lang.SecurityException` - if some underlying operation failed because of lack of permissions

    - #### openAtomicSession

          TransactionalDataSession openAtomicSession(java.lang.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` - the path to the subtree which is locked in the current session, must not be `null`
        `session` - the session from which this plugin instance is accessed, must not be `null`
      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
      Throws:
        `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
        `java.lang.SecurityException` - if some underlying operation failed because of lack of permissions