LeaderElection (com.neovisionaries:nv-zookeeper 1.2 API)

java.lang.Object
- com.neovisionaries.zookeeper.LeaderElection

public class LeaderElection
extends Object

An implementation of a "leader election" algorithm using ZooKeeper.

 // Prepare a ZooKeeper instance.
 ZooKeeper zooKeeper = ...

 // Prepare a Listener implementation.
 LeaderElection.LeaderElection.Listener listener = new LeaderElection.Listener() {
     @Override
     public void onWin(LeaderElection election) {
         System.out.println("I'm the leader.");
     }

     @Override
     public void onLose(LeaderElection election) {
         System.out.println("Someone else is the leader.");
     }

     @Override
     public void onVacant(LeaderElection election) {
         System.out.println("The leader resigned. An election will be conducted again.");
     }

     @Override
     public void onFinish(LeaderElection election) {
         System.out.println("The callback chain ended. Not run for election any more.");
     }

     @Override
     public void onStateChanged(LeaderElection election, LeaderElection.State oldState, LeaderElection.State newState) {
         System.out.format("The state was changed from %s to %s.\n", oldState, newState);
     }
 };

 // Conduct a leader election.
 new LeaderElection()
     .setZooKeeper(zooKeeper)
     .setListener(listener)
     .start();

 // Same as above.
 new LeaderElection()
     .setZooKeeper(zooKeeper)
     .setListener(listener)
     .setPath("/leader")
     .setId(
         String.valueOf(Math.abs(new Random().nextLong()))
     )
     .setAclList(ZooDefs.Ids.OPEN_ACL_UNSAFE)
     .start();

This implementation repeats to join a leader election, i.e. continues to schedule a callback (and a watcher as necessary), unless it detects either of the following.

The given ZooKeeper instance reports AUTH_FAILED or CLOSED.
This instance is marked as 'shouldFinish' by finish().

LeaderElection.Adapter is an empty implementation of LeaderElection.Listener. You may find it useful when you are interested in only some of the callback methods. For example, if you are interested in only onStateChanged(), using Adapter will make your code shorter like below.

 // Conduct a leader election.
 new LeaderElection()
     .setZooKeeper(zooKeeper)
     .setListener(new LeaderElection.LeaderElection.Adapter() {
         @Override
         public void onStateChanged(LeaderElection election, LeaderElection.State oldState, LeaderElection.State newState) {
             System.out.format("The state was changed from %s to %s.\n", oldState, newState);
         }
     })
     .start();

Author:: Takahiko Kawasaki

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`LeaderElection.Adapter` An empty implementation of `LeaderElection.Listener`.
`static interface`	`LeaderElection.Listener` The listener to receive leader election events.
`static class`	`LeaderElection.State` Leader election state.

Constructor Summary

Constructors
Constructor and Description

LeaderElection()

LeaderElection(org.apache.zookeeper.ZooKeeper zooKeeper)

Constructors
Constructor and Description
`LeaderElection()`
`LeaderElection(org.apache.zookeeper.ZooKeeper zooKeeper)`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`NodeReader`	`createReader()` Create a `NodeReader` instance to read the content of the znode that is used for leader election.
`LeaderElection`	`finish()` Mark as 'shouldFinish' not to schedule ZooKeeper callbacks any further.
`List<org.apache.zookeeper.data.ACL>`	`getAclList()` Get the ACL list used for creation of the znode for leader election.
`List<org.apache.zookeeper.data.ACL>`	`getDefaultAclList()` Get the default ACL list (`OPEN_ACL_UNSAFE`).
`String`	`getDefaultPath()` Get the default path (`"/leader"`).
`String`	`getId()` Get the ID that represents this candidate in leader election.
`LeaderElection.Listener`	`getListener()` Get the listener for leader election events.
`String`	`getPath()` Get the znode path used for leader election.
`LeaderElection.State`	`getState()` Get the current `state`.
`org.apache.zookeeper.ZooKeeper`	`getZooKeeper()` Get the `ZooKeeper` instance used for leader election.
`LeaderElection`	`setAclList(List<org.apache.zookeeper.data.ACL> list)` Set the ACL list used for creation of the znode for leader election.
`LeaderElection`	`setId(String id)` Set the ID that represents this candidate in leader election.
`LeaderElection`	`setListener(LeaderElection.Listener listener)` Set the listener for leader election events.
`LeaderElection`	`setPath(String path)` Set the znode path used for leader election.
`LeaderElection`	`setZooKeeper(org.apache.zookeeper.ZooKeeper zooKeeper)` Set the `ZooKeeper` instance used for leader election.
`LeaderElection`	`start()` Start leader election.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - LeaderElection
```
public LeaderElection()
```
  - LeaderElection
