panchenko
diff --git a/‎src/com/rabbitmq/client/Connection.java
Lines changed: 3 additions & 0 deletions b/‎src/com/rabbitmq/client/Connection.java
Lines changed: 3 additions & 0 deletions
diff --git a/‎src/com/rabbitmq/client/ConnectionFactory.java
Lines changed: 34 additions & 6 deletions b/‎src/com/rabbitmq/client/ConnectionFactory.java
Lines changed: 34 additions & 6 deletions
diff --git a/‎src/com/rabbitmq/client/Recoverable.java
Lines changed: 7 additions & 0 deletions b/‎src/com/rabbitmq/client/Recoverable.java
Lines changed: 7 additions & 0 deletions
@@ -101,6 +101,9 @@ public interface Connection extends ShutdownNotifier { // rename to AMQPConnecti
 
     /**
      * Create a new channel, using an internally allocated channel number.
+     * If <a href="http://www.rabbitmq.com/api-guide.html#recovery">automatic connection recovery</a>
+     * is enabled, the channel returned by this method will be {@link Recoverable}.
+     *
      * @return a new channel descriptor, or null if none is available
      * @throws IOException if an I/O problem is encountered
      */
 
@@ -530,16 +530,19 @@ public void useSslProtocol(SSLContext context)
     }
 
     /**
-     * Returns true if automatic connection recovery is enabled, false otherwise
+     * Returns true if <a href="http://www.rabbitmq.com/api-guide.html#recovery">automatic connection recovery</a>
+     * is enabled, false otherwise
      * @return true if automatic connection recovery is enabled, false otherwise
+     * @see <a href="http://www.rabbitmq.com/api-guide.html#recovery">Automatic Recovery</a>
      */
     public boolean isAutomaticRecoveryEnabled() {
         return automaticRecovery;
     }
 
     /**
-     * Enables or disables automatic connection recovery
+     * Enables or disables <a href="http://www.rabbitmq.com/api-guide.html#recovery">automatic connection recovery</a>.
      * @param automaticRecovery if true, enables connection recovery
+     * @see <a href="http://www.rabbitmq.com/api-guide.html#recovery">Automatic Recovery</a>
      */
     public void setAutomaticRecoveryEnabled(boolean automaticRecovery) {
         this.automaticRecovery = automaticRecovery;
@@ -548,6 +551,7 @@ public void setAutomaticRecoveryEnabled(boolean automaticRecovery) {
     /**
      * Returns true if topology recovery is enabled, false otherwise
      * @return true if topology recovery is enabled, false otherwise
+     * @see <a href="http://www.rabbitmq.com/api-guide.html#recovery">Automatic Recovery</a>
      */
     @SuppressWarnings("unused")
     public boolean isTopologyRecoveryEnabled() {
@@ -557,6 +561,7 @@ public boolean isTopologyRecoveryEnabled() {
     /**
      * Enables or disables topology recovery
      * @param topologyRecovery if true, enables topology recovery
+     * @see <a href="http://www.rabbitmq.com/api-guide.html#recovery">Automatic Recovery</a>
      */
     public void setTopologyRecoveryEnabled(boolean topologyRecovery) {
         this.topologyRecovery = topologyRecovery;
@@ -567,7 +572,13 @@ protected FrameHandlerFactory createFrameHandlerFactory() throws IOException {
     }
 
     /**
-     * Create a new broker connection
+     * Create a new broker connection, picking the first available address from
+     * the list.
+     *
+     * If <a href="http://www.rabbitmq.com/api-guide.html#recovery">automatic connection recovery</a>
+     * is enabled, the connection returned by this method will be {@link Recoverable}. Future
+     * reconnection attempts will pick a random accessible address from the provided list.
+     *
      * @param addrs an array of known broker addresses (hostname/port pairs) to try in order
      * @return an interface to the connection
      * @throws IOException if it encounters a problem
@@ -577,11 +588,18 @@ public Connection newConnection(Address[] addrs) throws IOException {
     }
 
     /**
-     * Create a new broker connection
+     * Create a new broker connection, picking the first available address from
+     * the list.
+     *
+     * If <a href="http://www.rabbitmq.com/api-guide.html#recovery">automatic connection recovery</a>
+     * is enabled, the connection returned by this method will be {@link Recoverable}. Future
+     * reconnection attempts will pick a random accessible address from the provided list.
+     *
      * @param executor thread execution service for consumers on the connection
      * @param addrs an array of known broker addresses (hostname/port pairs) to try in order
      * @return an interface to the connection
      * @throws java.io.IOException if it encounters a problem
+     * @see <a href="http://www.rabbitmq.com/api-guide.html#recovery">Automatic Recovery</a>
      */
     public Connection newConnection(ExecutorService executor, Address[] addrs)
         throws IOException
@@ -617,7 +635,12 @@ public ConnectionParams params(ExecutorService executor) {
     }
 
     /**
-     * Create a new broker connection
+     * Create a new broker connection.
+     *
+     * If <a href="http://www.rabbitmq.com/api-guide.html#recovery">automatic connection recovery</a>
+     * is enabled, the connection returned by this method will be {@link Recoverable}. Reconnection
+     * attempts will always use the address configured on {@link ConnectionFactory}.
+     *
      * @return an interface to the connection
      * @throws IOException if it encounters a problem
      */
@@ -628,7 +651,12 @@ public Connection newConnection() throws IOException {
     }
 
     /**
-     * Create a new broker connection
+     * Create a new broker connection.
+     *
+     * If <a href="http://www.rabbitmq.com/api-guide.html#recovery">automatic connection recovery</a>
+     * is enabled, the connection returned by this method will be {@link Recoverable}. Reconnection
+     * attempts will always use the address configured on {@link ConnectionFactory}.
+     *
      * @param executor thread execution service for consumers on the connection
      * @return an interface to the connection
      * @throws IOException if it encounters a problem
 
@@ -3,6 +3,13 @@
 /**
  * Provides a way to register (network, AMQP 0-9-1) connection recovery
  * callbacks.
+ *
+ * When connection recovery is enabled via {@link ConnectionFactory},
+ * {@link ConnectionFactory#newConnection()} and {@link Connection#createChannel()}
+ * return {@link Recoverable} connections and channels.
+ *
+ * @see com.rabbitmq.client.impl.recovery.AutorecoveringConnection
+ * @see com.rabbitmq.client.impl.recovery.AutorecoveringChannel
  */
 public interface Recoverable {
     /**