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