More Javadocing.

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

4 files changed, 131 insertions, 18 deletions

diff --git a/java/common/src/main/java/org/apache/qpid/codec/AMQCodecFactory.java b/java/common/src/main/java/org/apache/qpid/codec/AMQCodecFactory.java
index d7f1edbc30..4e3a46eb90 100644
--- a/java/common/src/main/java/org/apache/qpid/codec/AMQCodecFactory.java
+++ b/java/common/src/main/java/org/apache/qpid/codec/AMQCodecFactory.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
@@ -24,28 +24,52 @@ import org.apache.mina.filter.codec.ProtocolCodecFactory;
 import org.apache.mina.filter.codec.ProtocolDecoder;
 import org.apache.mina.filter.codec.ProtocolEncoder;
 
+/**
+ * AMQCodecFactory is a Mina codec factory. It supplies the encoders and decoders need to read and write the bytes to
+ * the wire.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations.
+ * <tr><td> Supply the protocol encoder. <td> {@link AMQEncoder}
+ * <tr><td> Supply the protocol decoder. <td> {@link AMQDecoder}
+ * </table>
+ */
 public class AMQCodecFactory implements ProtocolCodecFactory
 {
+    /** Holds the protocol encoder. */
     private AMQEncoder _encoder = new AMQEncoder();
 
+    /** Holds the protocol decoder. */
     private AMQDecoder _frameDecoder;
 
     /**
-     * @param expectProtocolInitiation true if the first frame received is going to be
-     * a protocol initiation frame, false if it is going to be a standard AMQ data block.
-     * The former case is used for the broker, which always expects to received the
-     * protocol initiation first from a newly connected client.
+     * Creates a new codec factory, specifiying whether it is expected that the first frame of data should be an
+     * initiation. This is the case for the broker, which always expects to received the protocol initiation on a newly
+     * connected client.
+     *
+     * @param expectProtocolInitiation <tt>true</tt> if the first frame received is going to be a protocol initiation
+     *                                 frame, <tt>false</tt> if it is going to be a standard AMQ data block.
      */
     public AMQCodecFactory(boolean expectProtocolInitiation)
     {
         _frameDecoder = new AMQDecoder(expectProtocolInitiation);
     }
 
+    /**
+     * Gets the AMQP encoder.
+     *
+     * @return The AMQP encoder.
+     */
     public ProtocolEncoder getEncoder()
     {
         return _encoder;
     }
 
+    /**
+     * Gets the AMQP decoder.
+     *
+     * @return The AMQP decoder.
+     */
     public ProtocolDecoder getDecoder()
     {
         return _frameDecoder;
diff --git a/java/common/src/main/java/org/apache/qpid/codec/AMQDecoder.java b/java/common/src/main/java/org/apache/qpid/codec/AMQDecoder.java
index bb981a242f..02ae3cb089 100644
--- a/java/common/src/main/java/org/apache/qpid/codec/AMQDecoder.java
+++ b/java/common/src/main/java/org/apache/qpid/codec/AMQDecoder.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
@@ -24,28 +24,61 @@ import org.apache.mina.common.ByteBuffer;
 import org.apache.mina.common.IoSession;
 import org.apache.mina.filter.codec.CumulativeProtocolDecoder;
 import org.apache.mina.filter.codec.ProtocolDecoderOutput;
+
 import org.apache.qpid.framing.AMQDataBlockDecoder;
 import org.apache.qpid.framing.ProtocolInitiation;
 
 /**
- * There is one instance of this class per session. Any changes or configuration done
- * at run time to the encoders or decoders only affects decoding/encoding of the
- * protocol session data to which is it bound.
+ * AMQDecoder delegates the decoding of AMQP either to a data block decoder, or in the case of new connections, to a
+ * protocol initiation decoder. It is a cumulative decoder, which means that it can accumulate data to decode in the
+ * buffer until there is enough data to decode.
+ *
+ * <p/>One instance of this class is created per session, so any changes or configuration done at run time to the
+ * decoder will only affect decoding of the protocol session data to which is it bound.
  *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Delegate protocol initiation to its decoder. <td> {@link ProtocolInitiation.Decoder}
+ * <tr><td> Delegate AMQP data to its decoder. <td> {@link AMQDataBlockDecoder}
+ * <tr><td> Accept notification that protocol initiation has completed.
+ * </table>
+ *
+ * @todo If protocol initiation decoder not needed, then don't create it. Probably not a big deal, but it adds to the
+ *       per-session overhead.
  */
 public class AMQDecoder extends CumulativeProtocolDecoder
 {
+    /** Holds the 'normal' AMQP data decoder. */
     private AMQDataBlockDecoder _dataBlockDecoder = new AMQDataBlockDecoder();
 
+    /** Holds the protocol initiation decoder. */
     private ProtocolInitiation.Decoder _piDecoder = new ProtocolInitiation.Decoder();
 
+    /** Flag to indicate whether this decoder needs to handle protocol initiation. */
     private boolean _expectProtocolInitiation;
 
+    /**
+     * Creates a new AMQP decoder.
+     *
+     * @param expectProtocolInitiation <tt>true</tt> if this decoder needs to handle protocol initiation.
+     */
     public AMQDecoder(boolean expectProtocolInitiation)
     {
         _expectProtocolInitiation = expectProtocolInitiation;
     }
 
+    /**
+     * Delegates decoding AMQP from the data buffer that Mina has retrieved from the wire, to the data or protocol
+     * intiation decoders.
+     *
+     * @param session The Mina session.
+     * @param in      The raw byte buffer.
+     * @param out     The Mina object output gatherer to write decoded objects to.
+     *
+     * @return <tt>true</tt> if the data was decoded, <tt>false<tt> if more is needed and the data should accumulate.
+     *
+     * @throws Exception If the data cannot be decoded for any reason.
+     */
     protected boolean doDecode(IoSession session, ByteBuffer in, ProtocolDecoderOutput out) throws Exception
     {
         if (_expectProtocolInitiation)
@@ -58,6 +91,17 @@ public class AMQDecoder extends CumulativeProtocolDecoder
         }
     }
 
+    /**
+     * Decodes AMQP data, delegating the decoding to an {@link AMQDataBlockDecoder}.
+     *
+     * @param session The Mina session.
+     * @param in      The raw byte buffer.
+     * @param out     The Mina object output gatherer to write decoded objects to.
+     *
+     * @return <tt>true</tt> if the data was decoded, <tt>false<tt> if more is needed and the data should accumulate.
+     *
+     * @throws Exception If the data cannot be decoded for any reason.
+     */
     protected boolean doDecodeDataBlock(IoSession session, ByteBuffer in, ProtocolDecoderOutput out) throws Exception
     {
         int pos = in.position();
@@ -72,10 +116,22 @@ public class AMQDecoder extends CumulativeProtocolDecoder
         else
         {
             _dataBlockDecoder.decode(session, in, out);
+
             return true;
         }
     }
 
+    /**
+     * Decodes an AMQP initiation, delegating the decoding to a {@link ProtocolInitiation.Decoder}.
+     *
+     * @param session The Mina session.
+     * @param in      The raw byte buffer.
+     * @param out     The Mina object output gatherer to write decoded objects to.
+     *
+     * @return <tt>true</tt> if the data was decoded, <tt>false<tt> if more is needed and the data should accumulate.
+     *
+     * @throws Exception If the data cannot be decoded for any reason.
+     */
     private boolean doDecodePI(IoSession session, ByteBuffer in, ProtocolDecoderOutput out) throws Exception
     {
         boolean enoughData = _piDecoder.decodable(session, in);
@@ -88,10 +144,18 @@ public class AMQDecoder extends CumulativeProtocolDecoder
         else
         {
             _piDecoder.decode(session, in, out);
+
             return true;
         }
     }
 
+    /**
+     * Sets the protocol initation flag, that determines whether decoding is handled by the data decoder of the protocol
+     * initation decoder. This method is expected to be called with <tt>false</tt> once protocol initation completes.
+     *
+     * @param expectProtocolInitiation <tt>true</tt> to use the protocol initiation decoder, <tt>false</tt> to use the
+     *                                data decoder.
+     */
     public void setExpectProtocolInitiation(boolean expectProtocolInitiation)
     {
         _expectProtocolInitiation = expectProtocolInitiation;
diff --git a/java/common/src/main/java/org/apache/qpid/codec/AMQEncoder.java b/java/common/src/main/java/org/apache/qpid/codec/AMQEncoder.java
index fdb2e60c62..53f48ae1c8 100644
--- a/java/common/src/main/java/org/apache/qpid/codec/AMQEncoder.java
+++ b/java/common/src/main/java/org/apache/qpid/codec/AMQEncoder.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,19 +23,44 @@ package org.apache.qpid.codec;
 import org.apache.mina.common.IoSession;
 import org.apache.mina.filter.codec.ProtocolEncoder;
 import org.apache.mina.filter.codec.ProtocolEncoderOutput;
+
 import org.apache.qpid.framing.AMQDataBlockEncoder;
 
+/**
+ * AMQEncoder delegates encoding of AMQP to a data encoder.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Delegate AMQP encoding. <td> {@link AMQDataBlockEncoder}
+ * </table>
+ *
+ * @todo This class just delegates to another, so seems to be pointless. Unless it is going to handle some
+ *       responsibilities in the future, then drop it.
+ */
 public class AMQEncoder implements ProtocolEncoder
 {
+    /** The data encoder that is delegated to. */
     private AMQDataBlockEncoder _dataBlockEncoder = new AMQDataBlockEncoder();
 
+    /**
+     * Encodes AMQP.
+     *
+     * @param session The Mina session.
+     * @param message The data object to encode.
+     * @param out     The Mina writer to output the raw byte data to.
+     *
+     * @throws Exception If the data cannot be encoded for any reason.
+     */
     public void encode(IoSession session, Object message, ProtocolEncoderOutput out) throws Exception
     {
         _dataBlockEncoder.encode(session, message, out);
     }
 
-    public void dispose(IoSession session) throws Exception
-    {
-
-    }
+    /**
+     * Does nothing. Called by Mina to allow this to clean up resources when it is no longer needed.
+     *
+     * @param session The Mina session.
+     */
+    public void dispose(IoSession session)
+    { }
 }
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 fa75bd5fb3..375df2a45d 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
@@ -30,7 +30,7 @@ import org.apache.qpid.framing.AMQShortString;
  * 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
+ *       exception for an unknown constant. Or else provide an explanation of why this is so. Also, there 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?
  *