io.atomix.cluster.messaging

Interface ClusterEventService

All Known Subinterfaces:

ManagedClusterEventService

public interface ClusterEventService

Publish-subscribe based messaging service.

This service is an abstraction for publish-subscribe based cluster communication. Messages are published and received based on arbitrary String topics. It supports several types of messaging:

• broadcast(String, Object) broadcasts a message to all subscribers registered for the topic
• unicast(String, Object) sends a unicast message directly to one of the subscribers registered for the topic; unicast messages are generally delivered in round-robin fashion
• send(String, Object) sends a message directly to one of the subscribers registered for the topic and awaits a reply; direct messages are generally delivered in round-robin fashion

To register to listen for messages, use one of the subscribe(String, Consumer, Executor) methods:

   
   Subscription subscription = atomix.getEventService().subscribe("test", message -> {
     System.out.println("Received message");
   }, executor).join();
   
 

To cancel the subscription for a topic, call Subscription.close() on the returned Subscription object:

   
   subscription.close().join();
   
 

This API relies on CompletableFuture for asynchronous completion of all method calls.

Method Summary

Modifier and Type	Method and Description
default <M> void	broadcast(String topic, M message) Broadcasts a message to all subscribers registered for the given topic.
<M> void	broadcast(String topic, M message, Function<M,byte[]> encoder) Broadcasts a message to all subscribers registered for the given topic.
List<Subscription>	getSubscriptions(String topic) Returns a list of subscriptions for the given topic.
default <M,R> CompletableFuture<R>	send(String topic, M message) Sends a direct message to the next registered subscriber for topic and awaits a reply.
default <M,R> CompletableFuture<R>	send(String topic, M message, Duration timeout) Sends a direct message to the next registered subscriber for topic and awaits a reply.
default <M,R> CompletableFuture<R>	send(String topic, M message, Function<M,byte[]> encoder, Function<byte[],R> decoder) Sends a direct message to the next registered subscriber for topic and awaits a reply.
<M,R> CompletableFuture<R>	send(String topic, M message, Function<M,byte[]> encoder, Function<byte[],R> decoder, Duration timeout) Sends a direct message to the next registered subscriber for topic and awaits a reply.
default <M> CompletableFuture<Subscription>	subscribe(String topic, Consumer<M> handler, Executor executor) Adds a new subscriber for the specified message topic.
<M> CompletableFuture<Subscription>	subscribe(String topic, Function<byte[],M> decoder, Consumer<M> handler, Executor executor) Adds a new subscriber for the specified message topic.
<M,R> CompletableFuture<Subscription>	subscribe(String topic, Function<byte[],M> decoder, Function<M,CompletableFuture<R>> handler, Function<R,byte[]> encoder) Adds a new subscriber for the specified message topic.
<M,R> CompletableFuture<Subscription>	subscribe(String topic, Function<byte[],M> decoder, Function<M,R> handler, Function<R,byte[]> encoder, Executor executor) Adds a new subscriber for the specified message topic.
default <M,R> CompletableFuture<Subscription>	subscribe(String topic, Function<M,CompletableFuture<R>> handler) Adds a new subscriber for the specified message topic.
default <M,R> CompletableFuture<Subscription>	subscribe(String topic, Function<M,R> handler, Executor executor) Adds a new subscriber for the specified message topic.
default <M> CompletableFuture<Void>	unicast(String topic, M message) Unicasts a message to the next registered subscriber for topic.
<M> CompletableFuture<Void>	unicast(String topic, M message, Function<M,byte[]> encoder) Unicasts a message to the next registered subscriber for topic.

Method Detail

broadcast

default <M> void broadcast(String topic,
                           M message)

Broadcasts a message to all subscribers registered for the given topic.

Type Parameters:

M - message type

Parameters:

topic - message topic

message - message to send

broadcast

<M> void broadcast(String topic,
                   M message,
                   Function<M,byte[]> encoder)

Broadcasts a message to all subscribers registered for the given topic.

Type Parameters:

M - message type

Parameters:

topic - message topic

message - message to send

encoder - function for encoding message to byte[]

unicast

default <M> CompletableFuture<Void> unicast(String topic,
                                            M message)

Unicasts a message to the next registered subscriber for topic.

Type Parameters:

M - message type

Parameters:

topic - message topic

message - message to send

Returns:

future that is completed when the message is sent

unicast

<M> CompletableFuture<Void> unicast(String topic,
                                    M message,
                                    Function<M,byte[]> encoder)

Unicasts a message to the next registered subscriber for topic.

Type Parameters:

M - message type

Parameters:

message - message to send

