Added to the Javadoc.

git-svn-id: https://svn.apache.org/repos/asf/incubator/qpid/branches/M2@537782 13f79535-47bb-0310-9956-ffa450edef68

9 files changed, 290 insertions, 68 deletions

diff --git a/java/common/src/main/java/org/apache/qpid/protocol/AMQConstant.java b/java/common/src/main/java/org/apache/qpid/protocol/AMQConstant.java
index 379f7feb4f..fa75bd5fb3 100644
--- a/java/common/src/main/java/org/apache/qpid/protocol/AMQConstant.java
+++ b/java/common/src/main/java/org/apache/qpid/protocol/AMQConstant.java
@@ -7,9 +7,9 @@
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
  * with the License.  You may obtain a copy of the License at
- * 
+ *
  *   http://www.apache.org/licenses/LICENSE-2.0
- * 
+ *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
@@ -25,87 +25,165 @@ import java.util.Map;
 
 import org.apache.qpid.framing.AMQShortString;
 
+/**
+ * Defines constants for AMQP codes and also acts as a factory for creating such constants from the raw codes. Each
+ * constant also defines a short human readable description of the constant.
+ *
+ * @todo Why would a constant be defined that is not in the map? Seems more natural that getConstant should raise an
+ *       exception for an unknown constant. Or else provide an explanation of why this is so. Also their is no way for
+ *       callers to determine the unknown status of a code except by comparing its name to "unknown code", which would
+ *       seem to render this scheme a little bit pointless?
+ *
+ * @todo Java has a nice enum construct for doing this sort of thing. Maybe this is done in the old style for Java 1.4
+ *       backward compatability? Now that is handled through retrotranslater it may be time to use enum.
+ *
+ * <p/><tabld id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Define the set of AMQP status codes.
+ * <tr><td> Provide a factory to lookup constants by their code.
+ * <tr><td>
+ */
 public final class AMQConstant
 {
-    private int _code;
-
-    private AMQShortString _name;
-
+    /** Defines a map from codes to constants. */
     private static Map _codeMap = new HashMap();
 
-    private AMQConstant(int code, String name, boolean map)
-    {
-        _code = code;
-        _name = new AMQShortString(name);
-        if (map)
-        {
-            _codeMap.put(new Integer(code), this);
-        }
-    }
-
-    public String toString()
-    {
-        return _code + ": " + _name;
-    }
-
-    public int getCode()
-    {
-        return _code;
-    }
-
-    public AMQShortString getName()
-    {
-        return _name;
-    }
-
-    public static final AMQConstant FRAME_MIN_SIZE = new AMQConstant(4096, "frame min size", true);
+    /** Indicates that the method completed successfully. */
+    public static final AMQConstant REPLY_SUCCESS = new AMQConstant(200, "reply success", true);
 
     public static final AMQConstant FRAME_END = new AMQConstant(206, "frame end", true);
 
-    public static final AMQConstant REPLY_SUCCESS = new AMQConstant(200, "reply success", true);
-
+    /**
+     * The client asked for a specific message that is no longer available. The message was delivered to another
+     * client, or was purged from the queue for some other reason.
+     */
     public static final AMQConstant NOT_DELIVERED = new AMQConstant(310, "not delivered", true);
 
+    /**
+     * The client attempted to transfer content larger than the server could accept at the present time.  The client
+     * may retry at a later time.
+     */
     public static final AMQConstant MESSAGE_TOO_LARGE = new AMQConstant(311, "message too large", true);
 
+    /**
+     * When the exchange cannot route the result of a .Publish, most likely due to an invalid routing key. Only when
+     * the mandatory flag is set.
+     */
     public static final AMQConstant NO_ROUTE = new AMQConstant(312, "no route", true);
 
+    /**
+     * When the exchange cannot deliver to a consumer when the immediate flag is set. As a result of pending data on
+     * the queue or the absence of any consumers of the queue.
+     */
     public static final AMQConstant NO_CONSUMERS = new AMQConstant(313, "no consumers", true);
 
+    /**
+     * An operator intervened to close the connection for some reason. The client may retry at some later date.
+     */
     public static final AMQConstant CONTEXT_IN_USE = new AMQConstant(320, "context in use", true);
 
+    /** The client tried to work with an unknown virtual host or cluster. */
     public static final AMQConstant INVALID_PATH = new AMQConstant(402, "invalid path", true);
 
+    /** The client attempted to work with a server entity to which it has no access due to security settings. */
     public static final AMQConstant ACCESS_REFUSED = new AMQConstant(403, "access refused", true);
 
+    /** The client attempted to work with a server entity that does not exist. */
     public static final AMQConstant NOT_FOUND = new AMQConstant(404, "not found", true);
 
+    /**
+     * The client attempted to work with a server entity to which it has no access because another client is
+     * working with it.
+     */
     public static final AMQConstant ALREADY_EXISTS = new AMQConstant(405, "Already exists", true);
 
+    /** The client requested a method that was not allowed because some precondition failed. */
     public static final AMQConstant IN_USE = new AMQConstant(406, "In use", true);
 
     public static final AMQConstant INVALID_ROUTING_KEY = new AMQConstant(407, "routing key invalid", true);
 
     public static final AMQConstant REQUEST_TIMEOUT = new AMQConstant(408, "Request Timeout", true);
 
-    public static final AMQConstant INVALID_ARGUMENT = new AMQConstant(409, "argument invalid", true);        
+    public static final AMQConstant INVALID_ARGUMENT = new AMQConstant(409, "argument invalid", true);
 
+    /**
+     * The client sent a malformed frame that the server could not decode. This strongly implies a programming error
+     * in the client.
+     */
     public static final AMQConstant FRAME_ERROR = new AMQConstant(501, "frame error", true);
 
+    /**
+     * The client sent a frame that contained illegal values for one or more fields. This strongly implies a
+     * programming error in the client.
+     */
     public static final AMQConstant SYNTAX_ERROR = new AMQConstant(502, "syntax error", true);
 
+    /**
+     * The client sent an invalid sequence of frames, attempting to perform an operation that was considered invalid
+     * by the server. This usually implies a programming error in the client.
+     */
     public static final AMQConstant COMMAND_INVALID = new AMQConstant(503, "command invalid", true);
 
+    /**
+     * The client attempted to work with a channel that had not been correctly opened. This most likely indicates a
+     * fault in the client layer.
+     */
     public static final AMQConstant CHANNEL_ERROR = new AMQConstant(504, "channel error", true);
 
+    /**
+     * The server could not complete the method because it lacked sufficient resources. This may be due to the client
+     * creating too many of some type of entity.
+     */
     public static final AMQConstant RESOURCE_ERROR = new AMQConstant(506, "resource error", true);
 
+    /**
+     * The client tried to work with some entity in a manner that is prohibited by the server, due to security settings
+     * or by some other criteria.
+     */
     public static final AMQConstant NOT_ALLOWED = new AMQConstant(530, "not allowed", true);
 
+    /** The client tried to use functionality that is not implemented in the server. */
     public static final AMQConstant NOT_IMPLEMENTED = new AMQConstant(540, "not implemented", true);
 
+    /**
+     * The server could not complete the method because of an internal error. The server may require intervention by
+     * an operator in order to resume normal operations.
+     */
     public static final AMQConstant INTERNAL_ERROR = new AMQConstant(541, "internal error", true);
 
+    public static final AMQConstant FRAME_MIN_SIZE = new AMQConstant(4096, "frame min size", true);
+
+    /** The AMQP status code. */
+    private int _code;
+
+    /** A short description of the status code. */
+    private AMQShortString _name;
+
+    /**
+     * Creates a new AMQP status code.
+     *
+     * @param code The code.
+     * @param name A short description of the code.
+     * @param map  <tt>true</tt> to register the code as a known code, <tt>false</tt> otherwise.
+     */
+    private AMQConstant(int code, String name, boolean map)
+    {
+        _code = code;
+        _name = new AMQShortString(name);
+        if (map)
+        {
+            _codeMap.put(new Integer(code), this);
+        }
+    }
+
+    /**
+     * Creates a constant for a status code by looking up the code in the map of known codes. If the code is not known
+     * a constant is still created for it, but it is marked as unknown.
+     *
+     * @param code The AMQP status code.
+     *
+     * @return The AMQP status code encapsulated as a constant.
+     */
     public static AMQConstant getConstant(int code)
     {
         AMQConstant c = (AMQConstant) _codeMap.get(new Integer(code));
@@ -113,6 +191,37 @@ public final class AMQConstant
         {
             c = new AMQConstant(code, "unknown code", false);
         }
+
         return c;
     }
+
+    /**
+     * Gets the underlying AMQP status code.
+     *
+     * @return The AMQP status code.
+     */
+    public int getCode()
+    {
+        return _code;
+    }
+
+    /**
+     * Gets a short description of the status code.
+     *
+     * @return A short description of the status code.
+     */
+    public AMQShortString getName()
+    {
+        return _name;
+    }
+
+    /**
+     * Renders the constant as a string, mainly for debugging purposes.
+     *
+     * @return The status code and its description.
+     */
+    public String toString()
+    {
+        return _code + ": " + _name;
+    }
 }
