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 731bf7c Add more JavaDocs to the engine module APIs
731bf7c is described below
commit 731bf7c7d1f89695f84170fea74d19c02ae9ecef
Author: Timothy Bish <tabish...@gmail.com>
AuthorDate: Thu Apr 22 17:14:04 2021 -0400
Add more JavaDocs to the engine module APIs
---
.../qpid/protonj2/buffer/ProtonAbstractBuffer.java | 2 +-
.../protonj2/buffer/ProtonBufferInputStream.java | 3 +
.../protonj2/buffer/ProtonBufferOutputStream.java | 3 +
.../protonj2/buffer/ProtonCompositeBuffer.java | 3 +
.../apache/qpid/protonj2/codec/CodecFactory.java | 24 +
.../org/apache/qpid/protonj2/codec/Encoder.java | 783 +++++++++++++++++++++
.../codec/decoders/ProtonDecoderFactory.java | 6 +
.../codec/decoders/ProtonDecoderState.java | 21 +-
.../codec/decoders/ProtonStreamDecoderFactory.java | 6 +
.../codec/decoders/ProtonStreamDecoderState.java | 16 +
.../protonj2/codec/decoders/ProtonStreamUtils.java | 167 ++++-
.../decoders/UnknownDescribedTypeDecoder.java | 3 +
.../protonj2/codec/encoders/ProtonEncoder.java | 11 +
.../codec/encoders/ProtonEncoderFactory.java | 6 +
.../codec/encoders/ProtonEncoderState.java | 20 +-
.../engine/AMQPPerformativeEnvelopePool.java | 33 +
.../qpid/protonj2/engine/ConnectionState.java | 19 +-
.../apache/qpid/protonj2/engine/EmptyEnvelope.java | 5 +-
.../apache/qpid/protonj2/engine/EngineFactory.java | 3 +
.../qpid/protonj2/engine/EngineSaslDriver.java | 4 +
.../engine/impl/ProtonDeliveryTagGenerator.java | 6 +
.../qpid/protonj2/engine/util/RingQueue.java | 22 +
.../qpid/protonj2/engine/util/StringUtils.java | 59 ++
23 files changed, 1218 insertions(+), 7 deletions(-)
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/buffer/ProtonAbstractBuffer.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/buffer/ProtonAbstractBuffer.java
index 366ba9a..c0ccb9a 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/buffer/ProtonAbstractBuffer.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/buffer/ProtonAbstractBuffer.java
@@ -635,7 +635,7 @@ public abstract class ProtonAbstractBuffer implements
ProtonBuffer {
}
}
- public static boolean isOutOfBounds(int index, int length, int capacity) {
+ protected static boolean isOutOfBounds(int index, int length, int
capacity) {
return (index | length | (index + length) | (capacity - (index +
length))) < 0;
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/buffer/ProtonBufferInputStream.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/buffer/ProtonBufferInputStream.java
index 4e29d39..0b00413 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/buffer/ProtonBufferInputStream.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/buffer/ProtonBufferInputStream.java
@@ -45,6 +45,9 @@ public class ProtonBufferInputStream extends InputStream
implements DataInput {
this.initialReadIndex = buffer.getReadIndex();
}
+ /**
+ * @return a running total of the number of bytes that has been read from
this {@link InputStream}.
+ */
public int getBytesRead() {
return buffer.getReadIndex() - initialReadIndex;
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/buffer/ProtonBufferOutputStream.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/buffer/ProtonBufferOutputStream.java
index 3d5a3f4..395c3ce 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/buffer/ProtonBufferOutputStream.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/buffer/ProtonBufferOutputStream.java
@@ -45,6 +45,9 @@ public class ProtonBufferOutputStream extends OutputStream
implements DataOutput
this.startWriteIndex = buffer.getWriteIndex();
}
+ /**
+ * @return a running total of the number of bytes that has been written to
this {@link OutputStream}
+ */
public int getBytesWritten() {
return buffer.getWriteIndex() - startWriteIndex;
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/buffer/ProtonCompositeBuffer.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/buffer/ProtonCompositeBuffer.java
index eb1e0ec..d587dde 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/buffer/ProtonCompositeBuffer.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/buffer/ProtonCompositeBuffer.java
@@ -25,6 +25,9 @@ import java.util.function.Consumer;
*/
public final class ProtonCompositeBuffer extends ProtonAbstractBuffer {
+ /**
+ * The default maximum capacity for a composite {@link ProtonBuffer}.
+ */
public static final int DEFAULT_MAXIMUM_CAPACITY = Integer.MAX_VALUE;
private static final byte[] EMPTY_BYTE_ARRAY = new byte[0];
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/CodecFactory.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/CodecFactory.java
index 3dda045..c0076dc 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/CodecFactory.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/CodecFactory.java
@@ -83,6 +83,9 @@ public final class CodecFactory {
saslTypeDecoder = decoder;
}
+ /**
+ * @return a cached {@link Encoder} instance that resulted from a call to
{@link #getDefaultEncoder()} if not set externally.
+ */
public static Encoder getEncoder() {
if (amqpTypeEncoder == null) {
amqpTypeEncoder = getDefaultEncoder();
@@ -91,6 +94,9 @@ public final class CodecFactory {
return amqpTypeEncoder;
}
+ /**
+ * @return a cached {@link Decoder} instance that resulted from a call to
{@link #getDefaultDecoder()} if not set externally.
+ */
public static Decoder getDecoder() {
if (amqpTypeDecoder == null) {
amqpTypeDecoder = getDefaultDecoder();
@@ -99,6 +105,9 @@ public final class CodecFactory {
return amqpTypeDecoder;
}
+ /**
+ * @return a cached {@link Encoder} instance that resulted from a call to
{@link #getDefaultSaslEncoder()} if not set externally.
+ */
public static Encoder getSaslEncoder() {
if (saslTypeEncoder == null) {
saslTypeEncoder = getDefaultSaslEncoder();
@@ -107,6 +116,9 @@ public final class CodecFactory {
return saslTypeEncoder;
}
+ /**
+ * @return a cached {@link Decoder} instance that resulted from a call to
{@link #getSaslDecoder()} if not set externally.
+ */
public static Decoder getSaslDecoder() {
if (saslTypeDecoder == null) {
saslTypeDecoder = getDefaultSaslDecoder();
@@ -115,18 +127,30 @@ public final class CodecFactory {
return saslTypeDecoder;
}
+ /**
+ * @return a new instance of the Proton default {@link Encoder}
implementation.
+ */
public static Encoder getDefaultEncoder() {
return ProtonEncoderFactory.create();
}
+ /**
+ * @return a new instance of the Proton default {@link Decoder}
implementation.
+ */
public static Decoder getDefaultDecoder() {
return ProtonDecoderFactory.create();
}
+ /**
+ * @return a new instance of the Proton default SASL only {@link Encoder}
implementation.
+ */
public static Encoder getDefaultSaslEncoder() {
return ProtonEncoderFactory.createSasl();
}
+ /**
+ * @return a new instance of the Proton default SASL only {@link Decoder}
implementation.
+ */
public static Decoder getDefaultSaslDecoder() {
return ProtonDecoderFactory.createSasl();
}
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/Encoder.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/Encoder.java
index 9f37772..db9b24a 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/Encoder.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/Encoder.java
@@ -65,76 +65,511 @@ public interface Encoder {
*/
EncoderState getCachedEncoderState();
+ /**
+ * Write a Null type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeNull(ProtonBuffer buffer, EncoderState state) throws
EncodeException;
+ /**
+ * Write a {@link Boolean} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeBoolean(ProtonBuffer buffer, EncoderState state, boolean value)
throws EncodeException;
+ /**
+ * Write a {@link Boolean} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeBoolean(ProtonBuffer buffer, EncoderState state, Boolean value)
throws EncodeException;
+ /**
+ * Write an {@link UnsignedByte} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeUnsignedByte(ProtonBuffer buffer, EncoderState state,
UnsignedByte value) throws EncodeException;
+ /**
+ * Write an {@link UnsignedByte} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeUnsignedByte(ProtonBuffer buffer, EncoderState state, byte
value) throws EncodeException;
+ /**
+ * Write a {@link UnsignedShort} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeUnsignedShort(ProtonBuffer buffer, EncoderState state,
UnsignedShort value) throws EncodeException;
+ /**
+ * Write a {@link UnsignedShort} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeUnsignedShort(ProtonBuffer buffer, EncoderState state, short
value) throws EncodeException;
+ /**
+ * Write a {@link UnsignedShort} type encoding to the given buffer using
the provided value with
+ * appropriate range checks to ensure invalid input is not accepted.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeUnsignedShort(ProtonBuffer buffer, EncoderState state, int
value) throws EncodeException;
+ /**
+ * Write a {@link UnsignedInteger} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeUnsignedInteger(ProtonBuffer buffer, EncoderState state,
UnsignedInteger value) throws EncodeException;
+ /**
+ * Write a {@link UnsignedInteger} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeUnsignedInteger(ProtonBuffer buffer, EncoderState state, byte
value) throws EncodeException;
+ /**
+ * Write a {@link UnsignedInteger} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeUnsignedInteger(ProtonBuffer buffer, EncoderState state, int
value) throws EncodeException;
+ /**
+ * Write a {@link UnsignedInteger} type encoding to the given buffer using
the provided value with
+ * appropriate range checks to ensure invalid input is not accepted.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeUnsignedInteger(ProtonBuffer buffer, EncoderState state, long
value) throws EncodeException;
+ /**
+ * Write a {@link UnsignedLong} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeUnsignedLong(ProtonBuffer buffer, EncoderState state,
UnsignedLong value) throws EncodeException;
+ /**
+ * Write a {@link UnsignedLong} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeUnsignedLong(ProtonBuffer buffer, EncoderState state, byte
value) throws EncodeException;
+ /**
+ * Write a {@link UnsignedLong} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeUnsignedLong(ProtonBuffer buffer, EncoderState state, long
value) throws EncodeException;
+ /**
+ * Write a {@link Byte} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeByte(ProtonBuffer buffer, EncoderState state, byte value) throws
EncodeException;
+ /**
+ * Write a {@link Byte} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeByte(ProtonBuffer buffer, EncoderState state, Byte value) throws
EncodeException;
+ /**
+ * Write a {@link Short} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeShort(ProtonBuffer buffer, EncoderState state, short value)
throws EncodeException;
+ /**
+ * Write a {@link Short} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeShort(ProtonBuffer buffer, EncoderState state, Short value)
throws EncodeException;
+ /**
+ * Write a {@link Integer} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeInteger(ProtonBuffer buffer, EncoderState state, int value)
throws EncodeException;
+ /**
+ * Write a {@link Integer} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeInteger(ProtonBuffer buffer, EncoderState state, Integer value)
throws EncodeException;
+ /**
+ * Write a {@link Long} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeLong(ProtonBuffer buffer, EncoderState state, long value) throws
EncodeException;
+ /**
+ * Write a {@link Long} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeLong(ProtonBuffer buffer, EncoderState state, Long value) throws
EncodeException;
+ /**
+ * Write a {@link Float} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeFloat(ProtonBuffer buffer, EncoderState state, float value)
throws EncodeException;
+ /**
+ * Write a {@link Float} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeFloat(ProtonBuffer buffer, EncoderState state, Float value)
throws EncodeException;
+ /**
+ * Write a {@link Double} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeDouble(ProtonBuffer buffer, EncoderState state, double value)
throws EncodeException;
+ /**
+ * Write a {@link Double} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeDouble(ProtonBuffer buffer, EncoderState state, Double value)
throws EncodeException;
+ /**
+ * Write a {@link Decimal32} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeDecimal32(ProtonBuffer buffer, EncoderState state, Decimal32
value) throws EncodeException;
+ /**
+ * Write a {@link Decimal64} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeDecimal64(ProtonBuffer buffer, EncoderState state, Decimal64
value) throws EncodeException;
+ /**
+ * Write a {@link Decimal128} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeDecimal128(ProtonBuffer buffer, EncoderState state, Decimal128
value) throws EncodeException;
+ /**
+ * Write a {@link Character} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeCharacter(ProtonBuffer buffer, EncoderState state, char value)
throws EncodeException;
+ /**
+ * Write a {@link Character} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeCharacter(ProtonBuffer buffer, EncoderState state, Character
value) throws EncodeException;
+ /**
+ * Write a Time stamp type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeTimestamp(ProtonBuffer buffer, EncoderState state, long value)
throws EncodeException;
+ /**
+ * Write a Time stamp type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeTimestamp(ProtonBuffer buffer, EncoderState state, Date value)
throws EncodeException;
+ /**
+ * Write a {@link UUID} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeUUID(ProtonBuffer buffer, EncoderState state, UUID value) throws
EncodeException;
+ /**
+ * Writes the contents of the given {@link Binary} value into the provided
{@link ProtonBuffer}
+ * instance as an AMQP Binary type.
+ * <p>
+ * If the provided value to write is null an AMQP null type is encoded
into the target buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeBinary(ProtonBuffer buffer, EncoderState state, Binary value)
throws EncodeException;
/**
@@ -155,16 +590,93 @@ public interface Encoder {
*/
void writeBinary(ProtonBuffer buffer, EncoderState state, ProtonBuffer
value) throws EncodeException;
+ /**
+ * Writes the contents of the given {@link byte[]} value into the provided
{@link ProtonBuffer}
+ * instance as an AMQP Binary type.
+ * <p>
+ * If the provided value to write is null an AMQP null type is encoded
into the target buffer.
+ *
+ * @param buffer
+ * the target buffer where the binary value is to be encoded
+ * @param state
+ * the {@link EncoderState} instance that manages the calling threads
state tracking.
+ * @param value
+ * the {@link ProtonBuffer} value to be encoded as an AMQP binary
instance.
+ *
+ * @throws EncodeException if an error occurs while performing the encode
+ */
void writeBinary(ProtonBuffer buffer, EncoderState state, byte[] value)
throws EncodeException;
+ /**
+ * Write a {@link String} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeString(ProtonBuffer buffer, EncoderState state, String value)
throws EncodeException;
+ /**
+ * Write a {@link Symbol} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeSymbol(ProtonBuffer buffer, EncoderState state, Symbol value)
throws EncodeException;
+ /**
+ * Write a {@link Symbol} type encoding to the given buffer. The provided
{@link String} instance should
+ * contain only ASCII characters and the encoder should throw an {@link
EncodeException} if a non-ASCII
+ * character is encountered.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeSymbol(ProtonBuffer buffer, EncoderState state, String value)
throws EncodeException;
+ /**
+ * Write a {@link List} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
<T> void writeList(ProtonBuffer buffer, EncoderState state, List<T> value)
throws EncodeException;
+ /**
+ * Write a {@link Map} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
<K, V> void writeMap(ProtonBuffer buffer, EncoderState state, Map<K, V>
value) throws EncodeException;
/**
@@ -184,50 +696,321 @@ public interface Encoder {
*/
void writeDeliveryTag(ProtonBuffer buffer, EncoderState state, DeliveryTag
value) throws EncodeException;
+ /**
+ * Write a {@link DescribedType} type encoding to the given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeDescribedType(ProtonBuffer buffer, EncoderState state,
DescribedType value) throws EncodeException;
+ /**
+ * Write the proper type encoding for the provided {@link Object} to the
given buffer if an {@link TypeEncoder}
+ * can be found for it in the collection of registered type encoders..
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeObject(ProtonBuffer buffer, EncoderState state, Object value)
throws EncodeException;
+ /**
+ * Write the given array as with the proper array type encoding to the
given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeArray(ProtonBuffer buffer, EncoderState state, boolean[] value)
throws EncodeException;
+ /**
+ * Write the given array as with the proper array type encoding to the
given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeArray(ProtonBuffer buffer, EncoderState state, byte[] value)
throws EncodeException;
+ /**
+ * Write the given array as with the proper array type encoding to the
given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeArray(ProtonBuffer buffer, EncoderState state, short[] value)
throws EncodeException;
+ /**
+ * Write the given array as with the proper array type encoding to the
given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeArray(ProtonBuffer buffer, EncoderState state, int[] value)
throws EncodeException;
+ /**
+ * Write the given array as with the proper array type encoding to the
given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeArray(ProtonBuffer buffer, EncoderState state, long[] value)
throws EncodeException;
+ /**
+ * Write the given array as with the proper array type encoding to the
given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeArray(ProtonBuffer buffer, EncoderState state, float[] value)
throws EncodeException;
+ /**
+ * Write the given array as with the proper array type encoding to the
given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeArray(ProtonBuffer buffer, EncoderState state, double[] value)
throws EncodeException;
+ /**
+ * Write the given array as with the proper array type encoding to the
given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeArray(ProtonBuffer buffer, EncoderState state, char[] value)
throws EncodeException;
+ /**
+ * Write the given array as with the proper array type encoding to the
given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeArray(ProtonBuffer buffer, EncoderState state, Object[] value)
throws EncodeException;
+ /**
+ * Write the given array as with the proper array type encoding to the
given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeArray(ProtonBuffer buffer, EncoderState state, Decimal32[]
value) throws EncodeException;
+ /**
+ * Write the given array as with the proper array type encoding to the
given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeArray(ProtonBuffer buffer, EncoderState state, Decimal64[]
value) throws EncodeException;
+ /**
+ * Write the given array as with the proper array type encoding to the
given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeArray(ProtonBuffer buffer, EncoderState state, Decimal128[]
value) throws EncodeException;
+ /**
+ * Write the given array as with the proper array type encoding to the
given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeArray(ProtonBuffer buffer, EncoderState state, Symbol[] value)
throws EncodeException;
+ /**
+ * Write the given array as with the proper array type encoding to the
given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeArray(ProtonBuffer buffer, EncoderState state, UnsignedByte[]
value) throws EncodeException;
+ /**
+ * Write the given array as with the proper array type encoding to the
given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeArray(ProtonBuffer buffer, EncoderState state, UnsignedShort[]
value) throws EncodeException;
+ /**
+ * Write the given array as with the proper array type encoding to the
given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeArray(ProtonBuffer buffer, EncoderState state, UnsignedInteger[]
value) throws EncodeException;
+ /**
+ * Write the given array as with the proper array type encoding to the
given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeArray(ProtonBuffer buffer, EncoderState state, UnsignedLong[]
value) throws EncodeException;
+ /**
+ * Write the given array as with the proper array type encoding to the
given buffer.
+ *
+ * @param buffer
+ * The buffer where the write operation is targeted
+ * @param state
+ * The {@link EncoderState} to use for any intermediate encoding work.
+ * @param value
+ * The value to be encoded into the provided buffer.
+ *
+ * @throws EncodeException if an error occurs during the encode operation.
+ */
void writeArray(ProtonBuffer buffer, EncoderState state, UUID[] value)
throws EncodeException;
+ /**
+ * Register a {@link DescribedTypeEncoder} which can be used when writing
custom types using this
+ * encoder. When an Object write is performed the type encoder registry
will be consulted in order
+ * to find the best match for the given {@link Object} instance.
+ *
+ * @param <V> The type that the encoder handles.
+ *
+ * @param encoder
+ * A new {@link DescribedTypeEncoder} that will be used
when encoding its matching type.
+ *
+ * @return this {@link Encoder} instance.
+ *
+ * @throws EncodeException if an error occurs while adding the encoder to
the registry.
+ */
<V> Encoder registerDescribedTypeEncoder(DescribedTypeEncoder<V> encoder)
throws EncodeException;
+ /**
+ * Lookup a {@link TypeEncoder} that would be used to encode the given
{@link Object}.
+ *
+ * @param value
+ * The value which should be used to resolve the {@link
TypeEncoder} that encodes it.
+ *
+ * @return the matching {@link TypeEncoder} for the given value or null if
no match found.
+ */
TypeEncoder<?> getTypeEncoder(Object value);
+ /**
+ * Lookup a {@link TypeEncoder} that would be used to encode the given
{@link Class}.
+ *
+ * @param typeClass
+ * The {@link Class} which should be used to resolve the
{@link TypeEncoder} that encodes it.
+ *
+ * @return the matching {@link TypeEncoder} for the given value or null if
no match found.
+ */
TypeEncoder<?> getTypeEncoder(Class<?> typeClass);
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonDecoderFactory.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonDecoderFactory.java
index 1da05e7..bc0b4f5 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonDecoderFactory.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonDecoderFactory.java
@@ -65,6 +65,9 @@ public final class ProtonDecoderFactory {
private ProtonDecoderFactory() {
}
+ /**
+ * @return a new {@link ProtonDecoder} instance that only decodes AMQP
types.
+ */
public static ProtonDecoder create() {
ProtonDecoder decoder = new ProtonDecoder();
@@ -75,6 +78,9 @@ public final class ProtonDecoderFactory {
return decoder;
}
+ /**
+ * @return a new {@link ProtonDecoder} instance that only decodes SASL
types.
+ */
public static ProtonDecoder createSasl() {
ProtonDecoder decoder = new ProtonDecoder();
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonDecoderState.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonDecoderState.java
index 08f57b5..6278b4d 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonDecoderState.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonDecoderState.java
@@ -25,6 +25,7 @@ import java.nio.charset.StandardCharsets;
import org.apache.qpid.protonj2.buffer.ProtonBuffer;
import org.apache.qpid.protonj2.codec.DecodeException;
+import org.apache.qpid.protonj2.codec.Decoder;
import org.apache.qpid.protonj2.codec.DecoderState;
/**
@@ -40,6 +41,10 @@ public final class ProtonDecoderState implements
DecoderState {
private UTF8Decoder stringDecoder;
+ /**
+ * Create a new {@link DecoderState} instance that is joined forever to
the given {@link Decoder}.
+ * @param decoder
+ */
public ProtonDecoderState(ProtonDecoder decoder) {
this.decoder = decoder;
}
@@ -55,12 +60,26 @@ public final class ProtonDecoderState implements
DecoderState {
return this;
}
+ /**
+ * @return the currently set custom UTF-8 {@link String} decoder or null
if non set.
+ */
public UTF8Decoder getStringDecoder() {
return stringDecoder;
}
- public void setStringDecoder(UTF8Decoder stringDecoder) {
+ /**
+ * Sets a custom UTF-8 {@link String} decoder that will be used for all
{@link String} decoding done
+ * from the encoder associated with this {@link DecoderState} instance.
If no decoder is registered
+ * then the implementation uses its own decoding algorithm.
+ *
+ * @param stringDecoder
+ * a custom {@link UTF8Decoder} that will be used for all
{@link String} decoding.
+ *
+ * @return this {@link Decoder} instance.
+ */
+ public ProtonDecoderState setStringDecoder(UTF8Decoder stringDecoder) {
this.stringDecoder = stringDecoder;
+ return this;
}
@Override
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonStreamDecoderFactory.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonStreamDecoderFactory.java
index bc415f0..52b15d8 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonStreamDecoderFactory.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonStreamDecoderFactory.java
@@ -65,6 +65,9 @@ public final class ProtonStreamDecoderFactory {
private ProtonStreamDecoderFactory() {
}
+ /**
+ * @return a new {@link ProtonDecoder} instance that only decodes AMQP
types.
+ */
public static ProtonStreamDecoder create() {
ProtonStreamDecoder decoder = new ProtonStreamDecoder();
@@ -75,6 +78,9 @@ public final class ProtonStreamDecoderFactory {
return decoder;
}
+ /**
+ * @return a new {@link ProtonDecoder} instance that only decodes SASL
types.
+ */
public static ProtonStreamDecoder createSasl() {
ProtonStreamDecoder decoder = new ProtonStreamDecoder();
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonStreamDecoderState.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonStreamDecoderState.java
index 3f268c4..0571ffa 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonStreamDecoderState.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonStreamDecoderState.java
@@ -27,6 +27,7 @@ import java.nio.charset.CoderResult;
import java.nio.charset.StandardCharsets;
import org.apache.qpid.protonj2.codec.DecodeException;
+import org.apache.qpid.protonj2.codec.Decoder;
import org.apache.qpid.protonj2.codec.StreamDecoderState;
/**
@@ -42,6 +43,10 @@ public final class ProtonStreamDecoderState implements
StreamDecoderState {
private UTF8StreamDecoder stringDecoder;
+ /**
+ * Create a new {@link StreamDecoderState} instance that is joined forever
to the given {@link Decoder}.
+ * @param decoder
+ */
public ProtonStreamDecoderState(ProtonStreamDecoder decoder) {
this.decoder = decoder;
}
@@ -57,10 +62,21 @@ public final class ProtonStreamDecoderState implements
StreamDecoderState {
return this;
}
+ /**
+ * @return the currently set custom UTF-8 {@link String} decoder or null
if non set.
+ */
public UTF8StreamDecoder getStringDecoder() {
return stringDecoder;
}
+ /**
+ * Sets a custom UTF-8 {@link String} decoder that will be used for all
{@link String} decoding done
+ * from the encoder associated with this {@link StreamDecoderState}
instance. If no decoder is registered
+ * then the implementation uses its own decoding algorithm.
+ *
+ * @param stringDecoder
+ * a custom {@link UTF8Decoder} that will be used for all
{@link String} decoding.
+ */
public void setStringDecoder(UTF8StreamDecoder stringDecoder) {
this.stringDecoder = stringDecoder;
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonStreamUtils.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonStreamUtils.java
index d7d5254..7cc5016 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonStreamUtils.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/ProtonStreamUtils.java
@@ -32,6 +32,18 @@ public abstract class ProtonStreamUtils {
private static final byte[] EMPTY_ARRAY = new byte[0];
+ /**
+ * Write the given {@link Byte} to the target {@link OutputStream}.
+ *
+ * @param value
+ * the value to write to the {@link OutputStream}.
+ * @param stream
+ * the {@link OutputStream} where the target value is to
be written.
+ *
+ * @return the given {@link OutputStream} instance.
+ *
+ * @throws EncodeException if an error occurs while writing to the target
{@link OutputStream}.
+ */
public static OutputStream writeByte(byte value, OutputStream stream)
throws EncodeException {
try {
stream.write(value);
@@ -42,6 +54,18 @@ public abstract class ProtonStreamUtils {
return stream;
}
+ /**
+ * Write the given {@link Short} to the target {@link OutputStream}.
+ *
+ * @param value
+ * the value to write to the {@link OutputStream}.
+ * @param stream
+ * the {@link OutputStream} where the target value is to
be written.
+ *
+ * @return the given {@link OutputStream} instance.
+ *
+ * @throws EncodeException if an error occurs while writing to the target
{@link OutputStream}.
+ */
public static OutputStream writeShort(short value, OutputStream stream)
throws EncodeException {
writeByte((byte) (value >>> 8), stream);
writeByte((byte) (value >>> 0), stream);
@@ -49,6 +73,18 @@ public abstract class ProtonStreamUtils {
return stream;
}
+ /**
+ * Write the given {@link Integer} to the target {@link OutputStream}.
+ *
+ * @param value
+ * the value to write to the {@link OutputStream}.
+ * @param stream
+ * the {@link OutputStream} where the target value is to
be written.
+ *
+ * @return the given {@link OutputStream} instance.
+ *
+ * @throws EncodeException if an error occurs while writing to the target
{@link OutputStream}.
+ */
public static OutputStream writeInt(int value, OutputStream stream) throws
EncodeException {
writeByte((byte) (value >>> 24), stream);
writeByte((byte) (value >>> 16), stream);
@@ -58,6 +94,18 @@ public abstract class ProtonStreamUtils {
return stream;
}
+ /**
+ * Write the given {@link Long} to the target {@link OutputStream}.
+ *
+ * @param value
+ * the value to write to the {@link OutputStream}.
+ * @param stream
+ * the {@link OutputStream} where the target value is to
be written.
+ *
+ * @return the given {@link OutputStream} instance.
+ *
+ * @throws EncodeException if an error occurs while writing to the target
{@link OutputStream}.
+ */
public static OutputStream writeLong(long value, OutputStream stream)
throws EncodeException {
writeByte((byte) (value >>> 56), stream);
writeByte((byte) (value >>> 48), stream);
@@ -71,6 +119,20 @@ public abstract class ProtonStreamUtils {
return stream;
}
+ /**
+ * Reads the given number of bytes from the provided {@link InputStream}
into an array and
+ * return that to the caller. If the requested number of bytes cannot be
read from the stream
+ * an {@link DecodeException} is thrown to indicate an underflow.
+ *
+ * @param stream
+ * The {@link InputStream} where the bytes should be read
from.
+ * @param length
+ * The number of bytes to read from the given input stream.
+ *
+ * @return a byte array containing the requested number of bytes read from
the given {@link InputStream}
+ *
+ * @throws DecodeException if an error occurs reading from the stream or
insufficient bytes are available.
+ */
public static byte[] readBytes(InputStream stream, int length) throws
DecodeException {
try {
if (length == 0) {
@@ -94,6 +156,17 @@ public abstract class ProtonStreamUtils {
}
}
+ /**
+ * Reads a single byte from the given {@link InputStream} and thrown a
{@link DecodeException} if the
+ * {@link InputStream} indicates an EOF condition was encountered.
+ *
+ * @param stream
+ * The {@link InputStream} where the bytes should be read
from.
+ *
+ * @return the given byte that was read from the stream.
+ *
+ * @throws DecodeException if an error occurs during the read or EOF is
reached.
+ */
public static byte readEncodingCode(InputStream stream) throws
DecodeException {
try {
int result = stream.read();
@@ -107,6 +180,17 @@ public abstract class ProtonStreamUtils {
}
}
+ /**
+ * Reads a single byte from the given {@link InputStream} and thrown a
{@link DecodeException} if the
+ * {@link InputStream} indicates an EOF condition was encountered.
+ *
+ * @param stream
+ * The {@link InputStream} where the bytes should be read
from.
+ *
+ * @return the given byte that was read from the stream.
+ *
+ * @throws DecodeException if an error occurs during the read or EOF is
reached.
+ */
public static byte readByte(InputStream stream) throws DecodeException {
try {
int result = stream.read();
@@ -120,11 +204,33 @@ public abstract class ProtonStreamUtils {
}
}
+ /**
+ * Reads a short value from the given {@link InputStream} and thrown a
{@link DecodeException} if the
+ * {@link InputStream} indicates an EOF condition was encountered.
+ *
+ * @param stream
+ * The {@link InputStream} where the bytes should be read
from.
+ *
+ * @return the given byte that was read from the stream.
+ *
+ * @throws DecodeException if an error occurs during the read or EOF is
reached.
+ */
public static short readShort(InputStream stream) {
return (short) ((readByte(stream) & 0xFF) << 8 |
(readByte(stream) & 0xFF) << 0);
}
+ /**
+ * Reads a integer value from the given {@link InputStream} and thrown a
{@link DecodeException} if the
+ * {@link InputStream} indicates an EOF condition was encountered.
+ *
+ * @param stream
+ * The {@link InputStream} where the bytes should be read
from.
+ *
+ * @return the given byte that was read from the stream.
+ *
+ * @throws DecodeException if an error occurs during the read or EOF is
reached.
+ */
public static int readInt(InputStream stream) {
return (readByte(stream) & 0xFF) << 24 |
(readByte(stream) & 0xFF) << 16 |
@@ -132,6 +238,17 @@ public abstract class ProtonStreamUtils {
(readByte(stream) & 0xFF) << 0;
}
+ /**
+ * Reads a long value from the given {@link InputStream} and thrown a
{@link DecodeException} if the
+ * {@link InputStream} indicates an EOF condition was encountered.
+ *
+ * @param stream
+ * The {@link InputStream} where the bytes should be read
from.
+ *
+ * @return the given byte that was read from the stream.
+ *
+ * @throws DecodeException if an error occurs during the read or EOF is
reached.
+ */
public static long readLong(InputStream stream) {
return (long) (readByte(stream) & 0xFF) << 56 |
(long) (readByte(stream) & 0xFF) << 48 |
@@ -143,14 +260,49 @@ public abstract class ProtonStreamUtils {
(long) (readByte(stream) & 0xFF) << 0;
}
+ /**
+ * Reads a float value from the given {@link InputStream} and thrown a
{@link DecodeException} if the
+ * {@link InputStream} indicates an EOF condition was encountered.
+ *
+ * @param stream
+ * The {@link InputStream} where the bytes should be read
from.
+ *
+ * @return the given byte that was read from the stream.
+ *
+ * @throws DecodeException if an error occurs during the read or EOF is
reached.
+ */
public static float readFloat(InputStream stream) {
return Float.intBitsToFloat(readInt(stream));
}
+ /**
+ * Reads a double value from the given {@link InputStream} and thrown a
{@link DecodeException} if the
+ * {@link InputStream} indicates an EOF condition was encountered.
+ *
+ * @param stream
+ * The {@link InputStream} where the bytes should be read
from.
+ *
+ * @return the given byte that was read from the stream.
+ *
+ * @throws DecodeException if an error occurs during the read or EOF is
reached.
+ */
public static double readDouble(InputStream stream) {
return Double.longBitsToDouble(readLong(stream));
}
+ /**
+ * Attempts to skip the given number of bytes from the provided {@link
InputStream} instance and
+ * throws a DecodeException if an error occurs during the skip.
+ *
+ * @param stream
+ * The {@link InputStream} where the bytes should be read
from.
+ * @param amount
+ * The number of bytes that should be skipped.
+ *
+ * @return the {@link InputStream} instance that was passed.
+ *
+ * @throws DecodeException if an error occurs during the read or EOF is
reached.
+ */
public static InputStream skipBytes(InputStream stream, long amount) {
try {
stream.skip(amount);
@@ -162,11 +314,24 @@ public abstract class ProtonStreamUtils {
return stream;
}
- public static void reset(InputStream stream) throws DecodeException {
+ /**
+ * Attempts to reset the provided {@link InputStream} to a previously
marked point. If an error occurs
+ * this method throws an DecodeException to describe the error.
+ *
+ * @param stream
+ * The {@link InputStream} that is to be reset.
+ *
+ * @return the {@link InputStream} instance that was passed.
+ *
+ * @throws DecodeException if an error occurs during the reset.
+ */
+ public static InputStream reset(InputStream stream) throws DecodeException
{
try {
stream.reset();
} catch (IOException ex) {
throw new DecodeException("Caught IO error when calling reset on
provided stream", ex);
}
+
+ return stream;
}
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/UnknownDescribedTypeDecoder.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/UnknownDescribedTypeDecoder.java
index 758845b..b8abfd3 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/UnknownDescribedTypeDecoder.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/decoders/UnknownDescribedTypeDecoder.java
@@ -34,6 +34,9 @@ import org.apache.qpid.protonj2.types.UnsignedLong;
*/
public abstract class UnknownDescribedTypeDecoder extends
AbstractDescribedTypeDecoder<DescribedType> {
+ /**
+ * @return the AMQP type descriptor for this {@link TypeDecoder}.
+ */
public abstract Object getDescriptor();
@Override
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/ProtonEncoder.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/ProtonEncoder.java
index f9020dc..c0d7bcd 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/ProtonEncoder.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/ProtonEncoder.java
@@ -726,6 +726,17 @@ public final class ProtonEncoder implements Encoder {
return getTypeEncoder(typeClass, null);
}
+ /**
+ * Lookup a {@link TypeEncoder} by first checking the given type {@link
Class} and then
+ * if none found to deduce a valid TypeEncoder from the {@link Object}
specified.
+ *
+ * @param typeClass
+ * The {@link Class} for which a type specific encoder is
requested.
+ * @param instance
+ * An {@link Object} instance to use as a fall back if no encoder
found for the {@link Class}
+ *
+ * @return a {@link TypeEncoder} if a match to the given query is found or
null of non can be deduced.
+ */
public TypeEncoder<?> getTypeEncoder(Class<?> typeClass, Object instance) {
TypeEncoder<?> encoder = typeEncoders.get(typeClass);
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/ProtonEncoderFactory.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/ProtonEncoderFactory.java
index 0d31f89..10dedd4 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/ProtonEncoderFactory.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/ProtonEncoderFactory.java
@@ -65,6 +65,9 @@ public final class ProtonEncoderFactory {
private ProtonEncoderFactory() {
}
+ /**
+ * @return a new {@link ProtonEncoder} instance that only decodes AMQP
types.
+ */
public static ProtonEncoder create() {
ProtonEncoder encoder = new ProtonEncoder();
@@ -75,6 +78,9 @@ public final class ProtonEncoderFactory {
return encoder;
}
+ /**
+ * @return a new {@link ProtonEncoder} instance that only decodes SASL
types.
+ */
public static ProtonEncoder createSasl() {
ProtonEncoder encoder = new ProtonEncoder();
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/ProtonEncoderState.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/ProtonEncoderState.java
index 08e4c19..d226587 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/ProtonEncoderState.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/ProtonEncoderState.java
@@ -17,6 +17,7 @@
package org.apache.qpid.protonj2.codec.encoders;
import org.apache.qpid.protonj2.buffer.ProtonBuffer;
+import org.apache.qpid.protonj2.codec.Encoder;
import org.apache.qpid.protonj2.codec.EncoderState;
/**
@@ -28,6 +29,10 @@ public final class ProtonEncoderState implements
EncoderState {
private UTF8Encoder utf8Encoder;
+ /**
+ * Creates a new {@link ProtonEncoderState} that is linked to the given
{@link ProtonEncoder}.
+ * @param encoder
+ */
public ProtonEncoderState(ProtonEncoder encoder) {
this.encoder = encoder;
}
@@ -37,12 +42,25 @@ public final class ProtonEncoderState implements
EncoderState {
return this.encoder;
}
+ /**
+ * @return the user configured custom {@link UTF8Encoder} instance or null
if none set.
+ */
public UTF8Encoder getUTF8Encoder() {
return utf8Encoder;
}
- public void setUTF8Encoder(UTF8Encoder utf8Encoder) {
+ /**
+ * Configures a custom {@link UTF8Encoder} instance that will be used for
all String decoding
+ * done by the parent {@link Encoder} instance.
+ *
+ * @param utf8Encoder
+ * The user specified {@link UTF8Encoder} or null to clear
a previous configuration.
+ *
+ * @return this {@link Encoder} instance.
+ */
+ public ProtonEncoderState setUTF8Encoder(UTF8Encoder utf8Encoder) {
this.utf8Encoder = utf8Encoder;
+ return this;
}
@Override
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/AMQPPerformativeEnvelopePool.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/AMQPPerformativeEnvelopePool.java
index 585d973..2805168 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/AMQPPerformativeEnvelopePool.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/AMQPPerformativeEnvelopePool.java
@@ -29,6 +29,9 @@ import org.apache.qpid.protonj2.types.transport.Performative;
*/
public class AMQPPerformativeEnvelopePool<E extends
PerformativeEnvelope<Performative>> {
+ /**
+ * The default maximum pool size to use if not otherwise configured.
+ */
public static final int DEFAULT_MAX_POOL_SIZE = 10;
private int maxPoolSize = DEFAULT_MAX_POOL_SIZE;
@@ -36,20 +39,50 @@ public class AMQPPerformativeEnvelopePool<E extends
PerformativeEnvelope<Perform
private final RingQueue<E> pool;
private final Function<AMQPPerformativeEnvelopePool<E>, E> envelopeBuilder;
+ /**
+ * Create a new envelope pool using the default pool size.
+ *
+ * @param envelopeBuilder
+ * The builder that will provide new envelope instances
when the pool is empty.
+ */
public
AMQPPerformativeEnvelopePool(Function<AMQPPerformativeEnvelopePool<E>, E>
envelopeBuilder) {
this(envelopeBuilder,
AMQPPerformativeEnvelopePool.DEFAULT_MAX_POOL_SIZE);
}
+ /**
+ * Create a new envelope pool using the default pool size.
+ *
+ * @param envelopeBuilder
+ * The builder that will provide new envelope instances
when the pool is empty.
+ * @param maxPoolSize
+ * The maximum number of envelopes to hold in the pool at any given
time.
+ */
public
AMQPPerformativeEnvelopePool(Function<AMQPPerformativeEnvelopePool<E>, E>
envelopeBuilder, int maxPoolSize) {
this.pool = new RingQueue<>(getMaxPoolSize());
this.maxPoolSize = maxPoolSize;
this.envelopeBuilder = envelopeBuilder;
}
+ /**
+ * @return the configured maximum pool size.
+ */
public final int getMaxPoolSize() {
return maxPoolSize;
}
+ /**
+ * Requests an envelope from the pool and if non is available creates one
using the given
+ * builder this pool was created with.
+ *
+ * @param body
+ * The body that will be stored in the envelope.
+ * @param channel
+ * The channel that is assigned to the envelope until
returned to the pool.
+ * @param payload
+ * The Binary payload that is to be encoded with the given
envelope body.
+ *
+ * @return the envelope instance that was taken from the pool or created
if the pool was empty.
+ */
@SuppressWarnings("unchecked")
public E take(Performative body, int channel, ProtonBuffer payload) {
return (E) pool.poll(this::supplyPooledResource).initialize(body,
channel, payload);
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/ConnectionState.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/ConnectionState.java
index 4157f1c..1c49463 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/ConnectionState.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/ConnectionState.java
@@ -17,10 +17,25 @@
package org.apache.qpid.protonj2.engine;
/**
- * Represents the state of an AMQP Connection.
+ * Represents the state of an AMQP Connection. Each {@link Connection}
provides both
+ * a local and remote connection state that independently reflects the state
at each
+ * end.
*/
public enum ConnectionState {
+
+ /**
+ * Indicates that the targeted end of the Connection (local or remote)
has not yet been opened.
+ */
IDLE,
+
+ /**
+ * Indicates that the targeted end of the Connection (local or remote)
is currently open.
+ */
ACTIVE,
- CLOSED,
+
+ /**
+ * Indicates that the targeted end of the Connection (local or remote)
has been closed.
+ */
+ CLOSED
+
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/EmptyEnvelope.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/EmptyEnvelope.java
index 9caac1c..787c135 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/EmptyEnvelope.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/EmptyEnvelope.java
@@ -23,9 +23,12 @@ import
org.apache.qpid.protonj2.types.transport.Performative.PerformativeHandler
*/
public final class EmptyEnvelope extends IncomingAMQPEnvelope {
+ /**
+ * The singleton instance of the {@link EmptyEnvelope} type.
+ */
public static final EmptyEnvelope INSTANCE = new EmptyEnvelope();
- public EmptyEnvelope() {
+ private EmptyEnvelope() {
super();
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/EngineFactory.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/EngineFactory.java
index 1db1db0..e0b79b1 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/EngineFactory.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/EngineFactory.java
@@ -23,6 +23,9 @@ import
org.apache.qpid.protonj2.engine.impl.ProtonEngineFactory;
*/
public interface EngineFactory {
+ /**
+ * The Proton provided EngineFactory instance.
+ */
public static final EngineFactory PROTON = new ProtonEngineFactory();
/**
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/EngineSaslDriver.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/EngineSaslDriver.java
index 09ed8bc..57737b8 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/EngineSaslDriver.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/EngineSaslDriver.java
@@ -30,6 +30,10 @@ import
org.apache.qpid.protonj2.engine.sasl.SaslServerContext;
*/
public interface EngineSaslDriver {
+ /**
+ * The SASL driver state used to determine at what point the current
SASL negotiation process
+ * is currently in. If the state is 'none' then no SASL negotiations
will be performed.
+ */
public enum SaslState {
/**
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonDeliveryTagGenerator.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonDeliveryTagGenerator.java
index 1558bae..f3ccb1d 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonDeliveryTagGenerator.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/impl/ProtonDeliveryTagGenerator.java
@@ -26,6 +26,9 @@ public abstract class ProtonDeliveryTagGenerator implements
DeliveryTagGenerator
private static final ProtonEmptyTagGenerator EMPTY_TAG_GENERATOR = new
ProtonEmptyTagGenerator();
+ /**
+ * An enumeration of the Proton provided {@link DeliveryTagGenerator}
implementations.
+ */
public enum BUILTIN {
/**
* Provides a {@link DeliveryTagGenerator} that creates tags based on
an incrementing
@@ -76,6 +79,9 @@ public abstract class ProtonDeliveryTagGenerator implements
DeliveryTagGenerator
}
};
+ /**
+ * @return a new {@link DeliveryTagGenerator} instance as requested
from the built in types.
+ */
public abstract DeliveryTagGenerator createGenerator();
}
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/util/RingQueue.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/util/RingQueue.java
index 7dfc723..77d11a7 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/util/RingQueue.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/util/RingQueue.java
@@ -39,10 +39,23 @@ public class RingQueue<E> extends AbstractQueue<E> {
private final Object[] backingArray;
+ /**
+ * Creates a new {@link RingQueue} instance with the given fixed Queue
size.
+ *
+ * @param queueSize
+ * The size to use for the ring queue.
+ */
public RingQueue(int queueSize) {
this.backingArray = new Object[queueSize];
}
+ /**
+ * Creates a new {@link RingQueue} instance with a size that matches the
size of the
+ * given {@link Collection} and filled with the values from that {@link
Collection}.
+ *
+ * @param collection
+ * the {@link Collection} whose values populates this
{@link RingQueue} instance.
+ */
public RingQueue(Collection<E> collection) {
this.backingArray = new Object[collection.size()];
@@ -78,6 +91,15 @@ public class RingQueue<E> extends AbstractQueue<E> {
return result;
}
+ /**
+ * Retrieves and removes the head of this ring queue, and if the queue is
currently empty
+ * a new instance of the queue type is provided by invoking the given
{@link Supplier}.
+ *
+ * @param createOnEmpty
+ * a {@link Supplier} which will return default values if the {@link
RingQueue} is empty.
+ *
+ * @return the head element of this queue or a default instance created
from the provided {@link Supplier}/
+ */
public E poll(Supplier<E> createOnEmpty) {
if (isEmpty()) {
return createOnEmpty.get();
diff --git
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/util/StringUtils.java
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/util/StringUtils.java
index 56d6c33..868de4d 100644
---
a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/util/StringUtils.java
+++
b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/util/StringUtils.java
@@ -32,8 +32,19 @@ import
org.apache.qpid.protonj2.buffer.ProtonByteBufferAllocator;
import org.apache.qpid.protonj2.types.Binary;
import org.apache.qpid.protonj2.types.Symbol;
+/**
+ * Set of {@link String} utilities used in the proton code.
+ */
public class StringUtils {
+ /**
+ * Converts the given String[] into a Symbol[] array.
+ *
+ * @param stringArray
+ * The given String[] to convert.
+ *
+ * @return a new Symbol array that contains Symbol versions of the
input Strings.
+ */
public static Symbol[] toSymbolArray(String[] stringArray) {
Symbol[] result = null;
@@ -47,6 +58,14 @@ public class StringUtils {
return result;
}
+ /**
+ * Converts the given Symbol[] into a String[] array.
+ *
+ * @param symbolArray
+ * The given Symbol[] to convert.
+ *
+ * @return a new String array that contains String versions of the
input Symbol.
+ */
public static String[] toStringArray(Symbol[] symbolArray) {
String[] result = null;
@@ -60,6 +79,14 @@ public class StringUtils {
return result;
}
+ /**
+ * Converts the given String keyed {@link Map} into a matching Symbol
keyed {@link Map}.
+ *
+ * @param stringsMap
+ * The given String keyed {@link Map} to convert.
+ *
+ * @return a new Symbol keyed {@link Map} that contains Symbol versions
of the input String keys.
+ */
public static Map<Symbol, Object> toSymbolKeyedMap(Map<String, Object>
stringsMap) {
final Map<Symbol, Object> result;
@@ -75,6 +102,14 @@ public class StringUtils {
return result;
}
+ /**
+ * Converts the given Symbol keyed {@link Map} into a matching String
keyed {@link Map}.
+ *
+ * @param symbolMap
+ * The given String keyed {@link Map} to convert.
+ *
+ * @return a new String keyed {@link Map} that contains String versions
of the input Symbol keys.
+ */
public static Map<String, Object> toStringKeyedMap(Map<Symbol, Object>
symbolMap) {
Map<String, Object> result;
@@ -90,6 +125,14 @@ public class StringUtils {
return result;
}
+ /**
+ * Converts the given String {@link Collection} into a Symbol array.
+ *
+ * @param stringsSet
+ * The given String {@link Collection} to convert.
+ *
+ * @return a new Symbol array that contains String versions of the
input Symbols.
+ */
public static Symbol[] toSymbolArray(Collection<String> stringsSet) {
final Symbol[] result;
@@ -106,6 +149,14 @@ public class StringUtils {
return result;
}
+ /**
+ * Converts the given String {@link Collection} into a matching Symbol
{@link Set}.
+ *
+ * @param stringsSet
+ * The given String {@link Collection} to convert.
+ *
+ * @return a new Symbol {@link Set} that contains String versions of
the input Symbols.
+ */
public static Set<Symbol> toSymbolSet(Collection<String> stringsSet) {
final Set<Symbol> result;
@@ -121,6 +172,14 @@ public class StringUtils {
return result;
}
+ /**
+ * Converts the given Symbol array into a matching String {@link Set}.
+ *
+ * @param symbols
+ * The given Symbol array to convert.
+ *
+ * @return a new String {@link Set} that contains String versions of
the input Symbols.
+ */
public static Set<String> toStringSet(Symbol[] symbols) {
Set<String> result;
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org
For additional commands, e-mail: commits-h...@qpid.apache.org
