ClusterInfoSession (Dempsy Commons Aggregator 2.1.2 API)

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

LocalClusterSessionFactory.LocalSession, ZookeeperSession
```
public interface ClusterInfoSession
extends AutoCloseable
```
This is the main interface for the dempsy-cluster.api abstraction. If you're familiar with ZooKeeper then this should be completely straightforward.

Cluster information is stored in a file system like tree structure where information is addressable using a '/' separated path. Each node in the tree can optionally contain a single data Object (NOTE: the main implementation (dempsy-cluster.zookeeper) uses dempsy-serialization.api so the data may need to be serializable according to whatever serialization scheme is registered with that Implementation).

Implementations of ClusterInfoWatchers can be registered with any node in the tree to receive notifications of changes at that node. To register for changes to the data at a node, you can use exists(String, ClusterInfoWatcher) or getData(String, ClusterInfoWatcher). For example:
```
 
  final ClusterInfoSession session = factory.createSession();
  session.mkdir("/root",null,DirMode.EPHEMERAL); // make parent dir
  session.mkdir("/root/subdir", null, DirMode.EPHEMERAL); // make child dir
  session.exists("/root/subdir", () -> System.out.prinln("The data at /root/subdir has changed")); // <- lambda callback will be invoked when the data changes.
  
  ....
  otherSession.setData("/root/subdir", new MyDataObject()); // <- this will cause the lambda to execute.
 
 
```
Note that there is a distinction made between registering for changes that include new or deleted subdirectories, and changes that include the data at a location changing. To register for changes to subdirectories of a particular node in the tree, use getSubdirs(String, ClusterInfoWatcher). For example:
```
 
  final ClusterInfoSession session = factory.createSession();
  session.mkdir("/root",null,DirMode.EPHEMERAL); // make parent dir
  session.getSubdirs("/root",() -&gt; System.out.prinln("The subdirs of /root have changed")); // - lambda callback will be invoked when subdirs come or go. *     );
  
  ....
  otherSession.mkdir("/root/subdir", null, DirMode.EPHEMERAL); // - this will cause the lambda to execute.
 }
 
```
SEQUENTIAL directories will appear as separately versioned directories when retrieved using getSubdirs(String, ClusterInfoWatcher). They will appear as different subdirectories with a suffix. For example:
```
 
 ...
  session.mkdir("/root/subdir_", null, DirMode.EPHEMERAL_SEQUENTIAL); // make child dir
  session.mkdir("/root/subdir_", null, DirMode.EPHEMERAL_SEQUENTIAL); // make child dir
  session.mkdir("/root/subdir_", null, DirMode.EPHEMERAL_SEQUENTIAL); // make child dir
  Collection<String> subdirs = session.getSubdirs("/root");
  subdirs.stream().forEach(s -> System.out.println(s));
  ....
 
 
```
This will result in something like the following:
```
 subdir_0000000000
 subdir_0000000001
 subdir_0000000002
 
```
The version suffixes are both lexographically sortable and also convertable to integers. This should be guaranteed by every implementation.

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`default void`	`close()` default implementation of the `AutoCloseable` interface.
`boolean`	`exists(String path, ClusterInfoWatcher watcher)` Check if a path has already been created.
`Object`	`getData(String path, ClusterInfoWatcher watcher)` If data is stored at the node indicated by the path, then the data will be returned.
`Collection<String>`	`getSubdirs(String path, ClusterInfoWatcher watcher)` Show all of the subdirectories of the given directory.
`String`	`mkdir(String path, Object data, DirMode mode)` This will create a node at the given path.
`default String`	`recursiveMkdir(String path, Object data, DirMode parentMode, DirMode mode)`
`void`	`rmdir(String path)` This will remove the directory stored at the path.
`void`	`setData(String path, Object data)` Set the data associated with the tree node identified by the path.
`void`	`stop()` Stop the session.

- Method Detail
  - recursiveMkdir
```
default String recursiveMkdir(String path,
                              Object data,
                              DirMode parentMode,
                              DirMode mode)
                       throws ClusterInfoException
```
    Throws:
    
    ClusterInfoException
  - mkdir
