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 <tabish...@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-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org