Add Javadoc

Author: Steve Powell

src/com/rabbitmq/client/impl/AMQConnection.java

@@ -175,7 +175,7 @@ public Map<String, Object> getServerProperties() {
      * @param password for <code><b>username</b></code>
      * @param frameHandler for sending and receiving frames on this connection
      * @param executor thread pool service for consumer threads for channels on this connection
-     * @param virtualHost
+     * @param virtualHost virtual host of this connection
      * @param clientProperties client info used in negotiating with the server
      * @param requestedFrameMax max size of frame offered
      * @param requestedChannelMax max number of channels offered
@@ -211,7 +211,7 @@ public AMQConnection(String username,
      * @param password for <code><b>username</b></code>
      * @param frameHandler for sending and receiving frames on this connection
      * @param executor thread pool service for consumer threads for channels on this connection
-     * @param virtualHost
+     * @param virtualHost virtual host of this connection
      * @param clientProperties client info used in negotiating with the server
      * @param requestedFrameMax max size of frame offered
      * @param requestedChannelMax max number of channels offered
@@ -623,10 +623,14 @@ public SocketCloseWait(ShutdownSignalException sse) {
     }
 
     /**
-     * Protected API - causes all attached channels to terminate with
-     * a ShutdownSignal built from the argument, and stops this
-     * connection from accepting further work from the application.
-     *
+     * Protected API - causes all attached channels to terminate (shutdown) with a ShutdownSignal
+     * built from the argument, and stops this connection from accepting further work from the
+     * application. {@link com.rabbitmq.client.ShutdownListener ShutdownListener}s for the
+     * connection are notified when the main loop terminates.
+     * @param reason object being shutdown
+     * @param initiatedByApplication true if caused by a client command
+     * @param cause trigger exception which caused shutdown
+     * @param notifyRpc true if outstanding rpc should be informed of shutdown
      * @return a shutdown signal built using the given arguments
      */
     public ShutdownSignalException shutdown(Object reason,
@@ -722,6 +726,7 @@ public void close(int closeCode,
         close(closeCode, closeMessage, initiatedByApplication, cause, -1, false);
     }
 
+    // TODO: Make this private
     /**
      * Protected API - Close this connection with the given code, message, source
      * and timeout value for all the close operations to complete.

src/com/rabbitmq/client/impl/ChannelManager.java

@@ -30,7 +30,6 @@
 /**
  * Manages a set of channels, indexed by channel number (<code><b>1.._channelMax</b></code>).
  */
-
 public final class ChannelManager {
     private static final int SHUTDOWN_TIMEOUT_SECONDS = 10;
 
@@ -77,6 +76,10 @@ public ChannelN getChannel(int channelNumber) {
         }
     }
 
+    /**
+     * Handle shutdown. All the managed {@link com.rabbitmq.client.Channel Channel}s are shutdown.
+     * @param signal reason for shutdown
+     */
     public void handleSignal(ShutdownSignalException signal) {
         Set<ChannelN> channels;
         synchronized(this.monitor) {

src/com/rabbitmq/client/impl/ShutdownNotifierComponent.java

@@ -24,6 +24,11 @@
 import com.rabbitmq.client.ShutdownNotifier;
 import com.rabbitmq.client.ShutdownSignalException;
 
+/**
+ * A class that manages {@link ShutdownListener}s and remembers the reason for a shutdown. Both
+ * {@link com.rabbitmq.client.Channel Channel}s and {@link com.rabbitmq.client.Connection
+ * Connection}s have shutdown listeners.
+ */
 public class ShutdownNotifierComponent implements ShutdownNotifier {
 
     /** Monitor for shutdown listeners and shutdownCause */
@@ -87,6 +92,11 @@ public boolean isOpen() {
         }
     }
 
+    /**
+     * Internal: this is the means of registering shutdown.
+     * @param sse the reason for the shutdown
+     * @return <code>true</code> if the component is open; <code>false</code> otherwise.
+     */
     public boolean setShutdownCauseIfOpen(ShutdownSignalException sse) {
         synchronized (this.monitor) {
             if (isOpen()) {

test/src/com/rabbitmq/client/test/CloseInMainLoop.java

@@ -32,7 +32,7 @@ public class CloseInMainLoop extends BrokerTestCase{
 
   class SpecialConnection extends AMQConnection{
     private AtomicBoolean validShutdown = new AtomicBoolean(false);
-    
+
     public boolean hadValidShutdown(){
       if(isOpen()) throw new IllegalStateException("hadValidShutdown called while connection is still open");
       return validShutdown.get();
@@ -61,6 +61,7 @@ public void handleConsumerException(Channel channel,
                                                     String consumerTag,
                                                     String methodName) {
                     try {
+                        // TODO: change this to call 4-parameter close and make 6-parm one private
                       ((AMQConnection) channel.getConnection())
                           .close(AMQP.INTERNAL_ERROR,
                                  "Internal error in Consumer " + consumerTag,