io.atomix.coordination

Class DistributedTopic<T>

java.lang.Object

io.atomix.resource.AbstractResource

io.atomix.coordination.DistributedTopic<T>

All Implemented Interfaces:

Resource

public class DistributedTopic<T>
extends AbstractResource

Facilitates persistent publish-subscribe messaging in the cluster.

The distributed topic resource provides persistent publish-subscribe messaging between instances of the resource. Pub-sub messaging is implemented as commands that are logged and replicated via the Raft consensus algorithm. When a message is published to a distributed topic the message will be persisted until it has been received by all instances listening to the topic.

To create a topic resource, use the DistributedTopic class or constructor:

   
   atomix.create("topic", DistributedTopic.class).thenAccept(topic -> {
     ...
   });
   
 

The topic resource exposes two simple methods: publish(Object) and subscribe(Consumer). Resources may publish but not subscribe to the topic or subscribe but not publish to the topic. Messages are only routed to the resource instance if a subscribe listener has been registered.

   
   topic.subscribe(message -> System.out.println("Received: " + message));
   topic.publish("Hello world!");
   
 

Author:

Jordan Halterman

Constructor Summary

Constructors

Constructor and Description
DistributedTopic(RaftClient client)

Method Summary

Modifier and Type	Method and Description
DistributedTopic<T>	async() Sets the topic to asynchronous mode.
CompletableFuture<Void>	publish(T message) Publishes a message to the topic.
CompletableFuture<Listener<T>>	subscribe(Consumer<T> listener) Subscribes to messages from the topic.
DistributedTopic<T>	sync() Sets the topic to synchronous mode.
DistributedTopic<T>	with(Consistency consistency)

Methods inherited from class io.atomix.resource.AbstractResource

context, delete, equals, hashCode, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DistributedTopic

public DistributedTopic(RaftClient client)

Method Detail

with

public DistributedTopic<T> with(Consistency consistency)

Specified by:

with in interface Resource

Overrides:

with in class AbstractResource

sync

public DistributedTopic<T> sync()

Sets the topic to synchronous mode.

Setting the topic to synchronous mode effectively configures the topic's Consistency to Consistency.ATOMIC. Atomic consistency means that messages published to the topic will be received by all subscribers some time between the invocation of the publish operation and its completion.

Returns:

The distributed topic.

async

public DistributedTopic<T> async()

Sets the topic to asynchronous mode.

Setting the topic to asynchronous mode effectively configures the topic's Consistency to Consistency.SEQUENTIAL. Sequential consistency means that once a message is published to the topic, the message will be persisted in the cluster but may be delivered to subscribers after some arbitrary delay. Messages are guaranteed to be delivered to subscribers in the order in which they were sent (sequential consistency) but different subscribers may receive different messages at different points in time.

Returns:

The distributed topic.

publish

public CompletableFuture<Void> publish(T message)

Publishes a message to the topic.

The message will be published according to the configured consistency level. Events published with Consistency.ATOMIC consistency are guaranteed to be received by all subscribers prior to the CompletableFuture returned by this method being completed. For all other consistency levels, messages will be received by subscribers asynchronously.

This method returns a CompletableFuture which can be used to block until the message has been persisted 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:

   
   topic.publish("Hello world!").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:

   
   topic.publish("Hello world!").thenRun(() -> System.out.println("Published to topic: " + topic.key()));
   
 

Parameters:

message - The message to publish.

Returns:

A completable future to be completed once the message has been published.

subscribe

public CompletableFuture<Listener<T>> subscribe(Consumer<T> listener)

Subscribes to messages from the topic.

Once the returned CompletableFuture is completed, the subscriber is guaranteed to receive all messages from any client thereafter. Messages are guaranteed to be received in the order specified by the instance from which they were sent. The provided Consumer will always be executed on the same thread.

This method returns a CompletableFuture which can be used to block until the listener has been registered 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:

   
   topic.subscribe(message -> {
     ...
   }).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:

   
   topic.subscribe(message -> {
     ...
   }).thenRun(() -> System.out.println("Subscribed to " + topic.key()));
   
 

Parameters:

listener - The message listener.

Returns:

The listener context.