Merge branch 'stable'

Author: michaelklishin

src/com/rabbitmq/client/Channel.java

@@ -86,9 +86,9 @@ public interface Channel extends ShutdownNotifier {
     void close(int closeCode, String closeMessage) throws IOException, TimeoutException;
 
     /**
-     * Indicates whether the server has asked this client to stop
-     * sending content-bearing commands (such as basic.publish) by
-     * issueing a channel.flow{active=false}.
+     * Deprecated, superseded by TCP back pressure.
+     * @deprecated
+     * @see <a href="http://www.rabbitmq.com/alarms.html">Resource-driven alarms</a>
      */
     boolean flowBlocked();
 
@@ -130,12 +130,18 @@ public interface Channel extends ShutdownNotifier {
 
     /**
      * Add a {@link FlowListener}.
+     * Deprecated, superseded by TCP back pressure.
+     * @deprecated
+     * @see <a href="http://www.rabbitmq.com/alarms.html">Resource-driven alarms</a>
      * @param listener the listener to add
      */
     void addFlowListener(FlowListener listener);
 
     /**
      * Remove a {@link FlowListener}.
+     * Deprecated, superseded by TCP back pressure.
+     * @deprecated
+     * @see <a href="http://www.rabbitmq.com/alarms.html">Resource-driven alarms</a>
      * @param listener the listener to remove
      * @return <code><b>true</b></code> if the listener was found and removed,
      * <code><b>false</b></code> otherwise
@@ -144,6 +150,9 @@ public interface Channel extends ShutdownNotifier {
 
     /**
      * Remove all {@link FlowListener}s.
+     * Deprecated, superseded by TCP back pressure.
+     * @deprecated
+     * @see <a href="http://www.rabbitmq.com/alarms.html">Resource-driven alarms</a>
      */
     void clearFlowListeners();
 

src/com/rabbitmq/client/Connection.java

@@ -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
      */

src/com/rabbitmq/client/ConnectionFactory.java

@@ -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

src/com/rabbitmq/client/Recoverable.java

@@ -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 {
     /**