PROTON-2610 Fix some javadoc issues and add some details
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 2456ea5..7f6e9ec 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.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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 495b656..ee2c787 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 @@
* 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 addec4b..572fb44 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 @@
/**
* 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 d94e381..8bbf61f 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 @@
/**
* 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 3e2c083..b22c686 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 @@
/**
* 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 @@
/**
* 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 9f34ac0..0e4f733 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 88c9506..332ba8d 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 @@
/**
* 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 852ee61..8907a8f 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 @@
/**
* 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 284a78a..74fde35 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 @@
/**
* 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 c1edd78..e5784bb 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 @@
/**
* 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 1f7f86b..40023e3 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 @@
}
@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 65a8189..4577b69 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 @@
}
@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 257bb04..0bec73e 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.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 @@
* 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 @@
* 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 3502e1a..b74e091 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.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 @@
* 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 @@
* 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
