You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ta...@apache.org on 2021/06/11 19:56:36 UTC
[qpid-protonj2] 02/02: PROTON-2394 Fill in more API Javadocs for
various types in the engine
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
commit cc5f0eaac88de368bb2665269fccbe221c79ba78
Author: Timothy Bish <ta...@gmail.com>
AuthorDate: Fri Jun 11 15:54:23 2021 -0400
PROTON-2394 Fill in more API Javadocs for various types in the engine
---
.../encoders/primitives/BinaryTypeEncoder.java | 24 +++++++
.../encoders/primitives/BooleanTypeEncoder.java | 36 ++++++++++
.../codec/encoders/primitives/ByteTypeEncoder.java | 13 ++++
.../encoders/primitives/DoubleTypeEncoder.java | 13 ++++
.../encoders/primitives/FloatTypeEncoder.java | 13 ++++
.../encoders/primitives/IntegerTypeEncoder.java | 13 ++++
.../codec/encoders/primitives/LongTypeEncoder.java | 13 ++++
.../encoders/primitives/ShortTypeEncoder.java | 13 ++++
.../encoders/primitives/TimestampTypeEncoder.java | 13 ++++
.../primitives/UnsignedByteTypeEncoder.java | 13 ++++
.../primitives/UnsignedIntegerTypeEncoder.java | 39 +++++++++++
.../primitives/UnsignedLongTypeEncoder.java | 26 ++++++++
.../primitives/UnsignedShortTypeEncoder.java | 26 ++++++++
.../apache/qpid/protonj2/engine/util/SplayMap.java | 78 ++++++++++++++++++++++
.../qpid/protonj2/logging/NoOpProtonLogger.java | 3 +
.../protonj2/logging/NoOpProtonLoggerFactory.java | 3 +
.../apache/qpid/protonj2/logging/ProtonLogger.java | 18 +++++
.../qpid/protonj2/logging/ProtonLoggerFactory.java | 16 +++++
.../qpid/protonj2/logging/Slf4JLoggerFactory.java | 6 ++
.../org/apache/qpid/protonj2/types/Symbol.java | 53 +++++++++++++++
.../qpid/protonj2/types/UnknownDescribedType.java | 15 +++++
21 files changed, 447 insertions(+)
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/BinaryTypeEncoder.java b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/BinaryTypeEncoder.java
index f5c30a1..8f0b021 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/BinaryTypeEncoder.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/BinaryTypeEncoder.java
@@ -37,6 +37,18 @@ public final class BinaryTypeEncoder extends AbstractPrimitiveTypeEncoder<Binary
writeType(buffer, state, value.asProtonBuffer());
}
+ /**
+ * Shortcut API that allows a {@link ProtonBuffer} to be directly encoded as an AMQP Binary
+ * type without the need to create a {@link Binary} instance. The encoder will attempt
+ * to write the smallest encoding possible based on the buffer size.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param value
+ * The {@link ProtonBuffer} instance that is to be encoded.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, ProtonBuffer value) {
if (value.getReadableBytes() > 255) {
buffer.writeByte(EncodingCodes.VBIN32);
@@ -53,6 +65,18 @@ public final class BinaryTypeEncoder extends AbstractPrimitiveTypeEncoder<Binary
}
}
+ /**
+ * Shortcut API that allows a <code>byte[]</code> to be directly encoded as an AMQP Binary
+ * type without the need to create a {@link Binary} instance. The encoder will attempt
+ * to write the smallest encoding possible based on the buffer size.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param value
+ * The <code>byte[]</code> instance that is to be encoded.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, byte[] value) {
if (value.length > 255) {
buffer.writeByte(EncodingCodes.VBIN32);
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/BooleanTypeEncoder.java b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/BooleanTypeEncoder.java
index 25d522a..4c2db84 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/BooleanTypeEncoder.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/BooleanTypeEncoder.java
@@ -36,6 +36,19 @@ public final class BooleanTypeEncoder extends AbstractPrimitiveTypeEncoder<Boole
buffer.writeByte(value == Boolean.TRUE ? EncodingCodes.BOOLEAN_TRUE : EncodingCodes.BOOLEAN_FALSE);
}
+ /**
+ * Write the full AMQP type data for the boolean to the given byte buffer.
+ *
+ * This can consist of writing both a type constructor value and the bytes that make up the
+ * value of the type being written.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param value
+ * The boolean value to encode.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, boolean value) {
buffer.writeByte(value == true ? EncodingCodes.BOOLEAN_TRUE : EncodingCodes.BOOLEAN_FALSE);
}
@@ -49,6 +62,16 @@ public final class BooleanTypeEncoder extends AbstractPrimitiveTypeEncoder<Boole
}
}
+ /**
+ * Write the AMQP type data to the given byte buffer without an type encoding metadata
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param values
+ * The boolean array value to encode.
+ */
public void writeRawArray(ProtonBuffer buffer, EncoderState state, boolean[] values) {
// Write the array elements after writing the array length
buffer.writeByte(EncodingCodes.BOOLEAN);
@@ -57,6 +80,19 @@ public final class BooleanTypeEncoder extends AbstractPrimitiveTypeEncoder<Boole
}
}
+ /**
+ * Write the full AMQP type data for the boolean array to the given byte buffer.
+ *
+ * This can consist of writing both a type constructor value and the bytes that make up the
+ * value of the type being written.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param values
+ * The primitive boolean array value to encode.
+ */
public void writeArray(ProtonBuffer buffer, EncoderState state, boolean[] values) {
if (values.length < 254) {
writeAsArray8(buffer, state, values);
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/ByteTypeEncoder.java b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/ByteTypeEncoder.java
index 602f741..8bdefd8 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/ByteTypeEncoder.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/ByteTypeEncoder.java
@@ -37,6 +37,19 @@ public final class ByteTypeEncoder extends AbstractPrimitiveTypeEncoder<Byte> {
buffer.writeByte(value.byteValue());
}
+ /**
+ * Write the full AMQP type data for the byte to the given byte buffer.
+ *
+ * This can consist of writing both a type constructor value and the bytes that make up the
+ * value of the type being written.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param value
+ * The byte value to encode.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, byte value) {
buffer.writeByte(EncodingCodes.BYTE);
buffer.writeByte(value);
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/DoubleTypeEncoder.java b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/DoubleTypeEncoder.java
index a2fcfd6..bcadf4f 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/DoubleTypeEncoder.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/DoubleTypeEncoder.java
@@ -37,6 +37,19 @@ public final class DoubleTypeEncoder extends AbstractPrimitiveTypeEncoder<Double
buffer.writeDouble(value.doubleValue());
}
+ /**
+ * Write the full AMQP type data for the double to the given byte buffer.
+ *
+ * This can consist of writing both a type constructor value and the bytes that make up the
+ * value of the type being written.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param value
+ * The double value to encode.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, double value) {
buffer.writeByte(EncodingCodes.DOUBLE);
buffer.writeDouble(value);
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/FloatTypeEncoder.java b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/FloatTypeEncoder.java
index a023a9d..a6c0f1d 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/FloatTypeEncoder.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/FloatTypeEncoder.java
@@ -37,6 +37,19 @@ public final class FloatTypeEncoder extends AbstractPrimitiveTypeEncoder<Float>
buffer.writeFloat(value.floatValue());
}
+ /**
+ * Write the full AMQP type data for the float to the given byte buffer.
+ *
+ * This can consist of writing both a type constructor value and the bytes that make up the
+ * value of the type being written.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param value
+ * The float value to encode.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, float value) {
buffer.writeByte(EncodingCodes.FLOAT);
buffer.writeFloat(value);
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/IntegerTypeEncoder.java b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/IntegerTypeEncoder.java
index ceb9ec2..760fa5f 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/IntegerTypeEncoder.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/IntegerTypeEncoder.java
@@ -36,6 +36,19 @@ public final class IntegerTypeEncoder extends AbstractPrimitiveTypeEncoder<Integ
writeType(buffer, state, value.intValue());
}
+ /**
+ * Write the full AMQP type data for the int to the given byte buffer.
+ *
+ * This can consist of writing both a type constructor value and the bytes that make up the
+ * value of the type being written.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param value
+ * The int value to encode.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, int value) {
if (value >= -128 && value <= 127) {
buffer.writeByte(EncodingCodes.SMALLINT);
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/LongTypeEncoder.java b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/LongTypeEncoder.java
index c4310c4..552fcfd 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/LongTypeEncoder.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/LongTypeEncoder.java
@@ -36,6 +36,19 @@ public final class LongTypeEncoder extends AbstractPrimitiveTypeEncoder<Long> {
writeType(buffer, state, value.longValue());
}
+ /**
+ * Write the full AMQP type data for the long to the given byte buffer.
+ *
+ * This can consist of writing both a type constructor value and the bytes that make up the
+ * value of the type being written.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param value
+ * The long value to encode.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, long value) {
if (value >= -128 && value <= 127) {
buffer.writeByte(EncodingCodes.SMALLLONG);
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/ShortTypeEncoder.java b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/ShortTypeEncoder.java
index 4198464..c183783 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/ShortTypeEncoder.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/ShortTypeEncoder.java
@@ -37,6 +37,19 @@ public final class ShortTypeEncoder extends AbstractPrimitiveTypeEncoder<Short>
buffer.writeShort(value.shortValue());
}
+ /**
+ * Write the full AMQP type data for the short to the given byte buffer.
+ *
+ * This can consist of writing both a type constructor value and the bytes that make up the
+ * value of the type being written.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param value
+ * The short value to encode.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, short value) {
buffer.writeByte(EncodingCodes.SHORT);
buffer.writeShort(value);
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/TimestampTypeEncoder.java b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/TimestampTypeEncoder.java
index cfc900a..5708308 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/TimestampTypeEncoder.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/TimestampTypeEncoder.java
@@ -39,6 +39,19 @@ public final class TimestampTypeEncoder extends AbstractPrimitiveTypeEncoder<Dat
buffer.writeLong(value.getTime());
}
+ /**
+ * Write the full AMQP type data for the time-stamp to the given byte buffer.
+ *
+ * This can consist of writing both a type constructor value and the bytes that make up the
+ * value of the type being written.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param value
+ * The time-stamp value to encode.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, long value) {
buffer.writeByte(EncodingCodes.TIMESTAMP);
buffer.writeLong(value);
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/UnsignedByteTypeEncoder.java b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/UnsignedByteTypeEncoder.java
index 89abc22..c358c15 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/UnsignedByteTypeEncoder.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/UnsignedByteTypeEncoder.java
@@ -38,6 +38,19 @@ public final class UnsignedByteTypeEncoder extends AbstractPrimitiveTypeEncoder<
buffer.writeByte(value.byteValue());
}
+ /**
+ * Write the full AMQP type data for the byte to the given byte buffer.
+ *
+ * This can consist of writing both a type constructor value and the bytes that make up the
+ * value of the type being written.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param value
+ * The primitive unsigned byte value to encode.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, byte value) {
buffer.writeByte(EncodingCodes.UBYTE);
buffer.writeByte(value);
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/UnsignedIntegerTypeEncoder.java b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/UnsignedIntegerTypeEncoder.java
index 3bc31bb..703a22f 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/UnsignedIntegerTypeEncoder.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/UnsignedIntegerTypeEncoder.java
@@ -47,6 +47,19 @@ public final class UnsignedIntegerTypeEncoder extends AbstractPrimitiveTypeEncod
}
}
+ /**
+ * Write the full AMQP type data for the unsigned int to the given byte buffer.
+ *
+ * This can consist of writing both a type constructor value and the bytes that make up the
+ * value of the type being written.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param value
+ * The unsigned integer single byte value to encode.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, byte value) {
if (value == 0) {
buffer.writeByte(EncodingCodes.UINT0);
@@ -56,6 +69,19 @@ public final class UnsignedIntegerTypeEncoder extends AbstractPrimitiveTypeEncod
}
}
+ /**
+ * Write the full AMQP type data for the unsigned int to the given byte buffer.
+ *
+ * This can consist of writing both a type constructor value and the bytes that make up the
+ * value of the type being written.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param value
+ * The unsigned int value to encode.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, int value) {
if (value == 0) {
buffer.writeByte(EncodingCodes.UINT0);
@@ -68,6 +94,19 @@ public final class UnsignedIntegerTypeEncoder extends AbstractPrimitiveTypeEncod
}
}
+ /**
+ * Write the full AMQP type data for the unsigned integer to the given byte buffer.
+ *
+ * This can consist of writing both a type constructor value and the bytes that make up the
+ * value of the type being written.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param value
+ * The long value to encode as an unsigned integer.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, long value) {
if (value < 0L || value >= (1L << 32)) {
throw new IllegalArgumentException("Value \"" + value + "\" lies outside the range [" + 0L + "-" + (1L << 32) + ").");
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/UnsignedLongTypeEncoder.java b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/UnsignedLongTypeEncoder.java
index 24f758f..b5c5038 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/UnsignedLongTypeEncoder.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/UnsignedLongTypeEncoder.java
@@ -37,6 +37,19 @@ public final class UnsignedLongTypeEncoder extends AbstractPrimitiveTypeEncoder<
writeType(buffer, state, value.longValue());
}
+ /**
+ * Write the full AMQP type data for the unsigned long to the given byte buffer.
+ *
+ * This can consist of writing both a type constructor value and the bytes that make up the
+ * value of the type being written.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param value
+ * The unsigned long primitive value to encode.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, long value) {
if (value == 0) {
buffer.writeByte(EncodingCodes.ULONG0);
@@ -49,6 +62,19 @@ public final class UnsignedLongTypeEncoder extends AbstractPrimitiveTypeEncoder<
}
}
+ /**
+ * Write the full AMQP type data for the unsigned long to the given byte buffer.
+ *
+ * This can consist of writing both a type constructor value and the bytes that make up the
+ * value of the type being written.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param value
+ * The byte value to encode as an unsigned long.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, byte value) {
if (value == 0) {
buffer.writeByte(EncodingCodes.ULONG0);
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/UnsignedShortTypeEncoder.java b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/UnsignedShortTypeEncoder.java
index 050b0e6..302941a 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/UnsignedShortTypeEncoder.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/codec/encoders/primitives/UnsignedShortTypeEncoder.java
@@ -38,11 +38,37 @@ public final class UnsignedShortTypeEncoder extends AbstractPrimitiveTypeEncoder
buffer.writeShort(value.shortValue());
}
+ /**
+ * Write the full AMQP type data for the unsigned short to the given byte buffer.
+ *
+ * This can consist of writing both a type constructor value and the bytes that make up the
+ * value of the type being written.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param value
+ * The short value to encode as an unsigned short.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, short value) {
buffer.writeByte(EncodingCodes.USHORT);
buffer.writeShort(value);
}
+ /**
+ * Write the full AMQP type data for the unsigned short to the given byte buffer.
+ *
+ * This can consist of writing both a type constructor value and the bytes that make up the
+ * value of the type being written.
+ *
+ * @param buffer
+ * The {@link ProtonBuffer} instance to write the encoding to.
+ * @param state
+ * The {@link EncoderState} for use in encoding operations.
+ * @param value
+ * The int value to encode unsigned short.
+ */
public void writeType(ProtonBuffer buffer, EncoderState state, int value) {
if (value < 0 || value > 65535) {
throw new IllegalArgumentException("Value given is out of range: " + value);
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/util/SplayMap.java b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/util/SplayMap.java
index 358548c..0e67f70 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/engine/util/SplayMap.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/engine/util/SplayMap.java
@@ -219,10 +219,31 @@ public class SplayMap<E> implements NavigableMap<UnsignedInteger, E> {
root = newRoot;
}
+ /**
+ * Removes the mapping for the {@link UnsignedInteger} key from this map if it is present
+ * and returns the value to which this map previously associated the key, or null if the
+ * map contained no mapping for the key.
+ *
+ * @param key
+ * The {@link UnsignedInteger} key whose value will be removed from the {@link SplayMap}.
+ *
+ * @return the value that was removed if one was present in the {@link Map}.
+ */
public E remove(UnsignedInteger key) {
return remove(key.intValue());
}
+ /**
+ * Removes the mapping for the primitive <code>int</code> key from this map if it is present
+ * and returns the value to which this map previously associated the key, or null if the
+ * map contained no mapping for the key. The integer value is treated as an unsigned int
+ * internally.
+ *
+ * @param key
+ * The {@link UnsignedInteger} key whose value will be removed from the {@link SplayMap}.
+ *
+ * @return the value that was removed if one was present in the {@link Map}.
+ */
public E remove(int key) {
if (root == null) {
return null;
@@ -242,6 +263,15 @@ public class SplayMap<E> implements NavigableMap<UnsignedInteger, E> {
return removed;
}
+ /**
+ * Searches the map using the given primitive integer key value which will be treated
+ * internally as an unsigned value when comparing against keys in the mapping.
+ *
+ * @param key
+ * The key which will be searched for in this mapping.
+ *
+ * @return <code>true</code> if the key mapping is found within this {@link Map}.
+ */
public boolean containsKey(int key) {
if (root == null) {
return false;
@@ -383,6 +413,17 @@ public class SplayMap<E> implements NavigableMap<UnsignedInteger, E> {
return remove(numericKey.intValue(), value);
}
+ /**
+ * Removes the entry for the specified primitive int (treated as unsigned) key only if it is
+ * currently mapped to the specified value in the {@link Map}.
+ *
+ * @param key
+ * The key whose value will be removed if matched.
+ * @param value
+ * The value that must be contained in the mapping for the remove to be performed.
+ *
+ * @return <code>true</code> if an entry was removed from the {@link Map}
+ */
public boolean remove(int key, Object value) {
root = splay(root, key);
if (root == null || root.key != key || !Objects.equals(root.value, value)) {
@@ -398,6 +439,19 @@ public class SplayMap<E> implements NavigableMap<UnsignedInteger, E> {
return replace(key.intValue(), oldValue, newValue);
}
+ /**
+ * Replaces the entry for the specified primitive int (treated as unsigned) key only if it is
+ * currently mapped to the specified value in the {@link Map} with the new value provided.
+ *
+ * @param key
+ * The key whose value will be removed if matched.
+ * @param oldValue
+ * The old value that must be contained in the mapping for the replace to be performed.
+ * @param newValue
+ * The value that will replace the old value mapped to the given key if one existed..
+ *
+ * @return <code>true</code> if an entry was replaced in the {@link Map}
+ */
public boolean replace(int key, E oldValue, E newValue) {
root = splay(root, key);
if (root == null || root.key != key || !Objects.equals(root.value, oldValue)) {
@@ -413,6 +467,17 @@ public class SplayMap<E> implements NavigableMap<UnsignedInteger, E> {
return replace(key.intValue(), value);
}
+ /**
+ * Replaces the entry for the specified primitive int (treated as unsigned) key only if it is
+ * currently mapped to the a value in the {@link Map} with the new value provided.
+ *
+ * @param key
+ * The key whose value will be removed if matched.
+ * @param value
+ * The value that will replace the old value mapped to the given key if one existed..
+ *
+ * @return <code>true</code> if an entry was replaced in the {@link Map}
+ */
public E replace(int key, E value) {
root = splay(root, key);
if (root == null || root.key != key || root.value == null) {
@@ -998,10 +1063,20 @@ public class SplayMap<E> implements NavigableMap<UnsignedInteger, E> {
}
}
+ /**
+ * An immutable {@link Map} entry that can be used when exposing raw entry mappings
+ * via the {@link Map} API.
+ */
public class ImmutableSplayMapEntry implements Map.Entry<UnsignedInteger, E> {
private final SplayedEntry<E> entry;
+ /**
+ * Create a new immutable {@link Map} entry.
+ *
+ * @param entry
+ * The inner {@link Map} entry that is wrapped.
+ */
public ImmutableSplayMapEntry(SplayedEntry<E> entry) {
this.entry = entry;
}
@@ -1011,6 +1086,9 @@ public class SplayMap<E> implements NavigableMap<UnsignedInteger, E> {
return entry.getKey();
}
+ /**
+ * @return the primitive integer view of the unsigned key.
+ */
public int getPrimitiveKey() {
return entry.getIntKey();
}
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/logging/NoOpProtonLogger.java b/protonj2/src/main/java/org/apache/qpid/protonj2/logging/NoOpProtonLogger.java
index 91a9ece..d2b86c5 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/logging/NoOpProtonLogger.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/logging/NoOpProtonLogger.java
@@ -21,6 +21,9 @@ package org.apache.qpid.protonj2.logging;
*/
public class NoOpProtonLogger implements ProtonLogger {
+ /**
+ * Singleton logger instance that should be used for all No-op logging operations.
+ */
public static final NoOpProtonLogger INSTANCE = new NoOpProtonLogger();
private NoOpProtonLogger() {
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/logging/NoOpProtonLoggerFactory.java b/protonj2/src/main/java/org/apache/qpid/protonj2/logging/NoOpProtonLoggerFactory.java
index 09b88ac..dc9ac84 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/logging/NoOpProtonLoggerFactory.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/logging/NoOpProtonLoggerFactory.java
@@ -21,6 +21,9 @@ package org.apache.qpid.protonj2.logging;
*/
public class NoOpProtonLoggerFactory extends ProtonLoggerFactory {
+ /**
+ * Singleton instance of a no-op logger factory used for all logger creations.
+ */
public static final NoOpProtonLoggerFactory INSTANCE = new NoOpProtonLoggerFactory();
private NoOpProtonLoggerFactory() {
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/logging/ProtonLogger.java b/protonj2/src/main/java/org/apache/qpid/protonj2/logging/ProtonLogger.java
index bbc2b5d..7f22986 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/logging/ProtonLogger.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/logging/ProtonLogger.java
@@ -24,8 +24,14 @@ package org.apache.qpid.protonj2.logging;
*/
public interface ProtonLogger {
+ /**
+ * @return the name that was given to this logger on creation.
+ */
public String getName();
+ /**
+ * @return if the trace log level is enabled for this {@link ProtonLogger}.
+ */
public boolean isTraceEnabled();
public void trace(String message);
@@ -36,6 +42,9 @@ public interface ProtonLogger {
public void trace(String message, Object... arguments);
+ /**
+ * @return if the debug log level is enabled for this {@link ProtonLogger}.
+ */
public boolean isDebugEnabled();
public void debug(String message);
@@ -46,6 +55,9 @@ public interface ProtonLogger {
public void debug(String message, Object... arguments);
+ /**
+ * @return if the info log level is enabled for this {@link ProtonLogger}.
+ */
public boolean isInfoEnabled();
public void info(String message);
@@ -56,6 +68,9 @@ public interface ProtonLogger {
public void info(String message, Object... arguments);
+ /**
+ * @return if the warn log level is enabled for this {@link ProtonLogger}.
+ */
public boolean isWarnEnabled();
public void warn(String message);
@@ -66,6 +81,9 @@ public interface ProtonLogger {
public void warn(String message, Object... arguments);
+ /**
+ * @return if the error log level is enabled for this {@link ProtonLogger}.
+ */
public boolean isErrorEnabled();
public void error(String message);
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/logging/ProtonLoggerFactory.java b/protonj2/src/main/java/org/apache/qpid/protonj2/logging/ProtonLoggerFactory.java
index f0562e1..2b7fe6c 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/logging/ProtonLoggerFactory.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/logging/ProtonLoggerFactory.java
@@ -59,10 +59,26 @@ public abstract class ProtonLoggerFactory {
ProtonLoggerFactory.loggerFactory = factory;
}
+ /**
+ * Logger lookup based on the {@link Class} that will host the logger instance.
+ *
+ * @param clazz
+ * The {@link Class} that will host the logger instance being requested.
+ *
+ * @return a {@link ProtonLogger} that is tied to the given {@link Class} instance.
+ */
public static ProtonLogger getLogger(Class<?> clazz) {
return getLoggerFactory().createLoggerWrapper(clazz.getName());
}
+ /**
+ * Logger lookup based on the given logger name that will host the logger instance.
+ *
+ * @param name
+ * The given name that will host the logger instance being requested.
+ *
+ * @return a {@link ProtonLogger} that is tied to the given logger name.
+ */
public static ProtonLogger getLogger(String name) {
return getLoggerFactory().createLoggerWrapper(name);
}
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/logging/Slf4JLoggerFactory.java b/protonj2/src/main/java/org/apache/qpid/protonj2/logging/Slf4JLoggerFactory.java
index 36b3c96..dbdfe80 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/logging/Slf4JLoggerFactory.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/logging/Slf4JLoggerFactory.java
@@ -32,6 +32,12 @@ public class Slf4JLoggerFactory extends ProtonLoggerFactory {
private Slf4JLoggerFactory() {
}
+ /**
+ * Static factory method that will create the correct Slf4j logging factory
+ * and return it or throw an {@link NoClassDefFoundError} if none found.
+ *
+ * @return a correct proton based logger factory wrapper.
+ */
public static ProtonLoggerFactory findLoggerFactory() {
// We don't support the NO-OP logger and instead will fall back to our own variant
if (LoggerFactory.getILoggerFactory() instanceof NOPLoggerFactory) {
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/types/Symbol.java b/protonj2/src/main/java/org/apache/qpid/protonj2/types/Symbol.java
index b4c604a..bbe8b84 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/types/Symbol.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/types/Symbol.java
@@ -24,6 +24,11 @@ import java.util.concurrent.ConcurrentHashMap;
import org.apache.qpid.protonj2.buffer.ProtonBuffer;
import org.apache.qpid.protonj2.buffer.ProtonByteBufferAllocator;
+/**
+ * Class that represents an AMQP Symbol value. The creation of a Symbol object
+ * occurs during a lookup operation which cannot find an already stored version
+ * of the string or byte buffer view of the Symbol's ASCII bytes.
+ */
public final class Symbol implements Comparable<Symbol> {
private static final Map<ProtonBuffer, Symbol> bufferToSymbols = new ConcurrentHashMap<>(2048);
@@ -48,6 +53,9 @@ public final class Symbol implements Comparable<Symbol> {
this.hashCode = underlying.hashCode();
}
+ /**
+ * @return the number of bytes that comprise the Symbol value.
+ */
public int getLength() {
return underlying.getReadableBytes();
}
@@ -91,18 +99,54 @@ public final class Symbol implements Comparable<Symbol> {
return false;
}
+ /**
+ * Writes the internal {@link Symbol} bytes to the provided {@link ProtonBuffer}. This
+ * is a raw ASCII encoding of the Symbol without and AMQP type encoding.
+ *
+ * @param target
+ * The buffer where the Symbol bytes should be written to.
+ */
public void writeTo(ProtonBuffer target) {
target.writeBytes(underlying, 0, underlying.getReadableBytes());
}
+ /**
+ * Look up a singleton {@link Symbol} instance that matches the given {@link String}
+ * name of the {@link Symbol}.
+ *
+ * @param symbolVal
+ * The {@link String} version of the {@link Symbol} value.
+ *
+ * @return a {@link Symbol} that matches the given {@link String}.
+ */
public static Symbol valueOf(String symbolVal) {
return getSymbol(symbolVal);
}
+ /**
+ * Look up a singleton {@link Symbol} instance that matches the given {@link ProtonBuffer}
+ * byte view of the {@link Symbol}.
+ *
+ * @param symbolBytes
+ * The {@link String} version of the {@link Symbol} value.
+ *
+ * @return a {@link Symbol} that matches the given {@link String}.
+ */
public static Symbol getSymbol(ProtonBuffer symbolBytes) {
return getSymbol(symbolBytes, false);
}
+ /**
+ * Look up a singleton {@link Symbol} instance that matches the given {@link ProtonBuffer}
+ * byte view of the {@link Symbol}.
+ *
+ * @param symbolBuffer
+ * The {@link ProtonBuffer} version of the {@link Symbol} value.
+ * @param copyOnCreate
+ * Should the provided buffer be copied during creation of a new {@link Symbol}.
+ *
+ * @return a {@link Symbol} that matches the given {@link String}.
+ */
public static Symbol getSymbol(ProtonBuffer symbolBuffer, boolean copyOnCreate) {
if (symbolBuffer == null) {
return null;
@@ -134,6 +178,15 @@ public final class Symbol implements Comparable<Symbol> {
return symbol;
}
+ /**
+ * Look up a singleton {@link Symbol} instance that matches the given {@link String}
+ * name of the {@link Symbol}.
+ *
+ * @param stringValue
+ * The {@link String} version of the {@link Symbol} value.
+ *
+ * @return a {@link Symbol} that matches the given {@link String}.
+ */
public static Symbol getSymbol(String stringValue) {
if (stringValue == null) {
return null;
diff --git a/protonj2/src/main/java/org/apache/qpid/protonj2/types/UnknownDescribedType.java b/protonj2/src/main/java/org/apache/qpid/protonj2/types/UnknownDescribedType.java
index 89a15a8..4ced7b6 100644
--- a/protonj2/src/main/java/org/apache/qpid/protonj2/types/UnknownDescribedType.java
+++ b/protonj2/src/main/java/org/apache/qpid/protonj2/types/UnknownDescribedType.java
@@ -16,11 +16,26 @@
*/
package org.apache.qpid.protonj2.types;
+import org.apache.qpid.protonj2.codec.DescribedTypeDecoder;
+
+/**
+ * Generic AMQP Described type wrapper that is used whenever a decode encounters
+ * an Described type encoding for which there is no {@link DescribedTypeDecoder}
+ * registered.
+ */
public class UnknownDescribedType implements DescribedType {
private final Object descriptor;
private final Object described;
+ /**
+ * Creates a new wrapper around the type descriptor and the described value.
+ *
+ * @param descriptor
+ * The type descriptor that was used for the encoding of this type.
+ * @param described
+ * The value that was encoded into the body of the described type.
+ */
public UnknownDescribedType(final Object descriptor, final Object described) {
this.descriptor = descriptor;
this.described = described;
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org