topic - message topic

encoder - function for encoding message to byte[]

Returns:

future that is completed when the message is sent

send

default <M,R> CompletableFuture<R> send(String topic,
                                        M message)

Sends a direct message to the next registered subscriber for topic and awaits a reply.

Type Parameters:

M - request type

R - reply type

Parameters:

topic - message topic

message - message to send

Returns:

reply future

send

default <M,R> CompletableFuture<R> send(String topic,
                                        M message,
                                        Duration timeout)

Sends a direct message to the next registered subscriber for topic and awaits a reply.

Type Parameters:

M - request type

R - reply type

Parameters:

topic - message topic

message - message to send

timeout - reply timeout

Returns:

reply future

send

default <M,R> CompletableFuture<R> send(String topic,
                                        M message,
                                        Function<M,byte[]> encoder,
                                        Function<byte[],R> decoder)

Sends a direct message to the next registered subscriber for topic and awaits a reply.

Type Parameters:

M - request type

R - reply type

Parameters:

topic - message topic

message - message to send

encoder - function for encoding request to byte[]

decoder - function for decoding response from byte[]

Returns:

reply future

send

<M,R> CompletableFuture<R> send(String topic,
                                M message,
                                Function<M,byte[]> encoder,
                                Function<byte[],R> decoder,
                                Duration timeout)

Sends a direct message to the next registered subscriber for topic and awaits a reply.

Type Parameters:

M - request type

R - reply type

Parameters:

topic - message topic

message - message to send

encoder - function for encoding request to byte[]

decoder - function for decoding response from byte[]

timeout - reply timeout

Returns:

reply future

subscribe

default <M,R> CompletableFuture<Subscription> subscribe(String topic,
                                                        Function<M,R> handler,
                                                        Executor executor)

Adds a new subscriber for the specified message topic.

Type Parameters:

M - incoming message type

R - reply message type

Parameters:

topic - message topic

handler - handler function that processes the incoming message and produces a reply

executor - executor to run this handler on

Returns:

future to be completed once the subscription has been propagated

subscribe

<M,R> CompletableFuture<Subscription> subscribe(String topic,
                                                Function<byte[],M> decoder,
                                                Function<M,R> handler,
                                                Function<R,byte[]> encoder,
                                                Executor executor)

Adds a new subscriber for the specified message topic.

Type Parameters:

M - incoming message type

R - reply message type

Parameters:

topic - message topic

decoder - decoder for resurrecting incoming message

handler - handler function that processes the incoming message and produces a reply

encoder - encoder for serializing reply

executor - executor to run this handler on

Returns:

future to be completed once the subscription has been propagated

subscribe

default <M,R> CompletableFuture<Subscription> subscribe(String topic,
                                                        Function<M,CompletableFuture<R>> handler)

Adds a new subscriber for the specified message topic.

Type Parameters:

M - incoming message type

R - reply message type

Parameters:

topic - message topic

handler - handler function that processes the incoming message and produces a reply

Returns:

future to be completed once the subscription has been propagated

subscribe

<M,R> CompletableFuture<Subscription> subscribe(String topic,
                                                Function<byte[],M> decoder,
                                                Function<M,CompletableFuture<R>> handler,
                                                Function<R,byte[]> encoder)

Adds a new subscriber for the specified message topic.

Type Parameters:

M - incoming message type

R - reply message type

Parameters:

topic - message topic

decoder - decoder for resurrecting incoming message

handler - handler function that processes the incoming message and produces a reply

encoder - encoder for serializing reply

Returns:

future to be completed once the subscription has been propagated

subscribe

default <M> CompletableFuture<Subscription> subscribe(String topic,
                                                      Consumer<M> handler,
                                                      Executor executor)

Adds a new subscriber for the specified message topic.

Type Parameters:

M - incoming message type

Parameters:

topic - message topic

handler - handler for handling message

executor - executor to run this handler on

Returns:

future to be completed once the subscription has been propagated

subscribe

<M> CompletableFuture<Subscription> subscribe(String topic,
                                              Function<byte[],M> decoder,
                                              Consumer<M> handler,
                                              Executor executor)

Adds a new subscriber for the specified message topic.

Type Parameters:

M - incoming message type

Parameters:

topic - message topic

decoder - decoder to resurrecting incoming message

handler - handler for handling message

executor - executor to run this handler on

Returns:

future to be completed once the subscription has been propagated

getSubscriptions

List<Subscription> getSubscriptions(String topic)

Returns a list of subscriptions for the given topic.

Parameters:

topic - the topic for which to return subscriptions

Returns:

the subscriptions for the given topic