harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r768919 [6/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/channels/ScatteringByteChannel.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ScatteringByteChannel.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ScatteringByteChannel.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ScatteringByteChannel.java Mon Apr 27 10:23:36 2009
@@ -20,81 +20,70 @@
 import java.nio.ByteBuffer;
 
 /**
- * The interface to channels that can read a set of buffers in a single
- * operation.
- * <p>
- * The corresponding interface for writes is called
- * <code>GatheringByteChannel</code>.
+ * The interface for channels that can read data into a set of buffers in a
+ * single operation. The corresponding interface for writes is
+ * {@link GatheringByteChannel}.
  */
 public interface ScatteringByteChannel extends ReadableByteChannel {
 
     /**
-     * Reads bytes from the channel into all the given buffers.
+     * Reads bytes from this channel into the specified array of buffers.
      * <p>
-     * This method is equivalent to:
-     * 
-     * <pre>
-     * read(buffers, 0, buffers.length);
-     * </pre>
-     * 
-     * </p>
-     * 
+     * This method is equivalent to {@code read(buffers, 0, buffers.length);}
+     *
      * @param buffers
-     *            the array of byte buffers to receive the bytes being read.
+     *            the array of byte buffers to store the bytes being read.
      * @return the number of bytes actually read.
+     * @throws AsynchronousCloseException
+     *             if the channel is closed by another thread during this read
+     *             operation.
+     * @throws ClosedByInterruptException
+     *             if another thread interrupts the calling thread while the
+     *             operation is in progress. The interrupt state of the calling
+     *             thread is set and the channel is closed.
      * @throws ClosedChannelException
      *             if the channel is closed.
-     * @throws NonReadableChannelException
-     *             if the channel is open, but not in a mode that permits
-     *             reading.
-     * @throws ClosedByInterruptException
-     *             if the thread is interrupted in its IO operation by another
-     *             thread closing the channel.
-     * @throws AsynchronousCloseException
-     *             if the read is interrupted by another thread sending an
-     *             explicit interrupt.
      * @throws IOException
-     *             if some other type of exception occurs. Details are in the
-     *             message.
+     *             if another I/O error occurs; details are in the message.
+     * @throws NonWritableChannelException
+     *             if the channel has not been opened in a mode that permits
+     *             reading.
      */
     public long read(ByteBuffer[] buffers) throws IOException;
 
     /**
-     * Reads bytes from the channel into a subset of the given buffers.
-     * <p>
-     * This method attempts to read all of the <code>remaining()</code> bytes
-     * from <code>length</code> byte buffers, in order, starting at
-     * <code>buffers[offset]</code>. The number of bytes actually read is
-     * returned.
-     * </p>
+     * Attempts to read all {@code remaining()} bytes from {@code length} byte
+     * buffers, in order, starting at {@code buffers[offset]}. The number of
+     * bytes actually read is returned.
      * <p>
      * If a read operation is in progress, subsequent threads will block until
-     * the read is completed, and will then contend for the ability to read.
-     * </p>
+     * the read is completed and will then contend for the ability to read.
      * 
      * @param buffers
-     *            the array of byte buffers into which the bytes will be read.
+     *            the array of byte buffers into which the bytes will be copied.
      * @param offset
-     *            the index of the first buffer to read.
+     *            the index of the first buffer to store bytes in.
      * @param length
-     *            the maximum number of buffers to read.
+     *            the maximum number of buffers to store bytes in.
      * @return the number of bytes actually read.
-     * @throws IndexOutOfBoundsException
-     *             if offset < 0 or > buffers.length; or length < 0 or >
-     *             buffers.length - offset.
-     * @throws NonReadableChannelException
-     *             if the channel was not opened for reading.
-     * @throws ClosedChannelException
-     *             the channel is currently closed.
      * @throws AsynchronousCloseException
-     *             the channel was closed by another thread while the write was
-     *             underway.
+     *             if the channel is closed by another thread during this read
+     *             operation.
      * @throws ClosedByInterruptException
-     *             the thread was interrupted by another thread while the write
-     *             was underway.
+     *             if another thread interrupts the calling thread while the
+     *             operation is in progress. The interrupt state of the calling
+     *             thread is set and the channel is closed.
+     * @throws ClosedChannelException
+     *             if the channel is closed.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code length < 0}, or if
+     *             {@code offset + length} is greater than the size of
+     *             {@code buffers}.
      * @throws IOException
-     *             if some other type of exception occurs. Details are in the
-     *             message.
+     *             if another I/O error occurs; details are in the message.
+     * @throws NonWritableChannelException
+     *             if the channel has not been opened in a mode that permits
+     *             reading.
      */
     public long read(ByteBuffer[] buffers, int offset, int length)
             throws IOException;

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/SelectableChannel.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/SelectableChannel.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/SelectableChannel.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/SelectableChannel.java Mon Apr 27 10:23:36 2009
@@ -21,94 +21,123 @@
 import java.nio.channels.spi.SelectorProvider;
 
 /**
- * A channel that can be detected by a selector. The channel can be registered
- * with some selectors, and when invoke select method of the selectors, the
- * channel can be checked if it is readable, writable, connectable or acceptable
- * according to its interesting operation.
+ * A channel that can be used with a {@link Selector}. The channel must be
+ * registered with a selector by calling one of the {@code register} methods,
+ * which return a {@link SelectionKey} object. In order to deregister a channel
+ * from a selector, its selection key must be canceled. This can be done
+ * explicitly by calling the {@link SelectionKey#cancel()} method but it is also
+ * done implicitly when the channel or the selector is closed.
+ * <p>
+ * A channel may be registered with several selectors at the same time but only
+ * once for any given selector.
  */
 public abstract class SelectableChannel extends AbstractInterruptibleChannel
         implements Channel {
 
     /**
-     * Default constructor, can be overridden.
+     * Constructs a new {@code SelectableChannel}.
      */
     protected SelectableChannel() {
         super();
     }
 
     /**
-     * Gets the blocking lock which synchronizes the configureBlocking and
-     * register methods.
+     * Gets the blocking lock which synchronizes the {@code configureBlocking}
+     * and {@code register} methods.
      * 
-     * @return the blocking object as lock
+     * @return the blocking object as lock.
      */
     public abstract Object blockingLock();
 
     /**
-     * Sets blocking mode of the channel.
+     * Sets the blocking mode of this channel. A call to this method blocks if
+     * other calls to this method or to a {@code register} method are executing.
+     * The new blocking mode is valid for calls to other methods that are
+     * invoked after the call to this method. If other methods are already
+     * executing when this method is called, they still have the old mode and
+     * the call to this method might block depending on the implementation.
      * 
      * @param block
-     *            true as blocking, false as non-blocking
-     * @return this channel
+     *            {@code true} for setting this channel's mode to blocking,
+     *            {@code false} to set it to non-blocking.
+     * @return this channel.
      * @throws ClosedChannelException
-     *             If this channel has been closed
+     *             if this channel is closed.
      * @throws IllegalBlockingModeException
-     *             If the channel has been registered
+     *             if {@code block} is {@code true} and this channel has been
+     *             registered with at least one selector.
      * @throws IOException
-     *             if I/O error occurs
+     *             if an I/O error occurs.
      */
     public abstract SelectableChannel configureBlocking(boolean block)
             throws IOException;
 
     /**
-     * Returns if channel is in blocking mode.
+     * Indicates whether this channel is in blocking mode.
      * 
-     * @return true if channel is blocking
+     * @return {@code true} if this channel is blocking, undefined if this
+     *         channel is closed.
      */
     public abstract boolean isBlocking();
 
     /**
-     * Returns if channel is registered.
+     * Indicates whether this channel is registered with at least one selector.
      * 
-     * @return true if channel is registered
+     * @return {@code true} if this channel is registered, {@code false}
+     *         otherwise.
      */
     public abstract boolean isRegistered();
 
     /**
-     * Gets the selection key for the channel with the given selector.
+     * Gets this channel's selection key for the specified selector.
      * 
      * @param sel
-     *            the selector with which this channel may register
-     * @return the selection key for the channel according to the given selector
+     *            the selector with which this channel has been registered.
+     * @return the selection key for the channel or {@code null} if this channel
+     *         has not been registered with {@code sel}.
      */
     public abstract SelectionKey keyFor(Selector sel);
 
     /**
-     * Gets the provider of the channel.
+     * Gets the provider of this channel.
      * 
-     * @return the provider of the channel
+     * @return the provider of this channel.
      */
     public abstract SelectorProvider provider();
 
     /**
-     * Registers with the given selector with a certain interesting operation.
-     * 
+     * Registers this channel with the specified selector for the specified
+     * interest set. If the channel is already registered with the selector, the
+     * corresponding selection key is returned but the
+     * {@link SelectionKey interest set} is updated to {@code operations}. The
+     * returned key is canceled if the channel is closed while registering is in
+     * progress.
+     * <p>
+     * Calling this method is valid at any time. If another thread executes this
+     * method or the {@code configureBlocking(boolean} method then this call is
+     * blocked until the other call finishes. After that, it will synchronize on
+     * the key set of the selector and thus may again block if other threads
+     * also hold locks on the key set of the same selector.
+     * <p>
+     * Calling this method is equivalent to calling
+     * {@code register(selector, operations, null)}.
+     *
      * @param selector
-     *            the selector with which this channel shall be registered
+     *            the selector with which to register this channel.
      * @param operations
-     *            the interesting operation
-     * @return the selection key indicates the channel
+     *            this channel's {@link SelectionKey interest set}.
+     * @return the selection key for this registration.
      * @throws ClosedChannelException
-     *             if the channel is closed
+     *             if the channel is closed.
      * @throws IllegalBlockingModeException
-     *             If the channel is in blocking mode
+     *             if the channel is in blocking mode.
      * @throws IllegalSelectorException
-     *             If this channel does not have the same provider as the given
-     *             selector
+     *             if this channel does not have the same provider as the given
+     *             selector.
      * @throws CancelledKeyException
-     *             If this channel is registered but its key has been cancelled
+     *             if this channel is registered but its key has been canceled.
      * @throws IllegalArgumentException
-     *             If the operation given is unsupported by this channel
+     *             if the operation given is not supported by this channel.
      */
     public final SelectionKey register(Selector selector, int operations)
             throws ClosedChannelException {
@@ -116,35 +145,46 @@
     }
 
     /**
-     * Registers with the given selector with a certain interesting operation
-     * and an attached object.
-     * 
+     * Registers this channel with the specified selector for the specified
+     * interest set and an object to attach. If the channel is already
+     * registered with the selector, the corresponding selection key is returned
+     * but its {@link SelectionKey interest set} is updated to {@code ops} and
+     * the attached object is updated to {@code att}. The returned key is
+     * canceled if the channel is closed while registering is in progress.
+     * <p>
+     * Calling this method is valid at any time. If another thread executes this
+     * method or the {@code configureBlocking(boolean)} method then this call is
+     * blocked until the other call finishes. After that, it will synchronize on
+     * the key set of the selector and thus may again block if other threads
+     * also hold locks on the key set of the same selector.
+     *
      * @param sel
-     *            the selector with which this channel shall be registered
+     *            the selector with which to register this channel.
      * @param ops
-     *            the interesting operation
+     *            this channel's {@link SelectionKey interest set}.
      * @param att
-     *            The attached object, which can be null
-     * @return the selection key indicates the channel
+     *            the object to attach, can be {@code null}.
+     * @return the selection key for this registration.
      * @throws ClosedChannelException
-     *             if the channel is closed
+     *             if this channel is closed.
+     * @throws IllegalArgumentException
+     *             if {@code ops} is not supported by this channel.
      * @throws IllegalBlockingModeException
-     *             If the channel is in blocking mode
+     *             if this channel is in blocking mode.
      * @throws IllegalSelectorException
-     *             If this channel does not have the same provider with the
-     *             given selector
+     *             if this channel does not have the same provider as the given
+     *             selector.
      * @throws CancelledKeyException
-     *             If this channel is registered but its key has been cancelled
-     * @throws IllegalArgumentException
-     *             If the operation given is unsupported by this channel
+     *             if this channel is registered but its key has been canceled.
      */
     public abstract SelectionKey register(Selector sel, int ops, Object att)
             throws ClosedChannelException;
 
     /**
-     * Gets the possible interesting operation of the channel.
-     * 
-     * @return the possible interesting operation of the channel
+     * Gets the set of valid {@link SelectionKey operations} of this channel.
+     * Instances of a concrete channel class always return the same value.
+     *
+     * @return the set of operations that this channel supports.
      */
     public abstract int validOps();
 }

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/SelectionKey.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/SelectionKey.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/SelectionKey.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/SelectionKey.java Mon Apr 27 10:23:36 2009
@@ -19,18 +19,29 @@
 import java.nio.channels.Selector;
 
 /**
- * A key that representing the relationship of a channel and the selector.
- * 
+ * A {@code SelectionKey} represents the relationship between a channel and a
+ * selector for which the channel is registered.
+ * <h3>Operation set</h3>
+ * An operation set is represented by an integer value. The bits of an operation
+ * set represent categories of operations for a key's channel: Accepting socket
+ * connections ({@code OP_ACCEPT}), connecting with a socket ({@code OP_CONNECT}),
+ * reading ({@code OP_READ}) and writing ({@code OP_WRITE}).
+ * <h4>Interest set</h4>
+ * The interest set is an operation set that defines the operations that a
+ * {@link SelectableChannel channel} is interested in performing.
+ * <h4>Ready set</h4>
+ * The ready set is an operation set that shows the operations that a
+ * {@code channel} is ready to execute.
  */
 public abstract class SelectionKey {
 
     /**
-     * Interesting operation mask bit for socket-accept operations.
+     * Interest set mask bit for socket-accept operations.
      */
     public static final int OP_ACCEPT = 16;
 
     /**
-     * Interesting operation mask bit for socket-connect operations.
+     * Interest set mask bit for socket-connect operations.
      */
     public static final int OP_CONNECT = 8;
 
@@ -40,26 +51,28 @@
     public static final int OP_READ = 1;
 
     /**
-     * Interesting operation mask bit for write operations.
+     * Interest set mask bit for write operations.
      */
     public static final int OP_WRITE = 4;
 
     private volatile Object attachment = null;
 
     /**
-     * The constructor.
-     * 
+     * Constructs a new {@code SelectionKey}.
      */
     protected SelectionKey() {
         super();
     }
 
     /**
-     * Attaches an object to the key.
+     * Attaches an object to this key. It is acceptable to attach {@code null},
+     * this discards the old attachment.
      * 
      * @param anObject
-     *            the object to attach
-     * @return the last attached object
+     *            the object to attach, or {@code null} to discard the current
+     *            attachment.
+     * @return the last attached object or {@code null} if no object has been
+     *         attached.
      */
     public final Object attach(Object anObject) {
         Object oldAttachment = attachment;
@@ -70,7 +83,8 @@
     /**
      * Gets the attached object.
      * 
-     * @return the attached object or null if no object has been attached
+     * @return the attached object or {@code null} if no object has been
+     *         attached.
      */
     public final Object attachment() {
         return attachment;
@@ -78,112 +92,130 @@
 
     /**
      * Cancels this key.
-     * 
+     * <p>
+     * A key that has been canceled is no longer valid. Calling this method on
+     * an already canceled key does nothing.
+     * <p>
+     * Calling this method is safe at any time. The call might block until
+     * another ongoing call to a method of this selector has finished. The
+     * reason is that it is synchronizing on the key set of the selector. After
+     * this call finishes, the key will have been added to the selectors
+     * canceled-keys set and will not be included in any future selects of this
+     * selector.
      */
     public abstract void cancel();
 
     /**
      * Gets the channel of this key.
      * 
-     * @return the channel of this key
+     * @return the channel of this key.
      */
     public abstract SelectableChannel channel();
 
     /**
-     * Gets the interesting operation of this key.
+     * Gets this key's {@link SelectionKey interest set}. The returned set has
+     * only those bits set that are valid for this key's channel.
      * 
-     * @return the interesting operation of this key
+     * @return the interest set of this key.
      * @throws CancelledKeyException
-     *             If the key has been cancelled already
+     *             if the key has already been canceled.
      */
     public abstract int interestOps();
 
     /**
-     * Sets the interesting operation for this key.
+     * Sets the {@link SelectionKey interest set} for this key.
      * 
      * @param operations
-     *            the interesting operation to set
-     * @return this key
+     *            the new interest set.
+     * @return this key.
      * @throws IllegalArgumentException
-     *             if the given operation is not in the key's interesting
-     *             operation set
+     *             if a bit in {@code operations} is not in the set of
+     *             {@link SelectableChannel#validOps() valid operations} of this
+     *             key's channel.
      * @throws CancelledKeyException
-     *             If the key has been cancelled already
+     *             if the key has already been canceled.
      */
     public abstract SelectionKey interestOps(int operations);
 
     /**
-     * Tells whether the channel of this key is interested in accept operation
-     * and ready for acceptation.
+     * Indicates whether this key's channel is interested in the accept
+     * operation and is ready to accept new connections. A call to this method
+     * is equal to executing {@code (readyOps() & OP_ACCEPT) == OP_ACCEPT}.
      * 
-     * @return true if the channel is interested in accept operation and ready
-     *         for acceptation
+     * @return {@code true} if the channel is interested in the accept operation
+     *         and is ready to accept new connections, {@code false} otherwise.
      * @throws CancelledKeyException
-     *             If the key has been cancelled already
+     *             if the key has already been canceled.
      */
     public final boolean isAcceptable() {
         return (readyOps() & OP_ACCEPT) == OP_ACCEPT;
     }
 
     /**
-     * Tells whether the channel of this key is interested in connect operation
-     * and ready for connection.
+     * Indicates whether this key's channel is interested in the connect
+     * operation and is ready to connect. A call to this method is equal to
+     * executing {@code (readyOps() & OP_CONNECT) == OP_CONNECT}.
      * 
-     * @return true if the channel is interested in connect operation and ready
-     *         for connection
+     * @return {@code true} if the channel is interested in the connect
+     *         operation and is ready to connect, {@code false} otherwise.
      * @throws CancelledKeyException
-     *             If the key has been cancelled already
+     *             if the key has already been canceled.
      */
     public final boolean isConnectable() {
         return (readyOps() & OP_CONNECT) == OP_CONNECT;
     }
 
     /**
-     * Tells whether the channel of this key is interested in read operation and
-     * ready for reading.
+     * Indicates whether this key's channel is interested in the read operation
+     * and is ready to read. A call to this method is equal to executing
+     * {@code (readyOps() & OP_READ) == OP_READ}.
      * 
-     * @return true if the channel is interested in read operation and ready for
-     *         reading
+     * @return {@code true} if the channel is interested in the read operation
+     *         and is ready to read, {@code false} otherwise.
      * @throws CancelledKeyException
-     *             If the key has been cancelled already
+     *             if the key has already been canceled.
      */
     public final boolean isReadable() {
         return (readyOps() & OP_READ) == OP_READ;
     }
 
     /**
-     * Tells whether the key is valid.
+     * Indicates whether this key is valid. A key is valid as long as it has not
+     * been canceled.
      * 
-     * @return true if the key has not been cancelled
+     * @return {@code true} if this key has not been canceled, {@code false}
+     *         otherwise.
      */
     public abstract boolean isValid();
 
     /**
-     * Tells whether the channel of this key is interested in write operation
-     * and ready for writing.
+     * Indicates whether this key's channel is interested in the write operation
+     * and is ready to write. A call to this method is equal to executing
+     * {@code (readyOps() & OP_WRITE) == OP_WRITE}.
      * 
-     * @return true if the channel is interested in write operation and ready
-     *         for writing
+     * @return {@code true} if the channel is interested in the wrie operation
+     *         and is ready to write, {@code false} otherwise.
      * @throws CancelledKeyException
-     *             If the key has been cancelled already
+     *             if the key has already been canceled.
      */
     public final boolean isWritable() {
         return (readyOps() & OP_WRITE) == OP_WRITE;
     }
 
     /**
-     * Gets the ready operation.
+     * Gets the set of operations that are ready. The returned set has only
+     * those bits set that are valid for this key's channel.
      * 
-     * @return the ready operation
+     * @return the operations for which this key's channel is ready.
      * @throws CancelledKeyException
-     *             If the key has been cancelled already
+     *             if the key has already been canceled.
      */
     public abstract int readyOps();
 
     /**
-     * Gets the related selector.
+     * Gets the selector for which this key's channel is registered.
      * 
-     * @return the related selector
+     * @return the related selector.
      */
     public abstract Selector selector();
 }

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Selector.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Selector.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Selector.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Selector.java Mon Apr 27 10:23:36 2009
@@ -21,128 +21,150 @@
 import java.util.Set;
 
 /**
- * A controller for selection of SelectableChannel objects.
- * 
- * Selectable channels can be registered with a selector, and get SelectionKey
- * as a linkage. The keys are also added to the selector's keyset. The
- * SelectionKey can be cancelled so that the corresponding channel is no longer
- * registered with the selector.
- * 
- * By invoking the select operation, the keyset is checked and all keys that are
- * cancelled since last select operation are moved to cancelledKey set. During
- * the select operation, the channels registered with this selector are checked
- * to see whether they are ready for operation according to their interesting
- * operation.
- * 
+ * A controller for the selection of {@link SelectableChannel} objects.
+ * Selectable channels can be registered with a selector and get a
+ * {@link SelectionKey} that represents the registration. The keys are also
+ * added to the selector's key set. Selection keys can be canceled so that the
+ * corresponding channel is no longer registered with the selector.
+ * <p>
+ * By invoking the {@code select} method, the key set is checked and all keys
+ * that have been canceled since last select operation are moved to the set of
+ * canceled keys. During the select operation, the channels registered with this
+ * selector are checked to see whether they are ready for operation according to
+ * their {@link SelectionKey interest set}.
  */
 public abstract class Selector {
 
     /**
-     * The factory method for selector.
+     * The factory method for selector. It returns the selector returned by the
+     * default {@link SelectorProvider} by calling its {@code openCollector}
+     * method.
      * 
-     * @return a new selector
+     * @return a new selector.
      * @throws IOException
-     *             if I/O error occurs
+     *             if an I/O error occurs.
      */
     public static Selector open() throws IOException {
         return SelectorProvider.provider().openSelector();
     }
 
     /**
-     * The constructor.
+     * Constructs a new {@code Selector}.
      */
     protected Selector() {
         super();
     }
 
     /**
-     * Closes this selector.
-     * 
+     * Closes this selector. Ongoing calls to the {@code select} methods of this
+     * selector will get interrupted. This interruption behaves as if the
+     * {@link #wakeup()} method of this selector is called. After this, all keys
+     * that are still valid are invalidated and their channels are unregistered.
+     * All resources held by this selector are released.
+     * <p>
+     * Any further attempt of using this selector after this method has been
+     * called (except calling {@link #close()} or {@link #wakeup()}) results in
+     * a {@link ClosedSelectorException} being thrown.
+     *
      * @throws IOException
-     *             if I/O error occurs
+     *             if an I/O error occurs.
      */
     public abstract void close() throws IOException;
 
     /**
-     * Tells whether this selector is open.
+     * Indicates whether this selector is open.
      * 
-     * @return true if this selector is not closed
+     * @return {@code true} if this selector is not closed, {@code false}
+     *         otherwise.
      */
     public abstract boolean isOpen();
 
     /**
-     * Gets the set of registered keys.
+     * Gets the set of registered keys. The set is immutable and is not thread-
+     * safe.
      * 
-     * @return the keyset of registered keys
+     * @return the set of registered keys.
      */
     public abstract Set<SelectionKey> keys();
 
     /**
      * Gets the provider of this selector.
      * 
-     * @return the provider of this selector
+     * @return the provider of this selector.
      */
     public abstract SelectorProvider provider();
 
     /**
-     * Detects if any of the registered channels are ready for I/O operations
-     * according to their interesting operation. This operation will not return
-     * until some of the channels are ready or wakeup is invoked.
+     * Detects if any of the registered channels is ready for I/O operations
+     * according to its {@link SelectionKey interest set}. This method does not
+     * return until at least one channel is ready, {@link #wakeup()} is
+     * invoked or the calling thread is interrupted.
      * 
-     * @return the number of channels that are ready for operation
+     * @return the number of channels that are ready for operation.
      * @throws IOException
-     *             if I/O error occurs
+     *             if an I/O error occurs.
      * @throws ClosedSelectorException
-     *             If the selector is closed
+     *             if the selector is closed.
      */
     public abstract int select() throws IOException;
 
     /**
-     * Detects if any of the registered channels are ready for I/O operations
-     * according to their interesting operation.This operation will not return
-     * until some of the channels are ready or wakeup is invoked or timeout
-     * expired.
+     * Detects if any of the registered channels is ready for I/O operations
+     * according to its {@link SelectionKey interest set}. This method does not
+     * return until at least one channel is ready, {@link #wakeup()} is invoked,
+     * the calling thread is interrupted or the specified {@code timeout}
+     * expires.
      * 
      * @param timeout
-     *            the timeout in millisecond
-     * @return the number of channels that are ready for operation
-     * @throws IOException
-     *             if I/O error occurs
+     *            the non-negative timeout in millisecond; 0 will block forever
+     *            if no channels get ready.
+     * @return the number of channels that are ready for operation.
      * @throws ClosedSelectorException
-     *             If the selector is closed
+     *             if the selector is closed.
      * @throws IllegalArgumentException
-     *             If the given timeout argument is less than zero
+     *             if the given timeout argument is less than zero.
+     * @throws IOException
+     *             if an I/O error occurs.
      */
     public abstract int select(long timeout) throws IOException;
 
     /**
-     * Gets the keys whose channels are ready for operation.
+     * Gets the selection keys whose channels are ready for operation. The set
+     * is not thread-safe and no keys may be added to it. Removing keys is
+     * allowed.
      * 
-     * @return the keys whose channels are ready for operation
+     * @return the selection keys whose channels are ready for operation.
+     * @throws ClosedSelectorException
+     *             if the selector is closed.
      */
     public abstract Set<SelectionKey> selectedKeys();
 
     /**
-     * Detects if any of the registered channels are ready for I/O operations
-     * according to their interesting operation.This operation will not return
-     * immediately.
+     * Detects if any of the registered channels is ready for I/O operations
+     * according to its {@link SelectionKey interest set}. This operation will
+     * return immediately.
      * 
-     * @return the number of channels that are ready for operation
+     * @return the number of channels that are ready for operation, 0 if none is
+     *         ready.
      * @throws IOException
-     *             if I/O error occur
+     *             if an I/O error occurrs.
      * @throws ClosedSelectorException
-     *             If the selector is closed
+     *             if the selector is closed.
      */
     public abstract int selectNow() throws IOException;
 
     /**
-     * Forces the blocked select operation to return immediately. If no select
-     * operation is blocked currently, the next select operation shall return
-     * immediately.
-     * 
-     * @return this selector
+     * Forces blocked {@code select} operations to return immediately.
+     * <p>
+     * If no {@code select} operation is blocked when {@code wakeup()} is called
+     * then the next {@code select} operation will return immediately. This can
+     * be undone by a call to {@code selectNow()}; after calling
+     * {@code selectNow()}, a subsequent call of {@code select} can block
+     * again.
+     *
+     * @return this selector.
      * @throws ClosedSelectorException
-     *             If the selector is closed
+     *             if the selector is closed.
      */
     public abstract Selector wakeup();
 }

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ServerSocketChannel.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ServerSocketChannel.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ServerSocketChannel.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ServerSocketChannel.java Mon Apr 27 10:23:36 2009
@@ -23,52 +23,50 @@
 import java.nio.channels.spi.SelectorProvider;
 
 /**
- * A ServerSocketChannel is a partly abstracted stream-oriented listening socket
- * which is selectable. Binding and manipulation of socket options can only be
- * done through the associated <code>ServerSocket</code> object, returned by
- * calling socket method. ServerSocketChannels can not be constructed for a
- * pre-existing server socket, nor can it be assigned a SocketImpl.
+ * A {@code ServerSocketChannel} is a partial abstraction of a selectable,
+ * stream-oriented listening socket. Binding and manipulation of socket options
+ * can only be done through the associated {@link ServerSocket} object, returned
+ * by calling {@code socket()}. ServerSocketChannels can not be constructed for
+ * an already existing server-socket, nor can a {@link java.net.SocketImpl} be assigned.
  * <p>
- * A Server-Socket channel is open but not bound when created by
- * <code>open</code> method. (Calling <code>accept</code> before bound will
- * cause a <code>NotYetBoundException</code>). It can be bound by calling the
- * bind method of a related <code>ServerSocket</code> instance.
- * </p>
+ * A server-socket channel is open but not bound when created by the {@code
+ * open()} method. Calling {@code accept} before bound will cause a
+ * {@link NotYetBoundException}. It can be bound by calling the bind method of a
+ * related {@code ServerSocket} instance.
  */
 public abstract class ServerSocketChannel extends AbstractSelectableChannel {
 
     /**
-     * Construct a new instance for ServerSocketChannel
+     * Constructs a new {@link ServerSocketChannel}.
      * 
      * @param selectorProvider
-     *            An instance of SelectorProvider
+     *            an instance of SelectorProvider.
      */
     protected ServerSocketChannel(SelectorProvider selectorProvider) {
         super(selectorProvider);
     }
 
     /**
-     * Create an open and unbound server-socket channel.
+     * Creates an open and unbound server-socket channel.
      * <p>
-     * This channel is got by calling <code>openServerSocketChannel</code>
-     * method of the default <code>SelectorProvider </code> instance.
-     * </p>
-     * 
-     * @return The new created channel which is open but unbound.
+     * This channel is created by calling {@code openServerSocketChannel} method
+     * of the default {@code SelectorProvider} instance.
+     *
+     * @return the new channel which is open but unbound.
      * @throws IOException
-     *             If some IO problem occurs.
+     *             if an I/O error occurs.
      */
     public static ServerSocketChannel open() throws IOException {
         return SelectorProvider.provider().openServerSocketChannel();
     }
 
     /**
-     * Get the valid operations of this channel. Server-socket channels support
-     * accepting operation.Currently the only supported operation is OP_ACCEPT.
-     * It always returns <code>SelectionKey.OP_ACCEPT</code>.
+     * Gets the valid operations of this channel. Server-socket channels support
+     * accepting operation, so this method returns {@code
+     * SelectionKey.OP_ACCEPT}.
      * 
      * @see java.nio.channels.SelectableChannel#validOps()
-     * @return Valid operations in bit-set.
+     * @return the operations supported by this channel.
      */
     @Override
     public final int validOps() {
@@ -76,47 +74,42 @@
     }
 
     /**
-     * Return the related server-socket of this channel. All public methods
-     * declared in returned object should be declared in
-     * <code>ServerSocket</code>.
+     * Return the server-socket assigned this channel, which does not declare
+     * any public methods that are not declared in {@code ServerSocket}.
      * 
-     * @return The related ServerSocket instance.
+     * @return the server-socket assigned to this channel.
      */
     public abstract ServerSocket socket();
 
     /**
-     * Accepts a connection to this socket.
+     * Accepts a connection to this server-socket channel.
      * <p>
-     * It returns null when the channel is non-blocking and no connections
-     * available, otherwise it blocks indefinitely until a new connection is
-     * available or an I/O error occurs. The returned channel will be in
-     * blocking mode any way.
-     * </p>
-     * 
+     * This method returns {@code null} when this channel is non-blocking and no
+     * connection is available, otherwise it blocks until a new connection is
+     * available or an I/O error occurs. The socket channel returned by this
+     * method will always be in blocking mode.
      * <p>
-     * This method just execute the same security checks as the accept method of
-     * the <code>ServerSocket</code> class.
-     * </p>
+     * This method just executes the same security checks as the {@code
+     * accept()} method of the {@link ServerSocket} class.
      * 
-     * @return The accepted SocketChannel instance, or null as the channel is
-     *         non-blocking and no connections available.
-     * @throws ClosedChannelException
-     *             If the channel is already closed.
+     * @return the accepted {@code SocketChannel} instance, or {@code null} if
+     *         the channel is non-blocking and no connection is available.
      * @throws AsynchronousCloseException
-     *             If the channel is closed by another thread while this method
+     *             if this channel is closed by another thread while this method
      *             is in operation.
      * @throws ClosedByInterruptException
-     *             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.
+     *             if another thread interrupts the calling thread while this
+     *             operation is in progress. The interrupt state of the calling
+     *             thread is set and the channel is closed.
+     * @throws ClosedChannelException
+     *             if this channel is closed.
+     * @throws IOException
+     *             if another I/O error occurs.
      * @throws NotYetBoundException
-     *             If the socket has not yet been bound.
+     *             if the socket has not yet been bound.
      * @throws SecurityException
-     *             If there is a security manager, and the new connection is not
-     *             permitted to access.
-     * @throws IOException
-     *             Some other IO error occurred.
-     * 
+     *             if there is a security manager and it does not permit to
+     *             access the new connection.
      */
     public abstract SocketChannel accept() throws IOException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/SocketChannel.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/SocketChannel.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/SocketChannel.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/SocketChannel.java Mon Apr 27 10:23:36 2009
@@ -27,36 +27,34 @@
 import org.apache.harmony.luni.platform.Platform;
 
 /**
- * A SocketChannel is a selectable channel for part abstraction of stream
- * connecting socket. The <code>socket</code> method of this class can return
- * the related <code>Socket</code> instance, which can handle the socket.
+ * A {@code SocketChannel} is a selectable channel that provides a partial
+ * abstraction of stream connecting socket. {@code socket()} returns the related
+ * {@link Socket} instance which can handle the socket.
  * <p>
- * A socket channel is open but not connected when created by <code>open</code>
- * method. After connected by calling the <code>connect</code> method, it will
- * keep connected before closed. The connection is non-blocking that the
- * <code>connect</code> method is for the initial connection and following
- * <code>finishConnect</code> method is for the final steps of connection. The
- * <code>isConnectionPending</code> method can tell the connection is blocked
- * or not; the <code>isConnected</code> method can tell the socket is
- * connected finally or not.
- * </p>
+ * A socket channel is open but not connected when created by {@code open()}.
+ * After connecting it by calling {@code connect(SocketAddress)}, it will remain
+ * connected until it gets closed. If the connection is non-blocking then
+ * {@code connect(SocketAddress)} is used to initiate the connection, followed
+ * by a call of {@code finishConnect()} to perform the final steps of
+ * connecting. {@code isConnectionPending()} indicates if the connection is
+ * blocked or not; {@code isConnected()} indicates if the socket is finally
+ * connected or not.
  * <p>
- * The shut down operation can be independent and asynchronous for input and
- * output. The <code>shutdownInput</code> method is for input, and can make
- * the following read operation fail as end of stream. If the input is shut down
- * and another thread is pending in read operation, the read will end without
- * effect and return end of stream. The <code>shutdownOutput</code> method is
- * for output, and can make the following write operation throwing a
- * <code>ClosedChannelException</code>. If the output is shut down and
- * another is pending in a write operation, an
- * <code>AsynchronousCloseException</code> will thrown to the pending thread.
- * </p>
+ * The input and output sides of a channel can be shut down independently and
+ * asynchronously without closing the channel. The {@code shutdownInput} method
+ * is used for the input side of a channel and subsequent read operations return
+ * -1, which means end of stream. If another thread is blocked in a read
+ * operation when the shutdown occurs, the read will end without effect and
+ * return end of stream. The {@code shutdownOutput} method is used for the
+ * output side of the channel; subsequent write operations throw a
+ * {@link ClosedChannelException}. If the output is shut down and another thread
+ * is blocked in a write operation, an {@link AsynchronousCloseException} will
+ * be thrown to the pending thread.
  * <p>
  * Socket channels are thread-safe, no more than one thread can read or write at
- * given time. The <code>connect</code> and <code>finishConnect</code>
- * methods are concurrent each other, when they are processing, other read and
- * write will block.
- * </p>
+ * any given time. The {@code connect(SocketAddress)} and {@code
+ * finishConnect()} methods are synchronized against each other; when they are
+ * processing, calls to {@code read} and {@code write} will block.
  */
 public abstract class SocketChannel extends AbstractSelectableChannel implements
         ByteChannel, ScatteringByteChannel, GatheringByteChannel {
@@ -66,57 +64,54 @@
     }
 
     /**
-     * Constructor for this class.
+     * Constructs a new {@code SocketChannel}.
      * 
      * @param selectorProvider
-     *            A instance of SelectorProvider
+     *            an instance of SelectorProvider.
      */
     protected SocketChannel(SelectorProvider selectorProvider) {
         super(selectorProvider);
     }
 
     /**
-     * Create a open and not-connected socket channel.
+     * Creates an open and unconnected socket channel.
      * <p>
-     * This channel is got by <code>openSocketChannel</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 {@code openSocketChannel()} of the
+     * default {@link SelectorProvider} instance.
+     *
+     * @return the new channel which is open but unconnected.
      * @throws IOException
-     *             If some IO problem occurs.
+     *             if an I/O error occurs.
      */
     public static SocketChannel open() throws IOException {
         return SelectorProvider.provider().openSocketChannel();
     }
 
     /**
-     * Create a socket channel and connect it to a socket address.
+     * Creates a socket channel and connects it to a socket address.
      * <p>
-     * This method perform just as <code>open</code> method following by the
-     * <code>connect</code> method.
-     * </p>
-     * 
+     * This method performs a call to {@code open()} followed by a call to
+     * {@code connect(SocketAdress)}.
+     *
      * @param address
-     *            The socket address to be connected.
-     * @return The new opened channel.
+     *            the socket address to be connected to.
+     * @return the new connected channel.
      * @throws AsynchronousCloseException
-     *             If the channel is closed by another thread while this method
-     *             is in operation.
+     *             if this channel is closed by another thread while this method
+     *             is executing.
      * @throws ClosedByInterruptException
-     *             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.
+     *             if another thread interrupts the calling thread while this
+     *             operation is executing. The calling thread will have the
+     *             interrupt state set and the channel will be closed.
+     * @throws SecurityException
+     *             if there is a security manager and it denies the access of
+     *             {@code address}.
      * @throws UnresolvedAddressException
-     *             If the address is not resolved.
+     *             if the address is not resolved.
      * @throws UnsupportedAddressTypeException
-     *             If the address type is not supported.
-     * @throws SecurityException
-     *             If there is a security manager, and the address is not
-     *             permitted to access.
+     *             if the address type is not supported.
      * @throws IOException
-     *             Some other IO error occurred.
-     * 
+     *             if an I/O error occurs.
      */
     public static SocketChannel open(SocketAddress address) throws IOException {
         SocketChannel socketChannel = open();
@@ -127,13 +122,12 @@
     }
 
     /**
-     * Get the valid operations of this channel. Socket channels support
-     * connect, read and write operation, so this method returns (
-     * <code>SelectionKey.OP_CONNECT</code> |
-     * <code>SelectionKey.OP_READ</code> | <code>SelectionKey.OP_WRITE</code> ).
+     * Gets the valid operations of this channel. Socket channels support
+     * connect, read and write operation, so this method returns
+     * {@code SelectionKey.OP_CONNECT | SelectionKey.OP_READ | SelectionKey.OP_WRITE}.
      * 
+     * @return the operations supported by this channel.
      * @see java.nio.channels.SelectableChannel#validOps()
-     * @return Valid operations in bit-set.
      */
     @Override
     public final int validOps() {
@@ -141,223 +135,204 @@
     }
 
     /**
-     * Return the related socket of this channel, which won't declare public
-     * methods that not declared in <code>Socket</code>.
+     * Returns the socket assigned to this channel, which does not declare any public
+     * methods that are not declared in {@code Socket}.
      * 
-     * @return The related Socket instance.
+     * @return the socket assigned to this channel.
      */
     public abstract Socket socket();
 
     /**
-     * Answer whether this channel's socket is connected or not.
+     * Indicates whether this channel's socket is connected.
      * 
-     * @return <code>true</code> for this channel's socket is connected;
-     *         <code>false</code> otherwise.
+     * @return {@code true} if this channel's socket is connected, {@code false}
+     *         otherwise.
      */
     public abstract boolean isConnected();
 
     /**
-     * Answer whether this channel's socket is in connecting or not.
+     * Indicates whether this channel's socket is still trying to connect.
      * 
-     * @return <code>true</code> for the connection is initiated but not
-     *         finished; <code>false</code> otherwise.
+     * @return {@code true} if the connection is initiated but not finished;
+     *         {@code false} otherwise.
      */
     public abstract boolean isConnectionPending();
 
     /**
-     * Connect the socket to remote address.
+     * Connects this channel's socket with a remote address.
      * <p>
-     * If the channel is blocking, this method will suspend before connection
-     * finished or an I/O exception. If the channel is non-blocking, this method
-     * will return <code>true</code> if the connection is finished at once or
-     * return <code>false</code> and the connection must wait
-     * <code>finishConnect</code> to finished otherwise.
-     * </p>
-     * <p>
-     * This method can be called at any moment, and can block other read and
-     * write operations while connecting.
-     * </p>
-     * <p>
-     * This method just execute the same security checks as the connect method
-     * of the <code>Socket</code> class.
-     * </p>
-     * 
+     * If this channel is blocking, this method will suspend until connecting is
+     * finished or an I/O exception occurrs. If the channel is non-blocking,
+     * this method will return {@code true} if the connection is finished at
+     * once or return {@code false} when the connection must be finished later
+     * by calling {@code finishConnect()}.
+     * <p>
+     * This method can be called at any moment and can block other read and
+     * write operations while connecting. It executes the same security checks
+     * as the connect method of the {@code Socket} class.
+     *
      * @param address
-     *            The address to be connected.
-     * @return <code>true</code> if connection is finished,<code>false</code>
+     *            the address to connect with.
+     * @return {@code true} if the connection is finished, {@code false}
      *         otherwise.
      * @throws AlreadyConnectedException
-     *             If the channel is connected already.
+     *             if the channel is already connected.
      * @throws ConnectionPendingException
-     *             A non-blocking connecting is doing on this channel.
+     *             a non-blocking connecting operation is already executing on
+     *             this channel.
      * @throws ClosedChannelException
-     *             If the channel is already closed.
+     *             if this channel is closed.
      * @throws AsynchronousCloseException
-     *             If the channel is closed by another thread while this method
-     *             is in operation.
+     *             if this channel is closed by another thread while this method
+     *             is executing.
      * @throws ClosedByInterruptException
-     *             If another thread interrupts the calling thread while the
+     *             if another thread interrupts the calling thread while this
      *             operation is in progress. The calling thread will have the
-     *             interrupt state set, and the channel will be closed.
+     *             interrupt state set and this channel will be closed.
      * @throws UnresolvedAddressException
-     *             If the address is not resolved.
+     *             if the address is not resolved.
      * @throws UnsupportedAddressTypeException
-     *             If the address type is not supported.
+     *             if the address type is not supported.
      * @throws SecurityException
-     *             If there is a security manager, and the address is not
-     *             permitted to access.
+     *             if there is a security manager and it denies the access of
+     *             {@code address}.
      * @throws IOException
-     *             Some other IO error occurred.
+     *             if an I/O error occurs.
      */
     public abstract boolean connect(SocketAddress address) throws IOException;
 
     /**
-     * Complete the connection.
+     * Completes the connection process initiated by a call of {@code
+     * connect(SocketAddress)}.
      * <p>
-     * This method is used when the channel is connectable to finish the
-     * connection, and the connectable status of a channel means the channel is
-     * after initiating in non-blocking mode and calling its
-     * <code>connect</code> method. It will throw related
-     * <code>IOException</code> if the connection failed.
-     * </p>
-     * <p>
-     * This method will return <code>true</code> if the connection is finished
-     * already, and return <code>false</code> if the channel is non-blocking
-     * and the connection is not finished yet.
-     * </p>
-     * <p>
-     * If the channel is in blocking mode, this method will suspend, and return
-     * <code>true</code> for connection finished or throw some exception
-     * otherwise. The channel will be closed if the connection failed and this
-     * method thrown some exception.
-     * </p>
-     * <p>
-     * This method can be called at any moment, and can block other read and
-     * write operations while connecting.
-     * </p>
-     * 
-     * @return <code>true</code> if the connection is successfully finished,
-     *         <code>false</code> otherwise.
+     * This method returns {@code true} if the connection is finished already
+     * and returns {@code false} if the channel is non-blocking and the
+     * connection is not finished yet.
+     * <p>
+     * If this channel is in blocking mode, this method will suspend and return
+     * {@code true} when the connection is finished. It closes this channel and
+     * throws an exception if the connection fails.
+     * <p>
+     * This method can be called at any moment and it can block other {@code
+     * read} and {@code write} operations while connecting.
+     *
+     * @return {@code true} if the connection is successfully finished, {@code
+     *         false} otherwise.
      * @throws NoConnectionPendingException
-     *             If the channel is not connected and the connection is not
-     *             initiated.
+     *             if the channel is not connected and the connection process
+     *             has not been initiated.
      * @throws ClosedChannelException
-     *             If the channel is already closed.
+     *             if this channel is closed.
      * @throws AsynchronousCloseException
-     *             If the channel is closed by another thread while this method
-     *             is in operation.
+     *             if this channel is closed by another thread while this method
+     *             is executing.
      * @throws ClosedByInterruptException
-     *             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.
+     *             if another thread interrupts the calling thread while this
+     *             operation is in progress. The calling thread has the
+     *             interrupt state set, and this channel is closed.
      * @throws IOException
-     *             Some other IO error occurred.
+     *             if an I/O error occurs.
      */
     public abstract boolean finishConnect() throws IOException;
 
     /**
-     * Reads bytes from the channel into the given buffer.
+     * Reads bytes from this socket channel into the given buffer.
      * <p>
-     * The maximum number of bytes that will be read is the
-     * <code>remaining()</code> number of bytes in the buffer when the method
-     * invoked. The bytes will be read into the buffer starting at the buffer's
-     * <code>position</code>.
-     * </p>
-     * <p>
-     * The call may block if other threads are also attempting to read on the
-     * same channel.
-     * </p>
-     * <p>
-     * Upon completion, the buffer's <code>position()</code> is updated to the
-     * end of the bytes that were read. The buffer's <code>limit()</code> is
-     * unmodified.
-     * </p>
-     * 
-     * @see java.nio.channels.ReadableByteChannel#read(java.nio.ByteBuffer)
+     * The maximum number of bytes that will be read is the remaining number of
+     * bytes in the buffer when the method is invoked. The bytes will be copied
+     * into the buffer starting at the buffer's current position.
+     * <p>
+     * The call may block if other threads are also attempting to read from this
+     * channel.
+     * <p>
+     * Upon completion, the buffer's position is set to the end of the bytes
+     * that have been read. The buffer's limit is not changed.
+     *
      * @param target
-     *            The byte buffer to receive the bytes.
-     * @return The number of bytes actually read.
-     * @throws NotYetConnectedException
-     *             If the channel is not connected yet.
-     * @throws ClosedChannelException
-     *             If the channel is already closed.
+     *            the byte buffer to receive the bytes.
+     * @return the number of bytes actually read.
      * @throws AsynchronousCloseException
-     *             If the channel is closed by another thread while this method
-     *             is in operation.
+     *             if another thread closes the channel during the read.
+     * @throws NotYetConnectedException
+     *             if this channel is not yet connected.
      * @throws ClosedByInterruptException
-     *             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.
+     *             if another thread interrupts the calling thread while this
+     *             operation is in progress. The interrupt state of the calling
+     *             thread is set and the channel is closed.
+     * @throws ClosedChannelException
+     *             if this channel is closed.
      * @throws IOException
-     *             Some other IO error occurred.
+     *             if another I/O error occurs.
+     * @see java.nio.channels.ReadableByteChannel#read(java.nio.ByteBuffer)
      */
     public abstract int read(ByteBuffer target) throws IOException;
 
     /**
-     * Reads bytes from the channel into a subset of the given buffers.
-     * <p>
-     * This method attempts to read all of the <code>remaining()</code> bytes
-     * from <code>length</code> byte buffers, in order, starting at
-     * <code>targets[offset]</code>. The number of bytes actually read is
-     * returned.
-     * </p>
+     * Reads bytes from this socket channel into a subset of the given buffers.
+     * This method attempts to read all {@code remaining()} bytes from {@code
+     * length} byte buffers, in order, starting at {@code targets[offset]}. The
+     * number of bytes actually read is returned.
      * <p>
      * If a read operation is in progress, subsequent threads will block until
-     * the read is completed, and will then contend for the ability to read.
-     * </p>
-     * 
-     * @see java.nio.channels.ScatteringByteChannel#read(java.nio.ByteBuffer[],
-     *      int, int)
+     * the read is completed and will then contend for the ability to read.
+     *
      * @param targets
-     *            the array of byte buffers into which the bytes will be read.
+     *            the array of byte buffers into which the bytes will be copied.
      * @param offset
-     *            the index of the first buffer to read.
+     *            the index of the first buffer to store bytes in.
      * @param length
-     *            the maximum number of buffers to read.
-     * @throws NotYetConnectedException
-     *             If the channel is not connected yet.
-     * @throws ClosedChannelException
-     *             If the channel is already closed.
+     *            the maximum number of buffers to store bytes in.
+     * @return the number of bytes actually read.
      * @throws AsynchronousCloseException
-     *             If the channel is closed by another thread while this method
-     *             is in operation.
+     *             if this channel is closed by another thread during this read
+     *             operation.
      * @throws ClosedByInterruptException
-     *             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.
+     *             if another thread interrupts the calling thread while this
+     *             operation is in progress. The interrupt state of the calling
+     *             thread is set and the channel is closed.
+     * @throws ClosedChannelException
+     *             if this channel is closed.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code length < 0}, or if {@code
+     *             offset + length} is greater than the size of {@code targets}.
      * @throws IOException
-     *             Some other IO error occurred.
-     * 
+     *             if another I/O error occurs.
+     * @throws NotYetConnectedException
+     *             if this channel is not yet connected.
+     * @see java.nio.channels.ScatteringByteChannel#read(java.nio.ByteBuffer[],
+     *      int, int)
      */
     public abstract long read(ByteBuffer[] targets, int offset, int length)
             throws IOException;
 
     /**
-     * Reads bytes from the channel into all the given buffers.
+     * Reads bytes from this socket channel and stores them in the specified
+     * array of buffers. This method attempts to read as many bytes as can be
+     * stored in the buffer array from this channel and returns the number of
+     * bytes actually read.
      * <p>
-     * This method is equivalent to:
-     * 
-     * <pre>
-     * read(targets, 0, targets.length);
-     * </pre>
-     * 
-     * @see java.nio.channels.ScatteringByteChannel#read(java.nio.ByteBuffer[])
+     * If a read operation is in progress, subsequent threads will block until
+     * the read is completed and will then contend for the ability to read.
+     * <p>
+     * Calling this method is equivalent to calling {@code read(targets, 0,
+     * targets.length);}
+     *
      * @param targets
-     *            the array of byte buffers to receive the bytes being read.
+     *            the array of byte buffers into which the bytes will be copied.
      * @return the number of bytes actually read.
-     * @throws NotYetConnectedException
-     *             If the channel is not connected yet.
-     * @throws ClosedChannelException
-     *             If the channel is already closed.
      * @throws AsynchronousCloseException
-     *             If the channel is closed by another thread while this method
-     *             is in operation.
+     *             if this channel is closed by another thread during this read
+     *             operation.
      * @throws ClosedByInterruptException
-     *             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.
+     *             if another thread interrupts the calling thread while this
+     *             operation is in progress. The interrupt state of the calling
+     *             thread is set and the channel is closed.
+     * @throws ClosedChannelException
+     *             if this channel is closed.
      * @throws IOException
-     *             Some other IO error occurred.
+     *             if another I/O error occurs.
+     * @throws NotYetConnectedException
+     *             if this channel is not yet connected.
      */
     public synchronized final long read(ByteBuffer[] targets)
             throws IOException {
@@ -365,111 +340,99 @@
     }
 
     /**
-     * Writes bytes from the given buffer to the channel.
-     * <p>
-     * The maximum number of bytes that will be written is the
-     * <code>remaining()</code> number of bytes in the buffer when the method
-     * invoked. The bytes will be written from the buffer starting at the
-     * buffer's <code>position</code>.
-     * </p>
+     * Writes bytes from the given byte buffer to this socket channel. The
+     * maximum number of bytes that are written is the remaining number of bytes
+     * in the buffer when this method is invoked. The bytes are taken from the
+     * buffer starting at the buffer's position.
      * <p>
-     * The call may block if other threads are also attempting to write on the
+     * The call may block if other threads are also attempting to write to the
      * same channel.
-     * </p>
      * <p>
-     * Upon completion, the buffer's <code>position()</code> is updated to the
-     * end of the bytes that were written. The buffer's <code>limit()</code>
-     * is unmodified.
-     * </p>
-     * 
-     * @see java.nio.channels.WritableByteChannel#write(java.nio.ByteBuffer)
+     * Upon completion, the buffer's position is updated to the end of the bytes
+     * that have been written. The buffer's limit is not changed.
+     *
      * @param source
      *            the byte buffer containing the bytes to be written.
      * @return the number of bytes actually written.
-     * @throws NotYetConnectedException
-     *             If the channel is not connected yet.
-     * @throws ClosedChannelException
-     *             If the channel is already closed.
      * @throws AsynchronousCloseException
-     *             If the channel is closed by another thread while this method
-     *             is in operation.
+     *             if another thread closes the channel during the write.
      * @throws ClosedByInterruptException
-     *             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.
+     *             if another thread interrupts the calling thread while this
+     *             operation is in progress. The interrupt state of the calling
+     *             thread is set and the channel is closed.
+     * @throws ClosedChannelException
+     *             if the channel was already closed.
      * @throws IOException
-     *             Some other IO error occurred.
+     *             if another I/O error occurs.
+     * @throws NotYetConnectedException
+     *             if this channel is not connected yet.
+     * @see java.nio.channels.WritableByteChannel#write(java.nio.ByteBuffer)
      */
     public abstract int write(ByteBuffer source) throws IOException;
 
     /**
-     * Writes a subset of the given bytes from the buffers to the channel.
-     * <p>
-     * This method attempts to write all of the <code>remaining()</code> bytes
-     * from <code>length</code> byte buffers, in order, starting at
-     * <code>sources[offset]</code>. The number of bytes actually written is
-     * returned.
-     * </p>
+     * Attempts to writes a subset of the given bytes from the buffers to this
+     * socket channel. This method attempts to write all {@code remaining()}
+     * bytes from {@code length} byte buffers, in order, starting at {@code
+     * sources[offset]}. The number of bytes actually written is returned.
      * <p>
      * If a write operation is in progress, subsequent threads will block until
-     * the write is completed, and will then contend for the ability to write.
-     * </p>
-     * 
-     * @see java.nio.channels.GatheringByteChannel#write(java.nio.ByteBuffer[],
-     *      int, int)
+     * the write is completed and then contend for the ability to write.
+     *
      * @param sources
-     *            the array of byte buffers containing the source of remaining
-     *            bytes that will be attempted to be written.
+     *            the array of byte buffers that is the source for bytes written
+     *            to this channel.
      * @param offset
-     *            the index of the first buffer to write.
+     *            the index of the first buffer in {@code buffers }to get bytes
+     *            from.
      * @param length
-     *            the number of buffers to write.
-     * @return the number of bytes actually written.
-     * @throws NotYetConnectedException
-     *             If the channel is not connected yet.
-     * @throws ClosedChannelException
-     *             If the channel is already closed.
+     *            the number of buffers to get bytes from.
+     * @return the number of bytes actually written to this channel.
      * @throws AsynchronousCloseException
-     *             If the channel is closed by another thread while this method
-     *             is in operation.
+     *             if this channel is closed by another thread during this write
+     *             operation.
      * @throws ClosedByInterruptException
-     *             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.
+     *             if another thread interrupts the calling thread while this
+     *             operation is in progress. The interrupt state of the calling
+     *             thread is set and the channel is closed.
+     * @throws ClosedChannelException
+     *             if this channel is closed.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code length < 0}, or if {@code
+     *             offset + length} is greater than the size of {@code sources}.
      * @throws IOException
-     *             Some other IO error occurred.
+     *             if another I/O error occurs.
+     * @throws NotYetConnectedException
+     *             if this channel is not yet connected.
+     * @see java.nio.channels.GatheringByteChannel#write(java.nio.ByteBuffer[],
+     *      int, int)
      */
     public abstract long write(ByteBuffer[] sources, int offset, int length)
             throws IOException;
 
     /**
-     * Writes bytes from all the given buffers to the channel.
+     * Writes bytes from all the given byte buffers to this socket channel.
      * <p>
-     * This method is equivalent to:
-     * 
-     * <pre>
-     * write(buffers, 0, buffers.length);
-     * </pre>
-     * 
-     * </p>
-     * 
-     * @see java.nio.channels.GatheringByteChannel#write(java.nio.ByteBuffer[])
+     * Calling this method is equivalent to calling {@code write(sources, 0,
+     * sources.length);}
+     *
      * @param sources
-     *            the buffers containing bytes to be written.
+     *            the buffers containing bytes to write.
      * @return the number of bytes actually written.
-     * @throws NotYetConnectedException
-     *             If the channel is not connected yet.
-     * @throws ClosedChannelException
-     *             If the channel is already closed.
      * @throws AsynchronousCloseException
-     *             If the channel is closed by another thread while this method
-     *             is in operation.
+     *             if this channel is closed by another thread during this write
+     *             operation.
      * @throws ClosedByInterruptException
-     *             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.
+     *             if another thread interrupts the calling thread while this
+     *             operation is in progress. The interrupt state of the calling
+     *             thread is set and the channel is closed.
+     * @throws ClosedChannelException
+     *             if this channel is closed.
      * @throws IOException
-     *             Some other IO error occurred.
+     *             if another I/O error occurs.
+     * @throws NotYetConnectedException
+     *             if this channel is not yet connected.
+     * @see java.nio.channels.GatheringByteChannel#write(java.nio.ByteBuffer[])
      */
     public synchronized final long write(ByteBuffer[] sources)
             throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/UnresolvedAddressException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/UnresolvedAddressException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/UnresolvedAddressException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/UnresolvedAddressException.java Mon Apr 27 10:23:36 2009
@@ -17,15 +17,15 @@
 package java.nio.channels;
 
 /**
- * Thrown when trying to use an unresolved network address in a network
- * operation.
+ * An {@code UnresolvedAddressException} is thrown when trying to use an
+ * unresolved network address in a network operation.
  */
 public class UnresolvedAddressException extends IllegalArgumentException {
 
     private static final long serialVersionUID = 6136959093620794148L;
 
     /**
-     * Default constructor.
+     * Constructs an {@code UnresolvedAddressException}.
      */
     public UnresolvedAddressException() {
         super();

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/UnsupportedAddressTypeException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/UnsupportedAddressTypeException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/UnsupportedAddressTypeException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/UnsupportedAddressTypeException.java Mon Apr 27 10:23:36 2009
@@ -17,14 +17,15 @@
 package java.nio.channels;
 
 /**
- * Thrown when connecting or binding to an unsupported address type.
+ * An {@code UnsupportedAddressTypeException} is thrown when connecting or
+ * binding to an unsupported address type.
  */
 public class UnsupportedAddressTypeException extends IllegalArgumentException {
 
     private static final long serialVersionUID = -2964323842829700493L;
 
     /**
-     * Default constructor.
+     * Constructs an {@code UnsupportedAddressTypeException}.
      */
     public UnsupportedAddressTypeException() {
         super();

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/WritableByteChannel.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/WritableByteChannel.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/WritableByteChannel.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/WritableByteChannel.java Mon Apr 27 10:23:36 2009
@@ -20,12 +20,13 @@
 import java.nio.ByteBuffer;
 
 /**
- * A WritableByteChannel is a type of Channel that can write bytes.
+ * A {@code WritableByteChannel} is a type of {@link Channel} that can write
+ * bytes.
  * <p>
- * Writes are synchronous on a WritableByteChannel, that is, if a write is
- * already in progress on the channel then subsequent writes will block until
- * the first write completes. It is undefined whether non-write operations will
- * block.
+ * Write operations are synchronous on a {@code WritableByteChannel}, that is,
+ * if a write is already in progress on the channel then subsequent writes will
+ * block until the first write completes. It is undefined whether non-write
+ * operations will block.
  */
 public interface WritableByteChannel extends Channel {
 
@@ -36,17 +37,14 @@
      * <code>remaining()</code> number of bytes in the buffer when the method
      * invoked. The bytes will be written from the buffer starting at the
      * buffer's <code>position</code>.
-     * </p>
      * <p>
      * The call may block if other threads are also attempting to write on the
      * same channel.
-     * </p>
      * <p>
      * Upon completion, the buffer's <code>position()</code> is updated to the
      * end of the bytes that were written. The buffer's <code>limit()</code>
      * is unmodified.
-     * </p>
-     * 
+     *
      * @param buffer
      *            the byte buffer containing the bytes to be written.
      * @return the number of bytes actually written.

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/AbstractInterruptibleChannel.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/AbstractInterruptibleChannel.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/AbstractInterruptibleChannel.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/AbstractInterruptibleChannel.java Mon Apr 27 10:23:36 2009
@@ -28,14 +28,14 @@
 import java.security.PrivilegedExceptionAction;
 
 /**
- * This class roots the implementation of interruptible channels.
+ * {@code AbstractInterruptibleChannel} is the root class for interruptible
+ * channels.
  * <p>
  * The basic usage pattern for an interruptible channel is to invoke
- * <code>begin()</code> before any IO operations, then
- * <code>end(boolean)</code> after completing the operation. The argument to
- * the end method shows whether there has been any change to the java
- * environment that is visible to the API user.
- * </p>
+ * {@code begin()} before any I/O operation that potentially blocks
+ * indefinitely, then {@code end(boolean)} after completing the operation. The
+ * argument to the {@code end} method should indicate if the I/O operation has
+ * actually completed so that any change may be visible to the invoker.
 */
 public abstract class AbstractInterruptibleChannel implements Channel,
         InterruptibleChannel {
@@ -73,9 +73,10 @@
     }
 
     /**
-     * Answers whether the channel is open.
+     * Indicates whether this channel is open.
      * 
-     * @return true if the channel is open, and false if it is closed.
+     * @return {@code true} if this channel is open, {@code false} if it is
+     *         closed.
      * @see java.nio.channels.Channel#isOpen()
      */
     public synchronized final boolean isOpen() {
@@ -83,12 +84,19 @@
     }
 
     /**
-     * Closes the channel.
+     * Closes an open channel. If the channel is already closed then this method
+     * has no effect, otherwise it closes the receiver via the
+     * {@code implCloseChannel} method.
      * <p>
-     * If the channel is already closed then this method has no effect,
-     * otherwise it closes the receiver via the implCloseChannel method.
-     * </p>
-     * 
+     * If an attempt is made to perform an operation on a closed channel then a
+     * {@link java.nio.channels.ClosedChannelException} is thrown.
+     * <p>
+     * If multiple threads attempt to simultaneously close a channel, then only
+     * one thread will run the closure code and the others will be blocked until
+     * the first one completes.
+     *
+     * @throws IOException
+     *             if a problem occurs while closing this channel.
      * @see java.nio.channels.Channel#close()
      */
     public final void close() throws IOException {
@@ -103,10 +111,9 @@
     }
 
     /**
-     * Start an IO operation that is potentially blocking.
-     * <p>
-     * Once the operation is completed the application should invoke a
-     * corresponding <code>end(boolean)</code>.
+     * Indicates the beginning of a code section that includes an I/O operation
+     * that is potentially blocking. After this operation, the application
+     * should invoke the corresponding {@code end(boolean)} method.
      */
     protected final void begin() {
         // FIXME: be accommodate before VM actually provides
@@ -131,16 +138,18 @@
     }
 
     /**
-     * End an IO operation that was previously started with <code>begin()</code>.
+     * Indicates the end of a code section that has been started with
+     * {@code begin()} and that includes a potentially blocking I/O operation.
      * 
      * @param success
-     *            pass true if the operation succeeded and had a side effect on
-     *            the Java system, or false if not.
+     *            pass {@code true} if the blocking operation has succeeded and
+     *            has had a noticeable effect; {@code false} otherwise.
      * @throws AsynchronousCloseException
-     *             the channel was closed while the IO operation was in
-     *             progress.
-     * @throws java.nio.channels.ClosedByInterruptException
-     *             the thread conducting the IO operation was interrupted.
+     *             if this channel is closed by another thread while this method
+     *             is executing.
+     * @throws ClosedByInterruptException
+     *             if another thread interrupts the calling thread while this
+     *             method is executing.
      */
     protected final void end(boolean success) throws AsynchronousCloseException {
         // FIXME: be accommodate before VM actually provides
@@ -163,18 +172,18 @@
     }
 
     /**
-     * Implements the close channel behavior.
+     * Implements the channel closing behavior.
      * <p>
      * Closes the channel with a guarantee that the channel is not currently
-     * closed via <code>close()</code> and that the method is thread-safe.
-     * </p>
+     * closed through another invocation of {@code close()} and that the method
+     * is thread-safe.
      * <p>
-     * any outstanding threads blocked on IO operations on this channel must be
-     * released with either a normal return code, or an
-     * <code>AsynchronousCloseException</code>.
+     * Any outstanding threads blocked on I/O operations on this channel must be
+     * released with either a normal return code, or by throwing an
+     * {@code AsynchronousCloseException}.
      * 
      * @throws IOException
-     *             if a problem occurs closing the channel.
+     *             if a problem occurs while closing the channel.
      */
     protected abstract void implCloseChannel() throws IOException;
 }



Mime
View raw message