You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/04/27 12:23:38 UTC
svn commit: r768919 [1/7] - in
/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio:
./ channels/ channels/spi/
Author: tellison
Date: Mon Apr 27 10:23:36 2009
New Revision: 768919
URL: http://svn.apache.org/viewvc?rev=768919&view=rev
Log:
Apply partial patch for HARMONY-6178 (Javadocs for java.nio.*)
Excluding patches that relate to LOGGING module for the moment.
Modified:
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/Buffer.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferOverflowException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferUnderflowException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteBuffer.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteOrder.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/CharBuffer.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/DirectByteBuffers.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/DoubleBuffer.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/FloatBuffer.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/IntBuffer.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/InvalidMarkException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/LongBuffer.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/LongToByteBufferAdapter.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/MappedByteBuffer.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ReadOnlyBufferException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ShortBuffer.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/AlreadyConnectedException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/AsynchronousCloseException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ByteChannel.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/CancelledKeyException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Channel.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Channels.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ClosedByInterruptException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ClosedChannelException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ClosedSelectorException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ConnectionPendingException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/DatagramChannel.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/FileChannel.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/FileLock.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/FileLockInterruptionException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/GatheringByteChannel.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/IllegalBlockingModeException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/IllegalSelectorException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/InterruptibleChannel.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NoConnectionPendingException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NonReadableChannelException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NonWritableChannelException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NotYetBoundException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NotYetConnectedException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/OverlappingFileLockException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Pipe.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ReadableByteChannel.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ScatteringByteChannel.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/SelectableChannel.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/SelectionKey.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Selector.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ServerSocketChannel.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/SocketChannel.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/UnresolvedAddressException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/UnsupportedAddressTypeException.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/WritableByteChannel.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/AbstractInterruptibleChannel.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/AbstractSelectableChannel.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/AbstractSelectionKey.java
harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/SelectorProvider.java
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/Buffer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/Buffer.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/Buffer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/Buffer.java Mon Apr 27 10:23:36 2009
@@ -19,32 +19,30 @@
/**
* A buffer is a list of elements of a specific primitive type.
* <p>
- * A buffer can be described by following properties:
+ * A buffer can be described by the following properties:
* <ul>
- * <li>Capacity, is the number of elements a buffer can hold. Capacity is no
- * less than zero and never changes.</li>
- * <li>Position, is a cursor of this buffer. Elements are read or write at the
- * position if you do not specify an index explicitly. Position is no less than
- * zero and no greater than the limit.</li>
- * <li>Limit controls the scope of accessible elements. You can only read or
+ * <li>Capacity: the number of elements a buffer can hold. Capacity may not be
+ * negative and never changes.</li>
+ * <li>Position: a cursor of this buffer. Elements are read or written at the
+ * position if you do not specify an index explicitly. Position may not be
+ * negative and not greater than the limit.</li>
+ * <li>Limit: controls the scope of accessible elements. You can only read or
* write elements from index zero to <code>limit - 1</code>. Accessing
- * elements out of the scope will cause exception. Limit is no less than zero
- * and no greater than capacity.</li>
- * <li>Mark, is used to remember the current position, so that you can reset
- * the position later. Mark is no less than zero and no greater than position.</li>
- * <li>A buffer can be readonly or read-write. Trying to modify the elements of
- * a readonly buffer will cause <code>ReadOnlyBufferException</code>, while
- * changing the position, limit and mark of a readonly buffer is OK.</li>
+ * elements out of the scope will cause an exception. Limit may not be negative
+ * and not greater than capacity.</li>
+ * <li>Mark: used to remember the current position, so that you can reset the
+ * position later. Mark may not be negative and no greater than position.</li>
+ * <li>A buffer can be read-only or read-write. Trying to modify the elements
+ * of a read-only buffer will cause a <code>ReadOnlyBufferException</code>,
+ * while changing the position, limit and mark of a read-only buffer is OK.</li>
* <li>A buffer can be direct or indirect. A direct buffer will try its best to
- * take advantage of native memory APIs and it may not stay in java heap, thus
- * not affected by GC.</li>
+ * take advantage of native memory APIs and it may not stay in the Java heap,
+ * thus it is not affected by garbage collection.</li>
* </ul>
- * </p>
* <p>
* Buffers are not thread-safe. If concurrent access to a buffer instance is
* required, then the callers are responsible to take care of the
* synchronization issues.
- * </p>
*/
public abstract class Buffer {
@@ -59,13 +57,13 @@
final int capacity;
/**
- * <code>limit - 1</code> is the last element that can be read or write.
+ * <code>limit - 1</code> is the last element that can be read or written.
* Limit must be no less than zero and no greater than <code>capacity</code>.
*/
int limit;
/**
- * Mark is the position will be set when <code>reset()</code> is called.
+ * Mark is where position will be set when <code>reset()</code> is called.
* Mark is not set by default. Mark is always no less than zero and no
* greater than <code>position</code>.
*/
@@ -94,7 +92,7 @@
/**
* Returns the capacity of this buffer.
*
- * @return The number of elements that are contained in this buffer.
+ * @return the number of elements that are contained in this buffer.
*/
public final int capacity() {
return capacity;
@@ -103,13 +101,12 @@
/**
* Clears this buffer.
* <p>
- * While the content of this buffer is not changed the following internal
- * changes take place : the current position is reset back to the start of
+ * While the content of this buffer is not changed, the following internal
+ * changes take place: the current position is reset back to the start of
* the buffer, the value of the buffer limit is made equal to the capacity
- * and mark is unset.
- * </p>
- *
- * @return This buffer
+ * and mark is cleared.
+ *
+ * @return this buffer.
*/
public final Buffer clear() {
position = 0;
@@ -123,12 +120,10 @@
* <p>
* The limit is set to the current position, then the position is set to
* zero, and the mark is cleared.
- * </p>
* <p>
* The content of this buffer is not changed.
- * </p>
- *
- * @return This buffer
+ *
+ * @return this buffer.
*/
public final Buffer flip() {
limit = position;
@@ -138,28 +133,28 @@
}
/**
- * Returns true if there are remaining element(s) in this buffer.
- * <p>
- * Or more precisely, returns <code>position < limit</code>.
- * </p>
+ * Indicates if there are elements remaining in this buffer, that is if
+ * {@code position < limit}.
*
- * @return True if there are remaining element(s) in this buffer.
+ * @return {@code true} if there are elements remaining in this buffer,
+ * {@code false} otherwise.
*/
public final boolean hasRemaining() {
return position < limit;
}
/**
- * Returns whether this buffer is readonly or not.
+ * Indicates whether this buffer is read-only.
*
- * @return Whether this buffer is readonly or not.
+ * @return {@code true} if this buffer is read-only, {@code false}
+ * otherwise.
*/
public abstract boolean isReadOnly();
/**
* Returns the limit of this buffer.
*
- * @return The limit of this buffer.
+ * @return the limit of this buffer.
*/
public final int limit() {
return limit;
@@ -172,14 +167,13 @@
* <code>newLimit</code> then, on returning from this call, it will have
* been adjusted to be equivalent to <code>newLimit</code>. If the mark
* is set and is greater than the new limit, then it is cleared.
- * </p>
- *
+ *
* @param newLimit
- * The new limit, must be no less than zero and no greater than
- * capacity
- * @return This buffer
+ * the new limit, must not be negative and not greater than
+ * capacity.
+ * @return this buffer.
* @exception IllegalArgumentException
- * If <code>newLimit</code> is invalid.
+ * if <code>newLimit</code> is invalid.
*/
public final Buffer limit(int newLimit) {
if (newLimit < 0 || newLimit > capacity) {
@@ -197,10 +191,10 @@
}
/**
- * Mark the current position, so that the position may return to this point
+ * Marks the current position, so that the position may return to this point
* later by calling <code>reset()</code>.
*
- * @return This buffer
+ * @return this buffer.
*/
public final Buffer mark() {
mark = position;
@@ -210,7 +204,7 @@
/**
* Returns the position of this buffer.
*
- * @return The value of this buffer's current position.
+ * @return the value of this buffer's current position.
*/
public final int position() {
return position;
@@ -219,16 +213,15 @@
/**
* Sets the position of this buffer.
* <p>
- * If the mark is set and is greater than the new position, then it is
+ * If the mark is set and it is greater than the new position, then it is
* cleared.
- * </p>
- *
+ *
* @param newPosition
- * The new position, must be no less than zero and no greater
- * than limit
- * @return This buffer
+ * the new position, must be not negative and not greater than
+ * limit.
+ * @return this buffer.
* @exception IllegalArgumentException
- * If <code>newPosition</code> is invalid
+ * if <code>newPosition</code> is invalid.
*/
public final Buffer position(int newPosition) {
if (newPosition < 0 || newPosition > limit) {
@@ -243,23 +236,21 @@
}
/**
- * Returns the number of remaining elements in this buffer.
- * <p>
- * Or more precisely, returns <code>limit - position</code>.
- * </p>
+ * Returns the number of remaining elements in this buffer, that is
+ * {@code limit - position}.
*
- * @return The number of remaining elements in this buffer.
+ * @return the number of remaining elements in this buffer.
*/
public final int remaining() {
return limit - position;
}
/**
- * Reset the position of this buffer to the <code>mark</code>.
+ * Resets the position of this buffer to the <code>mark</code>.
*
- * @return This buffer
+ * @return this buffer.
* @exception InvalidMarkException
- * If the mark is not set
+ * if the mark is not set.
*/
public final Buffer reset() {
if (mark == UNSET_MARK) {
@@ -272,13 +263,10 @@
/**
* Rewinds this buffer.
* <p>
- * The position is set to zero, and the mark is cleared.
- * </p>
- * <p>
- * The content of this buffer is not changed.
- * </p>
- *
- * @return This buffer
+ * The position is set to zero, and the mark is cleared. The content of this
+ * buffer is not changed.
+ *
+ * @return this buffer.
*/
public final Buffer rewind() {
position = 0;
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferOverflowException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferOverflowException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferOverflowException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferOverflowException.java Mon Apr 27 10:23:36 2009
@@ -17,9 +17,8 @@
package java.nio;
/**
- * A <code>BufferOverflowException</code> is thrown when you try to write
- * elements to a buffer, but there is not enough remaining space in the buffer.
- *
+ * A <code>BufferOverflowException</code> is thrown when elements are written
+ * to a buffer but there is not enough remaining space in the buffer.
*/
public class BufferOverflowException extends RuntimeException {
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferUnderflowException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferUnderflowException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferUnderflowException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferUnderflowException.java Mon Apr 27 10:23:36 2009
@@ -17,10 +17,8 @@
package java.nio;
/**
- * A <code>BufferUnderflowException</code> is thrown when you try to read
- * elements from a buffer, but there is not enough remaining elements in the
- * buffer.
- *
+ * A <code>BufferUnderflowException</code> is thrown when elements are read
+ * from a buffer but there are not enough remaining elements in the buffer.
*/
public class BufferUnderflowException extends RuntimeException {
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteBuffer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteBuffer.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteBuffer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteBuffer.java Mon Apr 27 10:23:36 2009
@@ -20,9 +20,9 @@
import org.apache.harmony.luni.platform.Endianness;
/**
- * A buffer of <code>byte</code>s.
+ * A buffer for bytes.
* <p>
- * A byte buffer can be created in either of the following ways:
+ * A byte buffer can be created in either one of the following ways:
* <ul>
* <li>{@link #allocate(int) Allocate} a new byte array and create a buffer
* based on it;</li>
@@ -31,20 +31,19 @@
* <li>{@link #wrap(byte[]) Wrap} an existing byte array to create a new
* buffer.</li>
* </ul>
- * </p>
- *
+ *
*/
public abstract class ByteBuffer extends Buffer implements
Comparable<ByteBuffer> {
/**
- * Creates a byte buffer based on a new allocated byte array.
+ * Creates a byte buffer based on a newly allocated byte array.
*
* @param capacity
- * The capacity of the new buffer
- * @return The created byte buffer
+ * the capacity of the new buffer
+ * @return the created byte buffer.
* @throws IllegalArgumentException
- * If <code>capacity</code> is less than zero
+ * if {@code capacity < 0}.
*/
public static ByteBuffer allocate(int capacity) {
if (capacity < 0) {
@@ -54,13 +53,13 @@
}
/**
- * Creates a direct byte buffer based on a new allocated memory block.
+ * Creates a direct byte buffer based on a newly allocated memory block.
*
* @param capacity
- * The capacity of the new buffer
- * @return The created byte buffer
+ * the capacity of the new buffer
+ * @return the created byte buffer.
* @throws IllegalArgumentException
- * If <code>capacity</code> is less than zero
+ * if {@code capacity < 0}.
*/
public static ByteBuffer allocateDirect(int capacity) {
if (capacity < 0) {
@@ -73,36 +72,33 @@
* Creates a new byte buffer by wrapping the given byte array.
* <p>
* Calling this method has the same effect as
- * <code>wrap(array, 0, array.length)</code>.
- * </p>
- *
+ * {@code wrap(array, 0, array.length)}.
+ *
* @param array
- * The byte array which the new buffer will be based on
- * @return The created byte buffer
+ * the byte array which the new buffer will be based on
+ * @return the created byte buffer.
*/
public static ByteBuffer wrap(byte[] array) {
return BufferFactory.newByteBuffer(array);
}
/**
- * Creates new a byte buffer by wrapping the given byte array.
+ * Creates a new byte buffer by wrapping the given byte array.
* <p>
- * The new buffer's position will be <code>start</code>, limit will be
- * <code>start + len</code>, capacity will be the length of the array.
- * </p>
- *
+ * The new buffer's position will be {@code start}, limit will be
+ * {@code start + len}, capacity will be the length of the array.
+ *
* @param array
- * The byte array which the new buffer will be based on
+ * the byte array which the new buffer will be based on.
* @param start
- * The start index, must be no less than zero and no greater than
- * <code>array.length</code>
+ * the start index, must not be negative and not greater than
+ * {@code array.length}.
* @param len
- * The length, must be no less than zero and no greater than
- * <code>array.length - start</code>
- * @return The created byte buffer
+ * the length, must not be negative and not greater than
+ * {@code array.length - start}.
+ * @return the created byte buffer.
* @exception IndexOutOfBoundsException
- * If either <code>start</code> or <code>len</code> is
- * invalid
+ * if either {@code start} or {@code len} is invalid.
*/
public static ByteBuffer wrap(byte[] array, int start, int len) {
int length = array.length;
@@ -118,28 +114,28 @@
}
/**
- * The byte order of this buffer, default is <code>BIG_ENDIAN</code>.
+ * The byte order of this buffer, default is {@code BIG_ENDIAN}.
*/
Endianness order = Endianness.BIG_ENDIAN;
/**
- * Constructs a <code>ByteBuffer</code> with given capacity.
+ * Constructs a {@code ByteBuffer} with given capacity.
*
* @param capacity
- * The capacity of the buffer
+ * the capacity of the buffer.
*/
ByteBuffer(int capacity) {
super(capacity);
}
/**
- * Returns the byte array which this buffer is based on, if there's one.
+ * Returns the byte array which this buffer is based on, if there is one.
*
- * @return The byte array which this buffer is based on
+ * @return the byte array which this buffer is based on.
* @exception ReadOnlyBufferException
- * If this buffer is based on a readonly array
+ * if this buffer is based on a read-only array.
* @exception UnsupportedOperationException
- * If this buffer is not based on an array
+ * if this buffer is not based on an array.
*/
public final byte[] array() {
return protectedArray();
@@ -147,17 +143,16 @@
/**
* Returns the offset of the byte array which this buffer is based on, if
- * there's one.
+ * there is one.
* <p>
- * The offset is the index of the array corresponds to the zero position of
- * the buffer.
- * </p>
- *
- * @return The offset of the byte array which this buffer is based on
+ * The offset is the index of the array which corresponds to the zero
+ * position of the buffer.
+ *
+ * @return the offset of the byte array which this buffer is based on.
* @exception ReadOnlyBufferException
- * If this buffer is based on a readonly array
+ * if this buffer is based on a read-only array.
* @exception UnsupportedOperationException
- * If this buffer is not based on an array
+ * if this buffer is not based on an array.
*/
public final int arrayOffset() {
return protectedArrayOffset();
@@ -169,16 +164,14 @@
* <p>
* The new buffer's position is zero, its limit and capacity is the number
* of remaining bytes divided by two, and its mark is not set. The new
- * buffer's readonly property and byte order are same as this buffer. The
- * new buffer is direct, if this byte buffer is direct.
- * </p>
+ * buffer's read-only property and byte order are the same as this buffer's.
+ * The new buffer is direct if this byte buffer is direct.
* <p>
- * The new buffer shares content with this buffer, which means either
+ * The new buffer shares its content with this buffer, which means either
* buffer's change of content will be visible to the other. The two buffer's
* position, limit and mark are independent.
- * </p>
- *
- * @return A char buffer which is based on the content of this byte buffer.
+ *
+ * @return a char buffer which is based on the content of this byte buffer.
*/
public abstract CharBuffer asCharBuffer();
@@ -187,17 +180,15 @@
* byte buffer.
* <p>
* The new buffer's position is zero, its limit and capacity is the number
- * of remaining bytes divided by two, and its mark is not set. The new
- * buffer's readonly property and byte order are same as this buffer. The
- * new buffer is direct, if this byte buffer is direct.
- * </p>
+ * of remaining bytes divided by eight, and its mark is not set. The new
+ * buffer's read-only property and byte order are the same as this buffer's.
+ * The new buffer is direct if this byte buffer is direct.
* <p>
- * The new buffer shares content with this buffer, which means either
+ * The new buffer shares its content with this buffer, which means either
* buffer's change of content will be visible to the other. The two buffer's
* position, limit and mark are independent.
- * </p>
- *
- * @return A double buffer which is based on the content of this byte
+ *
+ * @return a double buffer which is based on the content of this byte
* buffer.
*/
public abstract DoubleBuffer asDoubleBuffer();
@@ -207,17 +198,15 @@
* byte buffer.
* <p>
* The new buffer's position is zero, its limit and capacity is the number
- * of remaining bytes divided by two, and its mark is not set. The new
- * buffer's readonly property and byte order are same as this buffer. The
- * new buffer is direct, if this byte buffer is direct.
- * </p>
+ * of remaining bytes divided by four, and its mark is not set. The new
+ * buffer's read-only property and byte order are the same as this buffer's.
+ * The new buffer is direct if this byte buffer is direct.
* <p>
- * The new buffer shares content with this buffer, which means either
+ * The new buffer shares its content with this buffer, which means either
* buffer's change of content will be visible to the other. The two buffer's
* position, limit and mark are independent.
- * </p>
- *
- * @return A float buffer which is based on the content of this byte buffer.
+ *
+ * @return a float buffer which is based on the content of this byte buffer.
*/
public abstract FloatBuffer asFloatBuffer();
@@ -226,17 +215,15 @@
* buffer.
* <p>
* The new buffer's position is zero, its limit and capacity is the number
- * of remaining bytes divided by two, and its mark is not set. The new
- * buffer's readonly property and byte order are same as this buffer. The
- * new buffer is direct, if this byte buffer is direct.
- * </p>
+ * of remaining bytes divided by four, and its mark is not set. The new
+ * buffer's read-only property and byte order are the same as this buffer's.
+ * The new buffer is direct if this byte buffer is direct.
* <p>
- * The new buffer shares content with this buffer, which means either
+ * The new buffer shares its content with this buffer, which means either
* buffer's change of content will be visible to the other. The two buffer's
* position, limit and mark are independent.
- * </p>
- *
- * @return A int buffer which is based on the content of this byte buffer.
+ *
+ * @return a int buffer which is based on the content of this byte buffer.
*/
public abstract IntBuffer asIntBuffer();
@@ -245,34 +232,30 @@
* byte buffer.
* <p>
* The new buffer's position is zero, its limit and capacity is the number
- * of remaining bytes divided by two, and its mark is not set. The new
- * buffer's readonly property and byte order are same as this buffer. The
- * new buffer is direct, if this byte buffer is direct.
- * </p>
+ * of remaining bytes divided by eight, and its mark is not set. The new
+ * buffer's read-only property and byte order are the same as this buffer's.
+ * The new buffer is direct if this byte buffer is direct.
* <p>
- * The new buffer shares content with this buffer, which means either
+ * The new buffer shares its content with this buffer, which means either
* buffer's change of content will be visible to the other. The two buffer's
* position, limit and mark are independent.
- * </p>
- *
- * @return A long buffer which is based on the content of this byte buffer.
+ *
+ * @return a long buffer which is based on the content of this byte buffer.
*/
public abstract LongBuffer asLongBuffer();
/**
- * Returns a readonly buffer that shares content with this buffer.
- * <p>
- * The returned buffer is guaranteed to be a new instance, even if this buffer
- * is readonly itself. The new buffer's position, limit, capacity and mark
- * are the same as this buffer.
- * </p>
+ * Returns a read-only buffer that shares its content with this buffer.
* <p>
- * The new buffer shares content with this buffer, which means this buffer's
- * change of content will be visible to the new buffer. The two buffer's
- * position, limit and mark are independent.
- * </p>
- *
- * @return A readonly version of this buffer.
+ * The returned buffer is guaranteed to be a new instance, even if this
+ * buffer is read-only itself. The new buffer's position, limit, capacity
+ * and mark are the same as this buffer.
+ * <p>
+ * The new buffer shares its content with this buffer, which means this
+ * buffer's change of content will be visible to the new buffer. The two
+ * buffer's position, limit and mark are independent.
+ *
+ * @return a read-only version of this buffer.
*/
public abstract ByteBuffer asReadOnlyBuffer();
@@ -282,45 +265,42 @@
* <p>
* The new buffer's position is zero, its limit and capacity is the number
* of remaining bytes divided by two, and its mark is not set. The new
- * buffer's readonly property and byte order are same as this buffer. The
- * new buffer is direct, if this byte buffer is direct.
- * </p>
+ * buffer's read-only property and byte order are the same as this buffer's.
+ * The new buffer is direct if this byte buffer is direct.
* <p>
- * The new buffer shares content with this buffer, which means either
+ * The new buffer shares its content with this buffer, which means either
* buffer's change of content will be visible to the other. The two buffer's
* position, limit and mark are independent.
- * </p>
- *
- * @return A short buffer which is based on the content of this byte buffer.
+ *
+ * @return a short buffer which is based on the content of this byte buffer.
*/
public abstract ShortBuffer asShortBuffer();
/**
* Compacts this byte buffer.
* <p>
- * The remaining <code>byte</code>s will be moved to the head of the
- * buffer, staring from position zero. Then the position is set to
- * <code>remaining()</code>; the limit is set to capacity; the mark is
+ * The remaining bytes will be moved to the head of the
+ * buffer, starting from position zero. Then the position is set to
+ * {@code remaining()}; the limit is set to capacity; the mark is
* cleared.
- * </p>
- *
- * @return This buffer
+ *
+ * @return this buffer.
* @exception ReadOnlyBufferException
- * If no changes may be made to the contents of this buffer
+ * if no changes may be made to the contents of this buffer.
*/
public abstract ByteBuffer compact();
/**
- * Compare the remaining <code>byte</code>s of this buffer to another
- * byte buffer's remaining <code>byte</code>s.
+ * Compares the remaining bytes of this buffer to another byte buffer's
+ * remaining bytes.
*
* @param otherBuffer
- * Another byte buffer
- * @return a negative value if this is less than <code>other</code>; 0 if
- * this equals to <code>other</code>; a positive value if this is
- * greater than <code>other</code>
+ * another byte buffer.
+ * @return a negative value if this is less than {@code other}; 0 if this
+ * equals to {@code other}; a positive value if this is greater
+ * than {@code other}.
* @exception ClassCastException
- * If <code>other</code> is not a byte buffer
+ * if {@code other} is not a byte buffer.
*/
public int compareTo(ByteBuffer otherBuffer) {
int compareRemaining = (remaining() < otherBuffer.remaining()) ? remaining()
@@ -342,36 +322,31 @@
}
/**
- * Returns a duplicated buffer that shares content with this buffer.
+ * Returns a duplicated buffer that shares its content with this buffer.
* <p>
* The duplicated buffer's position, limit, capacity and mark are the same
- * as this buffer. The duplicated buffer's readonly property and byte order
- * are same as this buffer too.
- * </p>
+ * as this buffer's. The duplicated buffer's read-only property and byte
+ * order are the same as this buffer's too.
* <p>
- * The new buffer shares content with this buffer, which means either
+ * The new buffer shares its content with this buffer, which means either
* buffer's change of content will be visible to the other. The two buffer's
* position, limit and mark are independent.
- * </p>
- *
- * @return A duplicated buffer that shares content with this buffer.
+ *
+ * @return a duplicated buffer that shares its content with this buffer.
*/
public abstract ByteBuffer duplicate();
/**
- * Tests whether this byte buffer equals to another object.
- * <p>
- * If <code>other</code> is not a byte buffer, then false is returned.
- * </p>
+ * Checks whether this byte buffer is equal to another object.
* <p>
- * Two byte buffers are equals if, and only if, their remaining
- * <code>byte</code>s are exactly the same. Position, limit, capacity and
- * mark are not considered.
- * </p>
- *
+ * If {@code other} is not a byte buffer then {@code false} is returned. Two
+ * byte buffers are equal if and only if their remaining bytes are exactly
+ * the same. Position, limit, capacity and mark are not considered.
+ *
* @param other
- * the object to compare against
- * @return Whether this byte buffer equals to another object.
+ * the object to compare with this byte buffer.
+ * @return {@code true} if this byte buffer is equal to {@code other},
+ * {@code false} otherwise.
*/
@Override
public boolean equals(Object other) {
@@ -395,54 +370,49 @@
}
/**
- * Returns the byte at the current position and increase the position by 1.
+ * Returns the byte at the current position and increases the position by 1.
*
- * @return The byte at the current position.
+ * @return the byte at the current position.
* @exception BufferUnderflowException
- * If the position is equal or greater than limit
+ * if the position is equal or greater than limit.
*/
public abstract byte get();
/**
- * Reads <code>byte</code>s from the current position into the specified
- * byte array and increase the position by the number of <code>byte</code>s
- * read.
+ * Reads bytes from the current position into the specified byte array and
+ * increases the position by the number of bytes read.
* <p>
* Calling this method has the same effect as
- * <code>get(dest, 0, dest.length)</code>.
- * </p>
- *
+ * {@code get(dest, 0, dest.length)}.
+ *
* @param dest
- * The destination byte array
- * @return This buffer
+ * the destination byte array.
+ * @return this buffer.
* @exception BufferUnderflowException
- * if <code>dest.length</code> is greater than
- * <code>remaining()</code>
+ * if {@code dest.length} is greater than {@code remaining()}.
*/
public ByteBuffer get(byte[] dest) {
return get(dest, 0, dest.length);
}
/**
- * Reads <code>byte</code>s from the current position into the specified
- * byte array, starting from the specified offset, and increase the position
- * by the number of <code>byte</code>s read.
+ * Reads bytes from the current position into the specified byte array,
+ * starting at the specified offset, and increases the position by the
+ * number of bytes read.
*
* @param dest
- * The target byte array
+ * the target byte array.
* @param off
- * The offset of the byte array, must be no less than zero and no
- * greater than <code>dest.length</code>
+ * the offset of the byte array, must not be negative and
+ * not greater than {@code dest.length}.
* @param len
- * The number of <code>byte</code>s to read, must be no less
- * than zero and no greater than <code>dest.length - off</code>
- * @return This buffer
+ * the number of bytes to read, must not be negative and not
+ * greater than {@code dest.length - off}
+ * @return this buffer.
* @exception IndexOutOfBoundsException
- * If either <code>off</code> or <code>len</code> is
- * invalid
+ * if either {@code off} or {@code len} is invalid.
* @exception BufferUnderflowException
- * If <code>len</code> is greater than
- * <code>remaining()</code>
+ * if {@code len} is greater than {@code remaining()}.
*/
public ByteBuffer get(byte[] dest, int off, int len) {
int length = dest.length;
@@ -460,222 +430,202 @@
}
/**
- * Returns a byte at the specified index, and the position is not changed.
+ * Returns the byte at the specified index and does not change the position.
*
* @param index
- * The index, must be no less than zero and less than limit
- * @return A byte at the specified index.
+ * the index, must not be negative and less than limit.
+ * @return the byte at the specified index.
* @exception IndexOutOfBoundsException
- * If index is invalid
+ * if index is invalid.
*/
public abstract byte get(int index);
/**
- * Returns the char at the current position and increase the position by 2.
+ * Returns the char at the current position and increases the position by 2.
* <p>
- * The 2 bytes start from the current position are composed into a char
- * according to current byte order and returned. The position increases by
- * 2.
- * </p>
- *
- * @return The char at the current position.
+ * The 2 bytes starting at the current position are composed into a char
+ * according to the current byte order and returned.
+ *
+ * @return the char at the current position.
* @exception BufferUnderflowException
- * If the position is greater than <code>limit - 2</code>
+ * if the position is greater than {@code limit - 2}.
*/
public abstract char getChar();
/**
* Returns the char at the specified index.
* <p>
- * The 2 bytes start from the specified index are composed into a char
- * according to current byte order and returned. The position is not
+ * The 2 bytes starting from the specified index are composed into a char
+ * according to the current byte order and returned. The position is not
* changed.
- * </p>
*
* @param index
- * The index, must be no less than zero and equal or less than
- * <code>limit - 2</code>
- * @return The char at the specified index.
+ * the index, must not be negative and equal or less than
+ * {@code limit - 2}.
+ * @return the char at the specified index.
* @exception IndexOutOfBoundsException
- * If <code>index</code> is invalid
+ * if {@code index} is invalid.
*/
public abstract char getChar(int index);
/**
- * Returns the double at the current position and increase the position by
+ * Returns the double at the current position and increases the position by
* 8.
* <p>
- * The 8 bytes start from the current position are composed into a double
- * according to current byte order and returned. The position increases by
- * 8.
- * </p>
- *
- * @return The double at the current position.
+ * The 8 bytes starting from the current position are composed into a double
+ * according to the current byte order and returned.
+ *
+ * @return the double at the current position.
* @exception BufferUnderflowException
- * If the position is greater than <code>limit - 8</code>
+ * if the position is greater than {@code limit - 8}.
*/
public abstract double getDouble();
/**
* Returns the double at the specified index.
* <p>
- * The 8 bytes start from the specified index are composed into a double
- * according to current byte order and returned. The position is not
+ * The 8 bytes starting at the specified index are composed into a double
+ * according to the current byte order and returned. The position is not
* changed.
- * </p>
- *
+ *
* @param index
- * The index, must be no less than zero and equal or less than
- * <code>limit - 8</code>
- * @return The double at the specified index.
+ * the index, must not be negative and equal or less than
+ * {@code limit - 8}.
+ * @return the double at the specified index.
* @exception IndexOutOfBoundsException
- * If <code>index</code> is invalid
+ * if {@code index} is invalid.
*/
public abstract double getDouble(int index);
/**
- * Returns the float at the current position and increase the position by 4.
- * <p>
- * The 4 bytes start from the current position are composed into a float
- * according to current byte order and returned. The position increases by
+ * Returns the float at the current position and increases the position by
* 4.
- * </p>
- *
- * @return The float at the current position.
+ * <p>
+ * The 4 bytes starting at the current position are composed into a float
+ * according to the current byte order and returned.
+ *
+ * @return the float at the current position.
* @exception BufferUnderflowException
- * If the position is greater than <code>limit - 4</code>
+ * if the position is greater than {@code limit - 4}.
*/
public abstract float getFloat();
/**
* Returns the float at the specified index.
* <p>
- * The 4 bytes start from the specified index are composed into a float
- * according to current byte order and returned. The position is not
+ * The 4 bytes starting at the specified index are composed into a float
+ * according to the current byte order and returned. The position is not
* changed.
- * </p>
- *
+ *
* @param index
- * The index, must be no less than zero and equal or less than
- * <code>limit - 4</code>
- * @return The float at the specified index.
+ * the index, must not be negative and equal or less than
+ * {@code limit - 4}.
+ * @return the float at the specified index.
* @exception IndexOutOfBoundsException
- * If <code>index</code> is invalid
+ * if {@code index} is invalid.
*/
public abstract float getFloat(int index);
/**
- * Returns the int at the current position and increase the position by 4.
+ * Returns the int at the current position and increases the position by 4.
* <p>
- * The 4 bytes start from the current position are composed into a int
- * according to current byte order and returned. The position increases by
- * 4.
- * </p>
- *
- * @return The int at the current position.
+ * The 4 bytes starting at the current position are composed into a int
+ * according to the current byte order and returned.
+ *
+ * @return the int at the current position.
* @exception BufferUnderflowException
- * If the position is greater than <code>limit - 4</code>
+ * if the position is greater than {@code limit - 4}.
*/
public abstract int getInt();
/**
* Returns the int at the specified index.
* <p>
- * The 4 bytes start from the specified index are composed into a int
- * according to current byte order and returned. The position is not
+ * The 4 bytes starting at the specified index are composed into a int
+ * according to the current byte order and returned. The position is not
* changed.
- * </p>
- *
+ *
* @param index
- * The index, must be no less than zero and equal or less than
- * <code>limit - 4</code>
- * @return The int at the specified index.
+ * the index, must not be negative and equal or less than
+ * {@code limit - 4}.
+ * @return the int at the specified index.
* @exception IndexOutOfBoundsException
- * If <code>index</code> is invalid
+ * if {@code index} is invalid.
*/
public abstract int getInt(int index);
/**
- * Returns the long at the current position and increase the position by 8.
+ * Returns the long at the current position and increases the position by 8.
* <p>
- * The 8 bytes start from the current position are composed into a long
- * according to current byte order and returned. The position increases by
- * 8.
- * </p>
- *
- * @return The long at the current position.
+ * The 8 bytes starting at the current position are composed into a long
+ * according to the current byte order and returned.
+ *
+ * @return the long at the current position.
* @exception BufferUnderflowException
- * If the position is greater than <code>limit - 8</code>
+ * if the position is greater than {@code limit - 8}.
*/
public abstract long getLong();
/**
* Returns the long at the specified index.
* <p>
- * The 8 bytes start from the specified index are composed into a long
- * according to current byte order and returned. The position is not
+ * The 8 bytes starting at the specified index are composed into a long
+ * according to the current byte order and returned. The position is not
* changed.
- * </p>
- *
+ *
* @param index
- * The index, must be no less than zero and equal or less than
- * <code>limit - 8</code>
- * @return The long at the specified index.
+ * the index, must not be negative and equal or less than
+ * {@code limit - 8}.
+ * @return the long at the specified index.
* @exception IndexOutOfBoundsException
- * If <code>index</code> is invalid
+ * if {@code index} is invalid.
*/
public abstract long getLong(int index);
/**
- * Returns the short at the current position and increase the position by 2.
+ * Returns the short at the current position and increases the position by 2.
* <p>
- * The 2 bytes start from the current position are composed into a short
- * according to current byte order and returned. The position increases by
- * 2.
- * </p>
- *
- * @return The short at the current position.
+ * The 2 bytes starting at the current position are composed into a short
+ * according to the current byte order and returned.
+ *
+ * @return the short at the current position.
* @exception BufferUnderflowException
- * If the position is greater than <code>limit - 2</code>
+ * if the position is greater than {@code limit - 2}.
*/
public abstract short getShort();
/**
* Returns the short at the specified index.
* <p>
- * The 2 bytes start from the specified index are composed into a short
- * according to current byte order and returned. The position is not
+ * The 2 bytes starting at the specified index are composed into a short
+ * according to the current byte order and returned. The position is not
* changed.
- * </p>
- *
+ *
* @param index
- * The index, must be no less than zero and equal or less than
- * <code>limit - 2</code>
- * @return The short at the specified index.
+ * the index, must not be negative and equal or less than
+ * {@code limit - 2}.
+ * @return the short at the specified index.
* @exception IndexOutOfBoundsException
- * If <code>index</code> is invalid
+ * if {@code index} is invalid.
*/
public abstract short getShort(int index);
/**
- * Returns whether this buffer is based on a byte array and is read/write.
- * <p>
- * If this buffer is readonly, then false is returned.
- * </p>
+ * Indicates whether this buffer is based on a byte array and provides
+ * read/write access.
*
- * @return Whether this buffer is based on a byte array and is read/write.
+ * @return {@code true} if this buffer is based on a byte array and provides
+ * read/write access, {@code false} otherwise.
*/
public final boolean hasArray() {
return protectedHasArray();
}
/**
- * Hash code is calculated from the remaining <code>byte</code>s.
- * <p>
- * Position, limit, capacity and mark don't affect the hash code.
- * </p>
- *
- * @return The hash code calculated from the remaining <code>byte</code>s.
+ * Calculates this buffer's hash code from the remaining chars. The
+ * position, limit, capacity and mark don't affect the hash code.
+ *
+ * @return the hash code calculated from the remaining bytes.
*/
@Override
public int hashCode() {
@@ -688,25 +638,21 @@
}
/**
- * Returns true if this buffer is direct.
- * <p>
- * A byte buffer is direct, if it is based on a byte buffer and the byte
- * buffer is direct.
- * </p>
- *
- * @return True if this buffer is direct.
+ * Indicates whether this buffer is direct.
+ *
+ * @return {@code true} if this buffer is direct, {@code false} otherwise.
*/
public abstract boolean isDirect();
/**
- * Returns the byte order used by this buffer when converting
- * <code>byte</code>s from/to other primitive types.
+ * Returns the byte order used by this buffer when converting bytes from/to
+ * other primitive types.
* <p>
- * The default byte order of byte buffer is always BIG_ENDIAN.
- * </p>
- *
- * @return The byte order used by this buffer when converting
- * <code>byte</code>s from/to other primitive types.
+ * The default byte order of byte buffer is always
+ * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}
+ *
+ * @return the byte order used by this buffer when converting bytes from/to
+ * other primitive types.
*/
public final ByteOrder order() {
return order == Endianness.BIG_ENDIAN ? ByteOrder.BIG_ENDIAN
@@ -717,9 +663,9 @@
* Sets the byte order of this buffer.
*
* @param byteOrder
- * The byte order to set. If <code>null</code> then the order
+ * the byte order to set. If {@code null} then the order
* will be {@link ByteOrder#LITTLE_ENDIAN LITTLE_ENDIAN}.
- * @return This buffer
+ * @return this buffer.
* @see ByteOrder
*/
public final ByteBuffer order(ByteOrder byteOrder) {
@@ -733,88 +679,83 @@
}
/**
- * Child class implements this method to realize <code>array()</code>.
+ * Child class implements this method to realize {@code array()}.
*
- * @return see <code>array()</code>
+ * @see #array()
*/
abstract byte[] protectedArray();
/**
- * Child class implements this method to realize <code>arrayOffset()</code>.
+ * Child class implements this method to realize {@code arrayOffset()}.
*
- * @return see <code>arrayOffset()</code>
+ * @see #arrayOffset()
*/
abstract int protectedArrayOffset();
/**
- * Child class implements this method to realize <code>hasArray()</code>.
+ * Child class implements this method to realize {@code hasArray()}.
*
- * @return see <code>hasArray()</code>
+ * @see #hasArray()
*/
abstract boolean protectedHasArray();
/**
- * Writes the given byte to the current position and increase the position
+ * Writes the given byte to the current position and increases the position
* by 1.
*
* @param b
- * The byte to write
- * @return This buffer
+ * the byte to write.
+ * @return this buffer.
* @exception BufferOverflowException
- * If position is equal or greater than limit
+ * if position is equal or greater than limit.
* @exception ReadOnlyBufferException
- * If no changes may be made to the contents of this buffer
+ * if no changes may be made to the contents of this buffer.
*/
public abstract ByteBuffer put(byte b);
/**
- * Writes <code>byte</code>s in the given byte array to the current
- * position and increase the position by the number of <code>byte</code>s
- * written.
+ * Writes bytes in the given byte array to the current position and
+ * increases the position by the number of bytes written.
* <p>
* Calling this method has the same effect as
- * <code>put(src, 0, src.length)</code>.
- * </p>
- *
+ * {@code put(src, 0, src.length)}.
+ *
* @param src
- * The source byte array
- * @return This buffer
+ * the source byte array.
+ * @return this buffer.
* @exception BufferOverflowException
- * If <code>remaining()</code> is less than
- * <code>src.length</code>
+ * if {@code remaining()} is less than {@code src.length}.
* @exception ReadOnlyBufferException
- * If no changes may be made to the contents of this buffer
+ * if no changes may be made to the contents of this buffer.
*/
public final ByteBuffer put(byte[] src) {
return put(src, 0, src.length);
}
/**
- * Writes <code>byte</code>s in the given byte array, starting from the
- * specified offset, to the current position and increase the position by
- * the number of <code>byte</code>s written.
+ * Writes bytes in the given byte array, starting from the specified offset,
+ * to the current position and increases the position by the number of bytes
+ * written.
*
* @param src
- * The source byte array
+ * the source byte array.
* @param off
- * The offset of byte array, must be no less than zero and no
- * greater than <code>src.length</code>
+ * the offset of byte array, must not be negative and not greater
+ * than {@code src.length}.
* @param len
- * The number of <code>byte</code>s to write, must be no less
- * than zero and no greater than <code>src.length - off</code>
- * @return This buffer
+ * the number of bytes to write, must not be negative and not
+ * greater than {@code src.length - off}.
+ * @return this buffer.
* @exception BufferOverflowException
- * If <code>remaining()</code> is less than
- * <code>len</code>
+ * if {@code remaining()} is less than {@code len}.
* @exception IndexOutOfBoundsException
- * If either <code>off</code> or <code>len</code> is
- * invalid
+ * if either {@code off} or {@code len} is invalid.
* @exception ReadOnlyBufferException
- * If no changes may be made to the contents of this buffer
+ * if no changes may be made to the contents of this buffer.
*/
public ByteBuffer put(byte[] src, int off, int len) {
int length = src.length;
- if ((off < 0) || (len < 0) || ((long) off + (long) len > length)) {
+ if ((off < 0 ) || (len < 0) || ((long)off + (long)len > length)) {
throw new IndexOutOfBoundsException();
}
@@ -828,20 +769,20 @@
}
/**
- * Writes all the remaining <code>byte</code>s of the <code>src</code>
- * byte buffer to this buffer's current position, and increase both buffers'
- * position by the number of <code>byte</code>s copied.
+ * Writes all the remaining bytes of the {@code src} byte buffer to this
+ * buffer's current position, and increases both buffers' position by the
+ * number of bytes copied.
*
* @param src
- * The source byte buffer
- * @return This buffer
+ * the source byte buffer.
+ * @return this buffer.
* @exception BufferOverflowException
- * If <code>src.remaining()</code> is greater than this
- * buffer's <code>remaining()</code>
+ * if {@code src.remaining()} is greater than this buffer's
+ * {@code remaining()}.
* @exception IllegalArgumentException
- * If <code>src</code> is this buffer
+ * if {@code src} is this buffer.
* @exception ReadOnlyBufferException
- * If no changes may be made to the contents of this buffer
+ * if no changes may be made to the contents of this buffer.
*/
public ByteBuffer put(ByteBuffer src) {
if (src == this) {
@@ -857,266 +798,252 @@
}
/**
- * Write a byte to the specified index of this buffer and the position is
- * not changed.
+ * Write a byte to the specified index of this buffer without changing the
+ * position.
*
* @param index
- * The index, must be no less than zero and less than the limit
+ * the index, must not be negative and less than the limit.
* @param b
- * The byte to write
- * @return This buffer
+ * the byte to write.
+ * @return this buffer.
* @exception IndexOutOfBoundsException
- * If <code>index</code> is invalid
+ * if {@code index} is invalid.
* @exception ReadOnlyBufferException
- * If no changes may be made to the contents of this buffer
+ * if no changes may be made to the contents of this buffer.
*/
public abstract ByteBuffer put(int index, byte b);
/**
- * Writes the given char to the current position and increase the position
+ * Writes the given char to the current position and increases the position
* by 2.
* <p>
* The char is converted to bytes using the current byte order.
- * </p>
- *
+ *
* @param value
- * The char to write
- * @return This buffer
+ * the char to write.
+ * @return this buffer.
* @exception BufferOverflowException
- * If position is greater than <code>limit - 2</code>
+ * if position is greater than {@code limit - 2}.
* @exception ReadOnlyBufferException
- * If no changes may be made to the contents of this buffer
+ * if no changes may be made to the contents of this buffer.
*/
public abstract ByteBuffer putChar(char value);
/**
- * Write a char to the specified index of this buffer.
+ * Writes the given char to the specified index of this buffer.
* <p>
* The char is converted to bytes using the current byte order. The position
* is not changed.
- * </p>
- *
+ *
* @param index
- * The index, must be no less than zero and equal or less than
- * <code>limit - 2</code>
+ * the index, must not be negative and equal or less than
+ * {@code limit - 2}.
* @param value
- * The char to write
- * @return This buffer
+ * the char to write.
+ * @return this buffer.
* @exception IndexOutOfBoundsException
- * If <code>index</code> is invalid
+ * if {@code index} is invalid.
* @exception ReadOnlyBufferException
- * If no changes may be made to the contents of this buffer
+ * if no changes may be made to the contents of this buffer.
*/
public abstract ByteBuffer putChar(int index, char value);
/**
- * Writes the given double to the current position and increase the position
+ * Writes the given double to the current position and increases the position
* by 8.
* <p>
* The double is converted to bytes using the current byte order.
- * </p>
- *
+ *
* @param value
- * The double to write
- * @return This buffer
+ * the double to write.
+ * @return this buffer.
* @exception BufferOverflowException
- * If position is greater than <code>limit - 8</code>
+ * if position is greater than {@code limit - 8}.
* @exception ReadOnlyBufferException
- * If no changes may be made to the contents of this buffer
+ * if no changes may be made to the contents of this buffer.
*/
public abstract ByteBuffer putDouble(double value);
/**
- * Write a double to the specified index of this buffer.
+ * Writes the given double to the specified index of this buffer.
* <p>
* The double is converted to bytes using the current byte order. The
* position is not changed.
- * </p>
- *
+ *
* @param index
- * The index, must be no less than zero and equal or less than
- * <code>limit - 8</code>
+ * the index, must not be negative and equal or less than
+ * {@code limit - 8}.
* @param value
- * The double to write
- * @return This buffer
+ * the double to write.
+ * @return this buffer.
* @exception IndexOutOfBoundsException
- * If <code>index</code> is invalid
+ * if {@code index} is invalid.
* @exception ReadOnlyBufferException
- * If no changes may be made to the contents of this buffer
+ * if no changes may be made to the contents of this buffer.
*/
public abstract ByteBuffer putDouble(int index, double value);
/**
- * Writes the given float to the current position and increase the position
+ * Writes the given float to the current position and increases the position
* by 4.
* <p>
* The float is converted to bytes using the current byte order.
- * </p>
- *
+ *
* @param value
- * The float to write
- * @return This buffer
+ * the float to write.
+ * @return this buffer.
* @exception BufferOverflowException
- * If position is greater than <code>limit - 4</code>
+ * if position is greater than {@code limit - 4}.
* @exception ReadOnlyBufferException
- * If no changes may be made to the contents of this buffer
+ * if no changes may be made to the contents of this buffer.
*/
public abstract ByteBuffer putFloat(float value);
/**
- * Write a float to the specified index of this buffer.
+ * Writes the given float to the specified index of this buffer.
* <p>
* The float is converted to bytes using the current byte order. The
* position is not changed.
- * </p>
- *
+ *
* @param index
- * The index, must be no less than zero and equal or less than
- * <code>limit - 4</code>
+ * the index, must not be negative and equal or less than
+ * {@code limit - 4}.
* @param value
- * The float to write
- * @return This buffer
+ * the float to write.
+ * @return this buffer.
* @exception IndexOutOfBoundsException
- * If <code>index</code> is invalid
+ * if {@code index} is invalid.
* @exception ReadOnlyBufferException
- * If no changes may be made to the contents of this buffer
+ * if no changes may be made to the contents of this buffer.
*/
public abstract ByteBuffer putFloat(int index, float value);
/**
- * Writes the given int to the current position and increase the position by
+ * Writes the given int to the current position and increases the position by
* 4.
* <p>
* The int is converted to bytes using the current byte order.
- * </p>
- *
+ *
* @param value
- * The int to write
- * @return This buffer
+ * the int to write.
+ * @return this buffer.
* @exception BufferOverflowException
- * If position is greater than <code>limit - 4</code>
+ * if position is greater than {@code limit - 4}.
* @exception ReadOnlyBufferException
- * If no changes may be made to the contents of this buffer
+ * if no changes may be made to the contents of this buffer.
*/
public abstract ByteBuffer putInt(int value);
/**
- * Write a int to the specified index of this buffer.
+ * Writes the given int to the specified index of this buffer.
* <p>
* The int is converted to bytes using the current byte order. The position
* is not changed.
- * </p>
- *
+ *
* @param index
- * The index, must be no less than zero and equal or less than
- * <code>limit - 4</code>
+ * the index, must not be negative and equal or less than
+ * {@code limit - 4}.
* @param value
- * The int to write
- * @return This buffer
+ * the int to write.
+ * @return this buffer.
* @exception IndexOutOfBoundsException
- * If <code>index</code> is invalid
+ * if {@code index} is invalid.
* @exception ReadOnlyBufferException
- * If no changes may be made to the contents of this buffer
+ * if no changes may be made to the contents of this buffer.
*/
public abstract ByteBuffer putInt(int index, int value);
/**
- * Writes the given long to the current position and increase the position
+ * Writes the given long to the current position and increases the position
* by 8.
* <p>
* The long is converted to bytes using the current byte order.
- * </p>
- *
+ *
* @param value
- * The long to write
- * @return This buffer
+ * the long to write.
+ * @return this buffer.
* @exception BufferOverflowException
- * If position is greater than <code>limit - 8</code>
+ * if position is greater than {@code limit - 8}.
* @exception ReadOnlyBufferException
- * If no changes may be made to the contents of this buffer
+ * if no changes may be made to the contents of this buffer.
*/
public abstract ByteBuffer putLong(long value);
/**
- * Write a long to the specified index of this buffer.
+ * Writes the given long to the specified index of this buffer.
* <p>
* The long is converted to bytes using the current byte order. The position
* is not changed.
- * </p>
- *
+ *
* @param index
- * The index, must be no less than zero and equal or less than
- * <code>limit - 8</code>
+ * the index, must not be negative and equal or less than
+ * {@code limit - 8}.
* @param value
- * The long to write
- * @return This buffer
+ * the long to write.
+ * @return this buffer.
* @exception IndexOutOfBoundsException
- * If <code>index</code> is invalid
+ * if {@code index} is invalid.
* @exception ReadOnlyBufferException
- * If no changes may be made to the contents of this buffer
+ * if no changes may be made to the contents of this buffer.
*/
public abstract ByteBuffer putLong(int index, long value);
/**
- * Writes the given short to the current position and increase the position
+ * Writes the given short to the current position and increases the position
* by 2.
* <p>
* The short is converted to bytes using the current byte order.
- * </p>
- *
+ *
* @param value
- * The short to write
- * @return This buffer
+ * the short to write.
+ * @return this buffer.
* @exception BufferOverflowException
- * If position is greater than <code>limit - 2</code>
+ * if position is greater than {@code limit - 2}.
* @exception ReadOnlyBufferException
- * If no changes may be made to the contents of this buffer
+ * if no changes may be made to the contents of this buffer.
*/
public abstract ByteBuffer putShort(short value);
/**
- * Write a short to the specified index of this buffer.
+ * Writes the given short to the specified index of this buffer.
* <p>
* The short is converted to bytes using the current byte order. The
* position is not changed.
- * </p>
- *
+ *
* @param index
- * The index, must be no less than zero and equal or less than
- * <code>limit - 2</code>
+ * the index, must not be negative and equal or less than
+ * {@code limit - 2}.
* @param value
- * The short to write
- * @return This buffer
+ * the short to write.
+ * @return this buffer.
* @exception IndexOutOfBoundsException
- * If <code>index</code> is invalid
+ * if {@code index} is invalid.
* @exception ReadOnlyBufferException
- * If no changes may be made to the contents of this buffer
+ * if no changes may be made to the contents of this buffer.
*/
public abstract ByteBuffer putShort(int index, short value);
/**
- * Returns a sliced buffer that shares content with this buffer.
+ * Returns a sliced buffer that shares its content with this buffer.
* <p>
* The sliced buffer's capacity will be this buffer's
- * <code>remaining()</code>, and its zero position will correspond to
+ * {@code remaining()}, and it's zero position will correspond to
* this buffer's current position. The new buffer's position will be 0,
- * limit will be its capacity, and its mark is unset. The new buffer's
- * readonly property and byte order are same as this buffer.
- * </p>
+ * limit will be its capacity, and its mark is cleared. The new buffer's
+ * read-only property and byte order are the same as this buffer's.
* <p>
- * The new buffer shares content with this buffer, which means either
+ * The new buffer shares its content with this buffer, which means either
* buffer's change of content will be visible to the other. The two buffer's
* position, limit and mark are independent.
- * </p>
- *
- * @return A sliced buffer that shares content with this buffer.
+ *
+ * @return a sliced buffer that shares its content with this buffer.
*/
public abstract ByteBuffer slice();
/**
- * Returns a string represents the state of this byte buffer.
+ * Returns a string representing the state of this byte buffer.
*
- * @return A string represents the state of this byte buffer.
+ * @return a string representing the state of this byte buffer.
*/
@Override
public String toString() {
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteOrder.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteOrder.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteOrder.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteOrder.java Mon Apr 27 10:23:36 2009
@@ -19,8 +19,7 @@
import org.apache.harmony.luni.platform.Platform;
/**
- * Holds byte order constants.
- *
+ * Defines byte order constants.
*/
public final class ByteOrder {
@@ -45,10 +44,10 @@
}
/**
- * Answers the current platform byte order.
+ * Returns the current platform byte order.
*
- * @return the byte order object, which is either identical to LITTLE_ENDIAN
- * or BIG_ENDIAN.
+ * @return the byte order object, which is either LITTLE_ENDIAN or
+ * BIG_ENDIAN.
*/
public static ByteOrder nativeOrder() {
return NATIVE_ORDER;
@@ -61,10 +60,12 @@
this.name = name;
}
- /*
- * (non-Javadoc)
+ /**
+ * Returns a string that describes this object.
*
- * @see java.lang.Object#toString()
+ * @return "BIG_ENDIAN" for {@link #BIG_ENDIAN ByteOrder.BIG_ENDIAN}
+ * objects, "LITTLE_ENDIAN" for
+ * {@link #LITTLE_ENDIAN ByteOrder.LITTLE_ENDIAN} objects.
*/
@Override
public String toString() {