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 [4/7] - in
/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio:
./ channels/ channels/spi/
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ShortBuffer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ShortBuffer.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ShortBuffer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ShortBuffer.java Mon Apr 27 10:23:36 2009
@@ -18,7 +18,7 @@
package java.nio;
/**
- * A buffer of <code>short</code>s.
+ * A buffer of shorts.
* <p>
* A short buffer can be created in either of the following ways:
* <ul>
@@ -29,19 +29,18 @@
* <li>Use {@link java.nio.ByteBuffer#asShortBuffer() ByteBuffer.asShortBuffer}
* to create a short buffer based on a byte buffer.</li>
* </ul>
- * </p>
*/
public abstract class ShortBuffer extends Buffer implements
Comparable<ShortBuffer> {
/**
- * Creates a short buffer based on a new allocated short array.
+ * Creates a short buffer based on a newly allocated short array.
*
* @param capacity
- * The capacity of the new buffer
- * @return The created short buffer
+ * the capacity of the new buffer.
+ * @return the created short buffer.
* @throws IllegalArgumentException
- * If <code>capacity</code> is less than zero
+ * if {@code capacity} is less than zero.
*/
public static ShortBuffer allocate(int capacity) {
if (capacity < 0) {
@@ -54,36 +53,33 @@
* Creates a new short buffer by wrapping the given short 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 short array which the new buffer will be based on
- * @return The created short buffer
+ * the short array which the new buffer will be based on.
+ * @return the created short buffer.
*/
public static ShortBuffer wrap(short[] array) {
return wrap(array, 0, array.length);
}
/**
- * Creates new a short buffer by wrapping the given short array.
+ * Creates a new short buffer by wrapping the given short 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 short array which the new buffer will be based on
+ * the short 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 short buffer
+ * the length, must not be negative and not greater than
+ * {@code array.length - start}.
+ * @return the created short 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 ShortBuffer wrap(short[] array, int start, int len) {
if (array == null) {
@@ -101,8 +97,8 @@
}
/**
- * Constructs a <code>ShortBuffer</code> with given capacity.
- *
+ * Constructs a {@code ShortBuffer} with given capacity.
+ *
* @param capacity
* The capacity of the buffer
*/
@@ -111,13 +107,13 @@
}
/**
- * Returns the short array which this buffer is based on, if there's one.
+ * Returns the short array which this buffer is based on, if there is one.
*
- * @return The short array which this buffer is based on
+ * @return the short array which this buffer is based on.
* @exception ReadOnlyBufferException
- * If this buffer is based on an array, but it is readonly
+ * if this buffer is based on an array, but it is read-only.
* @exception UnsupportedOperationException
- * If this buffer is not based on an array
+ * if this buffer is not based on an array.
*/
public final short[] array() {
return protectedArray();
@@ -125,65 +121,60 @@
/**
* Returns the offset of the short 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 short array which this buffer is based on
+ * The offset is the index of the array corresponding to the zero position
+ * of the buffer.
+ *
+ * @return the offset of the short array which this buffer is based on.
* @exception ReadOnlyBufferException
- * If this buffer is based on an array, but it is readonly
+ * if this buffer is based on an array, but it is read-only.
* @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();
}
/**
- * Returns a readonly buffer that shares content with this buffer.
- * <p>
- * The returned buffer is guaranteed to be a new instance, even 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's.
+ * <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 ShortBuffer asReadOnlyBuffer();
/**
* Compacts this short buffer.
* <p>
- * The remaining <code>short</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
- * cleared.
- * </p>
- *
- * @return This buffer
+ * The remaining shorts 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.
+ *
+ * @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 ShortBuffer compact();
/**
- * Compare the remaining <code>short</code>s of this buffer to another
- * short buffer's remaining <code>short</code>s.
+ * Compare the remaining shorts of this buffer to another short buffer's
+ * remaining shorts.
*
* @param otherBuffer
- * Another short 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 short buffer.
+ * @return a negative value if this is less than {@code otherBuffer}; 0 if
+ * this equals to {@code otherBuffer}; a positive value if this is
+ * greater than {@code otherBuffer}.
* @exception ClassCastException
- * If <code>other</code> is not a short buffer
+ * if {@code otherBuffer} is not a short buffer.
*/
public int compareTo(ShortBuffer otherBuffer) {
int compareRemaining = (remaining() < otherBuffer.remaining()) ? remaining()
@@ -205,36 +196,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. The duplicated 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 duplicated buffer that shares content with this buffer.
+ *
+ * @return a duplicated buffer that shares its content with this buffer.
*/
public abstract ShortBuffer duplicate();
/**
- * Tests whether this short buffer equals to another object.
- * <p>
- * If <code>other</code> is not a short buffer, then false is returned.
- * </p>
+ * Checks whether this short buffer is equal to another object.
* <p>
- * Two short buffers are equals if, and only if, their remaining
- * <code>short</code>s are exactly the same. Position, limit, capacity
- * and mark are not considered.
- * </p>
- *
+ * If {@code other} is not a short buffer then {@code false} is returned.
+ * Two short buffers are equal if and only if their remaining shorts are
+ * exactly the same. Position, limit, capacity and mark are not considered.
+ *
* @param other
- * the object to be compared against
- * @return Whether this short buffer equals to another object.
+ * the object to compare with this short buffer.
+ * @return {@code true} if this short buffer is equal to {@code other},
+ * {@code false} otherwise.
*/
@Override
public boolean equals(Object other) {
@@ -258,54 +244,50 @@
}
/**
- * Returns the short at the current position and increase the position by 1.
+ * Returns the short at the current position and increases the position by
+ * 1.
*
- * @return The short at the current position.
+ * @return the short 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 short get();
/**
- * Reads <code>short</code>s from the current position into the specified
- * short array and increase the position by the number of <code>short</code>s
- * read.
+ * Reads shorts from the current position into the specified short array and
+ * increases the position by the number of shorts 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 short array
- * @return This buffer
+ * the destination short 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 ShortBuffer get(short[] dest) {
return get(dest, 0, dest.length);
}
/**
- * Reads <code>short</code>s from the current position into the specified
- * short array, starting from the specified offset, and increase the
- * position by the number of <code>short</code>s read.
+ * Reads shorts from the current position into the specified short array,
+ * starting from the specified offset, and increases the position by the
+ * number of shorts read.
*
* @param dest
- * The target short array
+ * the target short array.
* @param off
- * The offset of the short array, must be no less than zero and
- * no greater than <code>dest.length</code>
+ * the offset of the short array, must not be negative and not
+ * greater than {@code dest.length}.
* @param len
- * The number of <code>short</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 shorts to read, must be no less than zero 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 ShortBuffer get(short[] dest, int off, int len) {
int length = dest.length;
@@ -322,35 +304,32 @@
}
/**
- * Returns a short at the specified index, and the position is not changed.
+ * Returns the short at the specified index; the position is not changed.
*
* @param index
- * The index, must be no less than zero and less than limit
- * @return A short at the specified index.
+ * the index, must not be negative and less than limit.
+ * @return a short at the specified index.
* @exception IndexOutOfBoundsException
- * If index is invalid
+ * if index is invalid.
*/
public abstract short get(int index);
/**
- * Returns whether this buffer is based on a short array and is read/write.
- * <p>
- * If this buffer is readonly, then false is returned.
- * </p>
- *
- * @return Whether this buffer is based on a short array and is read/write.
+ * Indicates whether this buffer is based on a short array and is
+ * read/write.
+ *
+ * @return {@code true} if this buffer is based on a short array and
+ * provides read/write access, {@code false} otherwise.
*/
public final boolean hasArray() {
return protectedHasArray();
}
/**
- * Hash code is calculated from the remaining <code>short</code>s.
- * <p>
- * Position, limit, capacity and mark don't affect the hash code.
- * </p>
- *
- * @return The hash code calculated from the remaining <code>short</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 shorts.
*/
@Override
public int hashCode() {
@@ -363,112 +342,103 @@
}
/**
- * Returns true if this buffer is direct.
- * <p>
- * 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.
- * </p>
+ * Indicates whether this buffer is direct. A direct buffer will try its
+ * best to take advantage of native memory APIs and it may not stay in the
+ * Java heap, so it is not affected by garbage collection.
* <p>
- * A short buffer is direct, if it is based on a byte buffer and the byte
+ * A short 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.
+ *
+ * @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>short</code>s from/to <code>byte</code>s.
+ * Returns the byte order used by this buffer when converting shorts from/to
+ * bytes.
* <p>
* If this buffer is not based on a byte buffer, then always return the
* platform's native byte order.
- * </p>
- *
- * @return The byte order used by this buffer when converting
- * <code>short</code>s from/to <code>byte</code>s.
+ *
+ * @return the byte order used by this buffer when converting shorts from/to
+ * bytes.
*/
public abstract ByteOrder order();
/**
- * Child class implements this method to realize <code>array()</code>.
- *
- * @return see <code>array()</code>
+ * Child class implements this method to realize {@code array()}.
+ *
+ * @return see {@code array()}
*/
abstract short[] protectedArray();
/**
- * Child class implements this method to realize <code>arrayOffset()</code>.
- *
- * @return see <code>arrayOffset()</code>
+ * Child class implements this method to realize {@code arrayOffset()}.
+ *
+ * @return see {@code arrayOffset()}
*/
abstract int protectedArrayOffset();
/**
- * Child class implements this method to realize <code>hasArray()</code>.
- *
- * @return see <code>hasArray()</code>
+ * Child class implements this method to realize {@code hasArray()}.
+ *
+ * @return see {@code hasArray()}
*/
abstract boolean protectedHasArray();
/**
- * 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 1.
*
* @param s
- * The short to write
- * @return This buffer
+ * the short 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 ShortBuffer put(short s);
/**
- * Writes <code>short</code>s in the given short array to the current
- * position and increase the position by the number of <code>short</code>s
- * written.
+ * Writes shorts from the given short array to the current position and
+ * increases the position by the number of shorts 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 short array
- * @return This buffer
+ * the source short 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 ShortBuffer put(short[] src) {
return put(src, 0, src.length);
}
/**
- * Writes <code>short</code>s in the given short array, starting from the
- * specified offset, to the current position and increase the position by
- * the number of <code>short</code>s written.
+ * Writes shorts from the given short array, starting from the specified
+ * offset, to the current position and increases the position by the number
+ * of shorts written.
*
* @param src
- * The source short array
+ * the source short array.
* @param off
- * The offset of short array, must be no less than zero and no
- * greater than <code>src.length</code>
+ * the offset of short array, must not be negative and not
+ * greater than {@code src.length}.
* @param len
- * The number of <code>short</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 shorts to write, must be no less than zero 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 ShortBuffer put(short[] src, int off, int len) {
int length = src.length;
@@ -486,20 +456,20 @@
}
/**
- * Writes all the remaining <code>short</code>s of the <code>src</code>
- * short buffer to this buffer's current position, and increase both
- * buffers' position by the number of <code>short</code>s copied.
+ * Writes all the remaining shorts of the {@code src} short buffer to this
+ * buffer's current position, and increases both buffers' position by the
+ * number of shorts copied.
*
* @param src
- * The source short buffer
- * @return This buffer
+ * the source short 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 ShortBuffer put(ShortBuffer src) {
if (src == this) {
@@ -515,44 +485,42 @@
}
/**
- * Write a short to the specified index of this buffer and the position is
- * not changed.
+ * Writes a short to the specified index of this buffer; the position is not
+ * changed.
*
* @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 s
- * The short to write
- * @return This buffer
+ * the short to write.
+ * @return this buffer.
* @exception IndexOutOfBoundsException
- * If index is invalid
+ * if 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 ShortBuffer put(int index, short s);
/**
- * 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
- * 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>
+ * The sliced buffer's capacity will be this buffer's {@code remaining()},
+ * and its 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 cleared. The new buffer's read-only property and byte order are
+ * 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 ShortBuffer slice();
/**
- * Returns a string represents the state of this short buffer.
+ * Returns a string representing the state of this short buffer.
*
- * @return A string represents the state of this short buffer.
+ * @return a string representing the state of this short buffer.
*/
@Override
public String toString() {
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/AlreadyConnectedException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/AlreadyConnectedException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/AlreadyConnectedException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/AlreadyConnectedException.java Mon Apr 27 10:23:36 2009
@@ -17,15 +17,15 @@
package java.nio.channels;
/**
- * Thrown when an attempt is made to connect a SocketChannel that is already
- * connected.
+ * An {@code AlreadyConnectedException} is thrown when an attempt is made to
+ * connect a SocketChannel that is already connected.
*/
public class AlreadyConnectedException extends IllegalStateException {
private static final long serialVersionUID = -7331895245053773357L;
/**
- * Default constructor.
+ * Constructs an {@code AlreadyConnectedException}.
*/
public AlreadyConnectedException() {
super();
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/AsynchronousCloseException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/AsynchronousCloseException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/AsynchronousCloseException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/AsynchronousCloseException.java Mon Apr 27 10:23:36 2009
@@ -17,15 +17,15 @@
package java.nio.channels;
/**
- * Thrown when the underlying channel for an IO operation is closed by another
- * thread.
+ * An {@code AsynchronousCloseException} is thrown when the underlying channel
+ * for an I/O operation is closed by another thread.
*/
public class AsynchronousCloseException extends ClosedChannelException {
private static final long serialVersionUID = 6891178312432313966L;
/**
- * Default constructor
+ * Constructs an {@code AsynchronousCloseException}.
*/
public AsynchronousCloseException() {
super();
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ByteChannel.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ByteChannel.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ByteChannel.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ByteChannel.java Mon Apr 27 10:23:36 2009
@@ -21,7 +21,9 @@
* <p>
* The methods for the byte channel are precisely those defined by readable and
* writable byte channels.
- * </p>
+ *
+ * @see ReadableByteChannel
+ * @see WritableByteChannel
*/
public interface ByteChannel extends ReadableByteChannel, WritableByteChannel {
// No methods defined.
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/CancelledKeyException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/CancelledKeyException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/CancelledKeyException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/CancelledKeyException.java Mon Apr 27 10:23:36 2009
@@ -17,7 +17,8 @@
package java.nio.channels;
/**
- * Thrown when an invalid selection key is used.
+ * A {@code CancelledKeyException} is thrown when an invalid selection key is
+ * used.
*/
public class CancelledKeyException extends IllegalStateException {
@@ -27,7 +28,7 @@
private static final long serialVersionUID = -8438032138028814268L;
/**
- * Default constructor.
+ * Constructs a {@code CancelledKeyException}.
*/
public CancelledKeyException() {
super();
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Channel.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Channel.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Channel.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Channel.java Mon Apr 27 10:23:36 2009
@@ -20,44 +20,38 @@
import java.io.IOException;
/**
- * A channel is a conduit to IO services covering such items as files, sockets,
- * hardware devices, IO ports, or some software component.
+ * A channel is a conduit to I/O services covering such items as files, sockets,
+ * hardware devices, I/O ports or some software component.
* <p>
- * Channels are open upon creation, and can be explicitly closed. Once a channel
- * is closed it cannot be re-opened, and attempts to perform IO operations on
- * the closed channel result in a <code>ClosedChannelException
- * </code>.
- * </p>
+ * Channels are open upon creation, and can be closed explicitly. Once a channel
+ * is closed it cannot be re-opened, and any attempts to perform I/O operations
+ * on the closed channel result in a <code>ClosedChannelException</code>.
* <p>
- * Particular implementations or sub-interfaces of Channel dictate whether they
- * are thread-safe or not.
- * </p>
+ * Particular implementations or sub-interfaces of {@code Channel} dictate
+ * whether they are thread-safe or not.
*/
public interface Channel extends Closeable {
/**
- * Answers whether this channel is open or not.
+ * Returns whether this channel is open or not.
*
- * @return true if the channel is open, otherwise answers false.
+ * @return true if the channel is open, otherwise returns false.
*/
public boolean isOpen();
/**
- * Closes an open channel.
- *
- * If the channel is already closed this method has no effect. If there is a
- * problem with closing the channel then the method throws an IOException
- * and the exception contains reasons for the failure.
+ * Closes an open channel. If the channel is already closed then this method
+ * has no effect. If there is a problem with closing the channel then the
+ * method throws an IOException and the exception contains reasons for the
+ * failure.
* <p>
* If an attempt is made to perform an operation on a closed channel then a
- * <code>ClosedChannelException</code> will be thrown on that attempt.
- * </p>
+ * {@link ClosedChannelException} will be thrown on that attempt.
* <p>
- * If multiple threads attempts to simultaneously close a channel, then only
+ * If multiple threads attempt to simultaneously close a channel, then only
* one thread will run the closure code, and others will be blocked until
* the first returns.
- * </p>
- *
+ *
* @throws IOException
* if a problem occurs closing the channel.
*/
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Channels.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Channels.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Channels.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Channels.java Mon Apr 27 10:23:36 2009
@@ -43,10 +43,20 @@
}
/**
- * Answers an input stream on the given channel
+ * Returns an input stream on the given channel. The resulting stream has
+ * the following properties:
+ * <ul>
+ * <li>If the stream is closed, then the underlying channel is closed as
+ * well.</li>
+ * <li>It is thread safe.</li>
+ * <li>It throws an {@link IllegalBlockingModeException} if the channel is
+ * in non-blocking mode and {@code read} is called.</li>
+ * <li>Neither {@code mark} nor {@code reset} is supported.</li>
+ * <li>It is not buffered.</li>
+ * </ul>
*
* @param channel
- * The channel to be wrapped in an InputStream.
+ * the channel to be wrapped by an InputStream.
* @return an InputStream that takes bytes from the given byte channel.
*/
public static InputStream newInputStream(ReadableByteChannel channel) {
@@ -54,10 +64,19 @@
}
/**
- * Answers an output stream on the given channel
+ * Returns an output stream on the given channel. The resulting stream has
+ * the following properties:
+ * <ul>
+ * <li>If the stream is closed, then the underlying channel is closed as
+ * well.</li>
+ * <li>It is thread safe.</li>
+ * <li>It throws an {@link IllegalBlockingModeException} if the channel is
+ * in non-blocking mode and {@code write} is called.</li>
+ * <li>It is not buffered.</li>
+ * </ul>
*
* @param channel
- * the channel to be wrapped in an OutputStream.
+ * the channel to be wrapped by an OutputStream.
* @return an OutputStream that puts bytes onto the given byte channel.
*/
public static OutputStream newOutputStream(WritableByteChannel channel) {
@@ -65,10 +84,16 @@
}
/**
- * Answers a channel on the given input stream
+ * Returns a readable channel on the given input stream. The resulting
+ * channel has the following properties:
+ * <ul>
+ * <li>If the channel is closed, then the underlying stream is closed as
+ * well.</li>
+ * <li>It is not buffered.</li>
+ * </ul>
*
* @param inputStream
- * the stream to be wrapped in a byte channel.
+ * the stream to be wrapped by a byte channel.
* @return a byte channel that reads bytes from the input stream.
*/
public static ReadableByteChannel newChannel(InputStream inputStream) {
@@ -76,10 +101,17 @@
}
/**
- * Answers a channel on the given output stream
+ * Returns a writable channel on the given output stream.
*
+ * The resulting channel has following properties:
+ * <ul>
+ * <li>If the channel is closed, then the underlying stream is closed as
+ * well.</li>
+ * <li>It is not buffered.</li>
+ * </ul>
+ *
* @param outputStream
- * the stream to be wrapped in a byte channel.
+ * the stream to be wrapped by a byte channel.
* @return a byte channel that writes bytes to the output stream.
*/
public static WritableByteChannel newChannel(OutputStream outputStream) {
@@ -87,15 +119,16 @@
}
/**
- * Answers a reader that decodes bytes from a channel.
+ * Returns a reader that decodes bytes from a channel.
*
* @param channel
- * Channel to be read.
+ * the Channel to be read.
* @param decoder
- * Charset decoder to be used.
+ * the Charset decoder to be used.
* @param minBufferCapacity
- * The minimum size of byte buffer, -1 means to use default size.
- * @return The reader.
+ * The minimum size of the byte buffer, -1 means to use the
+ * default size.
+ * @return the reader.
*/
public static Reader newReader(ReadableByteChannel channel,
CharsetDecoder decoder, int minBufferCapacity) {
@@ -104,13 +137,16 @@
}
/**
- * Answers a reader that decodes bytes from a channel.
+ * Returns a reader that decodes bytes from a channel. This method creates a
+ * reader with a buffer of default size.
*
* @param channel
- * Channel to be read.
+ * the Channel to be read.
* @param charsetName
- * Name of charset.
- * @return The reader.
+ * the name of the charset.
+ * @return the reader.
+ * @throws java.nio.charset.UnsupportedCharsetException
+ * if the given charset name is not supported.
*/
public static Reader newReader(ReadableByteChannel channel,
String charsetName) {
@@ -118,16 +154,17 @@
}
/**
- * Answers a writer that encodes characters by encoder and output bytes to a
- * channel.
+ * Returns a writer that encodes characters with the specified
+ * {@code encoder} and sends the bytes to the specified channel.
*
* @param channel
- * Channel to be written.
+ * the Channel to write to.
* @param encoder
- * Charset decoder to be used.
+ * the CharsetEncoder to be used.
* @param minBufferCapacity
- * The minimum size of byte buffer, -1 means to use default size.
- * @return The writer.
+ * the minimum size of the byte buffer, -1 means to use the
+ * default size.
+ * @return the writer.
*/
public static Writer newWriter(WritableByteChannel channel,
CharsetEncoder encoder, int minBufferCapacity) {
@@ -136,14 +173,17 @@
}
/**
- * Answers a writer that encodes characters by encoder and output bytes to a
- * channel.
+ * Returns a writer that encodes characters with the specified
+ * {@code encoder} and sends the bytes to the specified channel. This method
+ * creates a writer with a buffer of default size.
*
* @param channel
- * Channel to be written.
+ * the Channel to be written to.
* @param charsetName
- * Name of charset.
- * @return The writer.
+ * the name of the charset.
+ * @return the writer.
+ * @throws java.nio.charset.UnsupportedCharsetException
+ * if the given charset name is not supported.
*/
public static Writer newWriter(WritableByteChannel channel,
String charsetName) {
@@ -171,9 +211,6 @@
channel = aChannel;
}
- /**
- * @see java.io.InputStream#read()
- */
@Override
public synchronized int read() throws IOException {
byte[] oneByte = new byte[1];
@@ -185,9 +222,6 @@
return -1;
}
- /**
- * @see java.io.InputStream#close()
- */
@Override
public synchronized void close() throws IOException {
channel.close();
@@ -204,9 +238,6 @@
super(aChannel);
}
- /**
- * @see java.io.InputStream#read(byte[], int, int)
- */
@Override
public synchronized int read(byte[] target, int offset, int length)
throws IOException {
@@ -237,9 +268,6 @@
super(aChannel);
}
- /**
- * @see java.io.InputStream#read(byte[], int, int)
- */
@Override
public synchronized int read(byte[] target, int offset, int length)
throws IOException {
@@ -267,9 +295,6 @@
channel = aChannel;
}
- /**
- * @see java.io.OutputStream#write(int)
- */
@Override
public synchronized void write(int oneByte) throws IOException {
byte[] wrappedByte = new byte[1];
@@ -277,9 +302,6 @@
write(wrappedByte);
}
- /**
- * @see java.io.OutputStream#write(byte[], int, int)
- */
@Override
public synchronized void write(byte[] source, int offset, int length)
throws IOException {
@@ -299,9 +321,6 @@
channel.write(buffer);
}
- /**
- * @see java.io.OutputStream#close()
- */
@Override
public synchronized void close() throws IOException {
channel.close();
@@ -320,9 +339,6 @@
inputStream = aInputStream;
}
- /**
- * @see java.nio.channels.ReadableByteChannel#read(java.nio.ByteBuffer)
- */
public synchronized int read(ByteBuffer target) throws IOException {
if (!isOpen()) {
throw new ClosedChannelException();
@@ -342,9 +358,6 @@
return readCount;
}
- /**
- * @see java.nio.channels.spi.AbstractInterruptibleChannel#implCloseChannel()
- */
@Override
protected void implCloseChannel() throws IOException {
inputStream.close();
@@ -363,9 +376,6 @@
outputStream = aOutputStream;
}
- /**
- * @see java.nio.channels.WritableByteChannel#write(java.nio.ByteBuffer)
- */
public synchronized int write(ByteBuffer source) throws IOException {
if (!isOpen()) {
throw new ClosedChannelException();
@@ -385,9 +395,6 @@
return bytesRemain;
}
- /**
- * @see java.nio.channels.spi.AbstractInterruptibleChannel#implCloseChannel()
- */
@Override
protected void implCloseChannel() throws IOException {
outputStream.close();
@@ -422,9 +429,6 @@
chars.limit(0);
}
- /**
- * @see java.io.Reader#close()
- */
@Override
public void close() throws IOException {
synchronized (lock) {
@@ -436,9 +440,6 @@
}
}
- /**
- * @see java.io.Reader#ready()
- */
@Override
public boolean ready() {
synchronized (lock) {
@@ -454,18 +455,12 @@
}
}
- /**
- * @see java.io.Reader#read()
- */
@Override
public int read() throws IOException {
return IOUtil.readInputStreamReader(inputStream, bytes, chars,
decoder, lock);
}
- /**
- * @see java.io.Reader#read(char[], int, int)
- */
@Override
public int read(char[] buf, int offset, int length) throws IOException {
return IOUtil.readInputStreamReader(buf, offset, length,
@@ -496,9 +491,6 @@
encoder = aEncoder;
}
- /**
- * @see java.io.Writer#close()
- */
@Override
public void close() throws IOException {
synchronized (lock) {
@@ -512,9 +504,6 @@
}
}
- /**
- * @see java.io.Writer#flush()
- */
@Override
public void flush() throws IOException {
IOUtil
@@ -522,27 +511,18 @@
lock);
}
- /**
- * @see java.io.Writer#write(char[], int, int)
- */
@Override
public void write(char[] buf, int offset, int count) throws IOException {
IOUtil.writeOutputStreamWriter(buf, offset, count, outputStream,
byteBuf, encoder, lock);
}
- /**
- * @see java.io.Writer#write(int)
- */
@Override
public void write(int oneChar) throws IOException {
IOUtil.writeOutputStreamWriter(oneChar, outputStream, byteBuf,
encoder, lock);
}
- /**
- * @see java.io.Writer#write(java.lang.String, int, int)
- */
@Override
public void write(String str, int offset, int count) throws IOException {
IOUtil.writeOutputStreamWriter(str, offset, count, outputStream,
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ClosedByInterruptException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ClosedByInterruptException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ClosedByInterruptException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ClosedByInterruptException.java Mon Apr 27 10:23:36 2009
@@ -17,18 +17,19 @@
package java.nio.channels;
/**
- * Thrown when a thread is interrupted in a blocking IO operation.
+ * A {@code ClosedByInterruptException} is thrown when a thread is interrupted
+ * in a blocking I/O operation.
* <p>
- * When the thread is interrupted by a call to <code>interrupt()</code> it
- * will close the channel, set the interrupt status of the thread to true, and
- * throw a <code>ClosedByInterruptException</code>.
+ * When the thread is interrupted by a call to {@code interrupt()}, it closes
+ * the channel, sets the interrupt status of the thread to {@code true} and
+ * throws a {@code ClosedByInterruptException}.
*/
public class ClosedByInterruptException extends AsynchronousCloseException {
private static final long serialVersionUID = -4488191543534286750L;
/**
- * Default constructor.
+ * Constructs a {@code ClosedByInterruptException}.
*/
public ClosedByInterruptException() {
super();
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ClosedChannelException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ClosedChannelException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ClosedChannelException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ClosedChannelException.java Mon Apr 27 10:23:36 2009
@@ -19,15 +19,15 @@
import java.io.IOException;
/**
- * This exception is thrown when a channel is closed for the type of operation
- * attempted.
+ * A {@code ClosedChannelException} is thrown when a channel is closed for the
+ * type of operation attempted.
*/
public class ClosedChannelException extends IOException {
private static final long serialVersionUID = 882777185433553857L;
/**
- * Default constructor.
+ * Constructs a {@code ClosedChannelException}.
*/
public ClosedChannelException() {
super();
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ClosedSelectorException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ClosedSelectorException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ClosedSelectorException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ClosedSelectorException.java Mon Apr 27 10:23:36 2009
@@ -17,14 +17,15 @@
package java.nio.channels;
/**
- * Thrown when an a selector is closed and an IO operation is attempted.
+ * A {@code ClosedSelectorException} is thrown when a {@link Selector selector}
+ * is closed and an I/O operation is attempted.
*/
public class ClosedSelectorException extends IllegalStateException {
private static final long serialVersionUID = 6466297122317847835L;
/**
- * Default constructor.
+ * Constructs a {@code ClosedSelectorException}.
*/
public ClosedSelectorException() {
super();
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ConnectionPendingException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ConnectionPendingException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ConnectionPendingException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ConnectionPendingException.java Mon Apr 27 10:23:36 2009
@@ -17,15 +17,16 @@
package java.nio.channels;
/**
- * Thrown when an attempt is made to connect a SocketChannel that has a
- * non-blocking connection already underway.
+ * A {@code ConnectionPendingException} is thrown when an attempt is made to
+ * connect a {@link SocketChannel} that has a non-blocking connection already
+ * underway.
*/
public class ConnectionPendingException extends IllegalStateException {
private static final long serialVersionUID = 2008393366501760879L;
/**
- * Default constructor.
+ * Constructs a {@code ConnectionPendingException}.
*/
public ConnectionPendingException() {
super();
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/DatagramChannel.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/DatagramChannel.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/DatagramChannel.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/DatagramChannel.java Mon Apr 27 10:23:36 2009
@@ -27,21 +27,19 @@
import org.apache.harmony.luni.platform.Platform;
/**
- * A DatagramChannel is a selectable channel for part abstraction of datagram
- * socket. The <code>socket</code> method of this class can return the related
- * <code>DatagramSocket</code> instance, which can handle the socket.
+ * A {@code DatagramChannel} is a selectable channel that represents a partial
+ * abstraction of a datagram socket. The {@code socket} method of this class can
+ * return the related {@code DatagramSocket} instance, which can handle the
+ * socket.
* <p>
- * A datagram channel is open but not connected when created by
- * <code>open</code> method. After connected, it will keep the connected
- * status before disconnecting or closing. The benefit of a connected channel is
- * the reduced effort of security checks during send and receive. When invoking
- * <code>read</code> or <code>write</code>, a connected channel is
- * required.
- * </p>
+ * A datagram channel is open but not connected when created with the
+ * {@code open()} method. After it is connected, it will keep the connected
+ * status until it is disconnected or closed. The benefit of a connected channel
+ * is the reduced effort of security checks during send and receive. When
+ * invoking {@code read} or {@code write}, a connected channel is required.
* <p>
- * Datagram channels are thread-safe, no more than one thread can read or write
- * at given time.
- * </p>
+ * Datagram channels are thread-safe; only one thread can read or write at the
+ * same time.
*/
public abstract class DatagramChannel extends AbstractSelectableChannel
implements ByteChannel, ScatteringByteChannel, GatheringByteChannel {
@@ -51,37 +49,36 @@
}
/**
- * Constructor for this class.
+ * Constructs a new {@code DatagramChannel}.
*
* @param selectorProvider
- * A instance of SelectorProvider
+ * an instance of SelectorProvider.
*/
protected DatagramChannel(SelectorProvider selectorProvider) {
super(selectorProvider);
}
/**
- * Create a open and not-connected datagram channel.
+ * Creates an opened and not-connected datagram channel.
* <p>
- * This channel is got by <code>openDatagramChannel</code> method of the
- * default <code>SelectorProvider </code> instance.
- * </p>
- *
- * @return The new created channel which is open but not-connected.
+ * This channel is created by calling the <code>openDatagramChannel</code>
+ * method of the default {@link SelectorProvider} instance.
+ *
+ * @return the new channel which is open but not connected.
* @throws IOException
- * If some IO problem occurs.
+ * if some I/O error occurs.
*/
public static DatagramChannel open() throws IOException {
return SelectorProvider.provider().openDatagramChannel();
}
/**
- * Get the valid operations of this channel. Datagram channels support read
- * and write operation, so this method returns (
+ * Gets the valid operations of this channel. Datagram channels support read
+ * and write operations, so this method returns (
* <code>SelectionKey.OP_READ</code> | <code>SelectionKey.OP_WRITE</code> ).
*
* @see java.nio.channels.SelectableChannel#validOps()
- * @return Valid operations in bit-set.
+ * @return valid operations in bit-set.
*/
@Override
public final int validOps() {
@@ -89,255 +86,251 @@
}
/**
- * Return the related datagram socket of this channel, which won't declare
- * public methods that not declared in <code>DatagramSocket</code>.
+ * Returns the related datagram socket of this channel, which does not
+ * define additional public methods to those defined by
+ * {@link DatagramSocket}.
*
- * @return The related DatagramSocket instance.
+ * @return the related DatagramSocket instance.
*/
public abstract DatagramSocket socket();
/**
- * Answer whether this channel's socket is connected or not.
+ * Returns whether this channel's socket is connected or not.
*
- * @return <code>true</code> for this channel's socket is connected;
+ * @return <code>true</code> if this channel's socket is connected;
* <code>false</code> otherwise.
*/
public abstract boolean isConnected();
/**
- * Connect the socket of this channel to a remote address, which is the only
- * communication peer of getting and sending datagrams after connected.
- * <p>
- * This method can be called at any moment, and won't affect the processing
- * read and write operation. The connect status won't changed before
- * disconnected and closed.
- * </p>
- * <p>
- * This method just execute the same security checks as the connect method
- * of the <code>DatagramSocket</code> class.
- * </p>
- *
+ * Connects the socket of this channel to a remote address, which is the
+ * only communication peer for getting and sending datagrams after being
+ * connected.
+ * <p>
+ * This method can be called at any time without affecting the read and
+ * write operations being processed at the time the method is called. The
+ * connection status does not change until the channel is disconnected or
+ * closed.
+ * <p>
+ * This method executes the same security checks as the connect method of
+ * the {@link DatagramSocket} class.
+ *
* @param address
- * The address to be connected.
- * @return This channel.
+ * the address to be connected to.
+ * @return this channel.
* @throws ClosedChannelException
- * If the channel is already closed.
+ * if the channel is already closed.
* @throws AsynchronousCloseException
- * If the channel is closed by another thread while this method
+ * if the channel is closed by another thread while this method
* is in operation.
* @throws ClosedByInterruptException
- * If another thread interrupts the calling thread while the
+ * if another thread interrupts the calling thread while the
* operation is in progress. The calling thread will have the
- * interrupt state set, and the channel will be closed.
+ * interrupt state set and the channel will be closed.
* @throws SecurityException
- * If there is a security manager, and the address is not
- * permitted to access.
+ * if there is a security manager, and the address is not
+ * permitted to be accessed.
* @throws IOException
- * Some other IO error occurred.
+ * if some other I/O error occurrs.
*/
public abstract DatagramChannel connect(SocketAddress address)
throws IOException;
/**
- * Disconnect the socket of this channel, which is connected before for
- * getting and sending datagrams.
+ * Disconnects the socket of this channel, which has been connected before
+ * in order to send and receive datagrams.
* <p>
- * This method can be called at any moment, and won't affect the processing
- * read and write operation. It won't has any effect if the socket is not
- * connected or the channel is closed.
- * </p>
- *
- * @return This channel.
+ * This method can be called at any time without affecting the read and
+ * write operations being underway. It does not have any effect if the
+ * socket is not connected or the channel is closed.
+ *
+ * @return this channel.
* @throws IOException
- * Some other IO error occurred.
+ * some other I/O error occurs.
*/
public abstract DatagramChannel disconnect() throws IOException;
/**
- * Get a datagram from this channel.
+ * Gets a datagram from this channel.
* <p>
- * This method transfers the datagram from the channel into the target byte
- * buffer and return the address of the datagram, if the datagram is
- * available or will be available as this channel is in blocking mode. This
- * method returns <code>null</code> if the datagram is not available now
- * and the channel is in non-blocking mode. The transfer start at the
- * current position of the buffer, and the residual part of the datagram
- * will be ignored if there is no efficient remaining in the buffer to store
- * the datagram.
- * </p>
- * <p>
- * This method can be called at any moment, and will block if there is
- * another thread started a read operation on the channel.
- * </p>
- * <p>
- * This method just execute the same security checks as the receive method
- * of the <code>DatagramSocket</code> class.
- * </p>
- *
+ * This method transfers a datagram from the channel into the target byte
+ * buffer. If this channel is in blocking mode, it waits for the datagram
+ * and returns its address when it is available. If this channel is in
+ * non-blocking mode and no datagram is available, it returns {@code null}
+ * immediately. The transfer starts at the current position of the buffer,
+ * and if there is not enough space remaining in the buffer to store the
+ * datagram then the part of the datagram that does not fit is discarded.
+ * <p>
+ * This method can be called at any time and it will block if there is
+ * another thread that has started a read operation on the channel.
+ * <p>
+ * This method executes the same security checks as the receive method of
+ * the {@link DatagramSocket} class.
+ *
* @param target
- * The byte buffer to store the received datagram.
- * @return Address of the datagram if the transfer is performed, or null if
- * the channel is in non-blocking mode and the datagram are
- * unavailable.
+ * the byte buffer to store the received datagram.
+ * @return the address of the datagram if the transfer is performed, or null
+ * if the channel is in non-blocking mode and no datagram is
+ * available.
* @throws ClosedChannelException
- * If the channel is already closed.
+ * if the channel is already closed.
* @throws AsynchronousCloseException
- * If the channel is closed by another thread while this method
+ * if the channel is closed by another thread while this method
* is in operation.
* @throws ClosedByInterruptException
- * If another thread interrupts the calling thread while the
+ * if another thread interrupts the calling thread while the
* operation is in progress. The calling thread will have the
- * interrupt state set, and the channel will be closed.
+ * interrupt state set and the channel will be closed.
* @throws SecurityException
- * If there is a security manager, and the address is not
- * permitted to access.
+ * if there is a security manager, and the address is not
+ * permitted to be accessed.
* @throws IOException
- * Some other IO error occurred.
+ * some other I/O error occurs.
*/
public abstract SocketAddress receive(ByteBuffer target) throws IOException;
/**
- * Sends out a datagram by the channel.
+ * Sends a datagram through this channel. The datagram consists of the
+ * remaining bytes in {@code source}.
* <p>
- * The precondition of sending is that whether the channel is in blocking
- * mode and enough byte buffer space will be available, or the channel is in
- * non-blocking mode and byte buffer space is enough. The transfer action is
- * just like a regular write operation.
- * </p>
- * <p>
- * This method can be called at any moment, and will block if there is
- * another thread started a read operation on the channel.
- * </p>
- * <p>
- * This method just execute the same security checks as the send method of
- * the <code>DatagramSocket</code> class.
- * </p>
- *
+ * If this channel is in blocking mode then the datagram is sent as soon as
+ * there is enough space in the underlying output buffer. If this channel is
+ * in non-blocking mode then the datagram is only sent if there is enough
+ * space in the underlying output buffer at that moment. The transfer action
+ * is just like a regular write operation.
+ * <p>
+ * This method can be called at any time and it will block if another thread
+ * has started a send operation on this channel.
+ * <p>
+ * This method executes the same security checks as the send method of the
+ * {@link DatagramSocket} class.
+ *
* @param source
- * The byte buffer with the datagram to be sent.
+ * the byte buffer with the datagram to be sent.
* @param address
- * The address to be sent.
- * @return The number of sent bytes. If this method is called, it returns
- * the number of bytes that remaining in the byte buffer. If the
- * channel is in non-blocking mode and no enough space for the
- * datagram in the buffer, it may returns zero.
+ * the destination address for the datagram.
+ * @return the number of bytes sent. This is the number of bytes remaining
+ * in {@code source} or zero if the channel is in non-blocking mode
+ * and there is not enough space for the datagram in the underlying
+ * output buffer.
* @throws ClosedChannelException
- * If the channel is already closed.
+ * if the channel is already closed.
* @throws AsynchronousCloseException
- * If the channel is closed by another thread while this method
+ * if the channel is closed by another thread while this method
* is in operation.
* @throws ClosedByInterruptException
- * If another thread interrupts the calling thread while the
+ * if another thread interrupts the calling thread while the
* operation is in progress. The calling thread will have the
- * interrupt state set, and the channel will be closed.
+ * interrupt state set and the channel will be closed.
* @throws SecurityException
- * If there is a security manager, and the address is not
+ * if there is a security manager, and the address is not
* permitted to access.
* @throws IOException
- * Some other IO error occurred.
+ * some other I/O error occurs.
*/
public abstract int send(ByteBuffer source, SocketAddress address)
throws IOException;
/**
- * Reads datagram from the channel into the byte buffer.
+ * Reads a datagram from this channel into the byte buffer.
* <p>
- * The precondition of calling this method is that the channel is connected
- * and the coming datagram is from the connected address. If the buffer is
- * not enough to store the datagram, the residual part of the datagram is
- * ignored. Otherwise, this method has the same behavior as the read method
- * in the <code>ReadableByteChannel</code> interface.
- * </p>
- *
+ * The precondition for calling this method is that the channel is connected
+ * and the incoming datagram is from the connected address. If the buffer is
+ * not big enough to store the datagram, the part of the datagram that does
+ * not fit in the buffer is discarded. Otherwise, this method has the same
+ * behavior as the {@code read} method in the {@link ReadableByteChannel}
+ * interface.
+ *
* @see java.nio.channels.ReadableByteChannel#read(java.nio.ByteBuffer)
* @param target
- * The byte buffer to store the received datagram.
- * @return Non-negative number as the number of bytes read, or -1 as the
+ * the byte buffer to store the received datagram.
+ * @return a non-negative number as the number of bytes read, or -1 as the
* read operation reaches the end of stream.
* @throws NotYetConnectedException
- * If the channel is not connected yet.
+ * if the channel is not connected yet.
* @throws ClosedChannelException
- * If the channel is already closed.
+ * if the channel is already closed.
* @throws AsynchronousCloseException
- * If the channel is closed by another thread while this method
+ * if the channel is closed by another thread while this method
* is in operation.
* @throws ClosedByInterruptException
- * If another thread interrupts the calling thread while the
+ * if another thread interrupts the calling thread while the
* operation is in progress. The calling thread will have the
- * interrupt state set, and the channel will be closed.
+ * interrupt state set and the channel will be closed.
* @throws IOException
- * Some other IO error occurred.
+ * some other I/O error occurs.
*/
public abstract int read(ByteBuffer target) throws IOException;
/**
- * Reads datagram from the channel into the byte buffer.
+ * Reads a datagram from this channel into an array of byte buffers.
* <p>
- * The precondition of calling this method is that the channel is connected
- * and the coming datagram is from the connected address. If the buffer is
- * not enough to store the datagram, the residual part of the datagram is
- * ignored. Otherwise, this method has the same behavior as the read method
- * in the <code>ScatteringByteChannel</code> interface.
- * </p>
- *
+ * The precondition for calling this method is that the channel is connected
+ * and the incoming datagram is from the connected address. If the buffers
+ * do not have enough remaining space to store the datagram, the part of the
+ * datagram that does not fit in the buffers is discarded. Otherwise, this
+ * method has the same behavior as the {@code read} method in the
+ * {@link ScatteringByteChannel} interface.
+ *
* @see java.nio.channels.ScatteringByteChannel#read(java.nio.ByteBuffer[],
* int, int)
* @param targets
- * The byte buffers to store the received datagram.
+ * the byte buffers to store the received datagram.
* @param offset
- * A non-negative offset in the array of buffer, pointing to the
- * starting buffer to store the byte transferred, must no larger
- * than targets.length.
+ * a non-negative offset in the array of buffers, pointing to the
+ * starting buffer to store the bytes transferred, must not be
+ * bigger than {@code targets.length}.
* @param length
- * A non-negative length to indicate the maximum number of byte
- * to be read, must no larger than targets.length - offset.
- * @return Non-negative number as the number of bytes read, or -1 as the
+ * a non-negative length to indicate the maximum number of
+ * buffers to be filled, must not be bigger than
+ * {@code targets.length - offset}.
+ * @return a non-negative number as the number of bytes read, or -1 if the
* read operation reaches the end of stream.
* @throws NotYetConnectedException
- * If the channel is not connected yet.
+ * if the channel is not connected yet.
* @throws ClosedChannelException
- * If the channel is already closed.
+ * if the channel is already closed.
* @throws AsynchronousCloseException
- * If the channel is closed by another thread while this method
+ * if the channel is closed by another thread while this method
* is in operation.
* @throws ClosedByInterruptException
- * If another thread interrupts the calling thread while the
+ * if another thread interrupts the calling thread while the
* operation is in progress. The calling thread will have the
- * interrupt state set, and the channel will be closed.
+ * interrupt state set and the channel will be closed.
* @throws IOException
- * Some other IO error occurred.
+ * some other I/O error occurs.
*/
public abstract long read(ByteBuffer[] targets, int offset, int length)
throws IOException;
/**
- * Reads datagram from the channel into the byte buffer.
+ * Reads a datagram from this channel into an array of byte buffers.
* <p>
- * The precondition of calling this method is that the channel is connected
- * and the coming datagram is from the connected address. If the buffer is
- * not enough to store the datagram, the residual part of the datagram is
- * ignored. Otherwise, this method has the same behavior as the read method
- * in the <code>ScatteringByteChannel</code> interface.
- * </p>
- *
+ * The precondition for calling this method is that the channel is connected
+ * and the incoming datagram is from the connected address. If the buffers
+ * do not have enough remaining space to store the datagram, the part of the
+ * datagram that does not fit in the buffers is discarded. Otherwise, this
+ * method has the same behavior as the {@code read} method in the
+ * {@link ScatteringByteChannel} interface.
+ *
* @see java.nio.channels.ScatteringByteChannel#read(java.nio.ByteBuffer[])
* @param targets
- * The byte buffers to store the received datagram.
- * @return Non-negative number as the number of bytes read, or -1 as the
+ * the byte buffers to store the received datagram.
+ * @return a non-negative number as the number of bytes read, or -1 if the
* read operation reaches the end of stream.
* @throws NotYetConnectedException
- * If the channel is not connected yet.
+ * if the channel is not connected yet.
* @throws ClosedChannelException
- * If the channel is already closed.
+ * if the channel is already closed.
* @throws AsynchronousCloseException
- * If the channel is closed by another thread while this method
+ * if the channel is closed by another thread while this method
* is in operation.
* @throws ClosedByInterruptException
- * If another thread interrupts the calling thread while the
+ * if another thread interrupts the calling thread while the
* operation is in progress. The calling thread will have the
- * interrupt state set, and the channel will be closed.
+ * interrupt state set and the channel will be closed.
* @throws IOException
- * Some other IO error occurred.
+ * some other I/O error occurs.
*/
public synchronized final long read(ByteBuffer[] targets)
throws IOException {
@@ -345,102 +338,102 @@
}
/**
- * Write datagram from the byte buffer into the channel.
+ * Writes a datagram from the byte buffer to this channel.
* <p>
* The precondition of calling this method is that the channel is connected
* and the datagram is sent to the connected address. Otherwise, this method
- * has the same behavior as the write method in the
- * <code>WritableByteChannel</code> interface.
- * </p>
- *
+ * has the same behavior as the {@code write} method in the
+ * {@link WritableByteChannel} interface.
+ *
* @see java.nio.channels.WritableByteChannel#write(java.nio.ByteBuffer)
* @param source
- * The byte buffer as the source of the datagram.
- * @return Non-negative number of bytes written.
+ * the byte buffer as the source of the datagram.
+ * @return a non-negative number of bytes written.
* @throws NotYetConnectedException
- * If the channel is not connected yet.
+ * if the channel is not connected yet.
* @throws ClosedChannelException
- * If the channel is already closed.
+ * if the channel is already closed.
* @throws AsynchronousCloseException
- * If the channel is closed by another thread while this method
+ * if the channel is closed by another thread while this method
* is in operation.
* @throws ClosedByInterruptException
- * If another thread interrupts the calling thread while the
+ * if another thread interrupts the calling thread while the
* operation is in progress. The calling thread will have the
- * interrupt state set, and the channel will be closed.
+ * interrupt state set and the channel will be closed.
* @throws IOException
- * Some other IO error occurred.
+ * some other I/O error occurs.
*/
public abstract int write(ByteBuffer source) throws IOException;
/**
- * Write datagram from the byte buffer into the channel.
+ * Writes a datagram from the byte buffers to this channel.
* <p>
* The precondition of calling this method is that the channel is connected
* and the datagram is sent to the connected address. Otherwise, this method
- * has the same behavior as the write method in the
- * <code>GatheringByteChannel</code> interface.
+ * has the same behavior as the {@code write} method in the
+ * {@link GatheringByteChannel} interface.
*
* @see java.nio.channels.GatheringByteChannel#write(java.nio.ByteBuffer[],
* int, int)
* @param sources
- * The byte buffers as the source of the datagram.
+ * the byte buffers as the source of the datagram.
* @param offset
- * A non-negative offset in the array of buffer, pointing to the
- * starting buffer to be retrieved, must no larger than
- * sources.length.
+ * a non-negative offset in the array of buffers, pointing to the
+ * starting buffer to be retrieved, must be no larger than
+ * {@code sources.length}.
* @param length
- * A non-negative length to indicate the maximum number of byte
- * to be written, must no larger than sources.length - offset.
- * @return The number of written bytes. If this method is called, it returns
- * the number of bytes that remaining in the byte buffer. If the
- * channel is in non-blocking mode and no enough space for the
- * datagram in the buffer, it may returns zero.
+ * a non-negative length to indicate the maximum number of
+ * buffers to be submitted, must be no bigger than
+ * {@code sources.length - offset}.
+ * @return the number of bytes written. If this method is called, it returns
+ * the number of bytes that where remaining in the byte buffers. If
+ * the channel is in non-blocking mode and there was not enough
+ * space for the datagram in the buffer, it may return zero.
* @throws NotYetConnectedException
- * If the channel is not connected yet.
+ * if the channel is not connected yet.
* @throws ClosedChannelException
- * If the channel is already closed.
+ * if the channel is already closed.
* @throws AsynchronousCloseException
- * If the channel is closed by another thread while this method
+ * if the channel is closed by another thread while this method
* is in operation.
* @throws ClosedByInterruptException
- * If another thread interrupts the calling thread while the
+ * if another thread interrupts the calling thread while the
* operation is in progress. The calling thread will have the
- * interrupt state set, and the channel will be closed.
+ * interrupt state set and the channel will be closed.
* @throws IOException
- * Some other IO error occurred.
+ * some other I/O error occurs.
*/
public abstract long write(ByteBuffer[] sources, int offset, int length)
throws IOException;
/**
- * Write datagram from the byte buffer into the channel.
+ * Writes a datagram from the byte buffers to this channel.
* <p>
* The precondition of calling this method is that the channel is connected
* and the datagram is sent to the connected address. Otherwise, this method
* has the same behavior as the write method in the
- * <code>GatheringByteChannel</code> interface.
+ * {@link GatheringByteChannel} interface.
*
* @see java.nio.channels.GatheringByteChannel#write(java.nio.ByteBuffer[])
* @param sources
- * The byte buffers as the source of the datagram.
- * @return The number of written bytes. If this method is called, it returns
- * the number of bytes that remaining in the byte buffer. If the
- * channel is in non-blocking mode and no enough space for the
- * datagram in the buffer, it may returns zero.
+ * the byte buffers as the source of the datagram.
+ * @return the number of bytes written. If this method is called, it returns
+ * the number of bytes that where remaining in the byte buffer. If
+ * the channel is in non-blocking mode and there was not enough
+ * space for the datagram in the buffer, it may return zero.
* @throws NotYetConnectedException
- * If the channel is not connected yet.
+ * if the channel is not connected yet.
* @throws ClosedChannelException
- * If the channel is already closed.
+ * if the channel is already closed.
* @throws AsynchronousCloseException
- * If the channel is closed by another thread while this method
+ * if the channel is closed by another thread while this method
* is in operation.
* @throws ClosedByInterruptException
- * If another thread interrupts the calling thread while the
+ * if another thread interrupts the calling thread while the
* operation is in progress. The calling thread will have the
- * interrupt state set, and the channel will be closed.
+ * interrupt state set and the channel will be closed.
* @throws IOException
- * Some other IO error occurred.
+ * some other I/O error occurs.
*/
public synchronized final long write(ByteBuffer[] sources)
throws IOException {