Document MasterSlave connection failure behavior #894

redis · Nov 7, 2018 · acb03f4 · acb03f4
1 parent e0433f4
commit acb03f4
Show file tree

Hide file tree

Showing 2 changed files with 15 additions and 7 deletions.
diff --git a/src/main/java/io/lettuce/core/masterslave/Connections.java b/src/main/java/io/lettuce/core/masterslave/Connections.java
@@ -97,7 +97,7 @@ protected void onEmit(Emission<Connections> emission) {
         if (getExpectedCount() != 0 && this.connections.isEmpty() && !this.exceptions.isEmpty()) {
 
             RedisConnectionException collector = new RedisConnectionException(
-                    "Unable to establish a connection to Redis Cluster");
+                    "Unable to establish a connection to Redis Master/Slave");
             this.exceptions.forEach(collector::addSuppressed);
 
             emission.error(collector);

diff --git a/src/main/java/io/lettuce/core/masterslave/MasterSlave.java b/src/main/java/io/lettuce/core/masterslave/MasterSlave.java
@@ -45,14 +45,14 @@
  * StatefulRedisMasterSlaveConnection&lt;String, String&gt; connection = MasterSlave.connect(client,
  *         RedisURI.create(&quot;redis://localhost&quot;), StringCodec.UTF8);
  * // ...
- *
+ * 
  * connection.close();
  * client.shutdown();
  * </pre>
  *
  * </p>
  * <h3>Topology Discovery</h3>
- * <p>
+ * <p />
  * Master-Slave topologies are either static or semi-static. Redis Standalone instances with attached slaves provide no
  * failover/HA mechanism. Redis Sentinel managed instances are controlled by Redis Sentinel and allow failover (which include
  * master promotion). The {@link MasterSlave} API supports both mechanisms. The topology is provided by a
@@ -70,14 +70,22 @@
  * {@code SENTINEL MASTER} and {@code SENTINEL SLAVES} output. Master/Slave failover is handled by lettuce.</li>
  * </ul>
  *
- * <p>
- * Topology Updates
- * </p>
+ * <h3>Topology Updates</h4>
  * <ul>
  * <li>Standalone Master/Slave: Performs a one-time topology lookup which remains static afterward</li>
  * <li>Redis Sentinel: Subscribes to all Sentinels and listens for Pub/Sub messages to trigger topology refreshing</li>
  * </ul>
- * </p>
+ * 
+ * <h3>Connection Fault-Tolerance</h3>
+ * Connecting to Master/Slave bears the possibility that individual nodes are not reachable. {@link MasterSlave} can still
+ * connect to a partially-available set of nodes.
+ * 
+ * <ul>
+ * <li>Redis Sentinel: At least one Sentinel must be reachable, the masterId must be registered and at least one host must be
+ * available (master or slave). Allows for runtime-recovery based on Sentinel Events.</li>
+ * <li>Static Setup (auto-discovery): The initial endpoint must be reachable. No recovery/reconfiguration during runtime.</li>
+ * <li>Static Setup (provided hosts): All endpoints must be reachable. No recovery/reconfiguration during runtime.</li>
+ * </ul>
  *
  * @author Mark Paluch
  * @since 4.1