merge bug20710 into v1_5

Author: Matthias Radestock

src/com/rabbitmq/client/GetResponse.java

@@ -47,7 +47,7 @@ public class GetResponse {
      * @param envelope the {@link Envelope}
      * @param props message properties
      * @param body the message body
-     * @param messageCount the number of messages in the response
+     * @param messageCount the server's most recent estimate of the number of messages remaining on the queue
      */
     public GetResponse(Envelope envelope, BasicProperties props, byte[] body, int messageCount)
     {
@@ -82,8 +82,20 @@ public byte[] getBody() {
     }
 
     /**
-     * Get the message count included in this response
-     * @return the message count
+     * Get the server's most recent estimate of the number of messages
+     * remaining on the queue. This number can only ever be a rough
+     * estimate, because of concurrent activity at the server and the
+     * delay between the server sending its estimate and the client
+     * receiving and processing the message containing the estimate.
+     *
+     * <p>According to the AMQP specification, this figure does not
+     * include the message being delivered. For example, this field
+     * will be zero in the simplest case of a single reader issuing a
+     * Basic.Get on a private queue holding a single message (the
+     * message being delivered in this GetResponse).
+     *
+     * @return an estimate of the number of messages remaining to be
+     * read from the queue
      */
     public int getMessageCount() {
         return messageCount;