From 9bbdb51f3d9975d713a93933ffad1be4fe934ab5 Mon Sep 17 00:00:00 2001 From: Robert Gemmell Date: Fri, 8 Aug 2014 15:07:23 +0000 Subject: QPID-5980: more javadoc fixups git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1616795 13f79535-47bb-0310-9956-ffa450edef68 --- .../src/main/java/org/apache/qpid/api/Message.java | 5 ++++- .../java/org/apache/qpid/common/AMQPFilterTypes.java | 5 ----- .../java/org/apache/qpid/common/QpidProperties.java | 14 +++++--------- .../apache/qpid/configuration/PropertyException.java | 8 ++------ .../org/apache/qpid/configuration/PropertyUtils.java | 12 ++++-------- .../java/org/apache/qpid/protocol/AMQConstant.java | 14 ++++---------- .../org/apache/qpid/protocol/AMQMethodEvent.java | 9 ++------- .../org/apache/qpid/protocol/AMQMethodListener.java | 20 +++++++------------- .../org/apache/qpid/protocol/AMQProtocolWriter.java | 5 ----- .../protocol/AMQVersionAwareProtocolSession.java | 9 ++------- .../apache/qpid/protocol/ProtocolVersionAware.java | 5 ----- 11 files changed, 30 insertions(+), 76 deletions(-) (limited to 'qpid/java/common/src') diff --git a/qpid/java/common/src/main/java/org/apache/qpid/api/Message.java b/qpid/java/common/src/main/java/org/apache/qpid/api/Message.java index c0427c2f37..fff62424ca 100644 --- a/qpid/java/common/src/main/java/org/apache/qpid/api/Message.java +++ b/qpid/java/common/src/main/java/org/apache/qpid/api/Message.java @@ -47,6 +47,7 @@ public interface Message *
  • To Socket (Stream) * * @param src - the data to append + * @throws IOException if there is an issue appending the data */ public void appendData(byte[] src) throws IOException; @@ -63,6 +64,7 @@ public interface Message *
  • To Socket (Stream) * * @param src - the data to append + * @throws IOException if there is an issue appending the data */ public void appendData(ByteBuffer src) throws IOException; @@ -78,6 +80,7 @@ public interface Message *
  • From Socket as and when it gets streamed * * @param target The target byte[] which the data gets copied to + * @throws IOException if there is an issue reading the data */ public void readData(byte[] target) throws IOException; @@ -94,7 +97,7 @@ public interface Message * * * @return A ByteBuffer containing data - * @throws IOException + * @throws IOException if there is an issue reading the data */ public ByteBuffer readData() throws IOException; diff --git a/qpid/java/common/src/main/java/org/apache/qpid/common/AMQPFilterTypes.java b/qpid/java/common/src/main/java/org/apache/qpid/common/AMQPFilterTypes.java index f50e65214c..483fbaea50 100644 --- a/qpid/java/common/src/main/java/org/apache/qpid/common/AMQPFilterTypes.java +++ b/qpid/java/common/src/main/java/org/apache/qpid/common/AMQPFilterTypes.java @@ -24,11 +24,6 @@ import org.apache.qpid.framing.AMQShortString; /** * Specifies the different filter types for consumers that filter their messages. - * - *

    - *
    CRC Card
    Responsibilities Collaborations - *
    Represent different consumer filter types. - *
    */ public enum AMQPFilterTypes { diff --git a/qpid/java/common/src/main/java/org/apache/qpid/common/QpidProperties.java b/qpid/java/common/src/main/java/org/apache/qpid/common/QpidProperties.java index 2c783aeaa4..25baf86fe6 100644 --- a/qpid/java/common/src/main/java/org/apache/qpid/common/QpidProperties.java +++ b/qpid/java/common/src/main/java/org/apache/qpid/common/QpidProperties.java @@ -35,17 +35,13 @@ import java.util.Properties; * idea behind this, is that every build has these values incorporated directly into its jar file, so that code in the * wild can be identified, should its origination be forgotten. * - *

    To get the build version of any Qpid code call the {@link #main} method. This version string is usually also + *

    To get the build version of any Qpid code call the {@link #main} method. This version string is usually also * printed to the console on broker start up. - * - *

    - *
    CRC Card
    Load build versioning information into the runtime, for code identification purposes. - *
    - * - * @todo Code to locate/load/log properties can be factored into a reusable properties utils class. Avoid having this + *

    + * TODO Code to locate/load/log properties can be factored into a reusable properties utils class. Avoid having this * same snippet of loading code scattered in many places. - * - * @todo Could also add a build number property for a sequential build number assigned by an automated build system, for + *

    + * TODO Could also add a build number property for a sequential build number assigned by an automated build system, for * build reproducability purposes. */ public class QpidProperties diff --git a/qpid/java/common/src/main/java/org/apache/qpid/configuration/PropertyException.java b/qpid/java/common/src/main/java/org/apache/qpid/configuration/PropertyException.java index b8181e3b87..cf08dafb49 100644 --- a/qpid/java/common/src/main/java/org/apache/qpid/configuration/PropertyException.java +++ b/qpid/java/common/src/main/java/org/apache/qpid/configuration/PropertyException.java @@ -26,12 +26,8 @@ import org.apache.qpid.AMQException; * Indicates a failure to parse a property expansion. See {@link PropertyUtils} for the code that does property * expansions. * - *

    - *
    CRC Card
    Responsibilities Collaboration - *
    Represent failure to expand a property name into a value. - *
    - * - * @todo Not an AMQP exception as no status code. + *

    + * TODO Not an AMQP exception as no status code. */ public class PropertyException extends AMQException { diff --git a/qpid/java/common/src/main/java/org/apache/qpid/configuration/PropertyUtils.java b/qpid/java/common/src/main/java/org/apache/qpid/configuration/PropertyUtils.java index 81702ee1ea..da366ffd0f 100644 --- a/qpid/java/common/src/main/java/org/apache/qpid/configuration/PropertyUtils.java +++ b/qpid/java/common/src/main/java/org/apache/qpid/configuration/PropertyUtils.java @@ -26,15 +26,11 @@ import java.util.Iterator; /** * PropertyUtils provides helper methods for dealing with Java properties. * - *

    - *
    CRC Card
    Responsibilities Collaborations - *
    Expand system properties into strings with named expansions. - *
    - * - * @todo Make the lookup method generic by passing in the properties to use for the expansion, rather than hard coding + *

    + * TODO Make the lookup method generic by passing in the properties to use for the expansion, rather than hard coding * as system properties. The expansion code has greater potential for re-use that way. - * - * @todo Some more property related code could be added to this utils class, which might more appropriately reside under + *

    + * TODO Some more property related code could be added to this utils class, which might more appropriately reside under * org.apache.qpid.util. For example standardised code to load properties from a resource name, currently found in * QpidProperties and possibly other places could be moved here. */ diff --git a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQConstant.java b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQConstant.java index 2a2342ca14..5e39409382 100644 --- a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQConstant.java +++ b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQConstant.java @@ -28,20 +28,14 @@ import java.util.Map; /** * 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 + *

    + * 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, 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? - * - * @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 + *

    + * 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. - * - *

    CRC Card - * Responsibilities Collaborations - * Define the set of AMQP status codes. - * Provide a factory to lookup constants by their code. - * */ public final class AMQConstant { diff --git a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodEvent.java b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodEvent.java index fd6907a152..9b38f7926b 100644 --- a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodEvent.java +++ b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodEvent.java @@ -25,19 +25,14 @@ import org.apache.qpid.framing.AMQMethodBody; /** * AMQMethodEvent encapsulates an AMQP method call, and the channel on which that method call occurred. * - *

    Supplies the: + *

    Supplies the: *

    * - *

    As the event contains the context in which it occurred, event listeners do not need to be statefull. + *

    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. - * - *

    - *
    CRC Card
    Responsibilities Collaborations - *
    Encapsulate an AMQP method call and the channel as the context for the method call. - *
    */ public class AMQMethodEvent { diff --git a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodListener.java b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodListener.java index 8cc9709c9c..3e7c67493d 100644 --- a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodListener.java +++ b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodListener.java @@ -27,17 +27,11 @@ import org.apache.qpid.framing.AMQMethodBody; * AMQMethodListener is a listener that receives notifications of AMQP methods. The methods are packaged as events in * {@link AMQMethodEvent}. * - *

    An event listener may be associated with a particular context, usually an AMQP channel, and in addition to + *

    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 or retried. - * - *

    - *
    CRC Card
    Responsibilities - *
    Accept notification of AMQP method events. {@link AMQMethodEvent} - *
    Accept notification of errors on the event context. - *
    - * - * @todo Document why the exception is passed to the error method. Is it so that the exception can be passed + *

    + * 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. @@ -49,14 +43,14 @@ public interface AMQMethodListener * * @param evt The AMQP method event (contains the method and channel). * - * @return true if the handler processes the method frame, false otherwise. Note that this does + * @return true if the handler processes 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 Exception if an error has occurred. This exception may be delivered to all registered listeners using + * @throws AMQException 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. + *

    + * TODO Consider narrowing the exception. */ boolean methodReceived(AMQMethodEvent evt) throws AMQException; diff --git a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQProtocolWriter.java b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQProtocolWriter.java index 65884e4950..0a050becdc 100644 --- a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQProtocolWriter.java +++ b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQProtocolWriter.java @@ -26,11 +26,6 @@ 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. - * - *

    - *
    CRC Card
    Responsibilities - *
    Write an encoded block of data to the write, in the context of a session. - *
    */ public interface AMQProtocolWriter { diff --git a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQVersionAwareProtocolSession.java b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQVersionAwareProtocolSession.java index 33604b05d9..0c643f6322 100644 --- a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQVersionAwareProtocolSession.java +++ b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQVersionAwareProtocolSession.java @@ -34,13 +34,8 @@ import java.nio.ByteBuffer; /** * 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. - * - *

    - *
    CRC Card
    Responsibilities - *
    Provide the method registry for a specific version of the AMQP. - *
    - * - * @todo Why is this a seperate interface to {@link ProtocolVersionAware}, could they be combined into a single + *

    + * 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. */ diff --git a/qpid/java/common/src/main/java/org/apache/qpid/protocol/ProtocolVersionAware.java b/qpid/java/common/src/main/java/org/apache/qpid/protocol/ProtocolVersionAware.java index 56f950dd85..f12cd9af8e 100644 --- a/qpid/java/common/src/main/java/org/apache/qpid/protocol/ProtocolVersionAware.java +++ b/qpid/java/common/src/main/java/org/apache/qpid/protocol/ProtocolVersionAware.java @@ -25,11 +25,6 @@ import org.apache.qpid.framing.ProtocolVersion; /** * 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. - * - *

    - *
    CRC Card
    Responsibilities - *
    Report the major and minor AMQP version handled. - *
    */ public interface ProtocolVersionAware { -- cgit v1.2.1