DistributedGroup (Atomix API Reference (1.0.0-rc1))

java.lang.Object
- io.atomix.resource.Resource<DistributedGroup>
- - io.atomix.coordination.DistributedGroup

All Implemented Interfaces:

Managed<DistributedGroup>
```
public class DistributedGroup
extends Resource<DistributedGroup>
```
Provides a mechanism for managing group membership and remote scheduling and execution.
The distributed membership group resource facilitates managing group membership within the Atomix cluster. Each instance of a DistributedGroup resource represents a single GroupMember. Members can join() and LocalGroupMember.leave() the group and be notified of other members joining and leaving the group. Members may leave the group either voluntarily or due to a failure or other disconnection from the cluster.
To create a membership group resource, use the DistributedGroup class or constructor:
```
   
   atomix.getGroup("my-group").thenAccept(group -> {
     ...
   });
   
 
```
Joining the group
When a new instance of the resource is created, it is initialized with an empty members() list as it is not yet a member of the group. Once the instance has been created, the user must join the group via join():
```
   
   group.join().thenAccept(member -> {
     System.out.println("Joined with member ID: " + member.id());
   });
   
 
```
Once the group has been joined, the members() list provides an up-to-date view of the group which will be automatically updated as members join and leave the group. To be explicitly notified when a member joins or leaves the group, use the onJoin(Consumer) or onLeave(Consumer) event consumers respectively:
```
   
   group.onJoin(member -> {
     System.out.println(member.id() + " joined the group!");
   });
   
 
```
Remote execution
Once members of the group, any member can execute immediate callbacks or schedule delayed callbacks to be run on any other member of the group. Submitting a Runnable callback to a member will cause it to be serialized and sent to that node to be executed.
```
   
   group.onJoin(member -> {
     long memberId = member.id();
     member.execute((Serializable & Runnable) () -> System.out.println("Executing on " + memberId));
   });
   
 
```
Author:

See Also:
GroupMember

Nested Class Summary
- Nested classes/interfaces inherited from class io.atomix.resource.Resource
  Resource.Config, Resource.Options, Resource.State

Constructor Summary

Constructors
Constructor and Description

DistributedGroup(CopycatClient client, Resource.Options options)

Constructors
Constructor and Description
`DistributedGroup(CopycatClient client, Resource.Options options)`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static Resource.Config`	`config()` Returns a new group configuration.
`CompletableFuture<LocalGroupMember>`	`join()` Joins the instance to the membership group.
`CompletableFuture<LocalGroupMember>`	`join(String memberId)` Joins the instance to the membership group with a user-provided member ID.
`GroupMember`	`leader()` Returns the current group leader.
`GroupMember`	`member(String memberId)` Gets a group member by ID.
`Collection<GroupMember>`	`members()` Gets the collection of all members in the group.
`Listener<GroupMember>`	`onElection(Consumer<GroupMember> callback)` Registers a callback to be called when a member of the group is elected leader.
`Listener<GroupMember>`	`onJoin(Consumer<GroupMember> listener)` Adds a listener for members joining the group.
`Listener<GroupMember>`	`onLeave(Consumer<GroupMember> listener)` Adds a listener for members leaving the group.
`Listener<Long>`	`onTerm(Consumer<Long> callback)` Registers a callback to be called when the term changes.
`CompletableFuture<DistributedGroup>`	`open()`
`static Resource.Options`	`options()` Returns new group options.
`long`	`term()` Returns the current group term.

Methods inherited from class io.atomix.resource.Resource
close, configure, context, delete, equals, hashCode, isClosed, isOpen, onStateChange, readConsistency, state, toString, type, with, with, writeConsistency

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - DistributedGroup
```
public DistributedGroup(CopycatClient client,
                        Resource.Options options)