diff --git a/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodEvent.java b/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodEvent.java
index ab36041cb8..fd6907a152 100644
--- a/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodEvent.java
+++ b/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodEvent.java
@@ -7,9 +7,9 @@
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
  * with the License.  You may obtain a copy of the License at
- * 
+ *
  *   http://www.apache.org/licenses/LICENSE-2.0
- * 
+ *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
@@ -23,43 +23,73 @@ package org.apache.qpid.protocol;
 import org.apache.qpid.framing.AMQMethodBody;
 
 /**
- * An event that is passed to AMQMethodListeners describing a particular method.
- * It supplies the:
- * <ul><li>channel id</li>
+ * AMQMethodEvent encapsulates an AMQP method call, and the channel on which that method call occurred.
+ *
+ * <p/>Supplies the:
+ * <ul>
+ * <li>channel id</li>
  * <li>protocol method</li>
- * to listeners. This means that listeners do not need to be stateful.
+ * </ul>
  *
- * In the StateAwareMethodListener, other useful objects such as the protocol session
- * are made available.
- * 
+ * <p/>As the event contains the context in which it occurred, event listeners do not need to be statefull.
+ * to listeners. Events are often handled by {@link AMQMethodListener}s.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Encapsulate an AMQP method call and the channel as the context for the method call.
+ * </table>
  */
 public class AMQMethodEvent<M extends AMQMethodBody>
 {
+    /** Holds the method call. */
     private final M _method;
 
+    /** Holds the channel handle for the method call. */
     private final int _channelId;
 
+    /**
+     * Creates a method event to encasulate a method call and channel.
+     *
+     * @param channelId The channel on which the method call occurred.
+     * @param method    The method call.
+     */
     public AMQMethodEvent(int channelId, M method)
     {
         _channelId = channelId;
         _method = method;
     }
 
+    /**
+     * Gets the method call.
+     *
+     * @return The method call.
+     */
     public M getMethod()
     {
         return _method;
     }
 
+    /**
+     * Gets the channel handle for the method call.
+     *
+     * @return The channel handle for the method call.
+     */
     public int getChannelId()
     {
         return _channelId;
     }
 
+    /**
+     * Prints the method call as a string, mainly for debugging purposes.
+     *
+     * @return The method call as a string, mainly for debugging purposes.
+     */
     public String toString()
     {
         StringBuilder buf = new StringBuilder("Method event: ");
         buf.append("\nChannel id: ").append(_channelId);
         buf.append("\nMethod: ").append(_method);
+
         return buf.toString();
     }
 }
