Add distributed topic documentation.

coordination/src/main/java/io/atomix/coordination/DistributedMembershipGroup.java

@@ -33,7 +33,7 @@
 import java.util.function.Consumer;
 
 /**
- * Provides a mechanism for managing group membership in a distributed system.
+ * Provides a mechanism for managing group membership and remote scheduling and execution.
  * <p>
  * The distributed membership group resource facilitates managing group membership within the Atomix cluster.
  * Each instance of a {@code DistributedMembershipGroup} resource represents a single {@link GroupMember}.

coordination/src/main/java/io/atomix/coordination/DistributedMessageBus.java

@@ -87,6 +87,22 @@ protected Class<? extends StateMachine> stateMachine() {
    * Opens the message bus.
    * <p>
    * When the message bus is opened, this instance will bind to the provided {@link Address}.
+   * <p>
+   * This method returns a {@link 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 {@link CompletableFuture#join()} method to block the calling thread:
+   * <pre>
+   *   {@code
+   *   bus.open(new Address("123.456.789.0", 5000)).join();
+   *   }
+   * </pre>
+   * 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:
+   * <pre>
+   *   {@code
+   *   bus.open(new Address("123.456.789.0", 5000)).thenRun(() -> System.out.println("Message bus open!"));
+   *   }
+   * </pre>
    *
    * @param address The address on which to listen.
    * @return A completable future to be completed once the message bus is started.

coordination/src/main/java/io/atomix/coordination/DistributedTopic.java

@@ -15,6 +15,7 @@
  */
 package io.atomix.coordination;
 
+import io.atomix.Consistency;
 import io.atomix.DistributedResource;
 import io.atomix.catalyst.util.Listener;
 import io.atomix.coordination.state.TopicCommands;
@@ -28,7 +29,31 @@
 import java.util.function.Consumer;
 
 /**
- * Async topic.
+ * Facilitates persistent publish-subscribe messaging in the cluster.
+ * <p>
+ * 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 {@link #publish(Object) published} to a distributed topic
+ * the message will be persisted until it has been received by all instances {@link #subscribe(Consumer) listening}
+ * to the topic.
+ * <p>
+ * To create a topic resource, use the {@code DistributedTopic} class or constructor:
+ * <pre>
+ *   {@code
+ *   atomix.create("topic", DistributedTopic.class).thenAccept(topic -> {
+ *     ...
+ *   });
+ *   }
+ * </pre>
+ * The topic resource exposes two simple methods: {@link #publish(Object)} and {@link #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.
+ * <pre>
+ *   {@code
+ *   topic.subscribe(message -> System.out.println("Received: " + message));
+ *   topic.publish("Hello world!");
+ *   }
+ * </pre>
  *
  * @author <a href="http://github.com/kuujo">Jordan Halterman</a>
  */
@@ -53,6 +78,27 @@ protected void open(ResourceContext context) {
 
   /**
    * Publishes a message to the topic.
+   * <p>
+   * The message will be published according to the {@link #with(Consistency) configured consistency level}.
+   * Events published with {@link Consistency#ATOMIC} consistency are guaranteed to be received by all
+   * subscribers prior to the {@link CompletableFuture} returned by this method being completed. For all other
+   * consistency levels, messages will be received by subscribers asynchronously.
+   * <p>
+   * This method returns a {@link 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 {@link CompletableFuture#join()} method to block the calling thread:
+   * <pre>
+   *   {@code
+   *   topic.publish("Hello world!").join();
+   *   }
+   * </pre>
+   * 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:
+   * <pre>
+   *   {@code
+   *   topic.publish("Hello world!").thenRun(() -> System.out.println("Published to topic: " + topic.key()));
+   *   }
+   * </pre>
    *
    * @param message The message to publish.
    * @return A completable future to be completed once the message has been published.
@@ -64,12 +110,37 @@ public CompletableFuture<Void> publish(T message) {
   }
 
   /**
-   * Sets a message listener on the topic.
+   * Subscribes to messages from the topic.
+   * <p>
+   * Once the returned {@link 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 {@link Consumer} will always be executed on the
+   * same thread.
+   * <p>
+   * This method returns a {@link 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 {@link CompletableFuture#join()} method to block the calling thread:
+   * <pre>
+   *   {@code
+   *   topic.subscribe(message -> {
+   *     ...
+   *   }).join();
+   *   }
+   * </pre>
+   * 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:
+   * <pre>
+   *   {@code
+   *   topic.subscribe(message -> {
+   *     ...
+   *   }).thenRun(() -> System.out.println("Subscribed to " + topic.key()));
+   *   }
+   * </pre>
    *
    * @param listener The message listener.
    * @return The listener context.
    */
-  public CompletableFuture<Listener<T>> onMessage(Consumer<T> listener) {
+  public CompletableFuture<Listener<T>> subscribe(Consumer<T> listener) {
     if (!listeners.isEmpty()) {
       listeners.add(listener);
       return CompletableFuture.completedFuture(new TopicListener(listener));