Skip to content

Commit

Permalink
[Java] Update Javadoc to explain byte order in wrapped buffers. Issue #…
Browse files Browse the repository at this point in the history 
…161.
  • Loading branch information
@mjpt777
mjpt777 committed Jan 28, 2019
1 parent f9d2052 commit 3f45f2b
Show file tree
Hide file tree
Showing 5 changed files with 50 additions and 39 deletions.
13 changes: 9 additions & 4 deletions agrona/src/main/java/org/agrona/DirectBuffer.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,9 @@

/**
* Abstraction over a range of buffer types that allows fields to be read in native typed fashion.
* <p>
* {@link ByteOrder} of a wrapped buffer is not applied to the {@link DirectBuffer};
* To control {@link ByteOrder} use the appropriate method with the {@link ByteOrder} overload.
*/
public interface DirectBuffer extends Comparable<DirectBuffer>
{
Expand All @@ -41,14 +44,14 @@ public interface DirectBuffer extends Comparable<DirectBuffer>

/**
* Attach a view to a {@link ByteBuffer} for providing direct access, the {@link ByteBuffer} can be
* heap based or direct.
*
* heap based or direct. The {@link ByteBuffer#order()} is not relevant for accessing the wrapped buffer.
* <p>
* When using this method to wrap the view of the ByteBuffer the entire ByteBuffer gets wrapped
* between index 0 and capacity. If you want to just wrap the ByteBuffer between the position
* and the limit then you should use the {@link #wrap(ByteBuffer, int, int)} method, eg:
*
* <code>
* directBuffer.wrap(byteBuffer, byteBuffer.position(), byteBuffer.remaining());
* directBuffer.wrap(byteBuffer, byteBuffer.position(), byteBuffer.remaining());
* </code>
*
* @param buffer to which the view is attached.
Expand All @@ -57,6 +60,8 @@ public interface DirectBuffer extends Comparable<DirectBuffer>

/**
* Attach a view to a {@link ByteBuffer} for providing direct access.
* <p>
* The {@link ByteBuffer#order()} is not relevant for accessing the wrapped buffer.
*
* @param buffer to which the view is attached.
* @param offset at which the view begins.
Expand Down Expand Up @@ -411,7 +416,7 @@ public interface DirectBuffer extends Comparable<DirectBuffer>

/**
* Get the adjustment in indices between an index in this buffer and the wrapped object.
* The wrapped object might be a bytebuffer or a byte[].
* The wrapped object might be a {@link ByteBuffer} or a byte[].
* <p>
* You only need to use this adjustment if you plan to perform operations on the underlying
* byte array or byte buffer that rely on their indices.
Expand Down
16 changes: 8 additions & 8 deletions agrona/src/main/java/org/agrona/ExpandableArrayBuffer.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@
* Put operations will expand the capacity as necessary up to {@link #MAX_ARRAY_LENGTH}. Get operations will throw
* a {@link IndexOutOfBoundsException} if past current capacity.
* <p>
* Note: this class has a natural ordering that is inconsistent with equals.
* Types my be different but equal on buffer contents.
* <b>Note:</b> this class has a natural ordering that is inconsistent with equals.
* Types may be different but equal on buffer contents.
*/
public class ExpandableArrayBuffer implements MutableDirectBuffer
{
Expand Down Expand Up @@ -685,12 +685,12 @@ public int putStringUtf8(final int index, final String value, final ByteOrder by
return putStringUtf8(index, value, byteOrder, Integer.MAX_VALUE);
}

public int putStringUtf8(final int index, final String value, final int maxEncodedSize)
public int putStringUtf8(final int index, final String value, final int maxEncodedLength)
{
final byte[] bytes = value != null ? value.getBytes(UTF_8) : NULL_BYTES;
if (bytes.length > maxEncodedSize)
if (bytes.length > maxEncodedLength)
{
throw new IllegalArgumentException("Encoded string larger than maximum size: " + maxEncodedSize);
throw new IllegalArgumentException("Encoded string larger than maximum size: " + maxEncodedLength);
}

ensureCapacity(index, SIZE_OF_INT + bytes.length);
Expand All @@ -701,12 +701,12 @@ public int putStringUtf8(final int index, final String value, final int maxEncod
return SIZE_OF_INT + bytes.length;
}

public int putStringUtf8(final int index, final String value, final ByteOrder byteOrder, final int maxEncodedSize)
public int putStringUtf8(final int index, final String value, final ByteOrder byteOrder, final int maxEncodedLength)
{
final byte[] bytes = value != null ? value.getBytes(UTF_8) : NULL_BYTES;
if (bytes.length > maxEncodedSize)
if (bytes.length > maxEncodedLength)
{
throw new IllegalArgumentException("Encoded string larger than maximum size: " + maxEncodedSize);
throw new IllegalArgumentException("Encoded string larger than maximum size: " + maxEncodedLength);
}

ensureCapacity(index, SIZE_OF_INT + bytes.length);
Expand Down
19 changes: 11 additions & 8 deletions agrona/src/main/java/org/agrona/ExpandableDirectByteBuffer.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,11 @@
* Put operations will expand the capacity as necessary up to {@link #MAX_BUFFER_LENGTH}. Get operations will throw
* a {@link IndexOutOfBoundsException} if past current capacity.
* <p>
* Note: this class has a natural ordering that is inconsistent with equals.
* Types my be different but equal on buffer contents.
* {@link ByteOrder} of a wrapped buffer is not applied to the {@link ExpandableDirectByteBuffer};
* To control {@link ByteOrder} use the appropriate method with the {@link ByteOrder} overload.
* <p>
* <b>Note:</b> this class has a natural ordering that is inconsistent with equals.
* Types may be different but equal on buffer contents.
*/
public class ExpandableDirectByteBuffer implements MutableDirectBuffer
{
Expand Down Expand Up @@ -935,12 +938,12 @@ public int putStringUtf8(final int index, final String value, final ByteOrder by
return putStringUtf8(index, value, byteOrder, Integer.MAX_VALUE);
}

public int putStringUtf8(final int index, final String value, final int maxEncodedSize)
public int putStringUtf8(final int index, final String value, final int maxEncodedLength)
{
final byte[] bytes = value != null ? value.getBytes(UTF_8) : NULL_BYTES;
if (bytes.length > maxEncodedSize)
if (bytes.length > maxEncodedLength)
{
throw new IllegalArgumentException("Encoded string larger than maximum size: " + maxEncodedSize);
throw new IllegalArgumentException("Encoded string larger than maximum size: " + maxEncodedLength);
}

ensureCapacity(index, SIZE_OF_INT + bytes.length);
Expand All @@ -951,12 +954,12 @@ public int putStringUtf8(final int index, final String value, final int maxEncod
return SIZE_OF_INT + bytes.length;
}

public int putStringUtf8(final int index, final String value, final ByteOrder byteOrder, final int maxEncodedSize)
public int putStringUtf8(final int index, final String value, final ByteOrder byteOrder, final int maxEncodedLength)
{
final byte[] bytes = value != null ? value.getBytes(UTF_8) : NULL_BYTES;
if (bytes.length > maxEncodedSize)
if (bytes.length > maxEncodedLength)
{
throw new IllegalArgumentException("Encoded string larger than maximum size: " + maxEncodedSize);
throw new IllegalArgumentException("Encoded string larger than maximum size: " + maxEncodedLength);
}

ensureCapacity(index, SIZE_OF_INT + bytes.length);
Expand Down
25 changes: 14 additions & 11 deletions agrona/src/main/java/org/agrona/MutableDirectBuffer.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,9 @@

/**
* Abstraction over a range of buffer types that allows fields to be written in native typed fashion.
* <p>
* {@link ByteOrder} of a wrapped buffer is not applied to the {@link MutableDirectBuffer};
* To control {@link ByteOrder} use the appropriate method with the {@link ByteOrder} overload.
*/
public interface MutableDirectBuffer extends DirectBuffer
{
Expand Down Expand Up @@ -300,25 +303,25 @@ public interface MutableDirectBuffer extends DirectBuffer
/**
* Encode a String as UTF-8 bytes the buffer with a length prefix with a maximum encoded size check.
*
* @param index at which the String should be encoded.
* @param value of the String to be encoded.
* @param maxEncodedSize to be checked before writing to the buffer.
* @param index at which the String should be encoded.
* @param value of the String to be encoded.
* @param maxEncodedLength to be checked before writing to the buffer.
* @return the number of bytes put to the buffer.
* @throws java.lang.IllegalArgumentException if the encoded bytes are greater than maxEncodedSize.
* @throws java.lang.IllegalArgumentException if the encoded bytes are greater than maxEncodedLength.
*/
int putStringUtf8(int index, String value, int maxEncodedSize);
int putStringUtf8(int index, String value, int maxEncodedLength);

/**
* Encode a String as UTF-8 bytes the buffer with a length prefix with a maximum encoded size check.
*
* @param index at which the String should be encoded.
* @param value of the String to be encoded.
* @param byteOrder for the length prefix.
* @param maxEncodedSize to be checked before writing to the buffer.
* @param index at which the String should be encoded.
* @param value of the String to be encoded.
* @param byteOrder for the length prefix.
* @param maxEncodedLength to be checked before writing to the buffer.
* @return the number of bytes put to the buffer.
* @throws java.lang.IllegalArgumentException if the encoded bytes are greater than maxEncodedSize.
* @throws java.lang.IllegalArgumentException if the encoded bytes are greater than maxEncodedLength.
*/
int putStringUtf8(int index, String value, ByteOrder byteOrder, int maxEncodedSize);
int putStringUtf8(int index, String value, ByteOrder byteOrder, int maxEncodedLength);

/**
* Encode a String as UTF-8 bytes in the buffer without a length prefix.
Expand Down
16 changes: 8 additions & 8 deletions agrona/src/main/java/org/agrona/concurrent/UnsafeBuffer.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,11 +37,11 @@
* byte[], one of the various {@link ByteBuffer} implementations, or an off Java heap memory address.
* <p>
* {@link ByteOrder} of a wrapped buffer is not applied to the {@link UnsafeBuffer}; {@link UnsafeBuffer}s are
* stateless and can be used concurrently. To control {@link ByteOrder} use the appropriate accessor method
* stateless and can be used concurrently. To control {@link ByteOrder} use the appropriate method
* with the {@link ByteOrder} overload.
* <p>
* <b>Note:</b> This class has a natural ordering that is inconsistent with equals.
* Types my be different but equal on buffer contents.
* Types may be different but equal on buffer contents.
* <p>
* <b>Note:</b> The wrap methods on this class are not thread safe. Concurrent access should only happen after a
* successful wrap.
Expand Down Expand Up @@ -1286,12 +1286,12 @@ public int putStringUtf8(final int index, final String value, final ByteOrder by
return putStringUtf8(index, value, byteOrder, Integer.MAX_VALUE);
}

public int putStringUtf8(final int index, final String value, final int maxEncodedSize)
public int putStringUtf8(final int index, final String value, final int maxEncodedLength)
{
final byte[] bytes = value != null ? value.getBytes(UTF_8) : NULL_BYTES;
if (bytes.length > maxEncodedSize)
if (bytes.length > maxEncodedLength)
{
throw new IllegalArgumentException("Encoded string larger than maximum size: " + maxEncodedSize);
throw new IllegalArgumentException("Encoded string larger than maximum size: " + maxEncodedLength);
}

if (SHOULD_BOUNDS_CHECK)
Expand All @@ -1305,12 +1305,12 @@ public int putStringUtf8(final int index, final String value, final int maxEncod
return SIZE_OF_INT + bytes.length;
}

public int putStringUtf8(final int index, final String value, final ByteOrder byteOrder, final int maxEncodedSize)
public int putStringUtf8(final int index, final String value, final ByteOrder byteOrder, final int maxEncodedLength)
{
final byte[] bytes = value != null ? value.getBytes(UTF_8) : NULL_BYTES;
if (bytes.length > maxEncodedSize)
if (bytes.length > maxEncodedLength)
{
throw new IllegalArgumentException("Encoded string larger than maximum size: " + maxEncodedSize);
throw new IllegalArgumentException("Encoded string larger than maximum size: " + maxEncodedLength);
}

if (SHOULD_BOUNDS_CHECK)
Expand Down

0 comments on commit 3f45f2b

Please sign in to comment.