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
The following commit(s) were added to refs/heads/main by this push:
new 762fa22 Another round of Javadoc additions for the ProtonJ2 API
762fa22 is described below
commit 762fa2255f250e12ea393d27ce12675b7768e2c5
Author: Timothy Bish <tabish...@gmail.com>
AuthorDate: Tue May 4 15:19:48 2021 -0400
Another round of Javadoc additions for the ProtonJ2 API
---
.../client/impl/ClientOutgoingEnvelope.java | 9 +++
.../qpid/protonj2/client/impl/ClientRedirect.java | 7 ++
.../qpid/protonj2/test/driver/AMQPTestDriver.java | 80 ++++++++++++++++++++++
.../primitives/AbstractBinaryTypeDecoder.java | 49 +++++++++++++
.../encoders/primitives/ArrayTypeEncoder.java | 80 ++++++++++++++++++++++
.../qpid/protonj2/engine/HeaderEnvelope.java | 40 +++++++++++
.../apache/qpid/protonj2/engine/SASLEnvelope.java | 28 ++++++++
.../apache/qpid/protonj2/engine/Transaction.java | 15 ++++
.../engine/impl/ProtonPooledTagGenerator.java | 12 ++++
.../qpid/protonj2/engine/impl/ProtonSession.java | 14 ++++
.../engine/sasl/client/AnonymousMechanism.java | 3 +
.../engine/sasl/client/CramMD5Mechanism.java | 3 +
.../engine/sasl/client/ExternalMechanism.java | 3 +
.../engine/sasl/client/PlainMechanism.java | 3 +
.../sasl/client/SaslCredentialsProvider.java | 15 ++++
.../engine/sasl/client/ScramSHA1Mechanism.java | 6 ++
.../engine/sasl/client/ScramSHA256Mechanism.java | 6 ++
.../engine/sasl/client/ScramSHA512Mechanism.java | 6 ++
.../engine/sasl/client/XOauth2Mechanism.java | 3 +
.../apache/qpid/protonj2/engine/util/SplayMap.java | 32 +++++++++
.../qpid/protonj2/types/transport/AmqpError.java | 3 +
.../qpid/protonj2/types/transport/Close.java | 21 ++++++
.../protonj2/types/transport/DeliveryState.java | 3 +
23 files changed, 441 insertions(+)
diff --git
a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientOutgoingEnvelope.java
b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientOutgoingEnvelope.java
index a66e528..2c022d6 100644
---
a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientOutgoingEnvelope.java
+++
b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientOutgoingEnvelope.java
@@ -112,10 +112,19 @@ public class ClientOutgoingEnvelope {
this.delivery = delivery;
}
+ /**
+ * @return the {@link ScheduledFuture} used to determine when the send
should fail if no credit available to write.
+ */
public ScheduledFuture<?> sendTimeout() {
return sendTimeout;
}
+ /**
+ * Sets the {@link ScheduledFuture} which should be used when a send
cannot be immediately performed.
+ *
+ * @param sendTimeout
+ * The {@link ScheduledFuture} that will fail the send if
not cancelled once it has been performed.
+ */
public void sendTimeout(ScheduledFuture<?> sendTimeout) {
this.sendTimeout = sendTimeout;
}
diff --git
a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientRedirect.java
b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientRedirect.java
index 3a41dcc..278b985 100644
---
a/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientRedirect.java
+++
b/protonj2-client/src/main/java/org/apache/qpid/protonj2/client/impl/ClientRedirect.java
@@ -46,6 +46,13 @@ public final class ClientRedirect {
this.redirect = redirect;
}
+ /**
+ * Validate the information conveyed in the redirect and signal an error
if it is invalid.
+ *
+ * @return this {@link ClientRedirect} instance which can be assumed
carries valid data.
+ *
+ * @throws Exception if an error occurs during validation of the redirect
payload.
+ */
public ClientRedirect validate() throws Exception {
String networkHost = (String) redirect.get(NETWORK_HOST);
if (networkHost == null || networkHost.isEmpty()) {
diff --git
a/protonj2-test-driver/src/main/java/org/apache/qpid/protonj2/test/driver/AMQPTestDriver.java
b/protonj2-test-driver/src/main/java/org/apache/qpid/protonj2/test/driver/AMQPTestDriver.java
index 71cd3a5..b339174 100644
---
a/protonj2-test-driver/src/main/java/org/apache/qpid/protonj2/test/driver/AMQPTestDriver.java
+++
b/protonj2-test-driver/src/main/java/org/apache/qpid/protonj2/test/driver/AMQPTestDriver.java
@@ -128,22 +128,40 @@ public class AMQPTestDriver implements
Consumer<ByteBuffer> {
//----- View the test driver state
+ /**
+ * @return the idle timeout value that will be set on outgoing Open frames.
+ */
public int getAdvertisedIdleTimeout() {
return advertisedIdleTimeout;
}
+ /**
+ * Sets the idle timeout which the test driver should supply to remote in
its Open frame.
+ *
+ * @param advertisedIdleTimeout
+ * The idle timeout value to supply to remote peers.
+ */
public void setAdvertisedIdleTimeout(int advertisedIdleTimeout) {
this.advertisedIdleTimeout = advertisedIdleTimeout;
}
+ /**
+ * @return the number of empty frames that the remote has sent for idle
timeout processing.
+ */
public int getEmptyFrameCount() {
return emptyFrameCount;
}
+ /**
+ * @return the number of performative frames that this test peer has
processed from incoming bytes.
+ */
public int getPerformativeCount() {
return performativeCount;
}
+ /**
+ * @return the number of SASL performative frames that this test peer has
processed from incoming bytes.
+ */
public int getSaslPerformativeCount() {
return saslPerformativeCount;
}
@@ -155,6 +173,12 @@ public class AMQPTestDriver implements
Consumer<ByteBuffer> {
return inboundMaxFrameSize;
}
+ /**
+ * Sets a limiting value on the size of incoming frames after which the
peer will signal an error.
+ *
+ * @param maxSize
+ * The maximum incoming frame size limit for this peer.
+ */
public void setInboundMaxFrameSize(int maxSize) {
this.inboundMaxFrameSize = maxSize;
}
@@ -166,6 +190,12 @@ public class AMQPTestDriver implements
Consumer<ByteBuffer> {
return outboundMaxFrameSize;
}
+ /**
+ * Sets a limiting value on the size of outgoing frames after which the
peer will signal an error.
+ *
+ * @param maxSize
+ * The maximum outgoing frame size limit for this peer.
+ */
public void setOutboundMaxFrameSize(int maxSize) {
this.outboundMaxFrameSize = maxSize;
}
@@ -177,6 +207,12 @@ public class AMQPTestDriver implements
Consumer<ByteBuffer> {
accept(Unpooled.wrappedBuffer(buffer));
}
+ /**
+ * Supply incoming bytes read to the test driver via an Netty {@link
ByteBuf} instance.
+ *
+ * @param buffer
+ * The Netty {@link ByteBuf} that contains new incoming
bytes read.
+ */
public void accept(ByteBuf buffer) {
LOG.trace("{} processing new inbound buffer of size: {}", driverName,
buffer.readableBytes());
@@ -281,6 +317,15 @@ public class AMQPTestDriver implements
Consumer<ByteBuffer> {
handlePerformative(HeartBeat.INSTANCE, channel, null);
}
+ /**
+ * Submits a new {@link ScriptedAction} which should be performed after
waiting for the
+ * given delay period in milliseconds.
+ *
+ * @param delay
+ * The time in milliseconds to wait before performing the
action
+ * @param action
+ * The action that should be performed after the given delay.
+ */
public synchronized void afterDelay(int delay, ScriptedAction action) {
Objects.requireNonNull(schedulerSupplier, "This driver cannot schedule
delayed events, no scheduler available");
ScheduledExecutorService scheduler = schedulerSupplier.get();
@@ -294,6 +339,11 @@ public class AMQPTestDriver implements
Consumer<ByteBuffer> {
//----- Test driver actions
+ /**
+ * Waits indefinitely for the scripted expectations and actions to be
performed. If the script
+ * execution encounters an error this method will throw an {@link
AssertionError} that describes
+ * the error.
+ */
public void waitForScriptToComplete() {
checkFailed();
@@ -318,6 +368,11 @@ public class AMQPTestDriver implements
Consumer<ByteBuffer> {
checkFailed();
}
+ /**
+ * Waits indefinitely for the scripted expectations and actions to be
performed. If the script
+ * execution encounters an error this method will not throw an {@link
AssertionError} that describes
+ * the error but simply ignore it and return.
+ */
public void waitForScriptToCompleteIgnoreErrors() {
ScriptCompleteAction possibleWait = null;
@@ -337,10 +392,28 @@ public class AMQPTestDriver implements
Consumer<ByteBuffer> {
}
}
+ /**
+ * Waits for the given amount of time for the scripted expectations and
actions to be performed. If
+ * the script execution encounters an error this method will throw an
{@link AssertionError} that
+ * describes the error.
+ *
+ * @param timeout
+ * The time in milliseconds to wait for the scripted
expectations to complete.
+ */
public void waitForScriptToComplete(long timeout) {
waitForScriptToComplete(timeout, TimeUnit.SECONDS);
}
+ /**
+ * Waits for the given amount of time for the scripted expectations and
actions to be performed. If
+ * the script execution encounters an error this method will throw an
{@link AssertionError} that
+ * describes the error.
+ *
+ * @param timeout
+ * The time to wait for the scripted expectations to
complete.
+ * @param units
+ * The {@link TimeUnit} instance that converts the given
time value.
+ */
public void waitForScriptToComplete(long timeout, TimeUnit units) {
checkFailed();
@@ -365,6 +438,13 @@ public class AMQPTestDriver implements
Consumer<ByteBuffer> {
checkFailed();
}
+ /**
+ * Adds the script element to the list of scripted expectations and
actions that should occur
+ * in order to complete the test outcome.
+ *
+ * @param element
+ * The element to add to the script.
+ */
public void addScriptedElement(ScriptedElement element) {
checkFailed();
synchronized (script) {
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/AbstractBinaryTypeDecoder.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/AbstractBinaryTypeDecoder.java
index db70da1..0b5967d 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/AbstractBinaryTypeDecoder.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/AbstractBinaryTypeDecoder.java
@@ -23,6 +23,7 @@ import org.apache.qpid.protonj2.buffer.ProtonBuffer;
import org.apache.qpid.protonj2.buffer.ProtonByteBufferAllocator;
import org.apache.qpid.protonj2.codec.DecodeException;
import org.apache.qpid.protonj2.codec.DecoderState;
+import org.apache.qpid.protonj2.codec.EncoderState;
import org.apache.qpid.protonj2.codec.StreamDecoderState;
import org.apache.qpid.protonj2.codec.decoders.AbstractPrimitiveTypeDecoder;
import org.apache.qpid.protonj2.types.Binary;
@@ -37,6 +38,18 @@ public abstract class AbstractBinaryTypeDecoder extends
AbstractPrimitiveTypeDec
return new Binary(readValueAsBuffer(buffer, state));
}
+ /**
+ * Read and decode an AMQP {@link Binary} into a {@link ProtonBuffer}
instance and return it.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the {@link Binary}
encoding should be read from.
+ * @param state
+ * The {@link EncoderState} that can be used when reading
the encoded value.
+ *
+ * @return the bytes that comprise the encoded Binary wrapped in a {@link
ProtonBuffer} instance.
+ *
+ * @throws DecodeException if an error occurs while reading the Binary
value.
+ */
public ProtonBuffer readValueAsBuffer(ProtonBuffer buffer, DecoderState
state) throws DecodeException {
final int length = readSize(buffer);
@@ -53,6 +66,18 @@ public abstract class AbstractBinaryTypeDecoder extends
AbstractPrimitiveTypeDec
return payload;
}
+ /**
+ * Read and decode an AMQP {@link Binary} into a byte array instance and
return it.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the {@link Binary}
encoding should be read from.
+ * @param state
+ * The {@link EncoderState} that can be used when reading
the encoded value.
+ *
+ * @return the bytes that comprise the encoded Binary copied into a byte
array instance.
+ *
+ * @throws DecodeException if an error occurs while reading the Binary
value.
+ */
public byte[] readValueAsArray(ProtonBuffer buffer, DecoderState state)
throws DecodeException {
final int length = readSize(buffer);
@@ -74,10 +99,34 @@ public abstract class AbstractBinaryTypeDecoder extends
AbstractPrimitiveTypeDec
return new Binary(readValueAsBuffer(stream, state));
}
+ /**
+ * Read and decode an AMQP {@link Binary} into a {@link ProtonBuffer}
instance and return it.
+ *
+ * @param stream
+ * The {@link InputStream} where the {@link Binary}
encoding should be read from.
+ * @param state
+ * The {@link EncoderState} that can be used when reading
the encoded value.
+ *
+ * @return the bytes that comprise the encoded Binary wrapped in a {@link
ProtonBuffer} instance.
+ *
+ * @throws DecodeException if an error occurs while reading the Binary
value.
+ */
public ProtonBuffer readValueAsBuffer(InputStream stream,
StreamDecoderState state) throws DecodeException {
return ProtonByteBufferAllocator.DEFAULT.wrap(readValueAsArray(stream,
state));
}
+ /**
+ * Read and decode an AMQP {@link Binary} into a byte array instance and
return it.
+ *
+ * @param stream
+ * The {@link InputStream} where the {@link Binary}
encoding should be read from.
+ * @param state
+ * The {@link EncoderState} that can be used when reading
the encoded value.
+ *
+ * @return the bytes that comprise the encoded Binary copied into a byte
array instance.
+ *
+ * @throws DecodeException if an error occurs while reading the Binary
value.
+ */
public byte[] readValueAsArray(InputStream stream, StreamDecoderState
state) throws DecodeException {
final int length = readSize(stream);
final byte[] payload = new byte[length];
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/ArrayTypeEncoder.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/ArrayTypeEncoder.java
index f98d7ad..70c7f93 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/ArrayTypeEncoder.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/ArrayTypeEncoder.java
@@ -166,41 +166,121 @@ public final class ArrayTypeEncoder implements
PrimitiveTypeEncoder<Object> {
//----- Write methods for primitive arrays
-------------------------------//
+ /**
+ * Encodes the given array into the provided buffer for transmission.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the array encoding
should be written.
+ * @param state
+ * The {@link EncoderState} which can be used when encoding the array
elements.
+ * @param value
+ * The array that should be encoded using this {@link
ArrayTypeEncoder}.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, boolean[]
value) {
final BooleanTypeEncoder typeEncoder = (BooleanTypeEncoder)
state.getEncoder().getTypeEncoder(Boolean.class);
typeEncoder.writeArray(buffer, state, value);
}
+ /**
+ * Encodes the given array into the provided buffer for transmission.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the array encoding
should be written.
+ * @param state
+ * The {@link EncoderState} which can be used when encoding the array
elements.
+ * @param value
+ * The array that should be encoded using this {@link
ArrayTypeEncoder}.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, byte[]
value) {
final ByteTypeEncoder typeEncoder = (ByteTypeEncoder)
state.getEncoder().getTypeEncoder(Byte.class);
typeEncoder.writeArray(buffer, state, value);
}
+ /**
+ * Encodes the given array into the provided buffer for transmission.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the array encoding
should be written.
+ * @param state
+ * The {@link EncoderState} which can be used when encoding the array
elements.
+ * @param value
+ * The array that should be encoded using this {@link
ArrayTypeEncoder}.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, short[]
value) {
final ShortTypeEncoder typeEncoder = (ShortTypeEncoder)
state.getEncoder().getTypeEncoder(Short.class);
typeEncoder.writeArray(buffer, state, value);
}
+ /**
+ * Encodes the given array into the provided buffer for transmission.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the array encoding
should be written.
+ * @param state
+ * The {@link EncoderState} which can be used when encoding the array
elements.
+ * @param value
+ * The array that should be encoded using this {@link
ArrayTypeEncoder}.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, int[]
value) {
final IntegerTypeEncoder typeEncoder = (IntegerTypeEncoder)
state.getEncoder().getTypeEncoder(Integer.class);
typeEncoder.writeArray(buffer, state, value);
}
+ /**
+ * Encodes the given array into the provided buffer for transmission.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the array encoding
should be written.
+ * @param state
+ * The {@link EncoderState} which can be used when encoding the array
elements.
+ * @param value
+ * The array that should be encoded using this {@link
ArrayTypeEncoder}.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, long[]
value) {
final LongTypeEncoder typeEncoder = (LongTypeEncoder)
state.getEncoder().getTypeEncoder(Long.class);
typeEncoder.writeArray(buffer, state, value);
}
+ /**
+ * Encodes the given array into the provided buffer for transmission.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the array encoding
should be written.
+ * @param state
+ * The {@link EncoderState} which can be used when encoding the array
elements.
+ * @param value
+ * The array that should be encoded using this {@link
ArrayTypeEncoder}.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, float[]
value) {
final FloatTypeEncoder typeEncoder = (FloatTypeEncoder)
state.getEncoder().getTypeEncoder(Float.class);
typeEncoder.writeArray(buffer, state, value);
}
+ /**
+ * Encodes the given array into the provided buffer for transmission.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the array encoding
should be written.
+ * @param state
+ * The {@link EncoderState} which can be used when encoding the array
elements.
+ * @param value
+ * The array that should be encoded using this {@link
ArrayTypeEncoder}.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, double[]
value) {
final DoubleTypeEncoder typeEncoder = (DoubleTypeEncoder)
state.getEncoder().getTypeEncoder(Double.class);
typeEncoder.writeArray(buffer, state, value);
}
+ /**
+ * Encodes the given array into the provided buffer for transmission.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the array encoding
should be written.
+ * @param state
+ * The {@link EncoderState} which can be used when encoding the array
elements.
+ * @param value
+ * The array that should be encoded using this {@link
ArrayTypeEncoder}.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, char[]
value) {
final CharacterTypeEncoder typeEncoder = (CharacterTypeEncoder)
state.getEncoder().getTypeEncoder(Character.class);
typeEncoder.writeArray(buffer, state, value);
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/HeaderEnvelope.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/HeaderEnvelope.java
index 2b678f2..4329561 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/HeaderEnvelope.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/HeaderEnvelope.java
@@ -24,38 +24,78 @@ import
org.apache.qpid.protonj2.types.transport.AMQPHeader.HeaderHandler;
*/
public class HeaderEnvelope extends PerformativeEnvelope<AMQPHeader> {
+ /**
+ * The frame type marker used when decoding or encoding AMQP Header frames.
+ */
public static final byte HEADER_FRAME_TYPE = (byte) 1;
+ /**
+ * A singleton instance of an SASL header that can be used to avoid
additional allocations.
+ */
public static final HeaderEnvelope SASL_HEADER_ENVELOPE = new
HeaderEnvelope(AMQPHeader.getSASLHeader());
+ /**
+ * A singleton instance of an AMQP header that can be used to avoid
additional allocations.
+ */
public static final HeaderEnvelope AMQP_HEADER_ENVELOPE = new
HeaderEnvelope(AMQPHeader.getAMQPHeader());
+ /**
+ * Create an header envelope with the given AMQHeader body.
+ *
+ * @param body
+ * The AMQP header instance that holds the header bytes.
+ */
public HeaderEnvelope(AMQPHeader body) {
super(HEADER_FRAME_TYPE);
initialize(body, 0, null);
}
+ /**
+ * @return the protocol id value contained in the header bytes.
+ */
public int getProtocolId() {
return getBody().getProtocolId();
}
+ /**
+ * @return the major version number contained in the header bytes.
+ */
public int getMajor() {
return getBody().getMajor();
}
+ /**
+ * @return the minor version number contained in the header bytes.
+ */
public int getMinor() {
return getBody().getMinor();
}
+ /**
+ * @return the revision version number contained in the header bytes.
+ */
public int getRevision() {
return getBody().getRevision();
}
+ /**
+ * @return true if the contained header bytes represents a SASL header.
+ */
public boolean isSaslHeader() {
return getBody().isSaslHeader();
}
+ /**
+ * Invoke the correct handler based on whether this header is a SASL or
AMQP header instance.
+ *
+ * @param <E> The type of the context object that accompanies the
invocation.
+ *
+ * @param handler
+ * The {@link HeaderHandler} that should be invoked based
on the header type.
+ * @param context
+ * The context value to provide when signaling the header
handler.
+ */
public <E> void invoke(HeaderHandler<E> handler, E context) {
getBody().invoke(handler, context);
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/SASLEnvelope.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/SASLEnvelope.java
index ea87686..5c3bbf0 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/SASLEnvelope.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/SASLEnvelope.java
@@ -19,24 +19,52 @@ package org.apache.qpid.protonj2.engine;
import org.apache.qpid.protonj2.buffer.ProtonBuffer;
import org.apache.qpid.protonj2.types.security.SaslPerformative;
import
org.apache.qpid.protonj2.types.security.SaslPerformative.SaslPerformativeHandler;
+import org.apache.qpid.protonj2.types.transport.AMQPHeader.HeaderHandler;
/**
* Frame object containing a SASL performative
*/
public class SASLEnvelope extends PerformativeEnvelope<SaslPerformative>{
+ /**
+ * The frame type marker used when decoding or encoding AMQP Header frames.
+ */
public static final byte SASL_FRAME_TYPE = (byte) 1;
+ /**
+ * Creates a new SASL envelope that wraps the given SASL performative.
+ *
+ * @param performative
+ * The SASL performative to be wrapped.
+ */
public SASLEnvelope(SaslPerformative performative) {
this(performative, null);
}
+ /**
+ * Creates a new SASL envelope that wraps the given SASL performative.
+ *
+ * @param performative
+ * The SASL performative to be wrapped.
+ * @param payload
+ * The payload that accompanies the wrapped SASL
performative.
+ */
public SASLEnvelope(SaslPerformative performative, ProtonBuffer payload) {
super(SASL_FRAME_TYPE);
initialize(performative, 0, payload);
}
+ /**
+ * Invoke the correct handler based on the SASL performative contained in
this envelope.
+ *
+ * @param <E> The type of the context object that accompanies the
invocation.
+ *
+ * @param handler
+ * The {@link HeaderHandler} that should be invoked based
on the performative type.
+ * @param context
+ * The context value to provide when signaling the SASL
handler.
+ */
public <E> void invoke(SaslPerformativeHandler<E> handler, E context) {
getBody().invoke(handler, context);
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/Transaction.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/Transaction.java
index 0f47295..bef8b56 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/Transaction.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/Transaction.java
@@ -27,9 +27,24 @@ import
org.apache.qpid.protonj2.types.transport.ErrorCondition;
*/
public interface Transaction<E extends Endpoint<?>> {
+ /**
+ * Provides state for this {@link Transaction}.
+ */
public enum DischargeState {
+
+ /**
+ * The transaction is live and has not yet been committed or rolled
back.
+ */
NONE,
+
+ /**
+ * The transaction has been committed and cannot be rolled back.
+ */
COMMIT,
+
+ /**
+ * The transaction has been rolled back and cannot be committed.
+ */
ROLLBACK
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonPooledTagGenerator.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonPooledTagGenerator.java
index 6b46c76..69e0e66 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonPooledTagGenerator.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonPooledTagGenerator.java
@@ -30,15 +30,27 @@ import org.apache.qpid.protonj2.types.DeliveryTag;
*/
public class ProtonPooledTagGenerator extends ProtonSequentialTagGenerator {
+ /**
+ * The default number of pooled transfer tags for this generator.
+ */
public static final int DEFAULT_MAX_NUM_POOLED_TAGS = 512;
private final int tagPoolSize;
private final Queue<ProtonPooledDeliveryTag> tagPool;
+ /**
+ * Creates a new {@link ProtonPooledTagGenerator} instance with the
default pool size.
+ */
public ProtonPooledTagGenerator() {
this(DEFAULT_MAX_NUM_POOLED_TAGS);
}
+ /**
+ * Creates a new {@link ProtonPooledTagGenerator} instance with the given
pool size.
+ *
+ * @param poolSize
+ * The size of the transfer tag pool that should be
allocated for this generator.
+ */
public ProtonPooledTagGenerator(int poolSize) {
if (poolSize == 0) {
throw new IllegalArgumentException("Cannot create a tag pool with
zero pool size");
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonSession.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonSession.java
index 7e79a4b..329fcb1 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonSession.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonSession.java
@@ -86,6 +86,14 @@ public class ProtonSession extends ProtonEndpoint<Session>
implements Session {
private EventHandler<Receiver> remoteReceiverOpenEventHandler;
private EventHandler<TransactionManager> remoteTxnManagerOpenEventHandler;
+ /**
+ * Creates a new {@link ProtonSession} instance bound to the given {@link
ProtonConnection}.
+ *
+ * @param connection
+ * The connection that is the parent of the session
instance.
+ * @param localChannel
+ * The local channel onto which this session is bound.
+ */
public ProtonSession(ProtonConnection connection, int localChannel) {
super(connection.getEngine());
@@ -111,10 +119,16 @@ public class ProtonSession extends
ProtonEndpoint<Session> implements Session {
return connection;
}
+ /**
+ * @return the local channel onto which this {@link Session} is bound.
+ */
public int getLocalChannel() {
return localChannel;
}
+ /**
+ * @return the remote channel onto which this {@link Session} is bound or
-1 if not yet remotely opened.
+ */
public int getRemoteChannel() {
return remoteBegin != null ? remoteBegin.getRemoteChannel() : -1;
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/AnonymousMechanism.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/AnonymousMechanism.java
index 406e1f8..728155d 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/AnonymousMechanism.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/AnonymousMechanism.java
@@ -23,6 +23,9 @@ import org.apache.qpid.protonj2.types.Symbol;
*/
public class AnonymousMechanism extends AbstractMechanism {
+ /**
+ * A singleton instance of the symbolic mechanism name.
+ */
public static final Symbol ANONYMOUS = Symbol.valueOf("ANONYMOUS");
@Override
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/CramMD5Mechanism.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/CramMD5Mechanism.java
index 6234e00..624b733 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/CramMD5Mechanism.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/CramMD5Mechanism.java
@@ -33,6 +33,9 @@ import org.apache.qpid.protonj2.types.Symbol;
*/
public class CramMD5Mechanism extends AbstractMechanism {
+ /**
+ * A singleton instance of the symbolic mechanism name.
+ */
public static final Symbol CRAM_MD5 = Symbol.valueOf("CRAM-MD5");
private static final String ASCII = "ASCII";
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/ExternalMechanism.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/ExternalMechanism.java
index f032059..4fefb43 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/ExternalMechanism.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/ExternalMechanism.java
@@ -23,6 +23,9 @@ import org.apache.qpid.protonj2.types.Symbol;
*/
public class ExternalMechanism extends AbstractMechanism {
+ /**
+ * A singleton instance of the symbolic mechanism name.
+ */
public static final Symbol EXTERNAL = Symbol.valueOf("EXTERNAL");
@Override
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/PlainMechanism.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/PlainMechanism.java
index 363507a..bf90bf0 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/PlainMechanism.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/PlainMechanism.java
@@ -31,6 +31,9 @@ import org.apache.qpid.protonj2.types.Symbol;
*/
public class PlainMechanism extends AbstractMechanism {
+ /**
+ * A singleton instance of the symbolic mechanism name.
+ */
public static final Symbol PLAIN = Symbol.valueOf("PLAIN");
@Override
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/SaslCredentialsProvider.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/SaslCredentialsProvider.java
index f055f6e..ab9ce8a 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/SaslCredentialsProvider.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/SaslCredentialsProvider.java
@@ -26,14 +26,29 @@ import java.util.Map;
*/
public interface SaslCredentialsProvider {
+ /**
+ * @return the virtual host value to use when performing SASL
authentication.
+ */
String vhost();
+ /**
+ * @return the user name value to use when performing SASL authentication.
+ */
String username();
+ /**
+ * @return the password value to use when performing SASL authentication.
+ */
String password();
+ /**
+ * @return the local principal value to use when performing SASL
authentication.
+ */
Principal localPrincipal();
+ /**
+ * @return a {@link Map} of optional values to use when performing SASL
authentication.
+ */
@SuppressWarnings("unchecked")
default Map<String, Object> options() {
return Collections.EMPTY_MAP;
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/ScramSHA1Mechanism.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/ScramSHA1Mechanism.java
index d291277..dad4a58 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/ScramSHA1Mechanism.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/ScramSHA1Mechanism.java
@@ -28,8 +28,14 @@ public class ScramSHA1Mechanism extends
AbstractScramSHAMechanism {
public static final String SHA_1 = "SHA-1";
public static final String HMAC_SHA_1 = "HmacSHA1";
+ /**
+ * A singleton instance of the symbolic mechanism name.
+ */
public static final Symbol SCRAM_SHA_1 = Symbol.valueOf("SCRAM-SHA-1");
+ /**
+ * Creates an instance of the {@link ScramSHA1Mechanism} with a generated
client Nonce.
+ */
public ScramSHA1Mechanism() {
this(UUID.randomUUID().toString());
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/ScramSHA256Mechanism.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/ScramSHA256Mechanism.java
index 946f6be..7dd74da 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/ScramSHA256Mechanism.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/ScramSHA256Mechanism.java
@@ -28,8 +28,14 @@ public class ScramSHA256Mechanism extends
AbstractScramSHAMechanism {
public static final String SHA_256 = "SHA-256";
public static final String HMAC_SHA_256 = "HmacSHA256";
+ /**
+ * A singleton instance of the symbolic mechanism name.
+ */
public static final Symbol SCRAM_SHA_256 = Symbol.valueOf("SCRAM-SHA-256");
+ /**
+ * Creates an instance of the {@link ScramSHA256Mechanism} with a
generated client Nonce.
+ */
public ScramSHA256Mechanism() {
this(UUID.randomUUID().toString());
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/ScramSHA512Mechanism.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/ScramSHA512Mechanism.java
index 9a38a61..83836a5 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/ScramSHA512Mechanism.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/ScramSHA512Mechanism.java
@@ -28,8 +28,14 @@ public class ScramSHA512Mechanism extends
AbstractScramSHAMechanism {
public static final String SHA_512 = "SHA-512";
public static final String HMAC_SHA_512 = "HmacSHA512";
+ /**
+ * A singleton instance of the symbolic mechanism name.
+ */
public static final Symbol SCRAM_SHA_512 = Symbol.valueOf("SCRAM-SHA-512");
+ /**
+ * Creates an instance of the {@link ScramSHA512Mechanism} with a
generated client Nonce.
+ */
public ScramSHA512Mechanism() {
this(UUID.randomUUID().toString());
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/XOauth2Mechanism.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/XOauth2Mechanism.java
index 627cdb7..73f11e2 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/XOauth2Mechanism.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/XOauth2Mechanism.java
@@ -34,6 +34,9 @@ public class XOauth2Mechanism extends AbstractMechanism {
private final Pattern ACCESS_TOKEN_PATTERN =
Pattern.compile("^[\\x20-\\x7F]+$");
+ /**
+ * A singleton instance of the symbolic mechanism name.
+ */
public static final Symbol XOAUTH2 = Symbol.valueOf("XOAUTH2");
private String additionalFailureInformation;
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/util/SplayMap.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/util/SplayMap.java
index 925b131..358548c 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/util/SplayMap.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/util/SplayMap.java
@@ -105,6 +105,22 @@ public class SplayMap<E> implements
NavigableMap<UnsignedInteger, E> {
}
}
+ /**
+ * Puts the value into the in the {@link Map} at the entry specified by
the given key (treated as an
+ * unsigned integer for comparison.
+ *
+ * As a side effect of calling this method the tree that comprises the Map
can be modified
+ * to bring up the found key or the last accessed key if the key given is
not in the {@link Map}.
+ * For entries at the root of the tree that match the given search key the
method returns
+ * immediately without modifying the {@link Map}.
+ *
+ * @param key
+ * the integer key value to search for and or insert in the {@link
SplayMap}.
+ * @param value
+ * the value to assign to the entry accessed via the given key.
+ *
+ * @return the previous value stored for the given key if found or null if
not in the {@link Map}.
+ */
public E put(int key, E value) {
E oldValue = null;
@@ -140,6 +156,22 @@ public class SplayMap<E> implements
NavigableMap<UnsignedInteger, E> {
return putIfAbsent(key.intValue(), value);
}
+ /**
+ * If the specified key is not already associated with a value associates
it with the given value and
+ * returns null, otherwise returns the current value.
+ *
+ * As a side effect of calling this method the tree that comprises the Map
can be modified
+ * to bring up the found key or the last accessed key if the key given is
not in the {@link Map}.
+ * For entries at the root of the tree that match the given search key the
method returns
+ * immediately without modifying the {@link Map}.
+ *
+ * @param key
+ * the integer key value to search for and or insert in the {@link
SplayMap}.
+ * @param value
+ * the value to assign to the entry accessed via the given key.
+ *
+ * @return the previous value associated with the given key or null if
none was present.
+ */
public E putIfAbsent(int key, E value) {
if (root == null) {
root = entryPool.poll(SplayMap::createEmtry).initialize(key,
value);
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/types/transport/AmqpError.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/types/transport/AmqpError.java
index 0f8310f..2af95a8 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/types/transport/AmqpError.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/types/transport/AmqpError.java
@@ -18,6 +18,9 @@ package org.apache.qpid.protonj2.types.transport;
import org.apache.qpid.protonj2.types.Symbol;
+/**
+ * List of {@link Symbol} constants that provide the defined AMQP Error space.
+ */
public interface AmqpError {
/**
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/types/transport/Close.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/types/transport/Close.java
index 47652bd..bcc8417 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/types/transport/Close.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/types/transport/Close.java
@@ -20,17 +20,38 @@ import org.apache.qpid.protonj2.buffer.ProtonBuffer;
import org.apache.qpid.protonj2.types.Symbol;
import org.apache.qpid.protonj2.types.UnsignedLong;
+/**
+ * Defines an AMQP Close performative used to end AMQP Connection instances.
+ */
public final class Close implements Performative {
+ /**
+ * The {@link UnsignedLong} descriptor code that defines this AMQP type.
+ */
public static final UnsignedLong DESCRIPTOR_CODE =
UnsignedLong.valueOf(0x0000000000000018L);
+
+ /**
+ * The {@link Symbol} descriptor code that defines this AMQP type.
+ */
public static final Symbol DESCRIPTOR_SYMBOL =
Symbol.valueOf("amqp:close:list");
private ErrorCondition error;
+ /**
+ * @return the {@link ErrorCondition} conveyed in the {@link Close} or
null if non set.
+ */
public ErrorCondition getError() {
return error;
}
+ /**
+ * Sets the error that should be conveyed with the AMQP {@link Close}.
+ *
+ * @param error
+ * The {@link ErrorCondition} to convey with the {@link
Close} or null if none.
+ *
+ * @return this {@link Close} instance.
+ */
public Close setError(ErrorCondition error) {
this.error = error;
return this;
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/types/transport/DeliveryState.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/types/transport/DeliveryState.java
index c24860b..f770ef0 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/types/transport/DeliveryState.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/types/transport/DeliveryState.java
@@ -24,6 +24,9 @@ package org.apache.qpid.protonj2.types.transport;
*/
public interface DeliveryState {
+ /**
+ * An enumeration of the valid {@link DeliveryState} types that the
library can provide.
+ */
enum DeliveryStateType {
Accepted,
Declared,
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org
For additional commands, e-mail: commits-h...@qpid.apache.org
