TransactionalDataSession
Date: 2016-06-25

org.osgi.service.dmt.spi

## Interface TransactionalDataSession

- All Superinterfaces:
    ReadableDataSession, ReadWriteDataSession

      public interface TransactionalDataSession
      extends ReadWriteDataSession

  Provides atomic read-write access to the part of the tree handled by the plugin that created this session.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `commit()` Commits a series of DMT operations issued in the current atomic session since the last transaction boundary.
    `void` | `rollback()` Rolls back a series of DMT operations issued in the current atomic session since the last transaction boundary.

    - ### Methods inherited from interface org.osgi.service.dmt.spi.ReadWriteDataSession

      `copy, createInteriorNode, createLeafNode, deleteNode, renameNode, setNodeTitle, setNodeType, setNodeValue`

    - ### Methods inherited from interface org.osgi.service.dmt.spi.ReadableDataSession

      `close, getChildNodeNames, getMetaNode, getNodeSize, getNodeTimestamp, getNodeTitle, getNodeType, getNodeValue, getNodeVersion, isLeafNode, isNodeUri, nodeChanged`

- - ### Method Detail

    - #### commit

          void commit()
                      throws DmtException

      Commits a series of DMT operations issued in the current atomic session since the last transaction boundary. Transaction boundaries are the creation of this object that starts the session, and all subsequent `commit()` and `rollback()` calls.

      This method can fail even if all operations were successful. This can happen due to some multi-node semantic constraints defined by a specific implementation. For example, node A can be required to always have children A/B, A/C and A/D. If this condition is broken when `commit()` is executed, the method will fail, and throw a `METADATA_MISMATCH` exception.

      In many cases the tree is not the only way to manage a given part of the system. It may happen that while modifying some nodes in an atomic session, the underlying settings are modified in parallel outside the scope of the DMT. If this is detected during commit, an exception with the code `CONCURRENT_ACCESS` is thrown.

      Throws:
        `DmtException` - with the following possible error codes
        - `METADATA_MISMATCH` if the operation failed because of meta-data restrictions
        - `CONCURRENT_ACCESS` if it is detected that some modification has been made outside the scope of the DMT to the nodes affected in the session's operations
        - `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

    - #### rollback

          void rollback()
                        throws DmtException

      Rolls back a series of DMT operations issued in the current atomic session since the last transaction boundary. Transaction boundaries are the creation of this object that starts the session, and all subsequent `commit()` and `rollback()` calls.
      Throws:
        `DmtException` - with the error code `ROLLBACK_FAILED` in case the rollback did not succeed
        `java.lang.SecurityException` - if the caller does not have the necessary permissions to execute the underlying management operation