```
public LeaderElection(org.apache.zookeeper.ZooKeeper zooKeeper)
```
- Method Detail
  - getZooKeeper
```
public org.apache.zookeeper.ZooKeeper getZooKeeper()
```
    Get the ZooKeeper instance used for leader election.
    
    Returns:
    
    The ZooKeeper instance used for leader election.
  - setZooKeeper
```
public LeaderElection setZooKeeper(org.apache.zookeeper.ZooKeeper zooKeeper)
```
    Set the ZooKeeper instance used for leader election.
    If no ZooKeeper instance is set when start() is called, an IllegalStateException is thrown.
    
    Parameters:
    
    zooKeeper - A ZooKeeper instance used for leader election.
    
    Returns:
    
    this object.
  - getPath
```
public String getPath()
```
    Get the znode path used for leader election.
    
    Returns:
    
    The znode path used for leader election.
  - setPath
```
public LeaderElection setPath(String path)
```
    Set the znode path used for leader election.
    If no znode path is set when start() is called, the default value, "/leader", is used.
    
    Parameters:
    
    path - The znode path used for leader election.
    
    Returns:
    
    this object.
  - getDefaultPath
```
public String getDefaultPath()
```
    Get the default path ("/leader").
    
    Returns:
    
    The default path.
    
    Since:
    
    1.2
  - getId
```
public String getId()
```
    Get the ID that represents this candidate in leader election.
    
    Returns:
    
    The ID that represents this candidate in leader election.
  - setId
```
public LeaderElection setId(String id)
```
    Set the ID that represents this candidate in leader election. The value must be different from other candidates' IDs.
    If no ID is set when start() is called, a random ID is generated.
    
    Parameters:
    
    id - The ID that represents this candidate in leader election.
    
    Returns:
    
    this object.
  - getAclList
```
public List<org.apache.zookeeper.data.ACL> getAclList()
```
    Get the ACL list used for creation of the znode for leader election.
    
    Returns:
    
    The ACL list used for creation of the znode for leader election.
  - setAclList
```
public LeaderElection setAclList(List<org.apache.zookeeper.data.ACL> list)
```
    Set the ACL list used for creation of the znode for leader election.
    If no ACL list is set when start() is called, the default list, ZooDefs.Ids.OPEN_ACL_UNSAFE, is used.
    
    Parameters:
    
    list - The ACL list used for creation of the znode for leader election.
    
    Returns:
    
    this object.
  - getDefaultAclList
```
public List<org.apache.zookeeper.data.ACL> getDefaultAclList()
```
    Get the default ACL list (OPEN_ACL_UNSAFE).
    
    Returns:
    
    The default ACL list.
    
    Since:
    
    1.2
  - getListener
```
public LeaderElection.Listener getListener()
```
    Get the listener for leader election events.
    
    Returns:
    
    The listener for leader election events.
  - setListener
```
public LeaderElection setListener(LeaderElection.Listener listener)
```
    Set the listener for leader election events.
    
    Parameters:
    
    listener - The listener for leader election events.
    
    Returns:
    
    this object.
  - start
```
public LeaderElection start()
```
    Start leader election.
    This implementation repeats to join a leader election, i.e. continues to schedule a callback (and a watcher as necessary), unless it detects either of the following.
    The given ZooKeeper instance reports AUTH_FAILED or CLOSED.
    This instance is marked as 'shouldStop' by finish().
    Returns:
    
    this object.
    
    Throws:
    IllegalStateException -
    
    No ZooKeeper instance is set.
    The current state is not CREATED.
  - finish
```
public LeaderElection finish()
```
    Mark as 'shouldFinish' not to schedule ZooKeeper callbacks any further. After calling finish(), this LeaderElection instance never joins a leader election.
    Note that calling this method does not remove an existing Watcher which is watching the znode for leader election.
    
    Returns:
    
    this object.
  - getState
```
public LeaderElection.State getState()
```
    Get the current state.
    
    Returns:
    
    The current state.
    
    Since:
    
    1.1
  - createReader
```
public NodeReader createReader()
```
    Create a NodeReader instance to read the content of the znode that is used for leader election. This method behaves almost the same way as the following code.
```
 return new NodeReader()
     .setZooKeeper(getZooKeeper())
     .setPath((getPath() != null) ? getPath() : getDefaultPath());
 
```
    Note that no listener is set to the returned NodeReader instance.
    Returns:
    
    A NodeReader instance to read the content of the znode that is used for leader election.
    
    Since:
    
    1.2

Class LeaderElection

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

LeaderElection

LeaderElection

Method Detail

getZooKeeper

setZooKeeper

getPath

setPath

getDefaultPath

getId

setId

getAclList

setAclList

getDefaultAclList

getListener

setListener

start

finish

getState

createReader