Merged revisions 540107 via svnmerge from

https://svn.apache.org/repos/asf/incubator/qpid/branches/M2

........
  r540107 | rupertlssmith | 2007-05-21 11:57:30 +0100 (Mon, 21 May 2007) | 1 line
  
  Documented all exception.
........


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

20 files changed, 212 insertions, 71 deletions

diff --git a/java/common/src/main/java/org/apache/qpid/AMQChannelClosedException.java b/java/common/src/main/java/org/apache/qpid/AMQChannelClosedException.java
index 272933ca04..251e91c1b9 100644
--- a/java/common/src/main/java/org/apache/qpid/AMQChannelClosedException.java
+++ b/java/common/src/main/java/org/apache/qpid/AMQChannelClosedException.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,7 +23,14 @@ package org.apache.qpid;
 import org.apache.qpid.protocol.AMQConstant;
 
 /**
- * AMQ channel closed exception.
+ * AMQChannelClosedException indicates that an operation cannot be performed becauase a channel has been closed.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Represents a failed operation on a closed channel.
+ * </table>
+ *
+ * @todo Does this duplicate AMQChannelException?
  */
 public class AMQChannelClosedException extends AMQException
 {
@@ -32,5 +39,3 @@ public class AMQChannelClosedException extends AMQException
         super(errorCode, msg);
     }
 }
-
-
diff --git a/java/common/src/main/java/org/apache/qpid/AMQChannelException.java b/java/common/src/main/java/org/apache/qpid/AMQChannelException.java
index d8c9b287bd..9efd271e4d 100644
--- a/java/common/src/main/java/org/apache/qpid/AMQChannelException.java
+++ b/java/common/src/main/java/org/apache/qpid/AMQChannelException.java
@@ -25,6 +25,16 @@ import org.apache.qpid.framing.AMQShortString;
 import org.apache.qpid.framing.ChannelCloseBody;
 import org.apache.qpid.protocol.AMQConstant;
 
+/**
+ * AMQChannelException indicates that an error that requires the channel to be closed has occurred.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Represents an error that rquires the channel to be closed.
+ * </table>
+ *
+ * @todo Does this duplicate AMQChannelClosedException?
+ */
 public class AMQChannelException extends AMQException
 {
     private final int _classId;
diff --git a/java/common/src/main/java/org/apache/qpid/AMQConnectionClosedException.java b/java/common/src/main/java/org/apache/qpid/AMQConnectionClosedException.java
index e0ed16a9f0..931c6cd87a 100644
--- a/java/common/src/main/java/org/apache/qpid/AMQConnectionClosedException.java
+++ b/java/common/src/main/java/org/apache/qpid/AMQConnectionClosedException.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,7 +23,14 @@ package org.apache.qpid;
 import org.apache.qpid.protocol.AMQConstant;
 
 /**
- * AMQ channel closed exception.
+ * AMQConnectionClosedException indicates that an operation cannot be performed becauase a connection has been closed.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Represents a failed operation on a closed conneciton.
+ * </table>
+ *
+ * @todo Does this duplicate AMQConnectionException?
  */
 public class AMQConnectionClosedException extends AMQException
 {
@@ -32,5 +39,3 @@ public class AMQConnectionClosedException extends AMQException
         super(errorCode, msg);
     }
 }
-
-
diff --git a/java/common/src/main/java/org/apache/qpid/AMQConnectionException.java b/java/common/src/main/java/org/apache/qpid/AMQConnectionException.java
index c4f80191a3..7edfa648ed 100644
--- a/java/common/src/main/java/org/apache/qpid/AMQConnectionException.java
+++ b/java/common/src/main/java/org/apache/qpid/AMQConnectionException.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
@@ -26,6 +26,16 @@ import org.apache.qpid.framing.AMQShortString;
 import org.apache.qpid.framing.ConnectionCloseBody;
 import org.apache.qpid.protocol.AMQConstant;
 