```
String mkdir(String path,
             Object data,
             DirMode mode)
      throws ClusterInfoException
```
    This will create a node at the given path. A node must be created before it can be used. This method is not recursive so parent directories will need to be created before this one is created.
    
    Parameters:
    
    path - a '/' separated path to a directory in the cluster information manager to create.
    
    data - optional data to set for that directory
    
    mode - is the mode to set for the new directory. See DirMode.
    
    Returns:
    
    directory path if the directory was created. null if the directory cannot be created or already exists. If the DirMode is sequential then the result will satisfy the SEQUENTIAL requirements (see DirMode for the details).
    
    Throws:
    
    ClusterInfoException - on an error which can include the fact that the parent directory doesn't exist (when it should throw a ClusterInfoException.NoParentException) or if you add a directory as a subdir of an EPHEMERAL directory.
  - rmdir
```
void rmdir(String path)
    throws ClusterInfoException
```
    This will remove the directory stored at the path. The directory can be deleted if there is a data object stored in it but it cannot be deleted it it has children. They should be removed first.
    
    Parameters:
    
    path - is the directory to delete.
    
    Throws:
    
    ClusterInfoException - if there is no node at the given path.
  - exists
```
boolean exists(String path,
               ClusterInfoWatcher watcher)
        throws ClusterInfoException
```
    Check if a path has already been created. If the path exists, and if watcher is non-null then the watcher will be called back when the node at the path has data added removed or changed. Once the notification takes place the watch is unregistered.
    
    Parameters:
    
    path - is the directory to check
    
    watcher - if non-null, and the path exists, then the watcher will be called back whenever the node at the path has data added to it, or is deleted.
    
    Returns:
    
    true if the node exists, false otherwise.
    
    Throws:
    
    ClusterInfoException - if there is an unforeseen problem.
  - getData
```
Object getData(String path,
               ClusterInfoWatcher watcher)
        throws ClusterInfoException
```
    If data is stored at the node indicated by the path, then the data will be returned. If the node exists, and if watcher is non-null then the watcher will be called back when the node at the path has data added removed or changed. Once the notification takes place the watch is unregistered.
    
    Parameters:
    
    path - place to put the data.
    
    watcher - if non-null, and the path exists, then the watcher will be called back whenever the node at the path has data added to it, or is deleted.
    
    Returns:
    
    the Object stored at the location.
    
    Throws:
    
    ClusterInfoException
  - setData
```
void setData(String path,
             Object data)
      throws ClusterInfoException
```
    Set the data associated with the tree node identified by the path. Any data watches set will be triggered.
    
    Parameters:
    
    path - identify the directory/tree node of the place to store the data
    
    data - the data to put at the given location.
    
    Throws:
    
    ClusterInfoException
  - getSubdirs
```
Collection<String> getSubdirs(String path,
                              ClusterInfoWatcher watcher)
                       throws ClusterInfoException
```
    Show all of the subdirectories of the given directory. If the path exists, and if watcher is non-null then the watcher will be called back when any subdirectories are added removed or changed. Once the notification takes place the watch is unregistered.
    
    Parameters:
    
    path - where the subdirectories to show are.
    
    watcher - if non-null, and the path exists, then the watcher will be called back whenever the node at the path has data added to it, or is deleted.
    
    Returns:
    
    the list of subdirectories. These strings WILL NOT contain the full path. They will only contain the subdirectory name. If they are versions of the same SEQUENTIAL directory then they will be lexographically sortable.
    
    Throws:
    
    ClusterInfoException
  - stop
```
void stop()
```
    Stop the session. Stopping the session should cause all EPHEMERAL nodes that were created by the session to be removed. stop() must be implemented such that it doesn't throw an exception no matter what but forces the stopping of any underlying resources that require stopping. Stop is expected to manage the stopping of all underlying MpClusters that it created and once complete no more MpWatcher callbacks should be, or be able to, execute. NOTE: stop() must be idempotent.
  - close
```
default void close()
```
    default implementation of the AutoCloseable interface. By default it simply calls stop().
    
    Specified by:
    
    close in interface AutoCloseable

Interface ClusterInfoSession

Method Summary

Method Detail

recursiveMkdir

mkdir

rmdir

exists

getData

setData

getSubdirs

stop

close