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 777d46c Add additional API documentation for the types in the proton
engine
777d46c is described below
commit 777d46c25c4c5297163620a3a172cac80b06c84d
Author: Timothy Bish <[email protected]>
AuthorDate: Fri May 7 13:35:19 2021 -0400
Add additional API documentation for the types in the proton engine
---
.../org/apache/qpid/protonj2/codec/Decoder.java | 664 ++++++++++++++++++++
.../apache/qpid/protonj2/codec/EncodingCodes.java | 13 +
.../apache/qpid/protonj2/codec/StreamDecoder.java | 668 ++++++++++++++++++++-
.../decoders/primitives/BooleanTypeDecoder.java | 24 +
.../codec/decoders/primitives/ByteTypeDecoder.java | 24 +
.../decoders/primitives/CharacterTypeDecoder.java | 24 +
.../decoders/primitives/DoubleTypeDecoder.java | 24 +
.../decoders/primitives/FloatTypeDecoder.java | 24 +
.../decoders/primitives/Integer32TypeDecoder.java | 24 +
.../decoders/primitives/Integer8TypeDecoder.java | 24 +
.../codec/decoders/primitives/ListTypeDecoder.java | 53 ++
.../codec/decoders/primitives/LongTypeDecoder.java | 24 +
.../decoders/primitives/ShortTypeDecoder.java | 24 +
.../engine/impl/ProtonEngineHandlerContext.java | 30 +
.../engine/impl/ProtonEngineNoOpSaslDriver.java | 6 +
.../engine/impl/ProtonFrameDecodingHandler.java | 10 +
.../engine/impl/ProtonFrameEncodingHandler.java | 7 +
.../engine/impl/ProtonOutgoingDelivery.java | 8 +
.../engine/impl/ProtonTransactionController.java | 6 +
.../engine/impl/ProtonTransactionManager.java | 6 +
.../engine/impl/sasl/ProtonSaslHandler.java | 3 +
.../qpid/protonj2/engine/sasl/SaslContext.java | 3 +
.../qpid/protonj2/engine/sasl/SaslOutcome.java | 3 +
.../engine/sasl/client/SaslAuthenticator.java | 9 +
24 files changed, 1703 insertions(+), 2 deletions(-)
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 b712060..257bb04 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
@@ -63,66 +63,559 @@ public interface Decoder {
*/
DecoderState getCachedDecoderState();
+ /**
+ * Reads an encoded {@link Boolean} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Boolean readBoolean(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Byte} value from the given {@link ProtonBuffer}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
boolean readBoolean(ProtonBuffer buffer, DecoderState state, boolean
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link Byte} value from the given {@link ProtonBuffer}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Byte readByte(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Byte} value from the given {@link ProtonBuffer}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
byte readByte(ProtonBuffer buffer, DecoderState state, byte defaultValue)
throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedByte} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
UnsignedByte readUnsignedByte(ProtonBuffer buffer, DecoderState state)
throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedByte} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
byte readUnsignedByte(ProtonBuffer buffer, DecoderState state, byte
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link Character} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Character readCharacter(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Character} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
char readCharacter(ProtonBuffer buffer, DecoderState state, char
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link Decimal32} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Decimal32 readDecimal32(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Decimal64} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Decimal64 readDecimal64(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Decimal128} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Decimal128 readDecimal128(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Short} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Short readShort(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Short} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
short readShort(ProtonBuffer buffer, DecoderState state, short
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedShort} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
UnsignedShort readUnsignedShort(ProtonBuffer buffer, DecoderState state)
throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedShort} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
short readUnsignedShort(ProtonBuffer buffer, DecoderState state, short
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedShort} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
int readUnsignedShort(ProtonBuffer buffer, DecoderState state, int
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link Integer} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Integer readInteger(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Integer} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
int readInteger(ProtonBuffer buffer, DecoderState state, int defaultValue)
throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedInteger} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
UnsignedInteger readUnsignedInteger(ProtonBuffer buffer, DecoderState
state) throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedInteger} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
int readUnsignedInteger(ProtonBuffer buffer, DecoderState state, int
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedInteger} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
long readUnsignedInteger(ProtonBuffer buffer, DecoderState state, long
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link Long} value from the given {@link ProtonBuffer}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Long readLong(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Long} value from the given {@link ProtonBuffer}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
long readLong(ProtonBuffer buffer, DecoderState state, long defaultValue)
throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedLong} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
UnsignedLong readUnsignedLong(ProtonBuffer buffer, DecoderState state)
throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedLong} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
long readUnsignedLong(ProtonBuffer buffer, DecoderState state, long
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link Float} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Float readFloat(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Float} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
float readFloat(ProtonBuffer buffer, DecoderState state, float
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link Double} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Double readDouble(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Double} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
double readDouble(ProtonBuffer buffer, DecoderState state, double
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link Binary} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Binary readBinary(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Binary} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source and returned in a
{@link ProtonBuffer}.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
ProtonBuffer readBinaryAsBuffer(ProtonBuffer buffer, DecoderState state)
throws DecodeException;
/**
@@ -141,26 +634,197 @@ public interface Decoder {
*/
DeliveryTag readDeliveryTag(ProtonBuffer buffer, DecoderState state)
throws DecodeException;
+ /**
+ * Reads an encoded {@link String} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
String readString(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Symbol} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Symbol readSymbol(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link String} value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
String readSymbol(ProtonBuffer buffer, DecoderState state, String
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded AMQP time stamp value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source and return a
{@link Long} with the time value.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Long readTimestamp(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded AMQP time stamp value from the given {@link
ProtonBuffer} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
long readTimestamp(ProtonBuffer buffer, DecoderState state, long
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link UUID} value from the given {@link ProtonBuffer}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
UUID readUUID(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded value from the given {@link ProtonBuffer} an return it
as an {@link Object}
+ * which the caller must then interpret.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not able to be
decoded.
+ */
Object readObject(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded value from the given {@link ProtonBuffer} an return it
as an {@link Object}
+ * which the caller must then interpret.
+ *
+ * @param <T> the type that will be used when casting and returning the
decoded value.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param clazz
+ * The {@link Class} type that should be used to cast the
returned value.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not able to be
decoded.
+ */
<T> T readObject(ProtonBuffer buffer, DecoderState state, final Class<T>
clazz) throws DecodeException;
+ /**
+ * Reads one or more encoded values from the given {@link ProtonBuffer} an
return it as an array of
+ * {@link Object} instances which the caller must then interpret.
+ *
+ * @param <T> the type that will be used when casting and returning the
decoded value.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param clazz
+ * The {@link Class} type that should be used to cast the
returned array.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not able to be
decoded.
+ */
<T> T[] readMultiple(ProtonBuffer buffer, DecoderState state, final
Class<T> clazz) throws DecodeException;
+ /**
+ * Reads an encoded {@link Map} value from the given {@link ProtonBuffer}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
<K,V> Map<K, V> readMap(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link List} value from the given {@link ProtonBuffer}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 buffer
+ * The {@link ProtonBuffer} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
<V> List<V> readList(ProtonBuffer buffer, DecoderState state) throws
DecodeException;
/**
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/EncodingCodes.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/EncodingCodes.java
index dd6bba3..5ba6d46 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/EncodingCodes.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/EncodingCodes.java
@@ -16,6 +16,10 @@
*/
package org.apache.qpid.protonj2.codec;
+/**
+ * Provides a set of definitions for the byte value that indicates what the
next
+ * AMQP encoding will be when encoding or decoding AMQP types.
+ */
public interface EncodingCodes {
public static final byte DESCRIBED_TYPE_INDICATOR = (byte) 0x00;
@@ -83,6 +87,15 @@ public interface EncodingCodes {
public static final byte ARRAY8 = (byte) 0xe0;
public static final byte ARRAY32 = (byte) 0xf0;
+ /**
+ * Returns a human readable string that describes a given AMQP type
encoding value which can be
+ * used in logging or other informational contexts.
+ *
+ * @param encoding
+ * The ANMQP encoding code to be turned into a readable
string.
+ *
+ * @return a human readable view of an AMQP type encoding code.
+ */
static String toString(byte encoding) {
switch (encoding) {
case DESCRIBED_TYPE_INDICATOR:
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 c7aae5b..3502e1a 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
@@ -64,70 +64,563 @@ public interface StreamDecoder {
*/
StreamDecoderState getCachedDecoderState();
+ /**
+ * Reads an encoded {@link Boolean} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Boolean readBoolean(InputStream stream, StreamDecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Byte} value from the given {@link InputStream}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
boolean readBoolean(InputStream stream, StreamDecoderState state, boolean
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link Byte} value from the given {@link InputStream}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Byte readByte(InputStream stream, StreamDecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Byte} value from the given {@link InputStream}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
byte readByte(InputStream stream, StreamDecoderState state, byte
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedByte} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
UnsignedByte readUnsignedByte(InputStream stream, StreamDecoderState
state) throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedByte} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
byte readUnsignedByte(InputStream stream, StreamDecoderState state, byte
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link Character} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Character readCharacter(InputStream stream, StreamDecoderState state)
throws DecodeException;
+ /**
+ * Reads an encoded {@link Character} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
char readCharacter(InputStream stream, StreamDecoderState state, char
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link Decimal32} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Decimal32 readDecimal32(InputStream stream, StreamDecoderState state)
throws DecodeException;
+ /**
+ * Reads an encoded {@link Decimal64} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Decimal64 readDecimal64(InputStream stream, StreamDecoderState state)
throws DecodeException;
+ /**
+ * Reads an encoded {@link Decimal128} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Decimal128 readDecimal128(InputStream stream, StreamDecoderState state)
throws DecodeException;
+ /**
+ * Reads an encoded {@link Short} value from the given {@link InputStream}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Short readShort(InputStream stream, StreamDecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Short} value from the given {@link InputStream}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
short readShort(InputStream stream, StreamDecoderState state, short
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedShort} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
UnsignedShort readUnsignedShort(InputStream stream, StreamDecoderState
state) throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedShort} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
short readUnsignedShort(InputStream stream, StreamDecoderState state,
short defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedShort} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
int readUnsignedShort(InputStream stream, StreamDecoderState state, int
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link Integer} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Integer readInteger(InputStream stream, StreamDecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Integer} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
int readInteger(InputStream stream, StreamDecoderState state, int
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedInteger} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
UnsignedInteger readUnsignedInteger(InputStream stream, StreamDecoderState
state) throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedInteger} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
int readUnsignedInteger(InputStream stream, StreamDecoderState state, int
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedInteger} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
long readUnsignedInteger(InputStream stream, StreamDecoderState state,
long defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link Long} value from the given {@link InputStream}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Long readLong(InputStream stream, StreamDecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Long} value from the given {@link InputStream}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
long readLong(InputStream stream, StreamDecoderState state, long
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedLong} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
UnsignedLong readUnsignedLong(InputStream stream, StreamDecoderState
state) throws DecodeException;
+ /**
+ * Reads an encoded {@link UnsignedLong} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
long readUnsignedLong(InputStream stream, StreamDecoderState state, long
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link Float} value from the given {@link InputStream}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Float readFloat(InputStream stream, StreamDecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Float} value from the given {@link InputStream}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
float readFloat(InputStream stream, StreamDecoderState state, float
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link Double} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Double readDouble(InputStream stream, StreamDecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Double} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
double readDouble(InputStream stream, StreamDecoderState state, double
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link Binary} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Binary readBinary(InputStream stream, StreamDecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Binary} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source and returned in a
{@link ProtonBuffer}.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
ProtonBuffer readBinaryAsBuffer(InputStream stream, StreamDecoderState
state) throws DecodeException;
/**
- * This method expects to read a {@link Binary} encoded type from the
provided buffer and
+ * This method expects to read a {@link Binary} encoded type from the
provided stream and
* constructs a {@link DeliveryTag} type that wraps the bytes encoded. If
the encoding is
* a NULL AMQP type then this method returns <code>null</code>.
*
@@ -142,26 +635,197 @@ public interface StreamDecoder {
*/
DeliveryTag readDeliveryTag(InputStream stream, StreamDecoderState state)
throws DecodeException;
+ /**
+ * Reads an encoded {@link String} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
String readString(InputStream stream, StreamDecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link Symbol} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Symbol readSymbol(InputStream stream, StreamDecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded {@link String} value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
String readSymbol(InputStream stream, StreamDecoderState state, String
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded AMQP time stamp value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source and return a
{@link Long} with the time value.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
Long readTimestamp(InputStream stream, StreamDecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded AMQP time stamp value from the given {@link
InputStream} assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param defaultValue
+ * A default value to return if the next encoded value is
a Null encoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
long readTimestamp(InputStream stream, StreamDecoderState state, long
defaultValue) throws DecodeException;
+ /**
+ * Reads an encoded {@link UUID} value from the given {@link InputStream}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
UUID readUUID(InputStream stream, StreamDecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded value from the given {@link InputStream} an return it
as an {@link Object}
+ * which the caller must then interpret.
+ *
+ * @param stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not able to be
decoded.
+ */
Object readObject(InputStream stream, StreamDecoderState state) throws
DecodeException;
+ /**
+ * Reads an encoded value from the given {@link InputStream} an return it
as an {@link Object}
+ * which the caller must then interpret.
+ *
+ * @param <T> the type that will be used when casting and returning the
decoded value.
+ *
+ * @param stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param clazz
+ * The {@link Class} type that should be used to cast the
returned value.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not able to be
decoded.
+ */
<T> T readObject(InputStream stream, StreamDecoderState state, final
Class<T> clazz) throws DecodeException;
+ /**
+ * Reads one or more encoded values from the given {@link InputStream} an
return it as an array of
+ * {@link Object} instances which the caller must then interpret.
+ *
+ * @param <T> the type that will be used when casting and returning the
decoded value.
+ *
+ * @param stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ * @param clazz
+ * The {@link Class} type that should be used to cast the
returned array.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not able to be
decoded.
+ */
<T> T[] readMultiple(InputStream stream, StreamDecoderState state, final
Class<T> clazz) throws DecodeException;
+ /**
+ * Reads an encoded {@link Map} value from the given {@link InputStream}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
<K,V> Map<K, V> readMap(InputStream stream, StreamDecoderState state)
throws DecodeException;
+ /**
+ * Reads an encoded {@link List} value from the given {@link InputStream}
assuming that the
+ * next value in the byte stream is that type. The operation fails if the
next encoded type is
+ * 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 stream
+ * The {@link InputStream} where the read operation takes
place.
+ * @param state
+ * The {@link DecoderState} that the decoder can use when
decoding.
+ *
+ * @return the value read from the provided byte source.
+ *
+ * @throws DecodeException if the value fails to decode is not of the
expected type,
+ */
<V> List<V> readList(InputStream stream, StreamDecoderState state) throws
DecodeException;
/**
@@ -174,7 +838,7 @@ public interface StreamDecoder {
* @param state
* The {@link DecoderState} value that can be used for intermediate
decoding tasks.
*
- * @return a {@link StreamTypeDecoder} instance that can read the next
type in the buffer.
+ * @return a {@link StreamTypeDecoder} instance that can read the next
type in the stream.
*
* @throws DecodeException if an error occurs while reading the next type
decoder.
*/
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/BooleanTypeDecoder.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/BooleanTypeDecoder.java
index 4824258..00e48f4 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/BooleanTypeDecoder.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/BooleanTypeDecoder.java
@@ -56,10 +56,34 @@ public class BooleanTypeDecoder extends
AbstractPrimitiveTypeDecoder<Boolean> {
return ProtonStreamUtils.readByte(stream) == 0 ? Boolean.FALSE :
Boolean.TRUE;
}
+ /**
+ * Reads the primitive value from the given {@link ProtonBuffer} and
returns it.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the primitive value
should be read from.
+ * @param state
+ * The {@link DecoderState} that can be used during decode
of the value.
+ *
+ * @return the decoded primitive value.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
value.
+ */
public boolean readPrimitiveValue(ProtonBuffer buffer, DecoderState state)
throws DecodeException {
return buffer.readByte() == 0 ? false : true;
}
+ /**
+ * Reads the primitive value from the given {@link InputStream} and
returns it.
+ *
+ * @param stream
+ * The {@link InputStream} where the primitive value
should be read from.
+ * @param state
+ * The {@link DecoderState} that can be used during decode
of the value.
+ *
+ * @return the decoded primitive value.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
value.
+ */
public boolean readPrimitiveValue(InputStream stream, StreamDecoderState
state) throws DecodeException {
return ProtonStreamUtils.readByte(stream) == 0 ? false : true;
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/ByteTypeDecoder.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/ByteTypeDecoder.java
index 396b3d3..4c16cf5 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/ByteTypeDecoder.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/ByteTypeDecoder.java
@@ -56,10 +56,34 @@ public final class ByteTypeDecoder extends
AbstractPrimitiveTypeDecoder<Byte> {
return ProtonStreamUtils.readByte(stream);
}
+ /**
+ * Reads the primitive value from the given {@link ProtonBuffer} and
returns it.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the primitive value
should be read from.
+ * @param state
+ * The {@link DecoderState} that can be used during decode
of the value.
+ *
+ * @return the decoded primitive value.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
value.
+ */
public byte readPrimitiveValue(ProtonBuffer buffer, DecoderState state)
throws DecodeException {
return buffer.readByte();
}
+ /**
+ * Reads the primitive value from the given {@link InputStream} and
returns it.
+ *
+ * @param stream
+ * The {@link InputStream} where the primitive value
should be read from.
+ * @param state
+ * The {@link DecoderState} that can be used during decode
of the value.
+ *
+ * @return the decoded primitive value.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
value.
+ */
public byte readPrimitiveValue(InputStream stream, StreamDecoderState
state) throws DecodeException {
return ProtonStreamUtils.readByte(stream);
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/CharacterTypeDecoder.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/CharacterTypeDecoder.java
index 3c775ee..2908b5d 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/CharacterTypeDecoder.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/CharacterTypeDecoder.java
@@ -56,10 +56,34 @@ public final class CharacterTypeDecoder extends
AbstractPrimitiveTypeDecoder<Cha
return Character.valueOf((char) ProtonStreamUtils.readInt(stream));
}
+ /**
+ * Reads the primitive value from the given {@link ProtonBuffer} and
returns it.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the primitive value
should be read from.
+ * @param state
+ * The {@link DecoderState} that can be used during decode
of the value.
+ *
+ * @return the decoded primitive value.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
value.
+ */
public char readPrimitiveValue(ProtonBuffer buffer, DecoderState state)
throws DecodeException {
return (char) (buffer.readInt() & 0xffff);
}
+ /**
+ * Reads the primitive value from the given {@link InputStream} and
returns it.
+ *
+ * @param stream
+ * The {@link InputStream} where the primitive value
should be read from.
+ * @param state
+ * The {@link DecoderState} that can be used during decode
of the value.
+ *
+ * @return the decoded primitive value.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
value.
+ */
public char readPrimitiveValue(InputStream stream, StreamDecoderState
state) throws DecodeException {
return (char) ProtonStreamUtils.readInt(stream);
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/DoubleTypeDecoder.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/DoubleTypeDecoder.java
index 759e065..aaab305 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/DoubleTypeDecoder.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/DoubleTypeDecoder.java
@@ -56,10 +56,34 @@ public final class DoubleTypeDecoder extends
AbstractPrimitiveTypeDecoder<Double
return ProtonStreamUtils.readDouble(stream);
}
+ /**
+ * Reads the primitive value from the given {@link ProtonBuffer} and
returns it.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the primitive value
should be read from.
+ * @param state
+ * The {@link DecoderState} that can be used during decode
of the value.
+ *
+ * @return the decoded primitive value.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
value.
+ */
public double readPrimitiveValue(ProtonBuffer buffer, DecoderState state)
throws DecodeException {
return buffer.readDouble();
}
+ /**
+ * Reads the primitive value from the given {@link InputStream} and
returns it.
+ *
+ * @param stream
+ * The {@link InputStream} where the primitive value
should be read from.
+ * @param state
+ * The {@link DecoderState} that can be used during decode
of the value.
+ *
+ * @return the decoded primitive value.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
value.
+ */
public double readPrimitiveValue(InputStream stream, StreamDecoderState
state) throws DecodeException {
return ProtonStreamUtils.readDouble(stream);
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/FloatTypeDecoder.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/FloatTypeDecoder.java
index 71c8e5f..451a35b 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/FloatTypeDecoder.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/FloatTypeDecoder.java
@@ -56,10 +56,34 @@ public final class FloatTypeDecoder extends
AbstractPrimitiveTypeDecoder<Float>
return ProtonStreamUtils.readFloat(stream);
}
+ /**
+ * Reads the primitive value from the given {@link ProtonBuffer} and
returns it.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the primitive value
should be read from.
+ * @param state
+ * The {@link DecoderState} that can be used during decode
of the value.
+ *
+ * @return the decoded primitive value.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
value.
+ */
public float readPrimitiveValue(ProtonBuffer buffer, DecoderState state)
throws DecodeException {
return buffer.readFloat();
}
+ /**
+ * Reads the primitive value from the given {@link InputStream} and
returns it.
+ *
+ * @param stream
+ * The {@link InputStream} where the primitive value
should be read from.
+ * @param state
+ * The {@link DecoderState} that can be used during decode
of the value.
+ *
+ * @return the decoded primitive value.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
value.
+ */
public float readPrimitiveValue(InputStream stream, StreamDecoderState
state) throws DecodeException {
return ProtonStreamUtils.readFloat(stream);
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/Integer32TypeDecoder.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/Integer32TypeDecoder.java
index 12a2684..4c27999 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/Integer32TypeDecoder.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/Integer32TypeDecoder.java
@@ -56,10 +56,34 @@ public final class Integer32TypeDecoder extends
AbstractPrimitiveTypeDecoder<Int
return ProtonStreamUtils.readInt(stream);
}
+ /**
+ * Reads the primitive value from the given {@link ProtonBuffer} and
returns it.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the primitive value
should be read from.
+ * @param state
+ * The {@link DecoderState} that can be used during decode
of the value.
+ *
+ * @return the decoded primitive value.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
value.
+ */
public int readPrimitiveValue(ProtonBuffer buffer, DecoderState state)
throws DecodeException {
return buffer.readInt();
}
+ /**
+ * Reads the primitive value from the given {@link InputStream} and
returns it.
+ *
+ * @param stream
+ * The {@link InputStream} where the primitive value
should be read from.
+ * @param state
+ * The {@link DecoderState} that can be used during decode
of the value.
+ *
+ * @return the decoded primitive value.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
value.
+ */
public int readPrimitiveValue(InputStream stream, StreamDecoderState
state) throws DecodeException {
return ProtonStreamUtils.readInt(stream);
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/Integer8TypeDecoder.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/Integer8TypeDecoder.java
index 4ae4aec..a3fe524 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/Integer8TypeDecoder.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/Integer8TypeDecoder.java
@@ -46,10 +46,34 @@ public final class Integer8TypeDecoder extends
AbstractPrimitiveTypeDecoder<Inte
return true;
}
+ /**
+ * Reads the primitive value from the given {@link ProtonBuffer} and
returns it.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the primitive value
should be read from.
+ * @param state
+ * The {@link DecoderState} that can be used during decode
of the value.
+ *
+ * @return the decoded primitive value.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
value.
+ */
public int readPrimitiveValue(ProtonBuffer buffer, DecoderState state)
throws DecodeException {
return buffer.readByte();
}
+ /**
+ * Reads the primitive value from the given {@link InputStream} and
returns it.
+ *
+ * @param stream
+ * The {@link InputStream} where the primitive value
should be read from.
+ * @param state
+ * The {@link DecoderState} that can be used during decode
of the value.
+ *
+ * @return the decoded primitive value.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
value.
+ */
public int readPrimitiveValue(InputStream stream, StreamDecoderState
state) throws DecodeException {
return ProtonStreamUtils.readByte(stream);
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/ListTypeDecoder.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/ListTypeDecoder.java
index 3c43dae..184d597 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/ListTypeDecoder.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/ListTypeDecoder.java
@@ -21,6 +21,7 @@ import java.util.List;
import org.apache.qpid.protonj2.buffer.ProtonBuffer;
import org.apache.qpid.protonj2.codec.DecodeException;
+import org.apache.qpid.protonj2.codec.TypeDecoder;
import org.apache.qpid.protonj2.codec.decoders.PrimitiveTypeDecoder;
/**
@@ -29,12 +30,64 @@ import
org.apache.qpid.protonj2.codec.decoders.PrimitiveTypeDecoder;
@SuppressWarnings("rawtypes")
public interface ListTypeDecoder extends PrimitiveTypeDecoder<List> {
+ /**
+ * Reads the size in bytes of the encoded list from the provided {@link
ProtonBuffer}.
+ *
+ * The implementation must read the correct size encoding based on the
type of {@link List}
+ * that this {@link TypeDecoder} handles.
+ *
+ * @param buffer
+ * The buffer where the size value should be read from.
+ *
+ * @return an integer containing the size in bytes of the encoded {@link
List}.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
size.
+ */
int readSize(ProtonBuffer buffer) throws DecodeException;
+ /**
+ * Reads the number of elements contained in the encoded list from the
provided {@link ProtonBuffer}.
+ *
+ * The implementation must read the correct size encoding based on the
type of {@link List}
+ * that this {@link TypeDecoder} handles.
+ *
+ * @param buffer
+ * The buffer where the size value should be read from.
+ *
+ * @return an integer containing the number of elements in the encoded
{@link List}.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
element count.
+ */
int readCount(ProtonBuffer buffer) throws DecodeException;
+ /**
+ * Reads the size in bytes of the encoded list from the provided {@link
InputStream}.
+ *
+ * The implementation must read the correct size encoding based on the
type of {@link List}
+ * that this {@link TypeDecoder} handles.
+ *
+ * @param stream
+ * The stream where the size value should be read from.
+ *
+ * @return an integer containing the size in bytes of the encoded {@link
List}.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
size.
+ */
int readSize(InputStream stream) throws DecodeException;
+ /**
+ * Reads the number of elements contained in the encoded list from the
provided {@link InputStream}.
+ *
+ * The implementation must read the correct size encoding based on the
type of {@link List}
+ * that this {@link TypeDecoder} handles.
+ *
+ * @param stream
+ * The stream where the size value should be read from.
+ *
+ * @return an integer containing the number of elements in the encoded
{@link List}.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
element count.
+ */
int readCount(InputStream stream) throws DecodeException;
@Override
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/LongTypeDecoder.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/LongTypeDecoder.java
index 3226068..62f54c9 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/LongTypeDecoder.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/LongTypeDecoder.java
@@ -56,10 +56,34 @@ public class LongTypeDecoder extends
AbstractPrimitiveTypeDecoder<Long> {
return Long.valueOf(ProtonStreamUtils.readLong(stream));
}
+ /**
+ * Reads the primitive value from the given {@link ProtonBuffer} and
returns it.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the primitive value
should be read from.
+ * @param state
+ * The {@link DecoderState} that can be used during decode
of the value.
+ *
+ * @return the decoded primitive value.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
value.
+ */
public long readPrimitiveValue(ProtonBuffer buffer, DecoderState state)
throws DecodeException {
return buffer.readLong();
}
+ /**
+ * Reads the primitive value from the given {@link InputStream} and
returns it.
+ *
+ * @param stream
+ * The {@link InputStream} where the primitive value
should be read from.
+ * @param state
+ * The {@link DecoderState} that can be used during decode
of the value.
+ *
+ * @return the decoded primitive value.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
value.
+ */
public long readPrimitiveValue(InputStream stream, StreamDecoderState
state) throws DecodeException {
return ProtonStreamUtils.readLong(stream);
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/ShortTypeDecoder.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/ShortTypeDecoder.java
index d0b39bd..1ba9040 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/ShortTypeDecoder.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/primitives/ShortTypeDecoder.java
@@ -56,10 +56,34 @@ public final class ShortTypeDecoder extends
AbstractPrimitiveTypeDecoder<Short>
return Short.valueOf(ProtonStreamUtils.readShort(stream));
}
+ /**
+ * Reads the primitive value from the given {@link ProtonBuffer} and
returns it.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} where the primitive value
should be read from.
+ * @param state
+ * The {@link DecoderState} that can be used during decode
of the value.
+ *
+ * @return the decoded primitive value.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
value.
+ */
public short readPrimitiveValue(ProtonBuffer buffer, DecoderState state)
throws DecodeException {
return buffer.readShort();
}
+ /**
+ * Reads the primitive value from the given {@link InputStream} and
returns it.
+ *
+ * @param stream
+ * The {@link InputStream} where the primitive value
should be read from.
+ * @param state
+ * The {@link DecoderState} that can be used during decode
of the value.
+ *
+ * @return the decoded primitive value.
+ *
+ * @throws DecodeException if an error occurs while reading the encoded
value.
+ */
public short readPrimitiveValue(InputStream stream, StreamDecoderState
state) throws DecodeException {
return ProtonStreamUtils.readShort(stream);
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonEngineHandlerContext.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonEngineHandlerContext.java
index 3a0245b..a079749 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonEngineHandlerContext.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonEngineHandlerContext.java
@@ -34,8 +34,19 @@ public class ProtonEngineHandlerContext implements
EngineHandlerContext {
ProtonEngineHandlerContext previous;
ProtonEngineHandlerContext next;
+ /**
+ * The context indicator for a handler that wants to be sent read events.
+ */
public static final int HANDLER_READS = 1 << 1;
+
+ /**
+ * The context indicator for a handler that wants to be sent write events.
+ */
public static final int HANDLER_WRITES = 1 << 2;
+
+ /**
+ * The context indicator for a handler that wants to be sent all read and
write events.
+ */
public static final int HANDLER_ALL_EVENTS = HANDLER_READS |
HANDLER_WRITES;
private final String name;
@@ -44,6 +55,16 @@ public class ProtonEngineHandlerContext implements
EngineHandlerContext {
private int intereskMask = HANDLER_ALL_EVENTS;
+ /**
+ * Creates a new {@link ProtonEngineHandlerContext} with the given options.
+ *
+ * @param name
+ * The name of this {@link ProtonEngineHandlerContext}.
+ * @param engine
+ * The engine that this context is assigned to.
+ * @param handler
+ * The {@link EngineHandler} that this {@link
EngineHandlerContext} manages.
+ */
public ProtonEngineHandlerContext(String name, Engine engine,
EngineHandler handler) {
this.name = name;
this.engine = engine;
@@ -77,6 +98,15 @@ public class ProtonEngineHandlerContext implements
EngineHandlerContext {
return intereskMask;
}
+ /**
+ * Sets the interest mask for this handler context which controls which
events should be routed
+ * here during normal engine handler pipeline operations.
+ *
+ * @param mask
+ * The interest mask for this {@link EngineHandlerContext}.
+ *
+ * @return this {@link ProtonEngineHandlerContext} instance.
+ */
public ProtonEngineHandlerContext interestMask(int mask) {
this.intereskMask = mask;
return this;
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonEngineNoOpSaslDriver.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonEngineNoOpSaslDriver.java
index 374cd26..a7afa2c 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonEngineNoOpSaslDriver.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonEngineNoOpSaslDriver.java
@@ -27,8 +27,14 @@ import
org.apache.qpid.protonj2.engine.sasl.SaslServerContext;
*/
public final class ProtonEngineNoOpSaslDriver implements EngineSaslDriver {
+ /**
+ * Default singleton instance of the No-Op SASL engine driver.
+ */
public static final ProtonEngineNoOpSaslDriver INSTANCE = new
ProtonEngineNoOpSaslDriver();
+ /**
+ * AMQP specified default value for maximum SASL frame size.
+ */
public static final int MIN_MAX_SASL_FRAME_SIZE = 512;
@Override
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonFrameDecodingHandler.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonFrameDecodingHandler.java
index e7c05cf..6abaf00 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonFrameDecodingHandler.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonFrameDecodingHandler.java
@@ -47,9 +47,19 @@ public class ProtonFrameDecodingHandler implements
EngineHandler, SaslPerformati
private static final ProtonLogger LOG =
ProtonLoggerFactory.getLogger(ProtonFrameDecodingHandler.class);
+ /**
+ * Frame type indicator for AMQP protocol frames.
+ */
public static final byte AMQP_FRAME_TYPE = (byte) 0;
+
+ /**
+ * Frame type indicator for SASL protocol frames.
+ */
public static final byte SASL_FRAME_TYPE = (byte) 1;
+ /**
+ * The specified encoding size for the frame size value of each encoded
frame.
+ */
public static final int FRAME_SIZE_BYTES = 4;
private final AMQPPerformativeEnvelopePool<IncomingAMQPEnvelope> framePool
= AMQPPerformativeEnvelopePool.incomingEnvelopePool();
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonFrameEncodingHandler.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonFrameEncodingHandler.java
index 69a0acc..5ecaa2e 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonFrameEncodingHandler.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonFrameEncodingHandler.java
@@ -35,7 +35,14 @@ import org.apache.qpid.protonj2.types.transport.Performative;
*/
public class ProtonFrameEncodingHandler implements EngineHandler {
+ /**
+ * Frame type indicator for AMQP protocol frames.
+ */
public static final byte AMQP_FRAME_TYPE = (byte) 0;
+
+ /**
+ * Frame type indicator for SASL protocol frames.
+ */
public static final byte SASL_FRAME_TYPE = (byte) 1;
private static final int AMQP_PERFORMATIVE_PAD = 256;
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonOutgoingDelivery.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonOutgoingDelivery.java
index 9e78fee..19e1548 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonOutgoingDelivery.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonOutgoingDelivery.java
@@ -19,6 +19,7 @@ package org.apache.qpid.protonj2.engine.impl;
import org.apache.qpid.protonj2.buffer.ProtonBuffer;
import org.apache.qpid.protonj2.engine.EventHandler;
import org.apache.qpid.protonj2.engine.OutgoingDelivery;
+import org.apache.qpid.protonj2.engine.Sender;
import org.apache.qpid.protonj2.types.DeliveryTag;
import org.apache.qpid.protonj2.types.transport.DeliveryState;
@@ -52,6 +53,13 @@ public class ProtonOutgoingDelivery implements
OutgoingDelivery {
private EventHandler<OutgoingDelivery> deliveryUpdatedEventHandler = null;
+ /**
+ * Creates an empty outgoing delivery instance that is owned by the given
{@link ProtonSender}
+ * instance.
+ *
+ * @param link
+ * the {@link Sender} link that owns this outgoing
delivery.
+ */
public ProtonOutgoingDelivery(ProtonSender link) {
this.link = link;
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonTransactionController.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonTransactionController.java
index b028791..28bcf72 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonTransactionController.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonTransactionController.java
@@ -92,6 +92,12 @@ public class ProtonTransactionController extends
ProtonEndpoint<TransactionContr
private List<EventHandler<TransactionController>> capacityObservers = new
ArrayList<>();
+ /**
+ * Creates a new {@link TransactionController} instance that wraps the
given {@link Sender} link.
+ *
+ * @param senderLink
+ * The {@link Sender} that this {@link
TransactionController} wraps.
+ */
public ProtonTransactionController(ProtonSender senderLink) {
super(senderLink.getEngine());
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonTransactionManager.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonTransactionManager.java
index 207957a..bac5e9c 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonTransactionManager.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonTransactionManager.java
@@ -63,6 +63,12 @@ public final class ProtonTransactionManager extends
ProtonEndpoint<TransactionMa
private Map<ProtonBuffer, ProtonManagerTransaction> transactions = new
HashMap<>();
+ /**
+ * Creates a new {@link TransactionManager} instance that wraps the given
{@link Receiver} link.
+ *
+ * @param receiverLink
+ * The {@link Receiver} link that this {@link
TransactionManager} wraps.
+ */
public ProtonTransactionManager(ProtonReceiver receiverLink) {
super(receiverLink.getEngine());
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/sasl/ProtonSaslHandler.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/sasl/ProtonSaslHandler.java
index eebf4ab..0f50d04 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/sasl/ProtonSaslHandler.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/sasl/ProtonSaslHandler.java
@@ -37,6 +37,9 @@ public final class ProtonSaslHandler implements EngineHandler
{
private ProtonEngine engine;
private ProtonSaslContext saslContext;
+ /**
+ * @return true if the SASL exchange has finished (succeed or failed).
+ */
public boolean isDone() {
return saslContext != null ? saslContext.isDone() : false;
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/SaslContext.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/SaslContext.java
index 94ed76e..1e301a5 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/SaslContext.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/SaslContext.java
@@ -25,6 +25,9 @@ import org.apache.qpid.protonj2.types.Symbol;
*/
public interface SaslContext {
+ /**
+ * Indicates the role that this SASL context plays either server or client.
+ */
enum Role { CLIENT, SERVER }
/**
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/SaslOutcome.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/SaslOutcome.java
index c7604bc..e18b920 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/SaslOutcome.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/SaslOutcome.java
@@ -64,6 +64,9 @@ public enum SaslOutcome {
}
};
+ /**
+ * @return the low level {@link SaslCode} that defines the outcome of the
SASL exchange.
+ */
public abstract SaslCode saslCode();
/**
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/SaslAuthenticator.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/SaslAuthenticator.java
index e4bd7e1..c2ea5f8 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/SaslAuthenticator.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/sasl/client/SaslAuthenticator.java
@@ -73,6 +73,15 @@ public class SaslAuthenticator implements SaslClientListener
{
this.selector = selector;
}
+ /**
+ * Sets a completion handler that will be notified once the SASL exchange
has completed. The notification
+ * includes the {@link SaslOutcome} value which indicates if
authentication succeeded or failed.
+ *
+ * @param saslCompleteEventHandler
+ * The {@link EventHandler} that will receive notification
when SASL authentication has completed.
+ *
+ * @return this {@link SaslAuthenticator} instance.
+ */
public SaslAuthenticator saslComplete(EventHandler<SaslOutcome>
saslCompleteEventHandler) {
this.saslCompleteHandler = saslCompleteEventHandler;
return this;
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
