public class DistributedGroup extends Resource<DistributedGroup>
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));
});
Resource.Config, Resource.Options, Resource.State| Constructor and Description |
|---|
DistributedGroup(CopycatClient client,
Resource.Options options) |
| 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.
|
public DistributedGroup(CopycatClient client, Resource.Options options)
public static Resource.Options options()
public static Resource.Config config()
public CompletableFuture<DistributedGroup> open()
open in interface Managed<DistributedGroup>open in class Resource<DistributedGroup>public GroupMember leader()
public long term()
public Listener<Long> onTerm(Consumer<Long> callback)
callback - The callback to be called when the term changes.public Listener<GroupMember> onElection(Consumer<GroupMember> callback)
callback - The callback to call when a member of the group is elected leader.public GroupMember member(String memberId)
If the member with the given ID has not joined the membership group, the resulting
GroupMember will be null.
memberId - The member ID for which to return a GroupMember.memberId or null if it is not a known member of the group.public Collection<GroupMember> members()
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!");
});
});
public CompletableFuture<LocalGroupMember> join()
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()));
public CompletableFuture<LocalGroupMember> join(String memberId)
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()));
memberId - The unique member ID to assign to the member.public Listener<GroupMember> onJoin(Consumer<GroupMember> listener)
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.
listener - The join listener.public Listener<GroupMember> onLeave(Consumer<GroupMember> listener)
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.
listener - The leave listener.Copyright © 2013–2016. All rights reserved.