This is an automated email from the ASF dual-hosted git repository. tabish pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/qpid-protonj2.git
commit 0a019e98747e5967efc6ecc28ab0ed6c4ee96257 Author: Timothy Bish <tabish...@gmail.com> AuthorDate: Wed Sep 14 17:53:00 2022 -0400 PROTON-2610 Fix some javadoc issues and add some details --- .../org/apache/qpid/protonj2/client/Client.java | 25 +++++++++++++++++++--- .../org/apache/qpid/protonj2/client/Delivery.java | 7 ++++-- .../java/org/apache/qpid/protonj2/client/Link.java | 2 ++ .../apache/qpid/protonj2/client/LinkOptions.java | 2 ++ .../org/apache/qpid/protonj2/client/Sender.java | 8 +++++-- .../apache/qpid/protonj2/client/StreamSender.java | 12 ++++++++--- .../protonj2/client/impl/ClientDeliverable.java | 3 +++ .../qpid/protonj2/client/impl/ClientLinkType.java | 3 +++ .../client/impl/ClientReceiverLinkType.java | 2 ++ .../protonj2/client/impl/ClientSenderLinkType.java | 4 +++- .../qpid/protonj2/client/impl/SenderTest.java | 2 +- .../protonj2/client/impl/StreamSenderTest.java | 2 +- .../org/apache/qpid/protonj2/codec/Decoder.java | 7 +++++- .../apache/qpid/protonj2/codec/StreamDecoder.java | 10 ++++++++- 14 files changed, 74 insertions(+), 15 deletions(-) diff --git a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Client.java b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Client.java index 2456ea5d..7f6e9ec9 100644 --- a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Client.java +++ b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Client.java @@ -22,7 +22,9 @@ import org.apache.qpid.protonj2.client.exceptions.ClientException; import org.apache.qpid.protonj2.client.impl.ClientInstance; /** - * The Container that hosts AMQP Connections + * The Container that hosts AMQP Connections. From this container new connections + * can be created and an API exists to close all open connections hosted in this + * container instance. */ public interface Client extends AutoCloseable { @@ -62,8 +64,9 @@ public interface Client extends AutoCloseable { /** * Closes all currently open {@link Connection} instances created by this client. * <p> - * This method blocks and waits for each connection to be closed in turn using the configured - * close timeout of the {@link ConnectionOptions} that the connection was created with. + * This method does not block and wait for each connection to be closed in turn, instead + * it returns a future which will be completed once the close of all connections has been + * completed. * * @return a {@link Future} that will be completed when all open connections have closed. */ @@ -72,6 +75,10 @@ public interface Client extends AutoCloseable { /** * Connect to the specified host and port, without credentials and with all * connection options set to their defaults. + * <p> + * The connection returned may still fail afterwards as the majority of connection + * setup is done asynchronously so the application should be prepared for errors to + * arise of the connection methods if the open future is not waited on. * * @param host * the host to connect to @@ -86,6 +93,10 @@ public interface Client extends AutoCloseable { /** * Connect to the specified host and port, with given connection options. + * <p> + * The connection returned may still fail afterwards as the majority of connection + * setup is done asynchronously so the application should be prepared for errors to + * arise of the connection methods if the open future is not waited on. * * @param host * the host to connect to @@ -103,6 +114,10 @@ public interface Client extends AutoCloseable { /** * Connect to the specified host, using the default port, without credentials and with all * connection options set to their defaults. + * <p> + * The connection returned may still fail afterwards as the majority of connection + * setup is done asynchronously so the application should be prepared for errors to + * arise of the connection methods if the open future is not waited on. * * @param host * the host to connect to @@ -116,6 +131,10 @@ public interface Client extends AutoCloseable { /** * Connect to the specified host, using the default port, without credentials and with all * connection options set to their defaults. + * <p> + * The connection returned may still fail afterwards as the majority of connection + * setup is done asynchronously so the application should be prepared for errors to + * arise of the connection methods if the open future is not waited on. * * @param host * the host to connect to diff --git a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Delivery.java b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Delivery.java index 495b6568..ee2c7870 100644 --- a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Delivery.java +++ b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Delivery.java @@ -45,12 +45,15 @@ public interface Delivery { * Calling this message claims the payload of the delivery for the returned {@link Message} and * excludes use of the {@link #rawInputStream()} method of the {@link Delivery} object. Calling * the {@link #rawInputStream()} method after calling this method throws {@link ClientIllegalStateException}. + * <p> + * Care should be taken if attempting to specify anything other than the wild card type for the body + * of the returned message as the wrong type specification can lead to an exception. + * + * @param <E> The type of message body that should be contained in the returned {@link Message}. * * @return a {@link Message} instance that wraps the decoded payload. * * @throws ClientException if an error occurs while decoding the payload. - * - * @param <E> The type of message body that should be contained in the returned {@link Message}. */ <E> Message<E> message() throws ClientException; diff --git a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Link.java b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Link.java index addec4bb..572fb442 100644 --- a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Link.java +++ b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Link.java @@ -24,6 +24,8 @@ import org.apache.qpid.protonj2.client.exceptions.ClientException; /** * Base for all AMQP link types (Sender, Receiver etc). + * + * @param <T> The actual link type that is being created (Sender or Receiver). */ public interface Link<T extends Link<T>> extends AutoCloseable { diff --git a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/LinkOptions.java b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/LinkOptions.java index d94e381f..8bbf61f2 100644 --- a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/LinkOptions.java +++ b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/LinkOptions.java @@ -26,6 +26,8 @@ import org.apache.qpid.protonj2.client.exceptions.ClientOperationTimedOutExcepti /** * Base options that are applied to AMQP link types. + * + * @param <T> The actual {@link LinkOptions} concrete type (SenderOptions or ReceiverOptions). */ public abstract class LinkOptions<T extends LinkOptions<T>> { diff --git a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Sender.java b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Sender.java index 3e2c083c..b22c6868 100644 --- a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Sender.java +++ b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Sender.java @@ -40,7 +40,9 @@ public interface Sender extends Link<Sender> { /** * Send the given message immediately if there is credit available or blocks if the link - * has not yet been granted credit. + * has not yet been granted credit. The provided delivery annotations are encoded along + * with the message, the annotations can be passed repeatedly to send calls if sending + * the same delivery annotations with each message. * * @param message * the {@link Message} to send. @@ -68,7 +70,9 @@ public interface Sender extends Link<Sender> { /** * Send the given message if credit is available or returns null if no credit has been - * granted to the link at the time of the send attempt. + * granted to the link at the time of the send attempt. The provided delivery annotations + * are encoded along with the message, the annotations can be passed repeatedly to send + * calls if sending the same delivery annotations with each message. * * @param message * the {@link Message} to send if credit is available. diff --git a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/StreamSender.java b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/StreamSender.java index 9f34ac04..0e4f7339 100644 --- a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/StreamSender.java +++ b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/StreamSender.java @@ -41,7 +41,9 @@ public interface StreamSender extends Link<StreamSender> { /** * Send the given message immediately if there is credit available or blocks if the link - * has not yet been granted credit or there is a streaming send ongoing.. + * has not yet been granted credit or there is a streaming send ongoing. The provided + * delivery annotations are encoded along with the message, the annotations can be passed + * repeatedly to send calls if sending the same delivery annotations with each message. * * @param message * the {@link Message} to send. @@ -69,7 +71,9 @@ public interface StreamSender extends Link<StreamSender> { /** * Send the given message if credit is available or returns null if no credit has been - * granted to the link at the time of the send attempt. + * granted to the link at the time of the send attempt. The provided delivery annotations + * are encoded along with the message, the annotations can be passed repeatedly to send + * calls if sending the same delivery annotations with each message. * * @param message * the {@link Message} to send if credit is available. @@ -94,7 +98,9 @@ public interface StreamSender extends Link<StreamSender> { /** * Creates and returns a new {@link StreamSenderMessage} that can be used by the caller to perform - * streaming sends of large message payload data. + * streaming sends of large message payload data. The provided delivery annotations are encoded + * along with the message, the annotations can be passed repeatedly to send calls if sending the + * same delivery annotations with each message. * * @param deliveryAnnotations * the delivery annotations that should be included in the sent {@link StreamSenderMessage}. diff --git a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientDeliverable.java b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientDeliverable.java index 88c95066..332ba8d5 100644 --- a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientDeliverable.java +++ b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientDeliverable.java @@ -29,6 +29,9 @@ import org.apache.qpid.protonj2.types.transport.ErrorCondition; /** * Abstract type that implements some of the common portions of a delivery * wrapper type. + * + * @param <DeliveryType> The client delivery type streamed or non-streamed + * @param <ReceiverType> The client receiver type streaming or non-streaming */ @SuppressWarnings("rawtypes") public abstract class ClientDeliverable<DeliveryType, ReceiverType extends ClientReceiverLinkType> { diff --git a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientLinkType.java b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientLinkType.java index 852ee616..8907a8f1 100644 --- a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientLinkType.java +++ b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientLinkType.java @@ -44,6 +44,9 @@ import org.slf4j.LoggerFactory; /** * Base type used by client resources that represent an AMQP link type. + * + * @param <LinkType> The actual link type implementation ClientSender or ClientReceiver + * @param <ProtonType> The proton concrete link type implementation Sender or Receiver */ public abstract class ClientLinkType<LinkType extends Link<LinkType>, ProtonType extends org.apache.qpid.protonj2.engine.Link<ProtonType>> implements Link<LinkType> { diff --git a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientReceiverLinkType.java b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientReceiverLinkType.java index 284a78a5..74fde357 100644 --- a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientReceiverLinkType.java +++ b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientReceiverLinkType.java @@ -34,6 +34,8 @@ import org.slf4j.LoggerFactory; /** * Base class for client link types that wrap a proton receiver to provide * delivery dispatch in some manner. + * + * @param <ReceiverType> The client receiver type that is being implemented. */ public abstract class ClientReceiverLinkType<ReceiverType extends Link<ReceiverType>> extends ClientLinkType<ReceiverType, Receiver> { diff --git a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientSenderLinkType.java b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientSenderLinkType.java index c1edd783..e5784bb4 100644 --- a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientSenderLinkType.java +++ b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientSenderLinkType.java @@ -29,7 +29,9 @@ import org.apache.qpid.protonj2.types.transport.SenderSettleMode; /** * Base type for all the proton client sender types which provides a few extra - * APIs for the connection and session to use when managing senders + * APIs for the connection and session to use when managing senders. + * + * @param <LinkType> The client sender link type being implemented. */ public abstract class ClientSenderLinkType<LinkType extends Link<LinkType>> extends ClientLinkType<LinkType, Sender> { diff --git a/protonj2-client/src/test/java/org/apache/qpid/protonj2/client/impl/SenderTest.java b/protonj2-client/src/test/java/org/apache/qpid/protonj2/client/impl/SenderTest.java index 1f7f86bd..40023e38 100644 --- a/protonj2-client/src/test/java/org/apache/qpid/protonj2/client/impl/SenderTest.java +++ b/protonj2-client/src/test/java/org/apache/qpid/protonj2/client/impl/SenderTest.java @@ -2586,7 +2586,7 @@ public class SenderTest extends ImperativeClientTestCase { } @Test - public void testSendeUsesCustomDeliveryTagGeneratorConfiguration() throws Exception { + public void testSenderUsesCustomDeliveryTagGeneratorConfiguration() throws Exception { try (ProtonTestServer peer = new ProtonTestServer()) { peer.expectSASLAnonymousConnect(); peer.expectOpen().respond(); diff --git a/protonj2-client/src/test/java/org/apache/qpid/protonj2/client/impl/StreamSenderTest.java b/protonj2-client/src/test/java/org/apache/qpid/protonj2/client/impl/StreamSenderTest.java index 65a8189a..4577b694 100644 --- a/protonj2-client/src/test/java/org/apache/qpid/protonj2/client/impl/StreamSenderTest.java +++ b/protonj2-client/src/test/java/org/apache/qpid/protonj2/client/impl/StreamSenderTest.java @@ -2813,7 +2813,7 @@ public class StreamSenderTest extends ImperativeClientTestCase { } @Test - public void testSendeUsesCustomDeliveryTagGeneratorConfiguration() throws Exception { + public void testSenderUsesCustomDeliveryTagGeneratorConfiguration() throws Exception { try (ProtonTestServer peer = new ProtonTestServer()) { peer.expectSASLAnonymousConnect(); peer.expectOpen().respond(); diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/Decoder.java b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/Decoder.java index 257bb04b..0bec73e1 100644 --- a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/Decoder.java +++ b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/Decoder.java @@ -33,7 +33,7 @@ import org.apache.qpid.protonj2.types.UnsignedLong; import org.apache.qpid.protonj2.types.UnsignedShort; /** - * Decode AMQP types from a byte stream + * Decode AMQP types from a byte stream read from a {@link ProtonBuffer} instance. */ public interface Decoder { @@ -799,6 +799,9 @@ public interface Decoder { * not what was expected. If the caller wishes to recover from failed decode attempt they should * mark the and reset the input to make a further read attempt. * + * @param <K> The key type for the map that is being read. + * @param <V> The value type for the map that is being read. + * * @param buffer * The {@link ProtonBuffer} where the read operation takes place. * @param state @@ -816,6 +819,8 @@ public interface Decoder { * not what was expected. If the caller wishes to recover from failed decode attempt they should * mark the and reset the input to make a further read attempt. * + * @param <V> The value type for the list being read. + * * @param buffer * The {@link ProtonBuffer} where the read operation takes place. * @param state diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/StreamDecoder.java b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/StreamDecoder.java index 3502e1ae..b74e0918 100644 --- a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/StreamDecoder.java +++ b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/StreamDecoder.java @@ -34,7 +34,10 @@ import org.apache.qpid.protonj2.types.UnsignedLong; import org.apache.qpid.protonj2.types.UnsignedShort; /** - * Decode AMQP types from a {@link InputStream} + * Decode AMQP types from a {@link InputStream} instance. When reading from an input stream + * care should be take to capture the stream position and state and reset if not enough bytes + * are available for the decoder to complete reading an encoded type as the decoder is not + * required to handle partially available type encodings. */ public interface StreamDecoder { @@ -800,6 +803,9 @@ public interface StreamDecoder { * not what was expected. If the caller wishes to recover from failed decode attempt they should * mark the and reset the input to make a further read attempt. * + * @param <K> The key type for the map that is being read. + * @param <V> The value type for the map that is being read. + * * @param stream * The {@link InputStream} where the read operation takes place. * @param state @@ -817,6 +823,8 @@ public interface StreamDecoder { * not what was expected. If the caller wishes to recover from failed decode attempt they should * mark the and reset the input to make a further read attempt. * + * @param <V> The value type for the list that is being read. + * * @param stream * The {@link InputStream} where the read operation takes place. * @param state --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org