diff --git a/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodListener.java b/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodListener.java
index 85bbe50b11..808272e9ec 100644
--- a/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodListener.java
+++ b/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodListener.java
@@ -7,9 +7,9 @@
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
  * with the License.  You may obtain a copy of the License at
- * 
+ *
  *   http://www.apache.org/licenses/LICENSE-2.0
- * 
+ *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
@@ -20,31 +20,52 @@
  */
 package org.apache.qpid.protocol;
 
-import org.apache.qpid.AMQException;
 import org.apache.qpid.framing.AMQMethodBody;
 
 /**
- * Interface that allows classes to register for interest in protocol method frames.
- * 
+ * AMQMethodListener is a listener that receives notifications of AMQP methods. The methods are packaged as events in
+ * {@link AMQMethodEvent}.
+ *
+ * <p/>An event listener may be associated with a particular context, usually an AMQP channel, and in addition to
+ * receiving method events will be notified of errors on that context. This enables listeners to perform any clean
+ * up that they need to do before the context is closed.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities
+ * <tr><td> Accept notification of AMQP method events. <td> {@link AMQMethodEvent}
+ * <tr><td> Accept notification of errors on the event context.
+ * </table>
+ *
+ * @todo Document why the exception is passed to the error method. Is it so that the exception can be passed
+ *       from the event handling thread to another thread and rethown from there? It is unusual to pass exceptions as
+ *       method arguments, because they have their own mechanism for propagating through the call stack, so some
+ *       explanation ought to be provided.
  */
 public interface AMQMethodListener
 {
     /**
-     * Invoked when a method frame has been received
-     * @param evt the event that contains the method and channel
-     * @param protocolSession the protocol session associated with the event
-     * @return true if the handler has processed the method frame, false otherwise. Note
-     * that this does not prohibit the method event being delivered to subsequent listeners
-     * but can be used to determine if nobody has dealt with an incoming method frame.
-     * @throws AMQException if an error has occurred. This exception will be delivered
-     * to all registered listeners using the error() method (see below) allowing them to
-     * perform cleanup if necessary.
+     * Notifies the listener that an AMQP method event has occurred.
+     *
+     * @param evt The AMQP method event (contains the method and channel).
+     *
+     * @return <tt>true</tt> if the handler processes the method frame, <tt>false<tt> otherwise. Note that this does
+     *         not prohibit the method event being delivered to subsequent listeners but can be used to determine if
+     *         nobody has dealt with an incoming method frame.
+     *
+     * @throws Exception if an error has occurred. This exception may be delivered to all registered listeners using
+     *         the error() method (see below) allowing them to perform cleanup if necessary.
+     *
+     * @todo Consider narrowing the exception.
      */
     <B extends AMQMethodBody> boolean methodReceived(AMQMethodEvent<B> evt) throws Exception;
 
     /**
-     * Callback when an error has occurred. Allows listeners to clean up.
-     * @param e
+     * Notifies the listener of an error on the event context to which it is listening. The listener should perform
+     * any necessary clean-up for the context.
+     *
+     * @param e The underlying exception that is the source of the error.
+     *
+     * @todo Consider narrowing the exception, or wrapping it.
      */
     void error(Exception e);
 }