+/**
+ * AMQConnectionException indicates that an error that requires the channel to be closed has occurred.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Represents an error that rquires the channel to be closed.
+ * </table>
+ *
+ * @todo Does this duplicate AMQChannelClosedException?
+ */
 public class AMQConnectionException extends AMQException
 {
     private final int _classId;
@@ -35,7 +45,8 @@ public class AMQConnectionException extends AMQException
     private final byte minor;
     boolean _closeConnetion;
 
-    public AMQConnectionException(AMQConstant errorCode, String msg, int classId, int methodId, byte major, byte minor, Throwable t)
+    public AMQConnectionException(AMQConstant errorCode, String msg, int classId, int methodId, byte major, byte minor,
+        Throwable t)
     {
         super(errorCode, msg, t);
         _classId = classId;
@@ -53,12 +64,10 @@ public class AMQConnectionException extends AMQException
         this.minor = minor;
     }
 
-
-
     public AMQFrame getCloseFrame(int channel)
     {
-        return ConnectionCloseBody.createAMQFrame(channel, major, minor, _classId, _methodId, getErrorCode().getCode(), new AMQShortString(getMessage()));
+        return ConnectionCloseBody.createAMQFrame(channel, major, minor, _classId, _methodId, getErrorCode().getCode(),
+                new AMQShortString(getMessage()));
     }
 
-
 }
diff --git a/java/common/src/main/java/org/apache/qpid/AMQConnectionFailureException.java b/java/common/src/main/java/org/apache/qpid/AMQConnectionFailureException.java
index 9513cfc468..72fa2ae984 100644
--- a/java/common/src/main/java/org/apache/qpid/AMQConnectionFailureException.java
+++ b/java/common/src/main/java/org/apache/qpid/AMQConnectionFailureException.java
@@ -1,5 +1,15 @@
 package org.apache.qpid;

 

+/**

+ * AMQConnectionFailureException indicates that a connection to a broker could not be formed.

+ *

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

+ * <tr><th> Responsibilities <th> Collaborations

+ * <tr><td> Represents failure to connect to a broker.

+ * </table>

+ *

+ * @todo Not an AMQP exception as no status code.

+ */

 public class AMQConnectionFailureException extends AMQException

 {

     public AMQConnectionFailureException(String message)

diff --git a/java/common/src/main/java/org/apache/qpid/AMQDisconnectedException.java b/java/common/src/main/java/org/apache/qpid/AMQDisconnectedException.java
index b142eea73c..e62b2c10a2 100644
--- a/java/common/src/main/java/org/apache/qpid/AMQDisconnectedException.java
+++ b/java/common/src/main/java/org/apache/qpid/AMQDisconnectedException.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
@@ -21,7 +21,14 @@
 package org.apache.qpid;
 
 /**
- * AMQ disconnected exception.
+ * AMQDisconnectedException indicates that a broker disconnected without failover.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Represents disconnection without failover by the broker.
+ * </table>
+ *
+ * @todo Not an AMQP exception as no status code.
  */
 public class AMQDisconnectedException extends AMQException
 {
@@ -30,5 +37,3 @@ public class AMQDisconnectedException extends AMQException
         super(msg);
     }
 }
