harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r768919 [4/7] - in /harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio: ./ channels/ channels/spi/
Date Mon, 27 Apr 2009 10:23:38 GMT
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 {



Mime
View raw message