harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r768919 [5/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/FileChannel.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/FileChannel.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/FileChannel.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/FileChannel.java Mon Apr 27 10:23:36 2009
@@ -24,70 +24,63 @@
 /**
  * An abstract channel type for interaction with a platform file.
  * <p>
- * A FileChannel defines the methods for reading, writing, memory mapping, and
- * manipulating the logical state of a platform file. This type does not have a
- * method for opening files, since this behaviour has been delegated to the
- * <code>FileInputStream</code>, <code>FileOutputStream</code>, and
- * <code>RandomAccessFile</code> types.
- * </p>
+ * A {@code FileChannel} defines the methods for reading, writing, memory
+ * mapping, and manipulating the logical state of a platform file. This type
+ * does not have a method for opening files, since this behavior has been
+ * delegated to the {@link java.io.FileInputStream},
+ * {@link java.io.FileOutputStream} and {@link java.io.RandomAccessFile} types.
  * <p>
- * FileChannels created from a FileInputStream, or a RandomAccessFile created in
- * mode "r", are read-only. FileChannels created from a FileOutputStream are
- * write-only. FileChannels created from a RandomAccessFile created in mode "rw"
- * are read/write. FileChannels created from a RandomAccessFile that was opened
- * in append-mode will also be in append-mode -- meaning that each write will be
- * proceeded by a seek to the end of file. Some platforms will seek and write
- * atomically, others will not.
- * </p>
+ * FileChannels created from a {@code FileInputStream} or a
+ * {@code RandomAccessFile} created in mode "r", are read-only. FileChannels
+ * created from a {@code FileOutputStream} are write-only. FileChannels created
+ * from a {@code RandomAccessFile} created in mode "rw" are read/write.
+ * FileChannels created from a {@code RandomAccessFile} that was opened in
+ * append-mode will also be in append-mode -- meaning that each write will be
+ * proceeded by a seek to the end of file.
  * <p>
- * FileChannels has a virtual pointer into the file which is referred to as a
- * file <em>position</em>. The position can be manipulated by repositioning
- * it within the file, and its current position can be queried.
- * </p>
+ * FileChannels have a virtual pointer into the file which is referred to as a
+ * file <em>position</em>. The position can be manipulated by moving it
+ * within the file, and the current position can be queried.
  * <p>
  * FileChannels also have an associated <em>size</em>. The size of the file
  * is the number of bytes that it currently contains. The size can be
  * manipulated by adding more bytes to the end of the file (which increases the
  * size) or truncating the file (which decreases the size). The current size can
  * also be queried.
- * </p>
  * <p>
  * FileChannels have operations beyond the simple read, write, and close. They
  * can also:
  * <ul>
- * <li>request that cached data be forced onto the disk</li>
- * <li>lock ranges of bytes associated with the file</li>
+ * <li>request that cached data be forced onto the disk,</li>
+ * <li>lock ranges of bytes associated with the file,</li>
  * <li>transfer data directly to another channel in a manner that has the
- * potential to be optimized by the platform</li>
+ * potential to be optimized by the platform,</li>
  * <li>memory-mapping files into NIO buffers to provide efficient manipulation
- * of file data</li>
+ * of file data,</li>
  * <li>read and write to the file at absolute byte offsets in a fashion that
- * does not modify the current position</li>
+ * does not modify the current position.</li>
  * </ul>
- * </p>
  * <p>
  * FileChannels are thread-safe. Only one operation involving manipulation of
- * the file position may be in-flight at once. Subsequent calls to such
+ * the file position may be executed at the same time. Subsequent calls to such
  * operations will block, and one of those blocked will be freed to continue
  * when the first operation has completed. There is no ordered queue or fairness
  * applied to the blocked threads.
- * </p>
  * <p>
  * It is undefined whether operations that do not manipulate the file position
  * will also block when there are any other operations in-flight.
- * </p>
  * <p>
  * The logical view of the underlying file is consistent across all FileChannels
- * and IO streams opened on the same file by the same JVM process. Therefore
- * modifications performed via a channel will be visible to the stream, and vice
- * versa; including modifications to the file position, content, size, etc.
- * </p>
+ * and I/O streams opened on the same file by the same virtual machine process.
+ * Therefore, modifications performed via a channel will be visible to the
+ * stream and vice versa; this includes modifications to the file position,
+ * content, size, etc.
  */
 public abstract class FileChannel extends AbstractInterruptibleChannel
         implements GatheringByteChannel, ScatteringByteChannel, ByteChannel {
 
     /**
-     * A type of file mapping modes.
+     * {@code MapMode} defines file mapping mode constants.
      */
     public static class MapMode {
         /**
@@ -117,10 +110,9 @@
         }
 
         /**
-         * Answers a string version of the mapping mode useful for debugging
-         * etc.
+         * Returns a string version of the mapping mode.
          * 
-         * @return the mode string.
+         * @return this map mode as string.
          */
         @Override
         public String toString() {
@@ -136,178 +128,169 @@
     }
 
     /**
-     * Request that all updates to the channel are committed to the storage
+     * Requests that all updates to this channel are committed to the storage
      * device.
      * <p>
-     * When this method returns all modifications made to the platform file
-     * underlying this channel will be committed to a local storage device. If
-     * the file is not hosted locally, such as a networked file system, then
-     * applications cannot be certain that the modifications have been
-     * committed.
-     * </p>
+     * When this method returns, all modifications made to the platform file
+     * underlying this channel have been committed if the file resides on a
+     * local storage device. If the file is not hosted locally, for example on a
+     * networked file system, then applications cannot be certain that the
+     * modifications have been committed.
      * <p>
      * There are no assurances given that changes made to the file using methods
      * defined elsewhere will be committed. For example, changes made via a
      * mapped byte buffer may not be committed.
-     * </p>
      * <p>
-     * The <code>metadata</code> parameter indicated whether the update should
+     * The <code>metadata</code> parameter indicates whether the update should
      * include the file's metadata such as last modification time, last access
      * time, etc. Note that passing <code>true</code> may invoke an underlying
      * write to the operating system (if the platform is maintaining metadata
      * such as last access time), even if the channel is opened read-only.
      * 
      * @param metadata
-     *            true if the file metadata should be flushed in addition to the
-     *            file content, and false otherwise.
+     *            {@code true} if the file metadata should be flushed in
+     *            addition to the file content, {@code false} otherwise.
      * @throws ClosedChannelException
-     *             if the channel is already closed.
+     *             if this channel is already closed.
      * @throws IOException
-     *             some other problem occurred.
+     *             if another I/O error occurs.
      */
     public abstract void force(boolean metadata) throws IOException;
 
     /**
-     * Obtain an exclusive lock on this file.
+     * Obtains an exclusive lock on this file.
      * <p>
      * This is a convenience method for acquiring a maximum length lock on a
      * file. It is equivalent to:
-     * 
-     * <pre>
-     * fileChannel.lock(0L, Long.MAX_VALUE, false)
-     * </pre>
-     * 
+     * {@code fileChannel.lock(0L, Long.MAX_VALUE, false);}
+     *
      * @return the lock object representing the locked file area.
      * @throws ClosedChannelException
      *             the file channel is closed.
      * @throws NonWritableChannelException
      *             this channel was not opened for writing.
      * @throws OverlappingFileLockException
-     *             Either a lock is already held that overlaps this lock
+     *             either a lock is already held that overlaps this lock
      *             request, or another thread is waiting to acquire a lock that
      *             will overlap with this request.
      * @throws FileLockInterruptionException
-     *             The calling thread was interrupted while waiting to acquire
+     *             the calling thread was interrupted while waiting to acquire
      *             the lock.
      * @throws AsynchronousCloseException
-     *             The channel was closed while the calling thread was waiting
+     *             the channel was closed while the calling thread was waiting
      *             to acquire the lock.
      * @throws IOException
-     *             some other problem occurred obtaining the requested lock.
+     *             if another I/O error occurs while obtaining the requested
+     *             lock.
      */
     public final FileLock lock() throws IOException {
         return lock(0L, Long.MAX_VALUE, false);
     }
 
     /**
-     * Obtain a lock on a specified region of the file.
+     * Obtains a lock on a specified region of the file.
      * <p>
      * This is the blocking version of lock acquisition, see also the
      * <code>tryLock()</code> methods.
-     * </p>
      * <p>
      * Attempts to acquire an overlapping lock region will fail. The attempt
      * will fail if the overlapping lock has already been obtained, or if
      * another thread is currently waiting to acquire the overlapping lock.
-     * </p>
      * <p>
      * If the request is not for an overlapping lock, the thread calling this
      * method will block until the lock is obtained (likely by no contention or
-     * another process releasing a lock), or this thread being interrupted or
-     * the channel closed.
-     * </p>
-     * <p>
-     * If the lock is obtained successfully then the FileLock object returned
-     * represents the lock for subsequent operations on the locked region.
-     * </p>
+     * another process releasing a lock), or until this thread is interrupted or
+     * the channel is closed.
+     * <p>
+     * If the lock is obtained successfully then the {@link FileLock} object
+     * returned represents the lock for subsequent operations on the locked
+     * region.
      * <p>
      * If the thread is interrupted while waiting for the lock, the thread is
-     * set to the interrupted state, and throws a
-     * <code>FileLockInterruptionException</code>. If the channel is closed
-     * while the thread is waiting to obtain the lock then the thread throws a
-     * <code>AsynchronousCloseException</code>.
-     * </p>
+     * set to the interrupted state and throws a
+     * {@link FileLockInterruptionException}. If this channel is closed while
+     * the thread is waiting to obtain the lock then the thread throws a
+     * {@link AsynchronousCloseException}.
      * <p>
      * There is no requirement for the position and size to be within the
      * current start and length of the file.
-     * </p>
      * <p>
      * Some platforms do not support shared locks, and if a request is made for
-     * a shared lock on such a platform this method will attempt to acquire an
+     * a shared lock on such a platform, this method will attempt to acquire an
      * exclusive lock instead. It is undefined whether the lock obtained is
      * advisory or mandatory.
-     * </p>
-     * 
+     *
      * @param position
-     *            the starting position for the lock region
+     *            the starting position for the locked region.
      * @param size
-     *            the length of the lock, in bytes
+     *            the length of the locked region in bytes.
      * @param shared
      *            a flag indicating whether an attempt should be made to acquire
      *            a shared lock.
-     * @return the file lock object
+     * @return the file lock object.
      * @throws IllegalArgumentException
-     *             if the parameters are invalid.
+     *             if {@code position} or {@code size} is negative.
      * @throws ClosedChannelException
-     *             if the channel is already closed.
+     *             if this channel is closed.
      * @throws OverlappingFileLockException
      *             if the requested region overlaps an existing lock or pending
      *             lock request.
      * @throws NonReadableChannelException
-     *             if the channel is not open in read-mode and shared is true.
+     *             if the channel is not opened in read-mode but shared is true.
      * @throws NonWritableChannelException
-     *             if the channel is not open in write mode and shared is false.
+     *             if the channel is not opened in write mode but shared is
+     *             false.
      * @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 FileLockInterruptionException
      *             if the thread is interrupted while in the state of waiting on
      *             the desired file lock.
      * @throws IOException
-     *             if some other IO problem occurs.
+     *             if another I/O error occurs.
      */
     public abstract FileLock lock(long position, long size, boolean shared)
             throws IOException;
 
     /**
-     * Maps the file into memory.There can be three modes:Read-only,Read/write
-     * and Private.
-     * 
-     * After mapping, the memory and the file channel do not affect each other.
-     * 
-     * Note : mapping a file into memory is usually expensive.
-     * 
+     * Maps the file into memory. There can be three modes: read-only,
+     * read/write and private. After mapping, changes made to memory or the file
+     * channel do not affect the other storage place.
+     * <p>
+     * Note: mapping a file into memory is usually expensive.
+     *
      * @param mode
-     *            one of three modes to map
+     *            one of the three mapping modes.
      * @param position
-     *            the starting position of the file
+     *            the starting position of the file.
      * @param size
-     *            the size to map
-     * @return the mapped byte buffer
-     * 
+     *            the size of the region to map into memory.
+     * @return the mapped byte buffer.
      * @throws NonReadableChannelException
-     *             If the file is not opened for reading but the given mode is
-     *             "READ_ONLY"
+     *             if the FileChannel is not opened for reading but the given
+     *             mode is "READ_ONLY".
      * @throws NonWritableChannelException
-     *             If the file is not opened for writing but the mode is not
-     *             "READ_ONLY"
+     *             if the FileChannel is not opened for writing but the given
+     *             mode is not "READ_ONLY".
      * @throws IllegalArgumentException
-     *             If the given parameters of position and size are not correct
+     *             if the given parameters of position and size are not correct.
+     *             Both must be non negative. {@code size} also must not be
+     *             bigger than max integer.
      * @throws IOException
-     *             If any I/O error occurs
+     *             if any I/O error occurs.
      */
     public abstract MappedByteBuffer map(FileChannel.MapMode mode,
             long position, long size) throws IOException;
 
     /**
-     * Answers the current value of the file position pointer.
+     * Returns the current value of the file position pointer.
      * 
      * @return the current position as a positive integer number of bytes from
      *         the start of the file.
      * @throws ClosedChannelException
-     *             if the channel is already closed.
+     *             if this channel is closed.
      * @throws IOException
-     *             if some other IO problem occurs.
+     *             if another I/O error occurs.
      */
     public abstract long position() throws IOException;
 
@@ -317,9 +300,9 @@
      * The argument is the number of bytes counted from the start of the file.
      * The position cannot be set to a value that is negative. The new position
      * can be set beyond the current file size. If set beyond the current file
-     * size, attempts to read will return end of file, and writes will succeed,
-     * but fill-in the bytes between the current end of file and the position
-     * with the required number of (unspecified) byte values.
+     * size, attempts to read will return end of file. Write operations will
+     * succeed but they will fill the bytes between the current end of file and
+     * the new position with the required number of (unspecified) byte values.
      * 
      * @param offset
      *            the new file position, in bytes.
@@ -327,204 +310,257 @@
      * @throws IllegalArgumentException
      *             if the new position is negative.
      * @throws ClosedChannelException
-     *             if the channel is already closed.
+     *             if this channel is closed.
      * @throws IOException
-     *             if some other IO problem occurs.
+     *             if another I/O error occurs.
      */
     public abstract FileChannel position(long offset) throws IOException;
 
     /**
-     * Reads bytes from the channel into the given byte buffer.
+     * Reads bytes from this file channel into the given buffer.
      * <p>
-     * The bytes are read starting at the current file position, and after some
-     * number of bytes are read (up to the remaining number of bytes in the
-     * buffer) the file position is increased by the number of bytes actually
-     * read.
-     * 
-     * @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 buffer
+     *            the byte buffer to receive the bytes.
+     * @return the number of bytes actually read.
+     * @throws AsynchronousCloseException
+     *             if another thread closes the channel during the read.
+     * @throws ClosedByInterruptException
+     *             if another thread interrupts the calling thread during the
+     *             read.
+     * @throws ClosedChannelException
+     *             if this channel is closed.
+     * @throws IOException
+     *             if another I/O error occurs, details are in the message.
+     * @throws NonReadableChannelException
+     *             if the channel has not been opened in a mode that permits
+     *             reading.
      */
     public abstract int read(ByteBuffer buffer) throws IOException;
 
     /**
-     * Reads bytes from the file channel into the given buffer starting from the
-     * given file position.
+     * Reads bytes from this file channel into the given buffer starting from
+     * the specified file position.
      * <p>
      * The bytes are read starting at the given file position (up to the
      * remaining number of bytes in the buffer). The number of bytes actually
      * read is returned.
-     * </p>
      * <p>
-     * If the position is beyond the current end of file, then no bytes are
+     * If {@code position} is beyond the current end of file, then no bytes are
      * read.
-     * </p>
      * <p>
-     * Note that file position is unmodified by this method.
-     * </p>
-     * 
+     * Note that the file position is unmodified by this method.
+     *
      * @param buffer
-     *            the buffer to receive the bytes
+     *            the buffer to receive the bytes.
      * @param position
      *            the (non-negative) position at which to read the bytes.
      * @return the number of bytes actually read.
-     * @throws IllegalArgumentException
-     *             if <code>position</code> is less than <code>-1</code>.
-     * @throws ClosedChannelException
-     *             if the channel is already closed.
-     * @throws NonReadableChannelException
-     *             if the channel was not opened in read-mode.
      * @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.
+     * @throws ClosedChannelException
+     *             if this channel is closed.
+     * @throws IllegalArgumentException
+     *             if <code>position</code> is less than 0.
      * @throws IOException
-     *             some other IO error occurred.
+     *             if another I/O error occurs.
+     * @throws NonReadableChannelException
+     *             if the channel has not been opened in a mode that permits
+     *             reading.
      */
     public abstract int read(ByteBuffer buffer, long position)
             throws IOException;
 
     /**
-     * Reads bytes from the channel into all the given byte buffers.
-     * <p>
-     * The bytes are read starting at the current file position, and after some
-     * number of bytes are read (up to the remaining number of bytes in all the
-     * buffers) the file position is increased by the number of bytes actually
+     * Reads bytes from this file 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. It also increases the file position by the number of bytes
      * read.
-     * </p>
      * <p>
-     * This method behaves exactly like:
-     * 
-     * <pre>
-     * read(buffers, 0, buffers.length);
-     * </pre>
-     * 
-     * </p>
-     * 
-     * @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(buffers, 0, buffers.length);}
+     *
+     * @param buffers
+     *            the array of byte buffers into which the bytes will be copied.
+     * @return the number of bytes actually read.
+     * @throws AsynchronousCloseException
+     *             if this channel is closed by another thread during this read
+     *             operation.
+     * @throws ClosedByInterruptException
+     *             if the thread is interrupted by another thread during this
+     *             read operation.
+     * @throws ClosedChannelException
+     *             if this channel is closed.
+     * @throws IOException
+     *             if another I/O error occurs; details are in the message.
+     * @throws NonReadableChannelException
+     *             if the channel has not been opened in a mode that permits
+     *             reading.
      */
     public final long read(ByteBuffer[] buffers) throws IOException {
         return read(buffers, 0, buffers.length);
     }
 
     /**
-     * Reads bytes from the file channel into a subset of the given byte
-     * buffers.
-     * 
-     * @see java.nio.channels.ScatteringByteChannel#read(java.nio.ByteBuffer[],
-     *      int, int)
+     * Reads bytes from this file 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]}. It
+     * increases the file position by the number of bytes actually read. 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.
+     *
+     * @param buffers
+     *            the array of byte buffers into which the bytes will be copied.
+     * @param start
+     *            the index of the first buffer to store bytes in.
+     * @param number
+     *            the maximum number of buffers to store bytes in.
+     * @return the number of bytes actually read.
+     * @throws AsynchronousCloseException
+     *             if this channel is closed by another thread during this read
+     *             operation.
+     * @throws ClosedByInterruptException
+     *             if the thread is interrupted by another thread during this
+     *             read operation.
+     * @throws ClosedChannelException
+     *             if this channel is closed.
+     * @throws IndexOutOfBoundsException
+     *             if {@code start < 0} or {@code number < 0}, or if
+     *             {@code start + number} is greater than the size of
+     *             {@code buffers}.
+     * @throws IOException
+     *             if another I/O error occurs; details are in the message.
+     * @throws NonReadableChannelException
+     *             if the channel has not been opened in a mode that permits
+     *             reading.
      */
     public abstract long read(ByteBuffer[] buffers, int start, int number)
             throws IOException;
 
     /**
-     * Answers the size of the file underlying this channel, in bytes.
+     * Returns the size of the file underlying this channel in bytes.
      * 
      * @return the size of the file in bytes.
      * @throws ClosedChannelException
-     *             if the channel is closed.
+     *             if this channel is closed.
      * @throws IOException
-     *             if a problem occurs getting the size of the file.
+     *             if an I/O error occurs while getting the size of the file.
      */
     public abstract long size() throws IOException;
 
     /**
-     * Transfers bytes into this channel's file from the given readable byte
-     * channel. It may be very efficient.
-     * 
-     * By invoking this method, it will read form the source channel and write
-     * into the file channel.
-     * 
-     * Note: no guarantee whether all bytes may be transferred. And it does not
-     * modify the position of the channel.
-     * 
+     * Reads up to {@code count} bytes from {@code src} and stores them in this
+     * channel's file starting at {@code position}. No bytes are transferred if
+     * {@code position} is larger than the size of this channel's file. Less
+     * than {@code count} bytes are transferred if there are less bytes
+     * remaining in the source channel or if the source channel is non-blocking
+     * and has less than {@code count} bytes immediately available in its output
+     * buffer.
+     * <p>
+     * Note that this channel's position is not modified.
+     *
      * @param src
-     *            the source channel to read
+     *            the source channel to read bytes from.
      * @param position
-     *            the non-negative position to begin
+     *            the non-negative start position.
      * @param count
-     *            the non-negative bytes to be transferred
+     *            the non-negative number of bytes to transfer.
      * @return the number of bytes that are transferred.
-     * 
      * @throws IllegalArgumentException
-     *             If the parameters are not correct
+     *             if the parameters are invalid.
      * @throws NonReadableChannelException
-     *             If the source channel is not readable
+     *             if the source channel is not readable.
      * @throws NonWritableChannelException
-     *             If this channel is not writable
+     *             if this channel is not writable.
      * @throws ClosedChannelException
-     *             If either channel has already been closed
+     *             if either channel has already been closed.
      * @throws AsynchronousCloseException
-     *             If either channel is closed by other threads during this
-     *             operation
+     *             if either channel is closed by other threads during this
+     *             operation.
      * @throws ClosedByInterruptException
-     *             If the thread is interrupted during this operation
+     *             if the thread is interrupted during this operation.
      * @throws IOException
-     *             If any I/O error occurs
+     *             if any I/O error occurs.
      */
     public abstract long transferFrom(ReadableByteChannel src, long position,
             long count) throws IOException;
 
     /**
-     * Transfers data from the file to the given channel. It may be very
-     * efficient.
-     * 
-     * By invoking this method, it will read form the file and write into the
-     * writable channel.
-     * 
-     * Note: no guarantee whether all bytes may be transfered.And it does not
-     * modify the position of the channel.
-     * 
+     * Reads up to {@code count} bytes from this channel's file starting at
+     * {@code position} and writes them to {@code target}. No bytes are
+     * transferred if {@code position} is larger than the size of this channel's
+     * file. Less than {@code count} bytes are transferred if there less bytes
+     * available from this channel's file or if the target channel is
+     * non-blocking and has less than {@code count} bytes free in its input
+     * buffer.
+     * <p>
+     * Note that this channel's position is not modified.
+     *
      * @param position
-     *            the non-negative position to begin
+     *            the non-negative position to begin.
      * @param count
-     *            the non-negative bytes to be transferred
+     *            the non-negative number of bytes to transfer.
      * @param target
-     *            the target channel to write into
+     *            the target channel to write to.
      * @return the number of bytes that were transferred.
-     * 
      * @throws IllegalArgumentException
-     *             If the parameters are not correct
+     *             if the parameters are invalid.
      * @throws NonReadableChannelException
-     *             If this channel is not readable
+     *             if this channel is not readable.
      * @throws NonWritableChannelException
-     *             If the target channel is not writable
+     *             if the target channel is not writable.
      * @throws ClosedChannelException
-     *             If either channel has already been closed
+     *             if either channel has already been closed.
      * @throws AsynchronousCloseException
-     *             If either channel is closed by other threads during this
-     *             operation
+     *             if either channel is closed by other threads during this
+     *             operation.
      * @throws ClosedByInterruptException
-     *             If the thread is interrupted during this operation
+     *             if the thread is interrupted during this operation.
      * @throws IOException
-     *             If any I/O error occurs
+     *             if any I/O error occurs.
      */
     public abstract long transferTo(long position, long count,
             WritableByteChannel target) throws IOException;
 
     /**
-     * Truncates the file underlying this channel to a given size.
-     * <p>
-     * Any bytes beyond the given size are removed from the file. If there are
-     * no bytes beyond the given size then the file contents are unmodified.
-     * </p>
+     * Truncates the file underlying this channel to a given size. Any bytes
+     * beyond the given size are removed from the file. If there are no bytes
+     * beyond the given size then the file contents are unmodified.
      * <p>
      * If the file position is currently greater than the given size, then it is
-     * set to be the given size.
-     * </p>
-     * 
+     * set to the new size.
+     *
      * @param size
-     *            the maximum size of the underlying file
+     *            the maximum size of the underlying file.
      * @throws IllegalArgumentException
-     *             the requested size is negative.
+     *             if the requested size is negative.
      * @throws ClosedChannelException
-     *             the channel is closed.
+     *             if this channel is closed.
      * @throws NonWritableChannelException
-     *             the channel cannot be written.
+     *             if the channel cannot be written to.
      * @throws IOException
-     *             some other IO problem occurred.
-     * @return this channel
+     *             if another I/O error occurs.
+     * @return this channel.
      */
     public abstract FileChannel truncate(long size) throws IOException;
 
@@ -533,143 +569,190 @@
      * <p>
      * This is a convenience method for attempting to acquire a maximum length
      * lock on the file. It is equivalent to:
-     * 
-     * <pre>
-     * fileChannel.tryLock(0L, Long.MAX_VALUE, false)
-     * </pre>
-     * 
-     * </p>
+     * {@code fileChannel.tryLock(0L, Long.MAX_VALUE, false);}
      * <p>
-     * The method returns <code>null</code> if the acquisition would result in
-     * an overlapped lock with another OS process.
-     * </p>
-     * 
-     * @return the file lock object, or <code>null</code> if the lock would
-     *         overlap an existing exclusive lock in another OS process.
+     * The method returns {@code null} if the acquisition would result in an
+     * overlapped lock with another OS process.
+     *
+     * @return the file lock object, or {@code null} if the lock would overlap
+     *         with an existing exclusive lock in another OS process.
      * @throws ClosedChannelException
-     *             the file channel is closed.
+     *             if the file channel is closed.
      * @throws OverlappingFileLockException
-     *             Either a lock is already held that overlaps this lock
-     *             request, or another thread is waiting to acquire a lock that
-     *             will overlap with this request.
+     *             if a lock already exists that overlaps this lock request or
+     *             another thread is waiting to acquire a lock that will overlap
+     *             with this request.
      * @throws IOException
-     *             if any I/O error occurs
+     *             if any I/O error occurs.
      */
     public final FileLock tryLock() throws IOException {
         return tryLock(0L, Long.MAX_VALUE, false);
     }
 
     /**
-     * Attempts to acquire an exclusive lock on this file without blocking.
-     * <p>
-     * The method returns <code>null</code> if the acquisition would result in
-     * an overlapped lock with another OS process.
-     * </p>
-     * 
+     * Attempts to acquire an exclusive lock on this file without blocking. The
+     * method returns {@code null} if the acquisition would result in an
+     * overlapped lock with another OS process.
+     * <p>
+     * It is possible to acquire a lock for any region even if it's completely
+     * outside of the file's size. The size of the lock is fixed. If the file
+     * grows outside of the lock that region of the file won't be locked by this
+     * lock.
+     *
      * @param position
-     *            the starting position
+     *            the starting position.
      * @param size
-     *            the size of file to lock
+     *            the size of file to lock.
      * @param shared
-     *            true if share
-     * @return the file lock object, or <code>null</code> if the lock would
-     *         overlap an existing exclusive lock in another OS process.
-     * 
+     *            true if the lock is shared.
+     * @return the file lock object, or {@code null} if the lock would overlap
+     *         with an existing exclusive lock in another OS process.
      * @throws IllegalArgumentException
-     *             If any parameters are bad
+     *             if any parameters are invalid.
      * @throws ClosedChannelException
-     *             the file channel is closed.
+     *             if the file channel is closed.
      * @throws OverlappingFileLockException
-     *             Either a lock is already held that overlaps this lock
-     *             request, or another thread is waiting to acquire a lock that
-     *             will overlap with this request.
+     *             if a lock is already held that overlaps this lock request or
+     *             another thread is waiting to acquire a lock that will overlap
+     *             with this request.
      * @throws IOException
-     *             if any I/O error occurs
+     *             if any I/O error occurs.
      */
     public abstract FileLock tryLock(long position, long size, boolean shared)
             throws IOException;
 
     /**
-     * Writes bytes from the given byte buffer into the file channel.
+     * Writes bytes from the given byte buffer to this file channel.
      * <p>
      * The bytes are written starting at the current file position, and after
      * some number of bytes are written (up to the remaining number of bytes in
      * the buffer) the file position is increased by the number of bytes
      * actually written.
      * 
-     * @see java.nio.channels.WritableByteChannel#write(java.nio.ByteBuffer)
-     * 
      * @param src
-     *            the source buffer to write
+     *            the byte buffer containing the bytes to be written.
+     * @return the number of bytes actually written.
+     * @throws NonWritableChannelException
+     *             if the channel was not opened for writing.
+     * @throws ClosedChannelException
+     *             if the channel was already closed.
+     * @throws AsynchronousCloseException
+     *             if another thread closes the channel during the write.
+     * @throws ClosedByInterruptException
+     *             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 IOException
+     *             if another I/O error occurs, details are in the message.
+     * @see java.nio.channels.WritableByteChannel#write(java.nio.ByteBuffer)
      */
     public abstract int write(ByteBuffer src) throws IOException;
 
     /**
-     * Writes bytes from the given buffer to the file channel starting at the
+     * Writes bytes from the given buffer to this file channel starting at the
      * given file position.
      * <p>
      * The bytes are written starting at the given file position (up to the
      * remaining number of bytes in the buffer). The number of bytes actually
      * written is returned.
-     * </p>
      * <p>
      * If the position is beyond the current end of file, then the file is first
      * extended up to the given position by the required number of unspecified
      * byte values.
-     * </p>
      * <p>
-     * Note that file position is unmodified by this method.
-     * </p>
-     * 
+     * Note that the file position is not modified by this method.
+     *
      * @param buffer
      *            the buffer containing the bytes to be written.
      * @param position
      *            the (non-negative) position at which to write the bytes.
      * @return the number of bytes actually written.
      * @throws IllegalArgumentException
-     *             if <code>position</code> is less than <code>-1</code>.
+     *             if <code>position</code> is less than 0.
      * @throws ClosedChannelException
-     *             if the channel is already closed.
+     *             if this channel is closed.
      * @throws NonWritableChannelException
      *             if the channel was not opened in write-mode.
      * @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 interrupt state of the calling
+     *             thread is set and the channel is closed.
      * @throws IOException
-     *             some other IO error occurred.
+     *             if another I/O error occurs.
      */
     public abstract int write(ByteBuffer buffer, long position)
             throws IOException;
 
     /**
-     * Writes bytes from all the given byte buffers into the file channel.
+     * Writes bytes from all the given byte buffers to this file channel.
      * <p>
      * The bytes are written starting at the current file position, and after
-     * some number of bytes are written (up to the remaining number of bytes in
-     * all the buffers) the file position is increased by the number of bytes
-     * actually written.
-     * <p>
-     * This method behaves exactly like:
-     * 
-     * <pre>
-     * write(buffers, 0, buffers.length);
-     * </pre>
-     * 
-     * </p>
-     * 
-     * @see java.nio.channels.GatheringByteChannel#write(java.nio.ByteBuffer[])
+     * the bytes are written (up to the remaining number of bytes in all the
+     * buffers), the file position is increased by the number of bytes actually
+     * written.
+     * <p>
+     * Calling this method is equivalent to calling
+     * {@code write(buffers, 0, buffers.length);}
+     *
+     * @param buffers
+     *            the buffers containing bytes to write.
+     * @return the number of bytes actually written.
+     * @throws AsynchronousCloseException
+     *             if this channel is closed by another thread during this write
+     *             operation.
+     * @throws ClosedByInterruptException
+     *             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; details are in the message.
+     * @throws NonWritableChannelException
+     *             if this channel was not opened for writing.
      */
     public final long write(ByteBuffer[] buffers) throws IOException {
         return write(buffers, 0, buffers.length);
     }
 
     /**
-     * @see java.nio.channels.GatheringByteChannel#write(java.nio.ByteBuffer[],
-     *      int, int)
+     * Attempts to writes a subset of the given bytes from the buffers to this
+     * file 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 then contend for the ability to write.
+     *
+     * @param buffers
+     *            the array of byte buffers that is the source for bytes written
+     *            to this channel.
+     * @param offset
+     *            the index of the first buffer in {@code buffers }to get bytes
+     *            from.
+     * @param length
+     *            the number of buffers to get bytes from.
+     * @return the number of bytes actually written to this channel.
+     * @throws AsynchronousCloseException
+     *             if this channel is closed by another thread during this write
+     *             operation.
+     * @throws ClosedByInterruptException
+     *             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 buffers}.
+     * @throws IOException
+     *             if another I/O error occurs; details are in the message.
+     * @throws NonWritableChannelException
+     *             if this channel was not opened for writing.
      */
     public abstract long write(ByteBuffer[] buffers, int offset, int length)
             throws IOException;

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/FileLock.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/FileLock.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/FileLock.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/FileLock.java Mon Apr 27 10:23:36 2009
@@ -20,53 +20,53 @@
 import java.io.IOException;
 
 /**
- * A <code>FileLock</code> represents a locked region of a file.
+ * A {@code FileLock} represents a locked region of a file.
  * <p>
  * Locks have certain properties that enable collaborating processes to avoid
- * the lost update problem, or reading inconsistent data.
- * </p>
- * <p>
- * logically, a file lock can be 'exclusive' or 'shared'. Multiple processes can
- * hold shared locks on the same region of a file, but only a single process can
- * hold an exclusive lock on a given region of a file and no other process can
+ * the lost update problem or reading inconsistent data. Logically, a file lock
+ * can be <em>exclusive</em> or <em>shared</em>. Multiple processes can hold
+ * shared locks on the same region of a file, but only a single process can hold
+ * an exclusive lock on a given region of a file and no other process can
  * simultaneously hold a shared lock overlapping the exclusive lock. An
- * application can determine whether a FileLock is shared or exclusive via the
- * <code>isShared()</code> API.
- * </p>
+ * application can determine whether a {@code FileLock} is shared or exclusive
+ * via the {@code isShared()} method.
  * <p>
  * Locks held by a particular process cannot overlap one another. Applications
- * can determine whether a proposed lock will overlap by using the
- * <code>overlaps(long, long)</code) API.  Locks held in
- * other processes may overlap locks held in this process.</p>
- * <p>
- * Locks are shared amongst all threads in the acquiring process, and are therefore unsuitable for
- * intra-process synchronization.</p>
- * <p>
- * Once a lock is acquired it is immutable in all its state except <code>isValid()</code>.  The lock
- * will initially be valid, but may be rendered invalid by explicit removal of the lock, using <code>
- * release()</code>, or implicitly by closing the channel or exiting the process (terminating the JVM).</p>
- * <p>
- * <em>Platform dependencies</em></p>
- * <p>
- * Locks are intended to be true platform operating system file locks, and therefore locks held by the
- * JVM process will be visible to other OS processes.</p>
- * <p>
- * The characteristics of the underlying OS locks will show through in the Java implementation.  For
- * example, some platforms' locks are 'mandatory' -- meaning the operating system enforces the locks
- * on processes that attempt to access locked regions of file; whereas other platforms' locks are
- * only 'advisory' -- meaning that processes are required to collaborate on ensuring locks are acquired
- * and there is a potential for processes not to play well.  The only safe answer is to assume that
- * the platform is adopting advisory locks an always acquire shared locks when reading a region of file.</p>
- * <p>
- * On some platforms the presence of a lock will prevent the file being memory mapped.  On some platforms
- * closing a channel on a given file handle will release all the locks held on that file -- even if there
- * are other channels open on the same file (their locks will be released).  The safe option here is to
- * ensure that you only acquire locks on a single channel for a particular file, and that becomes the
- * synchronization point.</p>
- * <p>
- * Further care should be exercised when locking files maintained on network file systems since they often
- * have further limitations.</p>  
- *
+ * can determine whether a proposed lock will overlap by using the {@code
+ * overlaps(long, long)}) method. Locks held in other processes may overlap
+ * locks held in this process. Locks are shared amongst all threads in the
+ * acquiring process, and are therefore unsuitable for intra-process
+ * synchronization.
+ * <p>
+ * Once a lock is acquired, it is immutable in all its state except {@code
+ * isValid()}. The lock will initially be valid, but may be rendered invalid by
+ * explicit removal of the lock, using {@code release()}, or implicitly by
+ * closing the channel or exiting the process (terminating the virtual machine).
+ * <h3>Platform dependencies</h3>
+ * <p>
+ * Locks are intended to be true platform operating system file locks, and
+ * therefore locks held by the virtual machine process will be visible to other
+ * operating system processes.
+ * <p>
+ * The characteristics of the underlying operating system locks will show
+ * through in the Java implementation. For example, some platforms' locks are
+ * 'mandatory' -- meaning the operating system enforces the locks on processes
+ * that attempt to access locked regions of files; whereas other platforms'
+ * locks are only 'advisory' -- meaning that processes are required to
+ * collaborate to ensure locks are acquired and there is a potential for
+ * processes to not play well. To be on the safe side, it is best to assume that
+ * the platform is adopting advisory locks and always acquire shared locks when
+ * reading a region of a file.
+ * <p>
+ * On some platforms, the presence of a lock will prevent the file from being
+ * memory-mapped. On some platforms, closing a channel on a given file handle
+ * will release all the locks held on that file -- even if there are other
+ * channels open on the same file; their locks will also be released. The safe
+ * option here is to ensure that you only acquire locks on a single channel for
+ * a particular file and that becomes the synchronization point.
+ * <p>
+ * Further care should be exercised when locking files maintained on network
+ * file systems, since they often have further limitations.
  */
 public abstract class FileLock {
 
@@ -83,18 +83,18 @@
     private final boolean shared;
 
     /**
-     * Constructor for a new file lock instance for a given channel. The
-     * constructor enforces the starting position, stretch, and shared status of
-     * the lock.
+     * Constructs a new file lock instance for a given channel. The constructor
+     * enforces the starting position, length and sharing mode of the lock.
      * 
      * @param channel
-     *            underlying file channel that holds the lock.
+     *            the underlying file channel that holds the lock.
      * @param position
-     *            starting point for the lock.
+     *            the starting point for the lock.
      * @param size
-     *            length of lock in number of bytes.
+     *            the length of the lock in number of bytes.
      * @param shared
-     *            shared status of lock (true is shared, false is exclusive).
+     *            the lock's sharing mode of lock; {@code true} is shared,
+     *            {@code false} is exclusive.
      */
     protected FileLock(FileChannel channel, long position, long size,
             boolean shared) {
@@ -109,7 +109,7 @@
     }
 
     /**
-     * Answers the lock's FileChannel.
+     * Returns the lock's {@link FileChannel}.
      * 
      * @return the channel.
      */
@@ -118,7 +118,7 @@
     }
 
     /**
-     * Answers the lock's starting position in the file.
+     * Returns the lock's starting position in the file.
      * 
      * @return the lock position.
      */
@@ -127,33 +127,34 @@
     }
 
     /**
-     * Answers the length of the file lock in bytes.
+     * Returns the length of the file lock in bytes.
      * 
-     * @return the size of file lock in bytes.
+     * @return the size of the file lock in bytes.
      */
     public final long size() {
         return size;
     }
 
     /**
-     * Answers true if the file lock is shared with other processes and false if
-     * it is not.
+     * Indicates if the file lock is shared with other processes or if it is
+     * exclusive.
      * 
-     * @return true if the lock is a shared lock, and false if it is exclusive.
+     * @return {@code true} if the lock is a shared lock, {@code false} if it is
+     *         exclusive.
      */
     public final boolean isShared() {
         return shared;
     }
 
     /**
-     * Answers true if the receiver's lock region overlapps the region described
-     * in the parameter list,and answers false otherwise.
+     * Indicates if the receiver's lock region overlaps the region described
+     * in the parameter list.
      * 
      * @param start
      *            the starting position for the comparative lock.
      * @param length
      *            the length of the comparative lock.
-     * @return true if there is an overlap, and false otherwise.
+     * @return {@code true} if there is an overlap, {@code false} otherwise.
      */
     public final boolean overlaps(long start, long length) {
         final long end = position + size - 1;
@@ -165,28 +166,28 @@
     }
 
     /**
-     * Answers whether the receiver is a valid file lock or not. The lock is
+     * Indicates whether this lock is a valid file lock. The lock is
      * valid unless the underlying channel has been closed or it has been
      * explicitly released.
      * 
-     * @return true if the lock is valid, and false otherwise.
+     * @return {@code true} if the lock is valid, {@code false} otherwise.
      */
     public abstract boolean isValid();
 
     /**
      * Releases this particular lock on the file. If the lock is invalid then
-     * this method has no effect. Once released the lock becomes invalid.
+     * this method has no effect. Once released, the lock becomes invalid.
      * 
      * @throws ClosedChannelException
      *             if the channel is already closed when an attempt to release
      *             the lock is made.
      * @throws IOException
-     *             some other IO exception occurred.
+     *             if another I/O error occurs.
      */
     public abstract void release() throws IOException;
 
     /**
-     * Answers a string that shows the details of the lock suitable for display
+     * Returns a string that shows the details of the lock suitable for display
      * to an end user.
      * 
      * @return the display string.

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/FileLockInterruptionException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/FileLockInterruptionException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/FileLockInterruptionException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/FileLockInterruptionException.java Mon Apr 27 10:23:36 2009
@@ -19,17 +19,17 @@
 import java.io.IOException;
 
 /**
- * Thrown when thread was interrupted while waiting to acquire a file lock.
+ * A {@code FileLockInterruptionException} is thrown when a thread is
+ * interrupted while waiting to acquire a file lock.
  * <p>
  * Note that the thread will also be in the 'interrupted' state.
- * </p>
  */
 public class FileLockInterruptionException extends IOException {
 
     private static final long serialVersionUID = 7104080643653532383L;
 
     /**
-     * Default constructor.
+     * Constructs a {@code FileLockInterruptionException}.
      */
     public FileLockInterruptionException() {
         super();

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/GatheringByteChannel.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/GatheringByteChannel.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/GatheringByteChannel.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/GatheringByteChannel.java Mon Apr 27 10:23:36 2009
@@ -20,82 +20,75 @@
 import java.nio.ByteBuffer;
 
 /**
- * The interface to channels that can write a set of buffers in a single
- * operation.
- * <p>
- * The corresponding interface for reads is called
- * <code>ScatteringByteChannel</code>.
+ * The interface for channels that can write a set of buffers in a single
+ * operation. The corresponding interface for read operations is
+ * {@link ScatteringByteChannel}.
  */
 public interface GatheringByteChannel extends WritableByteChannel {
 
     /**
-     * Writes bytes from all the given buffers to the channel.
+     * Writes bytes from all the given buffers to a channel.
      * <p>
-     * This method is equivalent to:
-     * 
-     * <pre>
-     * write(buffers, 0, buffers.length);
-     * </pre>
-     * 
-     * </p>
-     * 
+     * This method is equivalent to: {@code write(buffers, 0, buffers.length);}
+     *
      * @param buffers
      *            the buffers containing bytes to be written.
      * @return the number of bytes actually written.
+     * @throws AsynchronousCloseException
+     *             if the 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 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 another I/O error occurs; details are in the message.
      * @throws NonWritableChannelException
-     *             if the channel is open, but not in a mode that permits
+     *             if the channel has not been opened in a mode that permits
      *             writing.
-     * @throws ClosedByInterruptException
-     *             if the thread is interrupted in its IO operation by another
-     *             thread closing the channel.
-     * @throws AsynchronousCloseException
-     *             if the write is interrupted by another thread sending an
-     *             explicit interrupt.
-     * @throws IOException
-     *             if some other type of exception occurs. Details are in the
-     *             message.
      */
     public long write(ByteBuffer[] buffers) 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>buffers[offset]</code>. The number of bytes actually written is
-     * returned.
-     * </p>
+     * Attempts to write all <code>remaining()</code> bytes from {@code length}
+     * byte buffers, in order, starting at {@code buffers[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>
-     * 
+     * the write is completed and then contend for the ability to write.
+     *
      * @param buffers
-     *            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 the 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.
+     *            the number of buffers to get bytes from.
      * @return the number of bytes actually written.
-     * @throws IndexOutOfBoundsException
-     *             if offset < 0 or > buffers.length; or length < 0 or >
-     *             buffers.length - offset.
-     * @throws NonWritableChannelException
-     *             if the channel was not opened for writing.
-     * @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 write
+     *             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 was not opened for writing.
      */
     public long write(ByteBuffer[] buffers, int offset, int length)
             throws IOException;

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/IllegalBlockingModeException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/IllegalBlockingModeException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/IllegalBlockingModeException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/IllegalBlockingModeException.java Mon Apr 27 10:23:36 2009
@@ -17,15 +17,16 @@
 package java.nio.channels;
 
 /**
- * Thrown when when operation that requires a specific blocking mode is invoked
- * on a channel that is in a different blocking mode.
+ * An {@code IllegalBlockingModeException} is thrown when an operation that
+ * requires a specific blocking mode is invoked on a channel that is in a
+ * different blocking mode.
  */
 public class IllegalBlockingModeException extends IllegalStateException {
 
     private static final long serialVersionUID = -3335774961855590474L;
 
     /**
-     * Default constructor.
+     * Constructs a {@code IllegalBlockingModeException}.
      */
     public IllegalBlockingModeException() {
         super();

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/IllegalSelectorException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/IllegalSelectorException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/IllegalSelectorException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/IllegalSelectorException.java Mon Apr 27 10:23:36 2009
@@ -17,15 +17,15 @@
 package java.nio.channels;
 
 /**
- * Thrown when a call is made to register a channel on a selector that has been
- * created by a different provider.
+ * An {@code IllegalSelectorException} is thrown when a call is made to register
+ * a channel on a selector that has been created by a different provider.
  */
 public class IllegalSelectorException extends IllegalArgumentException {
 
     private static final long serialVersionUID = -8406323347253320987L;
 
     /**
-     * Default constructor.
+     * Constructs a {@code IllegalSelectorException}.
      */
     public IllegalSelectorException() {
         super();

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/InterruptibleChannel.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/InterruptibleChannel.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/InterruptibleChannel.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/InterruptibleChannel.java Mon Apr 27 10:23:36 2009
@@ -19,37 +19,33 @@
 import java.io.IOException;
 
 /**
- * Channels that implement this interface are both asynchronously closable and
- * interruptible.
+ * Channels that implement this interface can be asynchronously closed and
+ * interrupted.
  * <p>
- * A channel that is asynchronously closable permits a thread blocked on an IO
- * operation (the IO thread) to be released by another thread calling the
- * channel's <code>close()</code> method. The IO thread will throw an
- * <code>AsynchronousCloseException</code> and the channel will be closed.
- * </p>
+ * A channel that can be asynchronously closed permits that a thread blocked on
+ * an I/O operation (the I/O thread) can be released by another thread calling
+ * the channel's {@link #close()} method. The I/O thread will throw an
+ * {@link AsynchronousCloseException} and the channel will be closed.
  * <p>
- * A channel that is interruptible permits a thread blocked on an IO operation
- * (the IO thread) to be interrupted by another thread (by invoking
- * <code>interrupt()</code> on the IO thread). When the IO thread is
- * interrupted it will throw a <code>ClosedByInterruptException</code>
- * exception, it will have its interrupted status set, and the channel will be
- * closed. If the IO thread attempts to make an IO call with the interrupt
- * status set the call will immediately fail with a
- * <code>ClosedByInterruptException</code>.
+ * A channel that is interruptible permits a thread blocked on an I/O operation
+ * (the I/O thread) to be interrupted by another thread (by invoking
+ * {@link Thread#interrupt()} on the I/O thread). When the I/O thread is
+ * interrupted it will throw a {@link ClosedByInterruptException}, it will have
+ * its interrupted status set and the channel will be closed. If the I/O thread
+ * attempts to make an I/O call with the interrupt status set the call will
+ * immediately fail with a {@link ClosedByInterruptException}.
  */
 public interface InterruptibleChannel extends Channel {
 
     /**
-     * Closes an InterruptibleChannel. This method is precisely the same as the
-     * super-interface <code>close()</code>.
+     * Closes the channel.
      * <p>
-     * Any threads that are blocked on IO operations on this channel will be
-     * interrupted with an <code>AsynchronousCloseException
-     * </code>.
-     * </p>
+     * Any threads that are blocked on I/O operations on this channel will be
+     * interrupted with an {@link AsynchronousCloseException}. Otherwise, this
+     * method behaves the same as defined in the {@code Channel} interface.
      * 
      * @throws IOException
-     *             if an IO problem occurs closing the channel.
+     *             if an I/O error occurs while closing the channel.
      */
     public void close() throws IOException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NoConnectionPendingException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NoConnectionPendingException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NoConnectionPendingException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NoConnectionPendingException.java Mon Apr 27 10:23:36 2009
@@ -17,15 +17,18 @@
 package java.nio.channels;
 
 /**
- * Thrown if SocketChannel's finishConnect method is called before the
- * SocketChannel's connect method completed without error.
+ * A {@code NoConnectionPendingException} is thrown if {@code SocketChannel}'s
+ * {@link SocketChannel#finishConnect() finishConnect} method is called before
+ * the {@code SocketChannel}'s {@link
+ * SocketChannel#connect(java.net.SocketAddress)} connect} method completed
+ * without error.
  */
 public class NoConnectionPendingException extends IllegalStateException {
 
     private static final long serialVersionUID = -8296561183633134743L;
 
     /**
-     * Default constructor.
+     * Constructs a {@code NoConnectionPendingException}.
      */
     public NoConnectionPendingException() {
         super();

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NonReadableChannelException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NonReadableChannelException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NonReadableChannelException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NonReadableChannelException.java Mon Apr 27 10:23:36 2009
@@ -17,14 +17,15 @@
 package java.nio.channels;
 
 /**
- * Thrown when attempting to read from a channel that is not open for reading.
+ * A {@code NonReadableChannelException} is thrown when attempting to read from
+ * a channel that is not open for reading.
  */
 public class NonReadableChannelException extends IllegalStateException {
 
     private static final long serialVersionUID = -3200915679294993514L;
 
     /**
-     * Default constructor.
+     * Constructs a {@code NonReadableChannelException}.
      */
     public NonReadableChannelException() {
         super();

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NonWritableChannelException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NonWritableChannelException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NonWritableChannelException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NonWritableChannelException.java Mon Apr 27 10:23:36 2009
@@ -17,14 +17,15 @@
 package java.nio.channels;
 
 /**
- * Thrown when attempting to write to a channel that is not open for writing.
+ * A {@code NonWritableChannelException} is thrown when attempting to write to a
+ * channel that is not open for writing.
  */
 public class NonWritableChannelException extends IllegalStateException {
 
     private static final long serialVersionUID = -7071230488279011621L;
 
     /**
-     * Default constructor.
+     * Constructs a {@code NonWritableChannelException}.
      */
     public NonWritableChannelException() {
         super();

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NotYetBoundException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NotYetBoundException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NotYetBoundException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NotYetBoundException.java Mon Apr 27 10:23:36 2009
@@ -17,15 +17,15 @@
 package java.nio.channels;
 
 /**
- * Thrown if the server socket channel is not bound before an IO operation is
- * made.
+ * A {@code NotYetBoundException} is thrown if the server socket channel is not
+ * bound before an I/O operation is made.
  */
 public class NotYetBoundException extends IllegalStateException {
 
     private static final long serialVersionUID = 4640999303950202242L;
 
     /**
-     * Default constructor.
+     * Constructs a {@code NotYetBoundException}.
      */
     public NotYetBoundException() {
         super();

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NotYetConnectedException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NotYetConnectedException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NotYetConnectedException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NotYetConnectedException.java Mon Apr 27 10:23:36 2009
@@ -17,15 +17,15 @@
 package java.nio.channels;
 
 /**
- * Thrown if the socket channel is not connected before an IO operation is
- * invoked.
+ * A {@code NotYetConnectedException} is thrown if the socket channel is not
+ * connected before an I/O operation is invoked.
  */
 public class NotYetConnectedException extends IllegalStateException {
 
     private static final long serialVersionUID = 4697316551909513464L;
 
     /**
-     * Default constructor.
+     * Constructs a {@code NotYetConnectedException}.
      */
     public NotYetConnectedException() {
         super();

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/OverlappingFileLockException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/OverlappingFileLockException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/OverlappingFileLockException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/OverlappingFileLockException.java Mon Apr 27 10:23:36 2009
@@ -17,15 +17,15 @@
 package java.nio.channels;
 
 /**
- * Thrown when attempting to acquire a lock that overlaps an existing or pending
- * lock held by this process.
+ * An {@code OverlappingFileLockException} is thrown when attempting to acquire
+ * a lock that overlaps an existing or pending lock held by this process.
  */
 public class OverlappingFileLockException extends IllegalStateException {
 
     private static final long serialVersionUID = 2047812138163068433L;
 
     /**
-     * Default constructor.
+     * Constructs a {@code OverlappingFileLockException}.
      */
     public OverlappingFileLockException() {
         super();

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Pipe.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Pipe.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Pipe.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Pipe.java Mon Apr 27 10:23:36 2009
@@ -21,32 +21,33 @@
 import java.nio.channels.spi.SelectorProvider;
 
 /**
- * A pipe contains two channels. One is the writable sink channel and the other is
- * readable source channel. When bytes are written into the writable channel they
- * can be read from readable channel. The order of these bytes remains unchanged. 
+ * A pipe contains two channels. One is the writable sink channel and the other
+ * is the readable source channel. When bytes are written into the writable
+ * channel they can be read from the readable channel. The order of these bytes
+ * remains unchanged.
  */
 public abstract class Pipe {
 
     /**
-     * Writable sink channel for writing into.
+     * Writable sink channel used to write to a pipe.
      */
     public static abstract class SinkChannel extends AbstractSelectableChannel
             implements WritableByteChannel, GatheringByteChannel {
         
         /**
-         * The Constructor.
+         * Constructs a new {@code SinkChannel}.
          * 
          * @param provider
-         *            the provider of the channel
+         *            the provider of the channel.
          */
         protected SinkChannel(SelectorProvider provider) {
             super(provider);
         }
 
         /**
-         * Indicates this channel supports only writing.
+         * Indicates that this channel only supports writing.
          * 
-         * @return a static value of OP_WRITE
+         * @return a static value of OP_WRITE.
          */
         @Override
         public final int validOps() {
@@ -55,26 +56,26 @@
     }
 
     /**
-     * Readable source channel for reading from.
+     * Readable source channel used to read from a pipe.
      */
     public static abstract class SourceChannel extends
             AbstractSelectableChannel implements ReadableByteChannel,
             ScatteringByteChannel {
         
         /**
-         * The Constructor.
+         * Constructs a new {@code SourceChannel}.
          * 
          * @param provider
-         *            the provider of the channel
+         *            the provider of the channel.
          */
         protected SourceChannel(SelectorProvider provider) {
             super(provider);
         }
 
         /**
-         * Indicates this channel supports only reading.
+         * Indicates that this channel only supports reading.
          * 
-         * @return a static value of OP_READ
+         * @return a static value of OP_READ.
          */
         @Override
         public final int validOps() {
@@ -86,17 +87,17 @@
     /**
      * Initializes a pipe.
      * 
-     * @return a new instance of pipe
+     * @return a new instance of pipe.
      * 
      * @throws IOException
-     *             if I/O error occurs
+     *             if an I/O error occurs.
      */
     public static Pipe open() throws IOException {
         return SelectorProvider.provider().openPipe();
     }
 
     /**
-     * The protected constructor.
+     * The protected default constructor.
      */
     protected Pipe() {
         super();
@@ -105,14 +106,14 @@
     /**
      * Returns the sink channel of the pipe.
      * 
-     * @return a writable sink channel of the pipe
+     * @return a writable sink channel of the pipe.
      */
     public abstract SinkChannel sink();
 
     /**
      * Returns the source channel of the pipe.
      * 
-     * @return a readable source channel of the pipe
+     * @return a readable source channel of the pipe.
      */
     public abstract SourceChannel source();
 

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ReadableByteChannel.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ReadableByteChannel.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ReadableByteChannel.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ReadableByteChannel.java Mon Apr 27 10:23:36 2009
@@ -20,11 +20,13 @@
 import java.nio.ByteBuffer;
 
 /**
- * A ReadableByteChannel is a type of Channel that can read bytes.
+ * A {@code ReadableByteChannel} is a type of {@link Channel} that can read
+ * bytes.
  * <p>
- * Reads are synchronous on a ReadableByteChannel, that is, if a read is already
- * in progress on the channel then subsequent reads will block until the first
- * read completes. It is undefined whether non-read operations will block.
+ * Read operations are synchronous on a {@code ReadableByteChannel}, that is,
+ * if a read is already in progress on the channel then subsequent reads will
+ * block until the first read completes. It is undefined whether non-read
+ * operations will block.
  */
 public interface ReadableByteChannel extends Channel {
 
@@ -32,34 +34,33 @@
      * Reads bytes from the 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>
+     * {@link java.nio.Buffer#remaining() remaining} number of bytes in the
+     * buffer when the method is invoked. The bytes will be read into the buffer
+     * starting at the buffer's current
+     * {@link java.nio.Buffer#position() position}.
      * <p>
-     * The call may block if other threads are also attempting to read on the
+     * The call may block if other threads are also attempting to read from 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>
-     * 
+     * Upon completion, the buffer's {@code position} is updated to the end of
+     * the bytes that were read. The buffer's
+     * {@link java.nio.Buffer#limit() limit} is not changed.
+     *
      * @param buffer
      *            the byte buffer to receive the bytes.
      * @return the number of bytes actually read.
-     * @throws NonReadableChannelException
-     *             if the channel was not opened for reading.
-     * @throws ClosedChannelException
-     *             if the channel was already closed.
      * @throws AsynchronousCloseException
      *             if another thread closes the channel during the read.
      * @throws ClosedByInterruptException
-     *             if another thread interrupt the calling thread during the
-     *             read.
+     *             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 IOException
-     *             another IO exception occurs, details are in the message.
+     *             another I/O error occurs, details are in the message.
+     * @throws NonReadableChannelException
+     *             if the channel was not opened for reading.
      */
     public int read(ByteBuffer buffer) throws IOException;
 }



Mime
View raw message