diff --git a/java/common/src/main/java/org/apache/qpid/protocol/AMQProtocolWriter.java b/java/common/src/main/java/org/apache/qpid/protocol/AMQProtocolWriter.java
index bc06fc3e6f..65884e4950 100644
--- a/java/common/src/main/java/org/apache/qpid/protocol/AMQProtocolWriter.java
+++ b/java/common/src/main/java/org/apache/qpid/protocol/AMQProtocolWriter.java
@@ -22,11 +22,22 @@ package org.apache.qpid.protocol;
 
 import org.apache.qpid.framing.AMQDataBlock;
 
+/**
+ * AMQProtocolWriter provides a method to write a frame of data 'to the wire', in the context of the object
+ * that implements the method, usually some sort of session. The block of data, encapsulated by {@link AMQDataBlock},
+ * will be encoded as it is written.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities
+ * <tr><td> Write an encoded block of data to the write, in the context of a session.
+ * </table>
+ */
 public interface AMQProtocolWriter
 {
     /**
-     * Write a datablock, encoding where necessary (e.g. into a sequence of bytes)
-     * @param frame the frame to be encoded and written
+     * Writes a frame to the wire, encoding it as necessary, for example, into a sequence of bytes.
+     *
+     * @param frame The frame to be encoded and written.
      */
-       public void writeFrame(AMQDataBlock frame);
+    public void writeFrame(AMQDataBlock frame);
 }
diff --git a/java/common/src/main/java/org/apache/qpid/protocol/AMQVersionAwareProtocolSession.java b/java/common/src/main/java/org/apache/qpid/protocol/AMQVersionAwareProtocolSession.java
index b57c26e496..7c1d6fdaa0 100644
--- a/java/common/src/main/java/org/apache/qpid/protocol/AMQVersionAwareProtocolSession.java
+++ b/java/common/src/main/java/org/apache/qpid/protocol/AMQVersionAwareProtocolSession.java
@@ -22,7 +22,25 @@ package org.apache.qpid.protocol;
 

 import org.apache.qpid.framing.VersionSpecificRegistry;

 

+/**

+ * AMQVersionAwareProtocolSession is implemented by all AMQP session classes, that need to provide an awareness to

+ * callers of the version of the AMQP protocol that they are able to work with.

+ *

+ * <p/><table id="crc"><caption>CRC Card</caption>

+ * <tr><th> Responsibilities

+ * <tr><td> Provide the method registry for a specific version of the AMQP.

+ * </table>

+ *

+ * @todo Why is this a seperate interface to {@link ProtocolVersionAware}, could they be combined into a single

+ *       interface and one of them eliminated? Move getRegistry method to ProtocolVersionAware, make the sessions

+ *       implement AMQProtocolWriter directly and drop this interface.

+ */

 public interface AMQVersionAwareProtocolSession extends AMQProtocolWriter, ProtocolVersionAware

 {

+    /**

+     * Gets the method registry for a specific version of the AMQP.

+     *

+     * @return The method registry for a specific version of the AMQP.

+     */

     public VersionSpecificRegistry getRegistry();

 }

