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(java.lang.String topic, M message) Broadcasts a message to all subscribers registered for the given topic.
<M> void	broadcast(java.lang.String topic, M message, java.util.function.Function<M,byte[]> encoder) Broadcasts a message to all subscribers registered for the given topic.
java.util.List<Subscription>	getSubscriptions(java.lang.String topic) Returns a list of subscriptions for the given topic.
default <M,R> java.util.concurrent.CompletableFuture<R>	send(java.lang.String topic, M message) Sends a direct message to the next registered subscriber for topic and awaits a reply.
default <M,R> java.util.concurrent.CompletableFuture<R>	send(java.lang.String topic, M message, java.time.Duration timeout) Sends a direct message to the next registered subscriber for topic and awaits a reply.
default <M,R> java.util.concurrent.CompletableFuture<R>	send(java.lang.String topic, M message, java.util.function.Function<M,byte[]> encoder, java.util.function.Function<byte[],R> decoder) Sends a direct message to the next registered subscriber for topic and awaits a reply.
<M,R> java.util.concurrent.CompletableFuture<R>	send(java.lang.String topic, M message, java.util.function.Function<M,byte[]> encoder, java.util.function.Function<byte[],R> decoder, java.time.Duration timeout) Sends a direct message to the next registered subscriber for topic and awaits a reply.
default <M> java.util.concurrent.CompletableFuture<Subscription>	subscribe(java.lang.String topic, java.util.function.Consumer<M> handler, java.util.concurrent.Executor executor) Adds a new subscriber for the specified message topic.
<M> java.util.concurrent.CompletableFuture<Subscription>	subscribe(java.lang.String topic, java.util.function.Function<byte[],M> decoder, java.util.function.Consumer<M> handler, java.util.concurrent.Executor executor) Adds a new subscriber for the specified message topic.
<M,R> java.util.concurrent.CompletableFuture<Subscription>	subscribe(java.lang.String topic, java.util.function.Function<byte[],M> decoder, java.util.function.Function<M,java.util.concurrent.CompletableFuture<R>> handler, java.util.function.Function<R,byte[]> encoder) Adds a new subscriber for the specified message topic.
<M,R> java.util.concurrent.CompletableFuture<Subscription>	subscribe(java.lang.String topic, java.util.function.Function<byte[],M> decoder, java.util.function.Function<M,R> handler, java.util.function.Function<R,byte[]> encoder, java.util.concurrent.Executor executor) Adds a new subscriber for the specified message topic.
default <M,R> java.util.concurrent.CompletableFuture<Subscription>	subscribe(java.lang.String topic, java.util.function.Function<M,java.util.concurrent.CompletableFuture<R>> handler) Adds a new subscriber for the specified message topic.
default <M,R> java.util.concurrent.CompletableFuture<Subscription>	subscribe(java.lang.String topic, java.util.function.Function<M,R> handler, java.util.concurrent.Executor executor) Adds a new subscriber for the specified message topic.
default <M> java.util.concurrent.CompletableFuture<java.lang.Void>	unicast(java.lang.String topic, M message) Unicasts a message to the next registered subscriber for topic.
<M> java.util.concurrent.CompletableFuture<java.lang.Void>	unicast(java.lang.String topic, M message, java.util.function.Function<M,byte[]> encoder) Unicasts a message to the next registered subscriber for topic.

Method Detail

broadcast

default <M> void broadcast(java.lang.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(java.lang.String topic,
                   M message,
                   java.util.function.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> java.util.concurrent.CompletableFuture<java.lang.Void> unicast(java.lang.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> java.util.concurrent.CompletableFuture<java.lang.Void> unicast(java.lang.String topic,
                                                                   M message,
                                                                   java.util.function.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> java.util.concurrent.CompletableFuture<R> send(java.lang.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> java.util.concurrent.CompletableFuture<R> send(java.lang.String topic,
                                                             M message,
                                                             java.time.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> java.util.concurrent.CompletableFuture<R> send(java.lang.String topic,
                                                             M message,
                                                             java.util.function.Function<M,byte[]> encoder,
                                                             java.util.function.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> java.util.concurrent.CompletableFuture<R> send(java.lang.String topic,
                                                     M message,
                                                     java.util.function.Function<M,byte[]> encoder,
                                                     java.util.function.Function<byte[],R> decoder,
                                                     java.time.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> java.util.concurrent.CompletableFuture<Subscription> subscribe(java.lang.String topic,
                                                                             java.util.function.Function<M,R> handler,
                                                                             java.util.concurrent.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> java.util.concurrent.CompletableFuture<Subscription> subscribe(java.lang.String topic,
                                                                     java.util.function.Function<byte[],M> decoder,
                                                                     java.util.function.Function<M,R> handler,
                                                                     java.util.function.Function<R,byte[]> encoder,
                                                                     java.util.concurrent.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> java.util.concurrent.CompletableFuture<Subscription> subscribe(java.lang.String topic,
                                                                             java.util.function.Function<M,java.util.concurrent.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> java.util.concurrent.CompletableFuture<Subscription> subscribe(java.lang.String topic,
                                                                     java.util.function.Function<byte[],M> decoder,
                                                                     java.util.function.Function<M,java.util.concurrent.CompletableFuture<R>> handler,
                                                                     java.util.function.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> java.util.concurrent.CompletableFuture<Subscription> subscribe(java.lang.String topic,
                                                                           java.util.function.Consumer<M> handler,
                                                                           java.util.concurrent.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> java.util.concurrent.CompletableFuture<Subscription> subscribe(java.lang.String topic,
                                                                   java.util.function.Function<byte[],M> decoder,
                                                                   java.util.function.Consumer<M> handler,
                                                                   java.util.concurrent.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

java.util.List<Subscription> getSubscriptions(java.lang.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