Package 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 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, java.util.function.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, java.time.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, 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> CompletableFuture<R> send​(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> CompletableFuture<Subscription> subscribe​(String topic, java.util.function.Consumer<M> handler, Executor executor)
    Adds a new subscriber for the specified message topic.
    <M> CompletableFuture<Subscription> subscribe​(String topic, java.util.function.Function<byte[],​M> decoder, java.util.function.Consumer<M> handler, Executor executor)
    Adds a new subscriber for the specified message topic.
    <M,​ R> CompletableFuture<Subscription> subscribe​(String topic, java.util.function.Function<byte[],​M> decoder, java.util.function.Function<M,​CompletableFuture<R>> handler, java.util.function.Function<R,​byte[]> encoder)
    Adds a new subscriber for the specified message topic.
    <M,​ R> CompletableFuture<Subscription> subscribe​(String topic, java.util.function.Function<byte[],​M> decoder, java.util.function.Function<M,​R> handler, java.util.function.Function<R,​byte[]> encoder, Executor executor)
    Adds a new subscriber for the specified message topic.
    default <M,​ R> CompletableFuture<Subscription> subscribe​(String topic, java.util.function.Function<M,​CompletableFuture<R>> handler)
    Adds a new subscriber for the specified message topic.
    default <M,​ R> CompletableFuture<Subscription> subscribe​(String topic, java.util.function.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, java.util.function.Function<M,​byte[]> encoder)
    Unicasts a message to the next registered subscriber for topic.

  • Method Details

    • 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, 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> 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, 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> 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, 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> CompletableFuture<R> send​(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> CompletableFuture<R> send​(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> CompletableFuture<Subscription> subscribe​(String topic, java.util.function.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, java.util.function.Function<byte[],​M> decoder, java.util.function.Function<M,​R> handler, java.util.function.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, java.util.function.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, java.util.function.Function<byte[],​M> decoder, java.util.function.Function<M,​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> CompletableFuture<Subscription> subscribe​(String topic, java.util.function.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, java.util.function.Function<byte[],​M> decoder, java.util.function.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