diff --git a/java/common/src/main/java/org/apache/qpid/protocol/ProtocolVersionAware.java b/java/common/src/main/java/org/apache/qpid/protocol/ProtocolVersionAware.java
index 64db953bc2..60a7f30185 100644
--- a/java/common/src/main/java/org/apache/qpid/protocol/ProtocolVersionAware.java
+++ b/java/common/src/main/java/org/apache/qpid/protocol/ProtocolVersionAware.java
@@ -20,9 +20,28 @@
  */

 package org.apache.qpid.protocol;

 

+/**

+ * ProtocolVersionAware is implemented by all AMQP handling classes, that need to provide an awareness to callers of

+ * the version of the AMQP protocol that they are able to handle.

+ *

+ * <p/><table id="crc"><caption>CRC Card</caption>

+ * <tr><th> Responsibilities

+ * <tr><td> Report the major and minor AMQP version handled.

+ * </table>

+ */

 public interface ProtocolVersionAware

 {

+    /**

+     * Reports the AMQP minor version, that the implementer can handle.

+     *

+     * @return The AMQP minor version.

+     */

     public byte getProtocolMinorVersion();

 

+    /**

+     * Reports the AMQP major version, that the implementer can handle.

+     *

+     * @return The AMQP major version.

+     */

     public byte getProtocolMajorVersion();

 }

diff --git a/java/common/src/main/java/org/apache/qpid/util/MessageQueue.java b/java/common/src/main/java/org/apache/qpid/util/MessageQueue.java
index 9cf3319374..b5efaa61b6 100644
--- a/java/common/src/main/java/org/apache/qpid/util/MessageQueue.java
+++ b/java/common/src/main/java/org/apache/qpid/util/MessageQueue.java
@@ -14,17 +14,30 @@
  *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  *  KIND, either express or implied.  See the License for the
  *  specific language governing permissions and limitations
- *  under the License.    
+ *  under the License.
+ *
  *
- * 
  */
 package org.apache.qpid.util;
 
 import java.util.Queue;
 
+/**
+ * Defines a queue that has a push operation to add an element to the head of the queue.
+ *
+ * @todo Seems like this may be pointless, the implementation uses this method to increment the message count
+ *       then calls offer. Why not simply override offer and drop this interface?
+ */
 public interface MessageQueue<E> extends Queue<E>
 {
-
+    /**
+     * Inserts the specified element into this queue, if possible. When using queues that may impose insertion
+     * restrictions (for example capacity bounds), method offer is generally preferable to method Collection.add(E),
+     * which can fail to insert an element only by throwing an exception.
+     *
+     * @param o The element to insert.
+     *
+     * @return <tt>true</tt> if it was possible to add the element to this queue, else <tt>false</tt>
+     */
     boolean pushHead(E o);
-
 }
diff --git a/java/integrationtests/src/main/java/org/apache/qpid/interop/coordinator/CoordinatingTestCase.java b/java/integrationtests/src/main/java/org/apache/qpid/interop/coordinator/CoordinatingTestCase.java
index ef69d14be8..3003c00ca5 100644
--- a/java/integrationtests/src/main/java/org/apache/qpid/interop/coordinator/CoordinatingTestCase.java
+++ b/java/integrationtests/src/main/java/org/apache/qpid/interop/coordinator/CoordinatingTestCase.java
@@ -35,7 +35,7 @@ import org.apache.log4j.Logger;
 import org.apache.qpid.util.ConversationFactory;

 

 /**

- * An CoordinatingTestCase is a JUnit test case extension that knows how to coordinate test clients that take part in a

+ * A CoordinatingTestCase is a JUnit test case extension that knows how to coordinate test clients that take part in a

  * test case as defined in the interop testing specification

  * (http://cwiki.apache.org/confluence/display/qpid/Interop+Testing+Specification).

  *

diff --git a/java/integrationtests/src/main/java/org/apache/qpid/interop/coordinator/Coordinator.java b/java/integrationtests/src/main/java/org/apache/qpid/interop/coordinator/Coordinator.java
index de5faeac0f..2f9937cae9 100644
--- a/java/integrationtests/src/main/java/org/apache/qpid/interop/coordinator/Coordinator.java
+++ b/java/integrationtests/src/main/java/org/apache/qpid/interop/coordinator/Coordinator.java
@@ -134,6 +134,7 @@ public class Coordinator extends TKTestRunner
             String brokerUrl = options.getProperty("b");

             String virtualHost = options.getProperty("h");

             reportDir = options.getProperty("o");

+            reportDir = (reportDir == null) ? "." : reportDir;

 

             // Scan for available test cases using a classpath scanner.

             Collection<Class<? extends CoordinatingTestCase>> testCaseClasses =