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