```
- Method Detail
  - options
```
public static Resource.Options options()
```
    Returns new group options.
    
    Returns:
    
    New group options.
  - config
```
public static Resource.Config config()
```
    Returns a new group configuration.
    
    Returns:
    
    A new group configuration.
  - open
```
public CompletableFuture<DistributedGroup> open()
```
    Specified by:
    
    open in interface Managed<DistributedGroup>
    
    Overrides:
    
    open in class Resource<DistributedGroup>
  - leader
```
public GroupMember leader()
```
    Returns the current group leader.
    
    Returns:
    
    The current group leader.
  - term
```
public long term()
```
    Returns the current group term.
    
    Returns:
    
    The current group term.
  - onTerm
```
public Listener<Long> onTerm(Consumer<Long> callback)
```
    Registers a callback to be called when the term changes.
    
    Parameters:
    
    callback - The callback to be called when the term changes.
    
    Returns:
    
    The term listener.
  - onElection
```
public Listener<GroupMember> onElection(Consumer<GroupMember> callback)
```
    Registers a callback to be called when a member of the group is elected leader.
    
    Parameters:
    
    callback - The callback to call when a member of the group is elected leader.
    
    Returns:
    
    The leader election listener.
  - member
```
public GroupMember member(String memberId)
```
    Gets a group member by ID.
    If the member with the given ID has not joined the membership group, the resulting GroupMember will be null.
    
    Parameters:
    
    memberId - The member ID for which to return a GroupMember.
    
    Returns:
    
    The member with the given memberId or null if it is not a known member of the group.
  - members
```
public Collection<GroupMember> members()
```
    Gets the collection of all members in the group.
    The group members are fetched from the cluster. If any GroupMember instances have been referenced by this membership group instance, the same object will be returned for that member.
    This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.join() method to block the calling thread:
```
   
   Collection<GroupMember> members = group.members().get();
   
 
```
    Alternatively, to execute the operation asynchronous and be notified once the lock is acquired in a different thread, use one of the many completable future callbacks:
```
   
   group.members().thenAccept(members -> {
     members.forEach(member -> {
       member.send("test", "Hello world!");
     });
   });
   
 
```
    Returns:
    
    The collection of all members in the group.
  - join
```
public CompletableFuture<LocalGroupMember> join()
```
    Joins the instance to the membership group.
    When this instance joins the membership group, the membership lists of this and all other instances in the group are guaranteed to be updated before the CompletableFuture returned by this method is completed. Once this instance has joined the group, the returned future will be completed with the GroupMember instance for this member.
    This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.join() method to block the calling thread:
```
   
   group.join().join();
   
 
```
    Alternatively, to execute the operation asynchronous and be notified once the lock is acquired in a different thread, use one of the many completable future callbacks:
```
   
   group.join().thenAccept(thisMember -> System.out.println("This member is: " + thisMember.id()));
   
 
```
    Returns:
    
    A completable future to be completed once the member has joined.
  - join
```
public CompletableFuture<LocalGroupMember> join(String memberId)
```
    Joins the instance to the membership group with a user-provided member ID.
    When this instance joins the membership group, the membership lists of this and all other instances in the group are guaranteed to be updated before the CompletableFuture returned by this method is completed. Once this instance has joined the group, the returned future will be completed with the GroupMember instance for this member.
    This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.join() method to block the calling thread:
```
   
   group.join().join();
   
 
```
    Alternatively, to execute the operation asynchronous and be notified once the lock is acquired in a different thread, use one of the many completable future callbacks:
```
   
   group.join().thenAccept(thisMember -> System.out.println("This member is: " + thisMember.id()));
   
 
```
    Parameters:
    
    memberId - The unique member ID to assign to the member.
    
    Returns:
    
    A completable future to be completed once the member has joined.
  - onJoin
```
public Listener<GroupMember> onJoin(Consumer<GroupMember> listener)
```
    Adds a listener for members joining the group.
    The provided Consumer will be called each time a member joins the group. Note that the join consumer will be called before the joining member's join() completes.
    The returned Listener can be used to unregister the listener when its use if finished.
    
    Parameters:
    
    listener - The join listener.
    
    Returns:
    
    The listener context.
  - onLeave
```
public Listener<GroupMember> onLeave(Consumer<GroupMember> listener)
```
    Adds a listener for members leaving the group.
    The provided Consumer will be called each time a member leaves the group. Members can leave the group either voluntarily or by crashing or otherwise becoming disconnected from the cluster for longer than their session timeout. Note that the leave consumer will be called before the leaving member's LocalGroupMember.leave() completes.
    The returned Listener can be used to unregister the listener when its use if finished.
    
    Parameters:
    
    listener - The leave listener.
    
    Returns:
    
    The listener context.

Class DistributedGroup

Nested Class Summary

Nested classes/interfaces inherited from class io.atomix.resource.Resource

Constructor Summary

Method Summary

Methods inherited from class io.atomix.resource.Resource

Methods inherited from class java.lang.Object

Constructor Detail

DistributedGroup

Method Detail

options

config

open

leader

term

onTerm

onElection

member

members

join

join

onJoin

onLeave