-
-
diff --git a/java/common/src/main/java/org/apache/qpid/AMQException.java b/java/common/src/main/java/org/apache/qpid/AMQException.java
index 2f04a01f53..41599ed880 100644
--- a/java/common/src/main/java/org/apache/qpid/AMQException.java
+++ b/java/common/src/main/java/org/apache/qpid/AMQException.java
@@ -24,11 +24,11 @@ import org.apache.qpid.protocol.AMQConstant;
 
 /**
  * AMQException forms the root exception of all exceptions relating to the AMQ protocol. It provides space to associate
- * an AMQ error code with the exception, which is a numberic value, with a meaning defined by the protocol.
+ * a required AMQ error code with the exception, which is a numeric value, with a meaning defined by the protocol.
  *
  * <p/><table id="crc"><caption>CRC Card</caption>
  * <tr><th> Responsibilities <th> Collaborations
- * <tr><td> Represents an exception condition associated with an AMQ protocol error code.
+ * <tr><td> Represents an exception condition associated with an AMQ protocol status code.
  * </table>
  *
  * @todo This exception class is also used as a generic exception throughout Qpid code. This usage may not be strictly
diff --git a/java/common/src/main/java/org/apache/qpid/AMQInvalidArgumentException.java b/java/common/src/main/java/org/apache/qpid/AMQInvalidArgumentException.java
index 9406921d88..278128f924 100644
--- a/java/common/src/main/java/org/apache/qpid/AMQInvalidArgumentException.java
+++ b/java/common/src/main/java/org/apache/qpid/AMQInvalidArgumentException.java
@@ -14,14 +14,22 @@
  *  "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;
 
 import org.apache.qpid.protocol.AMQConstant;
 
+/**
+ * AMQInvalidArgumentException indicates that an invalid argument has been passed to an AMQP method.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Represents an error due to an invalid argument being passed to an AMQP method.
+ * </table>
+ */
 public class AMQInvalidArgumentException extends AMQException
 {
     public AMQInvalidArgumentException(String message)
diff --git a/java/common/src/main/java/org/apache/qpid/AMQInvalidRoutingKeyException.java b/java/common/src/main/java/org/apache/qpid/AMQInvalidRoutingKeyException.java
index caf8f3a572..b5ec9845d6 100644
--- a/java/common/src/main/java/org/apache/qpid/AMQInvalidRoutingKeyException.java
+++ b/java/common/src/main/java/org/apache/qpid/AMQInvalidRoutingKeyException.java
@@ -22,6 +22,14 @@ package org.apache.qpid;
 
 import org.apache.qpid.protocol.AMQConstant;
 
+/**
+ * AMQInvalidRoutingKeyException indicates an error with a routing key having an invalid format.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Represents a format error in a routing key.
+ * </table>
+ */
 public class AMQInvalidRoutingKeyException extends AMQException
 {
     public AMQInvalidRoutingKeyException(String message)
diff --git a/java/common/src/main/java/org/apache/qpid/AMQTimeoutException.java b/java/common/src/main/java/org/apache/qpid/AMQTimeoutException.java
index f1f973542d..0f8d9c47db 100644
--- a/java/common/src/main/java/org/apache/qpid/AMQTimeoutException.java
+++ b/java/common/src/main/java/org/apache/qpid/AMQTimeoutException.java
@@ -14,14 +14,22 @@
  *  "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;
 
 import org.apache.qpid.protocol.AMQConstant;
 
+/**
+ * AMQTimeoutException indicates that an expected response from a broker took too long.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Indicates that an expected response from a broker took too long.
+ * </table>
+ */
 public class AMQTimeoutException extends AMQException
 {
     public AMQTimeoutException(String message)
diff --git a/java/common/src/main/java/org/apache/qpid/AMQUndeliveredException.java b/java/common/src/main/java/org/apache/qpid/AMQUndeliveredException.java
index ad5aff7bb6..03220cc95e 100644
--- a/java/common/src/main/java/org/apache/qpid/AMQUndeliveredException.java
+++ b/java/common/src/main/java/org/apache/qpid/AMQUndeliveredException.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,7 +23,12 @@ package org.apache.qpid;
 import org.apache.qpid.protocol.AMQConstant;
 
 /**
- * Generic AMQ exception.
+ * AMQUndeliveredException indicates that a message, marked immediate or mandatory, could not be delivered.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Represents failure to delivery a message that must be delivered.
+ * </table>
  */
 public class AMQUndeliveredException extends AMQException
 {
@@ -40,7 +45,4 @@ public class AMQUndeliveredException extends AMQException
     {
         return _bounced;
     }
-
 }
-
-
diff --git a/java/common/src/main/java/org/apache/qpid/AMQUnknownExchangeType.java b/java/common/src/main/java/org/apache/qpid/AMQUnknownExchangeType.java
index ed1d2e8beb..c4aa992a01 100644
--- a/java/common/src/main/java/org/apache/qpid/AMQUnknownExchangeType.java
+++ b/java/common/src/main/java/org/apache/qpid/AMQUnknownExchangeType.java
@@ -1,5 +1,18 @@
 package org.apache.qpid;

 

+/**

+ * AMQUnknownExchangeType represents coding error where unknown exchange type requested from exchange factory.

+ *

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

+ * <tr><th> Responsibilities <th> Collaborations

+ * <tr><td> Represents unknown exchange type request.

+ * <tr><td>

+ *

+ * @todo Not an AMQP exception as no status code.

+ *

+ * @todo Represent coding error, where unknown exchange type is requested by passing a string parameter. Use a type safe

+ *       enum for the exchange type, or replace with IllegalArgumentException. Should be runtime.

+ */

 public class AMQUnknownExchangeType extends AMQException

 {

     public AMQUnknownExchangeType(String message)

diff --git a/java/common/src/main/java/org/apache/qpid/AMQUnresolvedAddressException.java b/java/common/src/main/java/org/apache/qpid/AMQUnresolvedAddressException.java
index 2201903ded..6cc9c3fe00 100644
--- a/java/common/src/main/java/org/apache/qpid/AMQUnresolvedAddressException.java
+++ b/java/common/src/main/java/org/apache/qpid/AMQUnresolvedAddressException.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,6 +20,19 @@
  */
 package org.apache.qpid;
 
+/**
+ * AMQUnresolvedAddressException indicates failure to resolve a socket address.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Represents failre to resolve a socket address.
+ * </table>
+ *
+ * @todo Not an AMQP exception as no status code.
+ *
+ * @todo Why replace java.nio.UnresolvedAddressException with this? This is checked, which may explain why, but it
+ *       doesn't wrap the underlying exception.
+ */
 public class AMQUnresolvedAddressException extends AMQException
 {
     String _broker;
@@ -32,6 +45,6 @@ public class AMQUnresolvedAddressException extends AMQException
 
     public String toString()
     {
-        return super.toString() + " Broker, \"" + _broker +"\"";
+        return super.toString() + " Broker, \"" + _broker + "\"";
     }
 }
diff --git a/java/common/src/main/java/org/apache/qpid/configuration/PropertyException.java b/java/common/src/main/java/org/apache/qpid/configuration/PropertyException.java
index 76225778e3..1e5cc57fff 100644
--- a/java/common/src/main/java/org/apache/qpid/configuration/PropertyException.java
+++ b/java/common/src/main/java/org/apache/qpid/configuration/PropertyException.java
@@ -32,8 +32,7 @@ import org.apache.qpid.protocol.AMQConstant;
  * <tr><td> Represent failure to expand a property name into a value.
  * </table>
  *
- * @todo AMQException is to be reserved for protocol related conditions. This exception does not have a status code, so
- *       don't inherit from AMQException.
+ * @todo Not an AMQP exception as no status code.
  */
 public class PropertyException extends AMQException
 {
diff --git a/java/common/src/main/java/org/apache/qpid/framing/AMQFrameDecodingException.java b/java/common/src/main/java/org/apache/qpid/framing/AMQFrameDecodingException.java
index 171da76771..cd5ccf8e04 100644
--- a/java/common/src/main/java/org/apache/qpid/framing/AMQFrameDecodingException.java
+++ b/java/common/src/main/java/org/apache/qpid/framing/AMQFrameDecodingException.java
@@ -23,13 +23,17 @@ package org.apache.qpid.framing;
 import org.apache.qpid.AMQException;
 import org.apache.qpid.protocol.AMQConstant;
 
+/**
+ * AMQFrameDecodingException indicates that an AMQP frame cannot be decoded because it does not have the correct
+ * format as defined by the protocol.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Represents a format error in a protocol frame.
+ * </table>
+ */
 public class AMQFrameDecodingException extends AMQException
 {
-    /*public AMQFrameDecodingException(String message)
-    {
-        super(message);
-    }*/
-
     public AMQFrameDecodingException(AMQConstant errorCode, String message, Throwable t)
     {
         super(errorCode, message, t);
diff --git a/java/common/src/main/java/org/apache/qpid/framing/AMQProtocolClassException.java b/java/common/src/main/java/org/apache/qpid/framing/AMQProtocolClassException.java
index e6acad502f..e48fd2e7f9 100644
--- a/java/common/src/main/java/org/apache/qpid/framing/AMQProtocolClassException.java
+++ b/java/common/src/main/java/org/apache/qpid/framing/AMQProtocolClassException.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,10 +20,20 @@
  */
 package org.apache.qpid.framing;
 
+/**
+ * AMQProtocolInstanceException indicates that the protocol class is incorrect in a header.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Represent incorrect protocol class in frame header.
+ * </table>
+ *
+ * @todo Not an AMQP exception as no status code.
+ */
 public class AMQProtocolClassException extends AMQProtocolHeaderException
 {
-   public AMQProtocolClassException(String message)
-   {
-       super(message);
-   }
-}
\ No newline at end of file
+    public AMQProtocolClassException(String message)
+    {
+        super(message);
+    }
+}
diff --git a/java/common/src/main/java/org/apache/qpid/framing/AMQProtocolHeaderException.java b/java/common/src/main/java/org/apache/qpid/framing/AMQProtocolHeaderException.java
index 888ed14faf..1ce49aba83 100644
--- a/java/common/src/main/java/org/apache/qpid/framing/AMQProtocolHeaderException.java
+++ b/java/common/src/main/java/org/apache/qpid/framing/AMQProtocolHeaderException.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
@@ -22,10 +22,20 @@ package org.apache.qpid.framing;
 
 import org.apache.qpid.AMQException;
 
+/**
+ * AMQProtocolHeaderException indicates a format error in an AMQP frame header.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Represent format error in frame header.
+ * </table>
+ *
+ * @todo Not an AMQP exception as no status code.
+ */
 public class AMQProtocolHeaderException extends AMQException
 {
-   public AMQProtocolHeaderException(String message)
-   {
-       super(message);
-   }
+    public AMQProtocolHeaderException(String message)
+    {
+        super(message);
+    }
 }
diff --git a/java/common/src/main/java/org/apache/qpid/framing/AMQProtocolInstanceException.java b/java/common/src/main/java/org/apache/qpid/framing/AMQProtocolInstanceException.java
index c58979f876..9049eace2a 100644
--- a/java/common/src/main/java/org/apache/qpid/framing/AMQProtocolInstanceException.java
+++ b/java/common/src/main/java/org/apache/qpid/framing/AMQProtocolInstanceException.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,10 +20,20 @@
  */
 package org.apache.qpid.framing;
 
+/**
+ * AMQProtocolInstanceException indicates that the protocol instance is incorrect in a header.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Represent incorrect protocol instance in frame header.
+ * </table>
+ *
+ * @todo Not an AMQP exception as no status code.
+ */
 public class AMQProtocolInstanceException extends AMQProtocolHeaderException
 {
-   public AMQProtocolInstanceException(String message)
-   {
-       super(message);
-   }
+    public AMQProtocolInstanceException(String message)
+    {
+        super(message);
+    }
 }
diff --git a/java/common/src/main/java/org/apache/qpid/framing/AMQProtocolVersionException.java b/java/common/src/main/java/org/apache/qpid/framing/AMQProtocolVersionException.java
index 7b326a0dc4..9074931617 100644
--- a/java/common/src/main/java/org/apache/qpid/framing/AMQProtocolVersionException.java
+++ b/java/common/src/main/java/org/apache/qpid/framing/AMQProtocolVersionException.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
@@ -21,13 +21,19 @@
 package org.apache.qpid.framing;
 
 /**
- * Exception that is thrown when the client and server differ on expected protocol version (header) information.
+ * AMQProtocolInstanceException indicates that the client and server differ on expected protocol version  in a header.
+ *
+ * <p/><table id="crc"><caption>CRC Card</caption>
+ * <tr><th> Responsibilities <th> Collaborations
+ * <tr><td> Represent incorrect protocol version in frame header.
+ * </table>
  *
+ * @todo Not an AMQP exception as no status code.
  */
 public class AMQProtocolVersionException extends AMQProtocolHeaderException
 {
-   public AMQProtocolVersionException(String message)
-   {
-       super(message);
-   }
+    public AMQProtocolVersionException(String message)
+    {
+        super(message);
+    }
 }
diff --git a/java/common/src/main/java/org/apache/qpid/pool/PoolingFilter.java b/java/common/src/main/java/org/apache/qpid/pool/PoolingFilter.java
index 90c09ea99e..ffc8f1643a 100644
--- a/java/common/src/main/java/org/apache/qpid/pool/PoolingFilter.java
+++ b/java/common/src/main/java/org/apache/qpid/pool/PoolingFilter.java
@@ -68,7 +68,13 @@ import org.apache.qpid.pool.Event.CloseEvent;
  * @todo Why set an event limit of 10 on the Job? This also seems bizarre, as the job can have more than 10 events in
  *       it. Its just that it runs them 10 at a time, but the completion hander here checks if there are more to run
  *       and trips off another batch of 10 until they are all done. Why not just have a straight forward
- *       consumer/producer queue scenario without the batches of 10?
+ *       consumer/producer queue scenario without the batches of 10? So instead of having many jobs with batches of 10
+ *       in them, just have one queue of events and worker threads taking the next event. There will be coordination
+ *       between worker threads and new events arriving on the job anyway, so the simpler scenario may have the same
+ *       amount of contention. I can see that the batches of 10 is done, so that no job is allowed to hog the worker
+ *       pool for too long. I'm not convinced this fairly complex scheme will actually add anything, and it might be
+ *       better to encapsulate it under a Queue interface anyway, so that different queue implementations can easily
+ *       be substituted in.
  *
  * @todo The static helper methods are pointless. Could just call new.
  */