io.atomix.coordination

Class DistributedMessageBus

java.lang.Object

io.atomix.resource.AbstractResource

io.atomix.coordination.DistributedMessageBus

All Implemented Interfaces:

Resource

public class DistributedMessageBus
extends AbstractResource

Provides a light-weight asynchronous messaging layer over Atomix's Transport.

The distributed message bus resource provides a simple interface for asynchronous messaging in an Atomix cluster. Message buses handle management of location information and connections and use Atomix's underlying Transport to communicate across the cluster.

To create a message bus resource, use the DistribtuedMessageBus class or constructor:

   
   atomix.get("bus", DistributedMessageBus.class).thenAccept(bus -> {
     ...
   });
   
 

Once a message bus instance has been created, it's not immediately opened. The message bus instance must be explicitly opened by calling open(Address), providing an Address to which to bind the message bus server. Because each message bus instance runs on a separate server, it's recommended that nodes use a singleton instance of this resource by using io.atomix.Atomix#get(String, Class) rather than io.atomix.Atomix#create(String, Class) to get a reference to the resource.

Messages are produced and consumed by producers and consumers respectively. Each producer and consumer is associated with a string message bus topic.

   
   bus.consumer("test", message -> {
     return "world!";
   });

   bus.producer("test").send("Hello");
   
 

The distributed message bus does not provide reliability guarantees. Messaging is implemented directly on top of the Transport layer with no additional coordination aside from managing a distributed list of topics and their consumers.

Author:

Constructor Summary

Constructors

Constructor and Description
DistributedMessageBus(RaftClient client)

Method Summary

Modifier and Type	Method and Description
CompletableFuture<Void>	close() Closes the message bus.
<T> CompletableFuture<MessageConsumer<T>>	consumer(String topic) Creates a message consumer.
<T> CompletableFuture<MessageConsumer<T>>	consumer(String topic, Function<T,?> consumer) Creates a message consumer.
boolean	isClosed() Returns a boolean value indicating whether the message bus is closed.
boolean	isOpen() Returns a boolean value indicating whether the message bus is open.
CompletableFuture<DistributedMessageBus>	open(Address address) Opens the message bus.
<T> CompletableFuture<MessageProducer<T>>	producer(String topic) Creates a message producer.
DistributedMessageBus	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

DistributedMessageBus

public DistributedMessageBus(RaftClient client)

Method Detail

with

public DistributedMessageBus with(Consistency consistency)

Specified by:

with in interface Resource

Overrides:

with in class AbstractResource

open

public CompletableFuture<DistributedMessageBus> open(Address address)

Opens the message bus.

When the message bus is opened, this instance will bind to the provided Address.

This method returns a CompletableFuture which can be used to block until the server is opened 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:

   
   bus.open(new Address("123.456.789.0", 5000)).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:

   
   bus.open(new Address("123.456.789.0", 5000)).thenRun(() -> System.out.println("Message bus open!"));
   
 

Parameters:

address - The address on which to listen.

Returns:

A completable future to be completed once the message bus is started.

isOpen

public boolean isOpen()

Returns a boolean value indicating whether the message bus is open.

Returns:

Indicates whether the message bus is open.

producer

public <T> CompletableFuture<MessageProducer<T>> producer(String topic)

Creates a message producer.

The topic is a cluster-wide identifier. Messages will be distributed to MessageConsumers registered for the given topic in round-robin order.

The producer will be created asynchronously. Once the returned CompletableFuture is completed, the producer will be prepared to send messages.

Type Parameters:

T - The message type.

Parameters:

topic - The topic to which to produce.

Returns:

A completable future to be completed once the producer has been created.

consumer

public <T> CompletableFuture<MessageConsumer<T>> consumer(String topic)

Creates a message consumer.

The consumer will be created asynchronously. Once the consumer has been registered and all other instances of the message bus across the cluster have been notified of the consumer, the returned CompletableFuture will be completed.

Type Parameters:

T - The message type.

Parameters:

topic - The topic from which to consume.

Returns:

A completable future to be completed once the consumer has been registered.

consumer

public <T> CompletableFuture<MessageConsumer<T>> consumer(String topic,
                                                          Function<T,?> consumer)

Creates a message consumer.

The consumer will be created asynchronously. Once the consumer has been registered and all other instances of the message bus across the cluster have been notified of the consumer, the returned CompletableFuture will be completed.

Type Parameters:

T - The message type.

Parameters:

topic - The topic from which to consume.

consumer - The message consumer.

Returns:

A completable future to be completed once the consumer has been registered.

close

public CompletableFuture<Void> close()

Closes the message bus.

Returns:

A completable future to be completed once the message bus is closed.

Throws:

IllegalStateException - if the message bus is not open

isClosed

public boolean isClosed()

Returns a boolean value indicating whether the message bus is closed.

Returns:

Indicates whether the message bus is closed.