com.h3c.dist.sync

## Interface SyncService

- All Known Subinterfaces:
    HAService

      public interface SyncService

  A distributed and synchronized in memory database providing mechanism to read/write to a data from several machines and not worry about synchronizing or unintentional overwriting. The database is eventually consistent. So a user might see older values at times. if no further updates are made, all users will see the latest value with in a time bound (tens of seconds)

  database is hierarchical and the hierarchy is specified by the strings in `SyncServiceNodePath` in order. i.e., At the root of the hierarchy is a node identified by the first string in `SyncServiceNodePath` and root's child node is identified by the next string and so on.

  To access the data in the database, user must first obtain `SyncServiceNode` either by creating a new node or accessing an existing node. Read/write/delete operations can be performed on the nodes using `SyncServiceNode`

  Some successful API calls can leave watches on the data nodes. Other calls can trigger those watches. Once a watch is triggered, an event will be delivered to the user which left the watch via `SyncServiceUser`. Each watch is triggered only once. Thus, up to one event will be delivered to a user for every watch it leaves. Watches of two types can be set on nodes. First type is a watch that is triggered on creation or deletion of node or changing node's data. The second type is triggered on changes to node's children or the node is deleted.

  All API calls described below, internally use a TCP session established with the distributed database. In case of unrecoverable errors such as session expiration or authentication failure the session is terminated and all associated ephemeral nodes see `createNode` are deleted

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `SyncServiceNode` | `createNode(SyncServiceNodePath nodePath, byte[] data, SyncServiceCreateMode createMode)` Create a new data node on distributed in memory database
    `SyncServiceNode` | `getNode(SyncServiceNodePath nodePath)` Get existing data node from distributed in memory database
    `Boolean` | `isSyncServiceUp()`
    `List<SyncServiceMultiOpResult>` | `multi(List<SyncServiceMultiOp> opList)` Execute a batch of sync services operations.
    `boolean` | `nodeExists(SyncServiceNodePath nodePath)` Check for node existence
    `boolean` | `nodeExists(SyncServiceNodePath nodePath, SyncServiceUser watcher)` Check for node existence and register watch on the node that is triggered when the node is created, deleted or node's data is changed
    `void` | `registerListener(SyncServiceUser watcher)`
    `void` | `unregisterListener(SyncServiceUser watcher)`

- - ### Method Detail

    - #### registerListener

          void registerListener(SyncServiceUser watcher)
                                throws IllegalArgumentException,
                                       DuplicateDataException

      Throws:
        `IllegalArgumentException`
        `DuplicateDataException`

    - #### unregisterListener

          void unregisterListener(SyncServiceUser watcher)
                                  throws IllegalArgumentException,
                                         NotFoundException

      Throws:
        `IllegalArgumentException`
        `NotFoundException`

    - #### isSyncServiceUp

          Boolean isSyncServiceUp()

    - #### getNode

          SyncServiceNode getNode(SyncServiceNodePath nodePath)
                                  throws ServiceNotAvailableException,
                                         SyncServiceException.NodeNotFoundException,
                                         InterruptedException

      Get existing data node from distributed in memory database
      Parameters:
        `nodePath` - Name of the node to be created
      Returns:
        existing node
      Throws:
        `ServiceNotAvailableException` - Sync service is not UP
        `SyncServiceException.NodeNotFoundException` - Node not found exception
        `InterruptedException` - Operation interrupted exception

    - #### createNode

          SyncServiceNode createNode(SyncServiceNodePath nodePath,
                                   byte[] data,
                                   SyncServiceCreateMode createMode)
                                     throws ServiceNotAvailableException,
                                            SyncServiceException.NodeExistsException,
                                            SyncServiceException.NodeNotFoundException,
                                            InterruptedException,
                                            SyncServiceException.NoChildrenForEphemeralException

      Create a new data node on distributed in memory database
      Parameters:
        `nodePath` - Name of the node to be created
        `data` - Data of the node to be created
        `createMode` - Mode of the created node (PERSISTENT, EPHEMERAL, ...) Persistent Nodes - These nodes exists till they are deleted Ephemeral Nodes - These nodes exists as long as the session that created is active. When the session ends the node is deleted. ephemeral nodes are not allowed to have children. Sequence Nodes - When creating a node you can also request to append a monotonically increasing counter to the end of path. This counter is unique to the parent node. The counter has a format of %010d -- that is 10 digits with 0 (zero) padding. i.e. "0000000001". Note: the counter used to store the next sequence number is a signed int (4bytes) maintained by the parent node, the counter will overflow when incremented beyond 2147483647 (resulting in a name "-2147483647").
      Returns:
        New node created.
      Throws:
        `ServiceNotAvailableException` - Sync service is not UP
        `SyncServiceException.NodeExistsException` - Node exists exception
        `SyncServiceException.NodeNotFoundException` - Node not found exception
        `InterruptedException` - Operation interrupted exception
        `SyncServiceException.NoChildrenForEphemeralException` - Children not allowed for ephemeral nodes

    - #### nodeExists

          boolean nodeExists(SyncServiceNodePath nodePath)
                             throws ServiceNotAvailableException,
                                    InterruptedException

      Check for node existence
      Parameters:
        `nodePath` - Node path to check if a node exists
      Returns:
        true if node exists. false otherwise
      Throws:
        `ServiceNotAvailableException` - Sync service is not UP
        `InterruptedException` - Operation interrupted exception

    - #### nodeExists

          boolean nodeExists(SyncServiceNodePath nodePath,
                           SyncServiceUser watcher)
                             throws ServiceNotAvailableException,
                                    InterruptedException

      Check for node existence and register watch on the node that is triggered when the node is created, deleted or node's data is changed
      Parameters:
        `nodePath` - Node path to check if a node exists and watch to be set
        `watcher` - Watcher object passed by the user
      Returns:
        Status of the node if path exists or null otherwise
      Throws:
        `ServiceNotAvailableException` - Sync service is not UP
        `InterruptedException` - Operation interrupted exception

    - #### multi

          List<SyncServiceMultiOpResult> multi(List<SyncServiceMultiOp> opList)
                                               throws ServiceNotAvailableException,
                                                      InterruptedException,
                                                      SyncServiceException.NodeExistsException,
                                                      SyncServiceException.NodeNotFoundException,
                                                      SyncServiceException.NodeHasChildrenException

      Execute a batch of sync services operations. It is ensured that all or none semantics is taken care in executing the transaction. The operation is allowed only if there are at least 2 operations in the input parameter
      Parameters:
        `opList` - List of sync service multi operation objects
      Returns:
        OpResult Result of each of the multi operation executed. Null is returned in case of failure. Application has to use e.getMultiOpResults() to analyze the execution status of each of the operation.
      Throws:
        `InterruptedException` - Operation interrupted exception
        `ServiceNotAvailableException` - Sync service is not UP
        `SyncServiceException.NodeHasChildrenException` - Node has children
        `SyncServiceException.NodeNotFoundException` - Node not found
        `SyncServiceException.NodeExistsException` - Node exists

Copyright © 2014. All Rights Reserved.