Note that this exception may be used when undefined type variables * are accessed as well as when types (e.g., classes, interfaces or * annotation types) are loaded. + * In particular, this exception can be thrown by the {@linkplain + * java.lang.reflect.AnnotatedElement API used to read annotations + * reflectively}. * * @author Josh Bloch + * @see java.lang.reflect.AnnotatedElement * @since 1.5 */ public class TypeNotPresentException extends RuntimeException { diff --git a/src/share/classes/java/lang/annotation/AnnotationFormatError.java b/src/share/classes/java/lang/annotation/AnnotationFormatError.java index 0bc2fd15169b94f52bffebed8a01a8800d5baf10..0263907cdba4f906752a28df59de911dd984941d 100644 --- a/src/share/classes/java/lang/annotation/AnnotationFormatError.java +++ b/src/share/classes/java/lang/annotation/AnnotationFormatError.java @@ -28,8 +28,12 @@ package java.lang.annotation; /** * Thrown when the annotation parser attempts to read an annotation * from a class file and determines that the annotation is malformed. + * This error can be thrown by the {@linkplain + * java.lang.reflect.AnnotatedElement API used to read annotations + * reflectively}. * * @author Josh Bloch + * @see java.lang.reflect.AnnotatedElement * @since 1.5 */ public class AnnotationFormatError extends Error { diff --git a/src/share/classes/java/lang/annotation/AnnotationTypeMismatchException.java b/src/share/classes/java/lang/annotation/AnnotationTypeMismatchException.java index c4cb7534c310f8ee025f853820e857df707eaa73..830b1f98dfe2ad2f9741b860e96f9a4973ced298 100644 --- a/src/share/classes/java/lang/annotation/AnnotationTypeMismatchException.java +++ b/src/share/classes/java/lang/annotation/AnnotationTypeMismatchException.java @@ -30,8 +30,12 @@ import java.lang.reflect.Method; * Thrown to indicate that a program has attempted to access an element of * an annotation whose type has changed after the annotation was compiled * (or serialized). + * This exception can be thrown by the {@linkplain + * java.lang.reflect.AnnotatedElement API used to read annotations + * reflectively}. * * @author Josh Bloch + * @see java.lang.reflect.AnnotatedElement * @since 1.5 */ public class AnnotationTypeMismatchException extends RuntimeException { diff --git a/src/share/classes/java/lang/annotation/IncompleteAnnotationException.java b/src/share/classes/java/lang/annotation/IncompleteAnnotationException.java index 04070a1bbd4a2700522a9834ab04e45b6e187317..9d5f43e1ad61503fd28b5f0447161c00ee0d5544 100644 --- a/src/share/classes/java/lang/annotation/IncompleteAnnotationException.java +++ b/src/share/classes/java/lang/annotation/IncompleteAnnotationException.java @@ -30,8 +30,12 @@ package java.lang.annotation; * an annotation type that was added to the annotation type definition after * the annotation was compiled (or serialized). This exception will not be * thrown if the new element has a default value. + * This exception can be thrown by the {@linkplain + * java.lang.reflect.AnnotatedElement API used to read annotations + * reflectively}. * * @author Josh Bloch + * @see java.lang.reflect.AnnotatedElement * @since 1.5 */ public class IncompleteAnnotationException extends RuntimeException { diff --git a/src/share/classes/java/lang/reflect/AnnotatedElement.java b/src/share/classes/java/lang/reflect/AnnotatedElement.java index 41436d63c0e21a8561fa5b3a4a96aa4b86652f00..0601168a0a064741c976b02a8d9c1e0799a55408 100644 --- a/src/share/classes/java/lang/reflect/AnnotatedElement.java +++ b/src/share/classes/java/lang/reflect/AnnotatedElement.java @@ -50,6 +50,11 @@ import java.lang.annotation.Annotation; * java.lang.annotation.AnnotationTypeMismatchException} or an * {@link java.lang.annotation.IncompleteAnnotationException}. * + * @see java.lang.EnumConstantNotPresentException + * @see java.lang.TypeNotPresentException + * @see java.lang.annotation.AnnotationFormatError + * @see java.lang.annotation.AnnotationTypeMismatchException + * @see java.lang.annotation.IncompleteAnnotationException * @since 1.5 * @author Josh Bloch */ diff --git a/src/share/classes/java/nio/channels/AsynchronousByteChannel.java b/src/share/classes/java/nio/channels/AsynchronousByteChannel.java index 7bc433574792ff82b734dbaf44f68e61f8b9bedd..2b2c8226d4f138cdb7e1aa05236d688a7f9dd7fc 100644 --- a/src/share/classes/java/nio/channels/AsynchronousByteChannel.java +++ b/src/share/classes/java/nio/channels/AsynchronousByteChannel.java @@ -56,18 +56,18 @@ public interface AsynchronousByteChannel /** * Reads a sequence of bytes from this channel into the given buffer. * - *
This method initiates an operation to read a sequence of bytes from - * this channel into the given buffer. The method returns a {@link Future} - * representing the pending result of the operation. The result of the - * operation, obtained by invoking the {@code Future} 's {@link - * Future#get() get} method, is the number of bytes read or {@code -1} if - * all bytes have been read and the channel has reached end-of-stream. - * - *
This method initiates a read operation to read up to r bytes - * from the channel, where r is the number of bytes remaining in the - * buffer, that is, {@code dst.remaining()} at the time that the read is - * attempted. Where r is 0, the read operation completes immediately - * with a result of {@code 0} without initiating an I/O operation. + *
This method initiates an asynchronous read operation to read a + * sequence of bytes from this channel into the given buffer. The {@code + * handler} parameter is a completion handler that is invoked when the read + * operation completes (or fails). The result passed to the completion + * handler is the number of bytes read or {@code -1} if no bytes could be + * read because the channel has reached end-of-stream. + * + *
The read operation may read up to r bytes from the channel, + * where r is the number of bytes remaining in the buffer, that is, + * {@code dst.remaining()} at the time that the read is attempted. Where + * r is 0, the read operation completes immediately with a result of + * {@code 0} without initiating an I/O operation. * *
Suppose that a byte sequence of length n is read, where * 0 < n <= r. @@ -79,44 +79,46 @@ public interface AsynchronousByteChannel * p + n; its limit will not have changed. * *
Buffers are not safe for use by multiple concurrent threads so care - * should be taken to not to access the buffer until the operaton has completed. + * should be taken to not access the buffer until the operation has + * completed. * *
This method may be invoked at any time. Some channel types may not * allow more than one read to be outstanding at any given time. If a thread * initiates a read operation before a previous read operation has * completed then a {@link ReadPendingException} will be thrown. * - *
The handler parameter is used to specify a {@link
- * CompletionHandler}. When the read operation completes the handler's
- * {@link CompletionHandler#completed completed} method is executed.
- *
- *
* @param dst
* The buffer into which bytes are to be transferred
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
- * The completion handler object; can be {@code null}
- *
- * @return A Future representing the result of the operation
+ * The completion handler
*
* @throws IllegalArgumentException
* If the buffer is read-only
* @throws ReadPendingException
* If the channel does not allow more than one read to be outstanding
* and a previous read has not completed
+ * @throws ShutdownChannelGroupException
+ * If the channel is associated with a {@link AsynchronousChannelGroup
+ * group} that has terminated
*/
- Future An invocation of this method of the form c.read(dst)
- * behaves in exactly the same manner as the invocation
- * This method initiates an asynchronous read operation to read a
+ * sequence of bytes from this channel into the given buffer. The method
+ * behaves in exactly the same manner as the {@link
+ * #read(ByteBuffer,Object,CompletionHandler)
+ * read(ByteBuffer,Object,CompletionHandler)} method except that instead
+ * of specifying a completion handler, this method returns a {@code Future}
+ * representing the pending result. The {@code Future}'s {@link Future#get()
+ * get} method returns the number of bytes read or {@code -1} if no bytes
+ * could be read because the channel has reached end-of-stream.
*
* @param dst
* The buffer into which bytes are to be transferred
@@ -134,17 +136,17 @@ public interface AsynchronousByteChannel
/**
* Writes a sequence of bytes to this channel from the given buffer.
*
- * This method initiates an operation to write a sequence of bytes to
- * this channel from the given buffer. This method returns a {@link
- * Future} representing the pending result of the operation. The result
- * of the operation, obtained by invoking the Future's {@link
- * Future#get() get} method, is the number of bytes written, possibly zero.
+ * This method initiates an asynchronous write operation to write a
+ * sequence of bytes to this channel from the given buffer. The {@code
+ * handler} parameter is a completion handler that is invoked when the write
+ * operation completes (or fails). The result passed to the completion
+ * handler is the number of bytes written.
*
- * This method initiates a write operation to write up to r bytes
- * to the channel, where r is the number of bytes remaining in the
- * buffer, that is, {@code src.remaining()} at the moment the write is
- * attempted. Where r is 0, the write operation completes immediately
- * with a result of {@code 0} without initiating an I/O operation.
+ * The write operation may write up to r bytes to the channel,
+ * where r is the number of bytes remaining in the buffer, that is,
+ * {@code src.remaining()} at the time that the write is attempted. Where
+ * r is 0, the write operation completes immediately with a result of
+ * {@code 0} without initiating an I/O operation.
*
* Suppose that a byte sequence of length n is written, where
* 0 < n <= r.
@@ -156,41 +158,43 @@ public interface AsynchronousByteChannel
* p + n; its limit will not have changed.
*
* Buffers are not safe for use by multiple concurrent threads so care
- * should be taken to not to access the buffer until the operaton has completed.
+ * should be taken to not access the buffer until the operation has
+ * completed.
*
* This method may be invoked at any time. Some channel types may not
* allow more than one write to be outstanding at any given time. If a thread
* initiates a write operation before a previous write operation has
* completed then a {@link WritePendingException} will be thrown.
*
- * The handler parameter is used to specify a {@link
- * CompletionHandler}. When the write operation completes the handler's
- * {@link CompletionHandler#completed completed} method is executed.
- *
* @param src
* The buffer from which bytes are to be retrieved
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
- * The completion handler object; can be {@code null}
- *
- * @return A Future representing the result of the operation
+ * The completion handler object
*
* @throws WritePendingException
* If the channel does not allow more than one write to be outstanding
* and a previous write has not completed
+ * @throws ShutdownChannelGroupException
+ * If the channel is associated with a {@link AsynchronousChannelGroup
+ * group} that has terminated
*/
- Future An invocation of this method of the form c.write(src)
- * behaves in exactly the same manner as the invocation
- * This method initiates an asynchronous write operation to write a
+ * sequence of bytes to this channel from the given buffer. The method
+ * behaves in exactly the same manner as the {@link
+ * #write(ByteBuffer,Object,CompletionHandler)
+ * write(ByteBuffer,Object,CompletionHandler)} method except that instead
+ * of specifying a completion handler, this method returns a {@code Future}
+ * representing the pending result. The {@code Future}'s {@link Future#get()
+ * get} method returns the number of bytes written.
*
* @param src
* The buffer from which bytes are to be retrieved
diff --git a/src/share/classes/java/nio/channels/AsynchronousChannel.java b/src/share/classes/java/nio/channels/AsynchronousChannel.java
index f3e4ffe4ea5ac488b3ed76c0417c64523f058133..69ee8bd65d7cf18da2674d1b34b654b34590d45a 100644
--- a/src/share/classes/java/nio/channels/AsynchronousChannel.java
+++ b/src/share/classes/java/nio/channels/AsynchronousChannel.java
@@ -34,7 +34,8 @@ import java.util.concurrent.Future; // javadoc
*
* A channel that implements this interface is asynchronously
* closeable: If an I/O operation is outstanding on the channel and the
@@ -63,33 +64,33 @@ import java.util.concurrent.Future; // javadoc
* The {@code Future} interface defines the {@link Future#cancel cancel}
- * method to cancel execution of a task.
- *
- * Where the {@code cancel} method is invoked with the {@code
+ * method to cancel execution. This causes all threads waiting on the result of
+ * the I/O operation to throw {@link java.util.concurrent.CancellationException}.
+ * Whether the underlying I/O operation can be cancelled is highly implementation
+ * specific and therefore not specified. Where cancellation leaves the channel,
+ * or the entity to which it is connected, in an inconsistent state, then the
+ * channel is put into an implementation specific error state that
+ * prevents further attempts to initiate I/O operations that are similar
+ * to the operation that was cancelled. For example, if a read operation is
+ * cancelled but the implementation cannot guarantee that bytes have not been
+ * read from the channel then it puts the channel into an error state; further
+ * attempts to initiate a {@code read} operation cause an unspecified runtime
+ * exception to be thrown. Similarly, if a write operation is cancelled but the
+ * implementation cannot guarantee that bytes have not been written to the
+ * channel then subsequent attempts to initiate a {@code write} will fail with
+ * an unspecified runtime exception.
+ *
+ * Where the {@link Future#cancel cancel} method is invoked with the {@code
* mayInterruptIfRunning} parameter set to {@code true} then the I/O operation
- * may be interrupted by closing the channel. This will cause any other I/O
- * operations outstanding on the channel to complete with the exception {@link
- * AsynchronousCloseException}.
- *
- * If a {@code CompletionHandler} is specified when initiating an I/O
- * operation, and the {@code cancel} method is invoked to cancel the I/O
- * operation before it completes, then the {@code CompletionHandler}'s {@link
- * CompletionHandler#cancelled cancelled} method is invoked.
- *
- * If an implementation of this interface supports a means to cancel I/O
- * operations, and where cancellation may leave the channel, or the entity to
- * which it is connected, in an inconsistent state, then the channel is put into
- * an implementation specific error state that prevents further
- * attempts to initiate I/O operations on the channel. For example, if a read
- * operation is cancelled but the implementation cannot guarantee that bytes
- * have not been read from the channel then it puts the channel into error state
- * state; further attempts to initiate a {@code read} operation causes an
- * unspecified runtime exception to be thrown.
+ * may be interrupted by closing the channel. In that case all threads waiting
+ * on the result of the I/O operation throw {@code CancellationException} and
+ * any other I/O operations outstanding on the channel complete with the
+ * exception {@link AsynchronousCloseException}.
*
* Where the {@code cancel} method is invoked to cancel read or write
- * operations then it recommended that all buffers used in the I/O operations be
- * discarded or care taken to ensure that the buffers are not accessed while the
- * channel remains open.
+ * operations then it is recommended that all buffers used in the I/O operations
+ * be discarded or care taken to ensure that the buffers are not accessed while
+ * the channel remains open.
*
* @since 1.7
*/
@@ -102,7 +103,7 @@ public interface AsynchronousChannel
*
* Any outstanding asynchronous operations upon this channel will
* complete with the exception {@link AsynchronousCloseException}. After a
- * channel is closed then further attempts to initiate asynchronous I/O
+ * channel is closed, further attempts to initiate asynchronous I/O
* operations complete immediately with cause {@link ClosedChannelException}.
*
* This method otherwise behaves exactly as specified by the {@link
diff --git a/src/share/classes/java/nio/channels/AsynchronousDatagramChannel.java b/src/share/classes/java/nio/channels/AsynchronousDatagramChannel.java
index 65b90d0f29d4ce611f31b34dedd6f5e60c55a70d..a229ce627376d8de83af6a7d5fb1870a9ccd7567 100644
--- a/src/share/classes/java/nio/channels/AsynchronousDatagramChannel.java
+++ b/src/share/classes/java/nio/channels/AsynchronousDatagramChannel.java
@@ -109,19 +109,13 @@ import java.nio.ByteBuffer;
* // print the source address of all packets that we receive
* dc.receive(buffer, buffer, new CompletionHandler<SocketAddress,ByteBuffer>() {
* public void completed(SocketAddress sa, ByteBuffer buffer) {
- * try {
- * System.out.println(sa);
- *
- * buffer.clear();
- * dc.receive(buffer, buffer, this);
- * } catch (...) { ... }
+ * System.out.println(sa);
+ * buffer.clear();
+ * dc.receive(buffer, buffer, this);
* }
* public void failed(Throwable exc, ByteBuffer buffer) {
* ...
* }
- * public void cancelled(ByteBuffer buffer) {
- * ...
- * }
* });
*
*
@@ -314,10 +308,10 @@ public abstract class AsynchronousDatagramChannel
/**
* Receives a datagram via this channel.
*
- * This method initiates the receiving of a datagram, returning a
- * {@code Future} representing the pending result of the operation.
- * The {@code Future}'s {@link Future#get() get} method returns
- * the source address of the datagram upon successful completion.
+ * This method initiates the receiving of a datagram into the given
+ * buffer. The {@code handler} parameter is a completion handler that is
+ * invoked when the receive operation completes (or fails). The result
+ * passed to the completion handler is the datagram's source address.
*
* The datagram is transferred into the given byte buffer starting at
* its current position, as if by a regular {@link AsynchronousByteChannel#read
@@ -350,28 +344,26 @@ public abstract class AsynchronousDatagramChannel
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
- * The handler for consuming the result; can be {@code null}
- *
- * @return a {@code Future} object representing the pending result
+ * The handler for consuming the result
*
* @throws IllegalArgumentException
* If the timeout is negative or the buffer is read-only
* @throws ShutdownChannelGroupException
- * If a handler is specified, and the channel group is shutdown
+ * If the channel group has terminated
*/
- public abstract Future This method initiates the receiving of a datagram, returning a
- * {@code Future} representing the pending result of the operation.
- * The {@code Future}'s {@link Future#get() get} method returns
- * the source address of the datagram upon successful completion.
+ * This method initiates the receiving of a datagram into the given
+ * buffer. The {@code handler} parameter is a completion handler that is
+ * invoked when the receive operation completes (or fails). The result
+ * passed to the completion handler is the datagram's source address.
*
* This method is equivalent to invoking {@link
* #receive(ByteBuffer,long,TimeUnit,Object,CompletionHandler)} with a
@@ -382,34 +374,30 @@ public abstract class AsynchronousDatagramChannel
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
- * The handler for consuming the result; can be {@code null}
- *
- * @return a {@code Future} object representing the pending result
+ * The handler for consuming the result
*
* @throws IllegalArgumentException
* If the buffer is read-only
* @throws ShutdownChannelGroupException
- * If a handler is specified, and the channel group is shutdown
+ * If the channel group has terminated
*/
- public final Future This method initiates the receiving of a datagram, returning a
- * {@code Future} representing the pending result of the operation.
- * The {@code Future}'s {@link Future#get() get} method returns
- * the source address of the datagram upon successful completion.
- *
- * This method is equivalent to invoking {@link
- * #receive(ByteBuffer,long,TimeUnit,Object,CompletionHandler)} with a
- * timeout of {@code 0L}, and an attachment and completion handler
- * of {@code null}.
+ * This method initiates the receiving of a datagram into the given
+ * buffer. The method behaves in exactly the same manner as the {@link
+ * #receive(ByteBuffer,Object,CompletionHandler)
+ * receive(ByteBuffer,Object,CompletionHandler)} method except that instead
+ * of specifying a completion handler, this method returns a {@code Future}
+ * representing the pending result. The {@code Future}'s {@link Future#get()
+ * get} method returns the datagram's source address.
*
* @param dst
* The buffer into which the datagram is to be transferred
@@ -419,95 +407,28 @@ public abstract class AsynchronousDatagramChannel
* @throws IllegalArgumentException
* If the buffer is read-only
*/
- public final Future This method initiates sending of a datagram, returning a
- * {@code Future} representing the pending result of the operation.
- * The operation sends the remaining bytes in the given buffer as a single
- * datagram to the given target address. The result of the operation, obtained
- * by invoking the {@code Future}'s {@link Future#get() get}
- * method, is the number of bytes sent.
- *
- * The datagram is transferred from the byte buffer as if by a regular
- * {@link AsynchronousByteChannel#write write} operation.
+ * This method initiates sending of a datagram from the given buffer to
+ * the given address. The {@code handler} parameter is a completion handler
+ * that is invoked when the send completes (or fails). The result passed to
+ * the completion handler is the number of bytes sent.
*
- * If a timeout is specified and the timeout elapses before the operation
- * completes then the operation completes with the exception {@link
- * InterruptedByTimeoutException}. When a timeout elapses then the state of
- * the {@link ByteBuffer} is not defined. The buffers should be discarded or
- * at least care must be taken to ensure that the buffer is not accessed
- * while the channel remains open.
- *
- * If there is a security manager installed and the channel is not
- * connected then this method verifies that the target address and port number
- * are permitted by the security manager's {@link SecurityManager#checkConnect
- * checkConnect} method. The overhead of this security check can be avoided
- * by first connecting the socket via the {@link #connect connect} method.
+ * Otherwise this method works in the same manner as the {@link
+ * AsynchronousByteChannel#write(ByteBuffer,Object,CompletionHandler)}
+ * method.
*
* @param src
* The buffer containing the datagram to be sent
* @param target
* The address to which the datagram is to be sent
- * @param timeout
- * The timeout, or {@code 0L} for no timeout
- * @param unit
- * The time unit of the {@code timeout} argument
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
- * The handler for consuming the result; can be {@code null}
- *
- * @return a {@code Future} object representing the pending result
- *
- * @throws UnresolvedAddressException
- * If the given remote address is not fully resolved
- * @throws UnsupportedAddressTypeException
- * If the type of the given remote address is not supported
- * @throws IllegalArgumentException
- * If the timeout is negative, or if the channel's socket is
- * connected to an address that is not equal to {@code target}
- * @throws SecurityException
- * If a security manager has been installed and it does not permit
- * datagrams to be sent to the given address
- * @throws ShutdownChannelGroupException
- * If a handler is specified, and the channel group is shutdown
- */
- public abstract Future This method initiates sending of a datagram, returning a
- * {@code Future} representing the pending result of the operation.
- * The operation sends the remaining bytes in the given buffer as a single
- * datagram to the given target address. The result of the operation, obtained
- * by invoking the {@code Future}'s {@link Future#get() get}
- * method, is the number of bytes sent.
- *
- * This method is equivalent to invoking {@link
- * #send(ByteBuffer,SocketAddress,long,TimeUnit,Object,CompletionHandler)}
- * with a timeout of {@code 0L}.
- *
- * @param src
- * The buffer containing the datagram to be sent
- * @param target
- * The address to which the datagram is to be sent
- * @param attachment
- * The object to attach to the I/O operation; can be {@code null}
- * @param handler
- * The handler for consuming the result; can be {@code null}
- *
- * @return a {@code Future} object representing the pending result
+ * The handler for consuming the result
*
* @throws UnresolvedAddressException
* If the given remote address is not fully resolved
@@ -520,30 +441,23 @@ public abstract class AsynchronousDatagramChannel
* If a security manager has been installed and it does not permit
* datagrams to be sent to the given address
* @throws ShutdownChannelGroupException
- * If a handler is specified, and the channel group is shutdown
+ * If the channel group has terminated
*/
- public final Future This method initiates sending of a datagram, returning a
- * {@code Future} representing the pending result of the operation.
- * The operation sends the remaining bytes in the given buffer as a single
- * datagram to the given target address. The result of the operation, obtained
- * by invoking the {@code Future}'s {@link Future#get() get}
- * method, is the number of bytes sent.
- *
- * This method is equivalent to invoking {@link
- * #send(ByteBuffer,SocketAddress,long,TimeUnit,Object,CompletionHandler)}
- * with a timeout of {@code 0L} and an attachment and completion handler
- * of {@code null}.
+ * This method initiates sending of a datagram from the given buffer to
+ * the given address. The method behaves in exactly the same manner as the
+ * {@link #send(ByteBuffer,SocketAddress,Object,CompletionHandler)
+ * send(ByteBuffer,SocketAddress,Object,CompletionHandler)} method except
+ * that instead of specifying a completion handler, this method returns a
+ * {@code Future} representing the pending result. The {@code Future}'s
+ * {@link Future#get() get} method returns the number of bytes sent.
*
* @param src
* The buffer containing the datagram to be sent
@@ -563,17 +477,15 @@ public abstract class AsynchronousDatagramChannel
* If a security manager has been installed and it does not permit
* datagrams to be sent to the given address
*/
- public final Future This method initiates the receiving of a datagram, returning a
- * {@code Future} representing the pending result of the operation.
- * The {@code Future}'s {@link Future#get() get} method returns
- * the number of bytes transferred upon successful completion.
+ * This method initiates the receiving of a datagram into the given
+ * buffer. The {@code handler} parameter is a completion handler that is
+ * invoked when the receive operation completes (or fails). The result
+ * passed to the completion handler is number of bytes read.
*
* This method may only be invoked if this channel is connected, and it
* only accepts datagrams from the peer that the channel is connected too.
@@ -599,120 +511,62 @@ public abstract class AsynchronousDatagramChannel
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
- * The handler for consuming the result; can be {@code null}
- *
- * @return a {@code Future} object representing the pending result
+ * The handler for consuming the result
*
* @throws IllegalArgumentException
* If the timeout is negative or buffer is read-only
* @throws NotYetConnectedException
* If this channel is not connected
* @throws ShutdownChannelGroupException
- * If a handler is specified, and the channel group is shutdown
+ * If the channel group has terminated
*/
- public abstract Future This method initiates sending of a datagram, returning a
- * {@code Future} representing the pending result of the operation.
- * The operation sends the remaining bytes in the given buffer as a single
- * datagram. The result of the operation, obtained by invoking the
- * {@code Future}'s {@link Future#get() get} method, is the
- * number of bytes sent.
- *
- * The datagram is transferred from the byte buffer as if by a regular
- * {@link AsynchronousByteChannel#write write} operation.
- *
- * This method may only be invoked if this channel is connected,
- * in which case it sends datagrams directly to the socket's peer. Otherwise
- * it behaves exactly as specified in the {@link
- * AsynchronousByteChannel} interface.
- *
- * If a timeout is specified and the timeout elapses before the operation
- * completes then the operation completes with the exception {@link
- * InterruptedByTimeoutException}. When a timeout elapses then the state of
- * the {@link ByteBuffer} is not defined. The buffers should be discarded or
- * at least care must be taken to ensure that the buffer is not accessed
- * while the channel remains open.
- *
- * @param src
- * The buffer containing the datagram to be sent
- * @param timeout
- * The timeout, or {@code 0L} for no timeout
- * @param unit
- * The time unit of the {@code timeout} argument
- * @param attachment
- * The object to attach to the I/O operation; can be {@code null}
- * @param handler
- * The handler for consuming the result; can be {@code null}
- *
- * @return a {@code Future} object representing the pending result
- *
- * @throws IllegalArgumentException
- * If the timeout is negative
- * @throws NotYetConnectedException
- * If this channel is not connected
- * @throws ShutdownChannelGroupException
- * If a handler is specified, and the channel group is shutdown
- */
- public abstract Future An asynchronous file channel does not have a current position
* within the file. Instead, the file position is specified to each read and
- * write operation.
+ * write methd that initiate asynchronous operations. A {@link CompletionHandler}
+ * is specified as a parameter and is invoked to consume the result of the I/O
+ * operation. This class also defines read and write methods that initiate
+ * asynchronous operations, returning a {@link Future} to represent the pending
+ * result of the operation. The {@code Future} may be used to check if the
+ * operation has completed, to wait for its completion.
*
* In addition to read and write operations, this class defines the
* following operations: A region of a file may be {@link FileLock locked}
- * against access by other programs. A region of a file may be {@link #lock locked} against
+ * access by other programs. The {@link #read read}, {@link #write write}, and {@link #lock lock}
- * methods defined by this class are asynchronous and return a {@link Future}
- * to represent the pending result of the operation. This may be used to check
- * if the operation has completed, to wait for its completion, and to retrieve
- * the result. These method may optionally specify a {@link CompletionHandler}
- * that is invoked to consume the result of the I/O operation when it completes.
- *
* An {@code AsynchronousFileChannel} is associated with a thread pool to
* which tasks are submitted to handle I/O events and dispatch to completion
* handlers that consume the results of I/O operations on the channel. The
@@ -122,22 +120,6 @@ public abstract class AsynchronousFileChannel
protected AsynchronousFileChannel() {
}
- /**
- * Closes this channel.
- *
- * If this channel is associated with its own thread pool then closing
- * the channel causes the thread pool to shutdown after all actively
- * executing completion handlers have completed. No attempt is made to stop
- * or interrupt actively completion handlers.
- *
- * This method otherwise behaves exactly as specified by the {@link
- * AsynchronousChannel} interface.
- *
- * @throws IOException {@inheritDoc}
- */
- @Override
- public abstract void close() throws IOException;
-
/**
* Opens or creates a file for reading and/or writing, returning an
* asynchronous file channel to access the file.
@@ -215,9 +197,8 @@ public abstract class AsynchronousFileChannel
* should be taken when configuring the {@code Executor}. Minimally it
* should support an unbounded work queue and should not run tasks on the
* caller thread of the {@link ExecutorService#execute execute} method.
- * {@link #close Closing} the channel results in the orderly {@link
- * ExecutorService#shutdown shutdown} of the executor service. Shutting down
- * the executor service by other means results in unspecified behavior.
+ * Shutting down the executor service while the channel is open results in
+ * unspecified behavior.
*
* The {@code attrs} parameter is an optional array of file {@link
* FileAttribute file-attributes} to set atomically when creating the file.
@@ -276,7 +257,8 @@ public abstract class AsynchronousFileChannel
* An invocation of this method behaves in exactly the same way as the
* invocation
* This method initiates an operation to acquire a lock on the given region
- * of this channel's file. The method returns a {@code Future} representing
- * the pending result of the operation. Its {@link Future#get() get}
- * method returns the {@link FileLock} on successful completion.
+ * This method initiates an operation to acquire a lock on the given
+ * region of this channel's file. The {@code handler} parameter is a
+ * completion handler that is invoked when the lock is acquired (or the
+ * operation fails). The result passed to the completion handler is the
+ * resulting {@code FileLock}.
*
* The region specified by the {@code position} and {@code size}
* parameters need not be contained within, or even overlap, the actual
@@ -455,9 +438,7 @@ public abstract class AsynchronousFileChannel
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
- * The handler for consuming the result; can be {@code null}
- *
- * @return a {@code Future} object representing the pending result
+ * The handler for consuming the result
*
* @throws OverlappingFileLockException
* If a lock that overlaps the requested region is already held by
@@ -466,26 +447,24 @@ public abstract class AsynchronousFileChannel
* @throws IllegalArgumentException
* If the preconditions on the parameters do not hold
* @throws NonReadableChannelException
- * If {@code shared} is true this channel but was not opened for reading
+ * If {@code shared} is true but this channel was not opened for reading
* @throws NonWritableChannelException
* If {@code shared} is false but this channel was not opened for writing
- * @throws ShutdownChannelGroupException
- * If a handler is specified, the channel is closed, and the channel
- * was originally created with its own thread pool
*/
- public abstract Future This method initiates an operation to acquire an exclusive lock on this
- * channel's file. The method returns a {@code Future} representing
- * the pending result of the operation. Its {@link Future#get() get}
- * method returns the {@link FileLock} on successful completion.
+ * This method initiates an operation to acquire a lock on the given
+ * region of this channel's file. The {@code handler} parameter is a
+ * completion handler that is invoked when the lock is acquired (or the
+ * operation fails). The result passed to the completion handler is the
+ * resulting {@code FileLock}.
*
* An invocation of this method of the form {@code ch.lock(att,handler)}
* behaves in exactly the same way as the invocation
@@ -496,40 +475,72 @@ public abstract class AsynchronousFileChannel
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
- * The handler for consuming the result; can be {@code null}
- *
- * @return a {@code Future} object representing the pending result
+ * The handler for consuming the result
*
* @throws OverlappingFileLockException
* If a lock is already held by this Java virtual machine, or there
* is already a pending attempt to lock a region
* @throws NonWritableChannelException
* If this channel was not opened for writing
- * @throws ShutdownChannelGroupException
- * If a handler is specified, the channel is closed, and the channel
- * was originally created with its own thread pool
*/
- public final Future This method initiates an operation to acquire a lock on the given
+ * region of this channel's file. The method behaves in exactly the same
+ * manner as the {@link #lock(long, long, boolean, Object, CompletionHandler)}
+ * method except that instead of specifying a completion handler, this
+ * method returns a {@code Future} representing the pending result. The
+ * {@code Future}'s {@link Future#get() get} method returns the {@link
+ * FileLock} on successful completion.
+ *
+ * @param position
+ * The position at which the locked region is to start; must be
+ * non-negative
+ * @param size
+ * The size of the locked region; must be non-negative, and the sum
+ * {@code position} + {@code size} must be non-negative
+ * @param shared
+ * {@code true} to request a shared lock, in which case this
+ * channel must be open for reading (and possibly writing);
+ * {@code false} to request an exclusive lock, in which case this
+ * channel must be open for writing (and possibly reading)
+ *
+ * @return a {@code Future} object representing the pending result
+ *
+ * @throws OverlappingFileLockException
+ * If a lock is already held by this Java virtual machine, or there
+ * is already a pending attempt to lock a region
+ * @throws IllegalArgumentException
+ * If the preconditions on the parameters do not hold
+ * @throws NonReadableChannelException
+ * If {@code shared} is true but this channel was not opened for reading
+ * @throws NonWritableChannelException
+ * If {@code shared} is false but this channel was not opened for writing
+ */
+ public abstract Future This method initiates an operation to acquire an exclusive lock on this
* channel's file. The method returns a {@code Future} representing the
- * pending result of the operation. Its {@link Future#get() get} method
- * returns the {@link FileLock} on successful completion.
+ * pending result of the operation. The {@code Future}'s {@link Future#get()
+ * get} method returns the {@link FileLock} on successful completion.
*
* An invocation of this method behaves in exactly the same way as the
* invocation
* This method initiates the reading of a sequence of bytes from this
- * channel into the given buffer, starting at the given file position. This
- * method returns a {@code Future} representing the pending result of the
- * operation. The Future's {@link Future#get() get} method returns the
- * number of bytes read or {@code -1} if the given position is greater than
- * or equal to the file's size at the time that the read is attempted.
+ * channel into the given buffer, starting at the given file position. The
+ * result of the read is the number of bytes read or {@code -1} if the given
+ * position is greater than or equal to the file's size at the time that the
+ * read is attempted.
*
* This method works in the same manner as the {@link
* AsynchronousByteChannel#read(ByteBuffer,Object,CompletionHandler)}
@@ -649,22 +659,17 @@ public abstract class AsynchronousFileChannel
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
- * The handler for consuming the result; can be {@code null}
- *
- * @return A {@code Future} object representing the pending result
+ * The handler for consuming the result
*
* @throws IllegalArgumentException
* If the position is negative or the buffer is read-only
* @throws NonReadableChannelException
* If this channel was not opened for reading
- * @throws ShutdownChannelGroupException
- * If a handler is specified, the channel is closed, and the channel
- * was originally created with its own thread pool
*/
- public abstract Future This method initiates the reading of a sequence of bytes from this
* channel into the given buffer, starting at the given file position. This
* method returns a {@code Future} representing the pending result of the
- * operation. The Future's {@link Future#get() get} method returns the
- * number of bytes read or {@code -1} if the given position is greater
+ * operation. The {@code Future}'s {@link Future#get() get} method returns
+ * the number of bytes read or {@code -1} if the given position is greater
* than or equal to the file's size at the time that the read is attempted.
*
- * This method is equivalent to invoking {@link
- * #read(ByteBuffer,long,Object,CompletionHandler)} with the {@code attachment}
- * and handler parameters set to {@code null}.
+ * This method works in the same manner as the {@link
+ * AsynchronousByteChannel#read(ByteBuffer)} method, except that bytes are
+ * read starting at the given file position. If the given file position is
+ * greater than the file's size at the time that the read is attempted then
+ * no bytes are read.
*
* @param dst
* The buffer into which bytes are to be transferred
@@ -694,20 +701,12 @@ public abstract class AsynchronousFileChannel
* @throws NonReadableChannelException
* If this channel was not opened for reading
*/
- public final Future This method initiates the writing of a sequence of bytes to this channel
- * from the given buffer, starting at the given file position. The method
- * returns a {@code Future} representing the pending result of the write
- * operation. The Future's {@link Future#get() get} method returns the
- * number of bytes written.
- *
* This method works in the same manner as the {@link
* AsynchronousByteChannel#write(ByteBuffer,Object,CompletionHandler)}
* method, except that bytes are written starting at the given file position.
@@ -724,36 +723,35 @@ public abstract class AsynchronousFileChannel
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
- * The handler for consuming the result; can be {@code null}
- *
- * @return A {@code Future} object representing the pending result
+ * The handler for consuming the result
*
* @throws IllegalArgumentException
* If the position is negative
* @throws NonWritableChannelException
* If this channel was not opened for writing
- * @throws ShutdownChannelGroupException
- * If a handler is specified, the channel is closed, and the channel
- * was originally created with its own thread pool
*/
- public abstract Future This method initiates the writing of a sequence of bytes to this channel
- * from the given buffer, starting at the given file position. The method
- * returns a {@code Future} representing the pending result of the write
- * operation. The Future's {@link Future#get() get} method returns the
- * number of bytes written.
+ * This method initiates the writing of a sequence of bytes to this
+ * channel from the given buffer, starting at the given file position. The
+ * method returns a {@code Future} representing the pending result of the
+ * write operation. The {@code Future}'s {@link Future#get() get} method
+ * returns the number of bytes written.
*
- * This method is equivalent to invoking {@link
- * #write(ByteBuffer,long,Object,CompletionHandler)} with the {@code attachment}
- * and handler parameters set to {@code null}.
+ * This method works in the same manner as the {@link
+ * AsynchronousByteChannel#write(ByteBuffer)} method, except that bytes are
+ * written starting at the given file position. If the given position is
+ * greater than the file's size, at the time that the write is attempted,
+ * then the file will be grown to accommodate the new bytes; the values of
+ * any bytes between the previous end-of-file and the newly-written bytes
+ * are unspecified.
*
* @param src
* The buffer from which bytes are to be transferred
@@ -768,7 +766,5 @@ public abstract class AsynchronousFileChannel
* @throws NonWritableChannelException
* If this channel was not opened for writing
*/
- public final Future This method initiates accepting a connection made to this channel's
- * socket, returning a {@link Future} representing the pending result
- * of the operation. The {@code Future}'s {@link Future#get() get}
- * method will return the {@link AsynchronousSocketChannel} for the new
- * connection on successful completion.
+ * This method initiates an asynchronous operation to accept a
+ * connection made to this channel's socket. The {@code handler} parameter is
+ * a completion handler that is invoked when a connection is accepted (or
+ * the operation fails). The result passed to the completion handler is
+ * the {@link AsynchronousSocketChannel} to the new connection.
*
* When a new connection is accepted then the resulting {@code
* AsynchronousSocketChannel} will be bound to the same {@link
@@ -269,35 +266,35 @@ public abstract class AsynchronousServerSocketChannel
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
- * The handler for consuming the result; can be {@code null}
- *
- * @return an Future object representing the pending result
+ * The handler for consuming the result
*
* @throws AcceptPendingException
* If an accept operation is already in progress on this channel
* @throws NotYetBoundException
* If this channel's socket has not yet been bound
* @throws ShutdownChannelGroupException
- * If a handler is specified, and the channel group is shutdown
+ * If the channel group has terminated
*/
- public abstract Future This method is equivalent to invoking {@link
- * #accept(Object,CompletionHandler)} with the {@code attachment}
- * and {@code handler} parameters set to {@code null}.
+ * This method initiates an asynchronous operation to accept a
+ * connection made to this channel's socket. The method behaves in exactly
+ * the same manner as the {@link #accept(Object, CompletionHandler)} method
+ * except that instead of specifying a completion handler, this method
+ * returns a {@code Future} representing the pending result. The {@code
+ * Future}'s {@link Future#get() get} method returns the {@link
+ * AsynchronousSocketChannel} to the new connection on successful completion.
*
- * @return an Future object representing the pending result
+ * @return a {@code Future} object representing the pending result
*
* @throws AcceptPendingException
* If an accept operation is already in progress on this channel
* @throws NotYetBoundException
* If this channel's socket has not yet been bound
*/
- public final Future This method initiates an operation to connect this channel, returning
- * a {@code Future} representing the pending result of the operation. If
- * the connection is successfully established then the {@code Future}'s
- * {@link Future#get() get} method will return {@code null}. If the
- * connection cannot be established then the channel is closed. In that case,
- * invoking the {@code get} method throws {@link
- * java.util.concurrent.ExecutionException} with an {@code IOException} as
- * the cause.
+ * This method initiates an operation to connect this channel. The
+ * {@code handler} parameter is a completion handler that is invoked when
+ * the connection is successfully established or connection cannot be
+ * established. If the connection cannot be established then the channel is
+ * closed.
*
* This method performs exactly the same security checks as the {@link
* java.net.Socket} class. That is, if a security manager has been
@@ -294,9 +291,7 @@ public abstract class AsynchronousSocketChannel
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
- * The handler for consuming the result; can be {@code null}
- *
- * @return A {@code Future} object representing the pending result
+ * The handler for consuming the result
*
* @throws UnresolvedAddressException
* If the given remote address is not fully resolved
@@ -307,23 +302,26 @@ public abstract class AsynchronousSocketChannel
* @throws ConnectionPendingException
* If a connection operation is already in progress on this channel
* @throws ShutdownChannelGroupException
- * If a handler is specified, and the channel group is shutdown
+ * If the channel group has terminated
* @throws SecurityException
* If a security manager has been installed
* and it does not permit access to the given remote endpoint
*
* @see #getRemoteAddress
*/
- public abstract Future This method is equivalent to invoking {@link
- * #connect(SocketAddress,Object,CompletionHandler)} with the {@code attachment}
- * and handler parameters set to {@code null}.
+ * This method initiates an operation to connect this channel. This
+ * method behaves in exactly the same manner as the {@link
+ * #connect(SocketAddress, Object, CompletionHandler)} method except that
+ * instead of specifying a completion handler, this method returns a {@code
+ * Future} representing the pending result. The {@code Future}'s {@link
+ * Future#get() get} method returns {@code null} on successful completion.
*
* @param remote
* The remote address to which this channel is to be connected
@@ -342,18 +340,17 @@ public abstract class AsynchronousSocketChannel
* If a security manager has been installed
* and it does not permit access to the given remote endpoint
*/
- public final Future This method initiates the reading of a sequence of bytes from this
- * channel into the given buffer, returning a {@code Future} representing
- * the pending result of the operation. The {@code Future}'s {@link
- * Future#get() get} method returns the number of bytes read or {@code -1}
- * if all bytes have been read and channel has reached end-of-stream.
+ * This method initiates an asynchronous read operation to read a
+ * sequence of bytes from this channel into the given buffer. The {@code
+ * handler} parameter is a completion handler that is invoked when the read
+ * operation completes (or fails). The result passed to the completion
+ * handler is the number of bytes read or {@code -1} if no bytes could be
+ * read because the channel has reached end-of-stream.
*
* If a timeout is specified and the timeout elapses before the operation
* completes then the operation completes with the exception {@link
@@ -376,9 +373,7 @@ public abstract class AsynchronousSocketChannel
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
- * The handler for consuming the result; can be {@code null}
- *
- * @return A {@code Future} object representing the pending result
+ * The handler for consuming the result
*
* @throws IllegalArgumentException
* If the {@code timeout} parameter is negative or the buffer is
@@ -388,13 +383,13 @@ public abstract class AsynchronousSocketChannel
* @throws NotYetConnectedException
* If this channel is not yet connected
* @throws ShutdownChannelGroupException
- * If a handler is specified, and the channel group is shutdown
+ * If the channel group has terminated
*/
- public abstract Future This method initiates a read of up to r bytes from this channel,
* where r is the total number of bytes remaining in the specified
@@ -456,11 +453,6 @@ public abstract class AsynchronousSocketChannel
* I/O operation is performed with the maximum number of buffers allowed by
* the operating system.
*
- * The return value from this method is a {@code Future} representing
- * the pending result of the operation. The {@code Future}'s {@link
- * Future#get() get} method returns the number of bytes read or {@code -1L}
- * if all bytes have been read and the channel has reached end-of-stream.
- *
* If a timeout is specified and the timeout elapses before the operation
* completes then it completes with the exception {@link
* InterruptedByTimeoutException}. Where a timeout occurs, and the
@@ -485,9 +477,7 @@ public abstract class AsynchronousSocketChannel
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
- * The handler for consuming the result; can be {@code null}
- *
- * @return A {@code Future} object representing the pending result
+ * The handler for consuming the result
*
* @throws IndexOutOfBoundsException
* If the pre-conditions for the {@code offset} and {@code length}
@@ -500,23 +490,24 @@ public abstract class AsynchronousSocketChannel
* @throws NotYetConnectedException
* If this channel is not yet connected
* @throws ShutdownChannelGroupException
- * If a handler is specified, and the channel group is shutdown
+ * If the channel group has terminated
*/
- public abstract Future This method initiates the writing of a sequence of bytes to this channel
- * from the given buffer, returning a {@code Future} representing the
- * pending result of the operation. The {@code Future}'s {@link Future#get()
- * get} method will return the number of bytes written.
+ * This method initiates an asynchronous write operation to write a
+ * sequence of bytes to this channel from the given buffer. The {@code
+ * handler} parameter is a completion handler that is invoked when the write
+ * operation completes (or fails). The result passed to the completion
+ * handler is the number of bytes written.
*
* If a timeout is specified and the timeout elapses before the operation
* completes then it completes with the exception {@link
@@ -539,9 +530,7 @@ public abstract class AsynchronousSocketChannel
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
- * The handler for consuming the result; can be {@code null}
- *
- * @return A {@code Future} object representing the pending result
+ * The handler for consuming the result
*
* @throws IllegalArgumentException
* If the {@code timeout} parameter is negative
@@ -550,28 +539,28 @@ public abstract class AsynchronousSocketChannel
* @throws NotYetConnectedException
* If this channel is not yet connected
* @throws ShutdownChannelGroupException
- * If a handler is specified, and the channel group is shutdown
+ * If the channel group has terminated
*/
- public abstract Future This method initiates a write of up to r bytes to this channel,
* where r is the total number of bytes remaining in the specified
@@ -616,10 +605,6 @@ public abstract class AsynchronousSocketChannel
* remaining), exceeds this limit, then the I/O operation is performed with
* the maximum number of buffers allowed by the operating system.
*
- * The return value from this method is a {@code Future} representing
- * the pending result of the operation. The {@code Future}'s {@link
- * Future#get() get} method will return the number of bytes written.
- *
* If a timeout is specified and the timeout elapses before the operation
* completes then it completes with the exception {@link
* InterruptedByTimeoutException}. Where a timeout occurs, and the
@@ -644,9 +629,7 @@ public abstract class AsynchronousSocketChannel
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
- * The handler for consuming the result; can be {@code null}
- *
- * @return A {@code Future} object representing the pending result
+ * The handler for consuming the result
*
* @throws IndexOutOfBoundsException
* If the pre-conditions for the {@code offset} and {@code length}
@@ -658,13 +641,13 @@ public abstract class AsynchronousSocketChannel
* @throws NotYetConnectedException
* If this channel is not yet connected
* @throws ShutdownChannelGroupException
- * If a handler is specified, and the channel group is shutdown
+ * If the channel group has terminated
*/
- public abstract Future The stream will not be buffered, and it will not support the {@link
@@ -258,7 +257,6 @@ public final class Channels {
}
/**
- * {@note new}
* Constructs a stream that writes bytes to the given channel.
*
* The stream will not be buffered. The stream will be safe for access
diff --git a/src/share/classes/java/nio/channels/CompletionHandler.java b/src/share/classes/java/nio/channels/CompletionHandler.java
index c4d4add8ff9424b47d94499f58885f9868d251f8..43e5abeafb4888833b756fa09ea9c5e1893904e7 100644
--- a/src/share/classes/java/nio/channels/CompletionHandler.java
+++ b/src/share/classes/java/nio/channels/CompletionHandler.java
@@ -32,11 +32,9 @@ package java.nio.channels;
* handler to be specified to consume the result of an asynchronous operation.
* The {@link #completed completed} method is invoked when the I/O operation
* completes successfully. The {@link #failed failed} method is invoked if the
- * I/O operations fails. The {@link #cancelled cancelled} method is invoked when
- * the I/O operation is cancelled by invoking the {@link
- * java.util.concurrent.Future#cancel cancel} method. The implementations of
- * these methods should complete in a timely manner so as to avoid keeping the
- * invoking thread from dispatching to other completion handlers.
+ * I/O operations fails. The implementations of these methods should complete
+ * in a timely manner so as to avoid keeping the invoking thread from dispatching
+ * to other completion handlers.
*
* @param {@note revised}
- * A file channel is a {@link SeekableByteChannel} that is connected to
+ * A file channel is a {@link SeekableByteChannel} that is connected to
* a file. It has a current position within its file which can
* be both {@link #position() queried} and {@link #position(long)
* modified}. The file itself contains a variable-length sequence
@@ -151,7 +150,6 @@ import java.util.Collections;
* @author Mike McCloskey
* @author JSR-51 Expert Group
* @since 1.4
- * @updated 1.7
*/
public abstract class FileChannel
@@ -164,7 +162,6 @@ public abstract class FileChannel
protected FileChannel() { }
/**
- * {@note new}
* Opens or creates a file, returning a file channel to access the file.
*
* The {@code options} parameter determines how the file is opened.
@@ -293,7 +290,6 @@ public abstract class FileChannel
private static final FileAttribute[] NO_ATTRIBUTES = new FileAttribute[0];
/**
- * {@note new}
* Opens or creates a file, returning a file channel to access the file.
*
* An invocation of this method behaves in exactly the same way as the
diff --git a/src/share/classes/java/nio/channels/FileLock.java b/src/share/classes/java/nio/channels/FileLock.java
index b0ec37f1ba5a78f2c7a1b425fceb9d5686a6a232..8e1321144b5a6f2e60a2b4faced21c87c4173f82 100644
--- a/src/share/classes/java/nio/channels/FileLock.java
+++ b/src/share/classes/java/nio/channels/FileLock.java
@@ -114,7 +114,6 @@ import java.io.IOException;
* @author Mark Reinhold
* @author JSR-51 Expert Group
* @since 1.4
- * @updated 1.7
*/
public abstract class FileLock {
@@ -161,7 +160,7 @@ public abstract class FileLock {
}
/**
- * {@note new} Initializes a new instance of this class.
+ * Initializes a new instance of this class.
*
* @param channel
* The channel upon whose file this lock is held
@@ -199,7 +198,6 @@ public abstract class FileLock {
}
/**
- * {@note revised}
* Returns the file channel upon whose file this lock was acquired.
*
* This method has been superseded by the {@link #acquiredBy acquiredBy}
@@ -213,7 +211,6 @@ public abstract class FileLock {
}
/**
- * {@note new}
* Returns the channel upon whose file this lock was acquired.
*
* @return The channel upon whose file this lock was acquired.
diff --git a/src/share/classes/java/nio/channels/exceptions b/src/share/classes/java/nio/channels/exceptions
index fed9f72ab2e068642926f5467b61dda42434a3eb..d78ea57738fcb9f4ed266bf409a61cc63e292b04 100644
--- a/src/share/classes/java/nio/channels/exceptions
+++ b/src/share/classes/java/nio/channels/exceptions
@@ -190,5 +190,5 @@ gen WritePendingException "
gen ShutdownChannelGroupException "
* Unchecked exception thrown when an attempt is made to construct a channel in
* a group that is shutdown or the completion handler for an I/O operation
- * cannot be invoked because the channel group is shutdown." \
+ * cannot be invoked because the channel group has terminated." \
-3903801676350154157L
diff --git a/src/share/classes/java/nio/channels/package-info.java b/src/share/classes/java/nio/channels/package-info.java
index 36a408402607648d6f6c60c8ce12c2ee0ae3a47d..d5bf5110e317cb8c9b634c26dfad30b1512e69b1 100644
--- a/src/share/classes/java/nio/channels/package-info.java
+++ b/src/share/classes/java/nio/channels/package-info.java
@@ -285,7 +285,6 @@
* java.lang.NullPointerException NullPointerException} to be thrown.
*
* @since 1.4
- * @updated 1.7
* @author Mark Reinhold
* @author JSR-51 Expert Group
*/
diff --git a/src/share/classes/java/nio/file/FileRef.java b/src/share/classes/java/nio/file/FileRef.java
index 8a19ce285c2f10bced56b2c07869a392ee6b3376..c2bfee92916b65a6803bfc97d18e0b61ac4917f6 100644
--- a/src/share/classes/java/nio/file/FileRef.java
+++ b/src/share/classes/java/nio/file/FileRef.java
@@ -39,8 +39,6 @@ import java.io.IOException;
* metadata or file attributes.
*
* @since 1.7
- * @see java.io.Inputs
- * @see java.io.Outputs
* @see java.nio.file.attribute.Attributes
* @see java.io.File#toPath
*/
diff --git a/src/share/classes/java/util/Scanner.java b/src/share/classes/java/util/Scanner.java
index c1032337bd2de111887443cdd082f51290de84ab..b7ec4b847d2682c6de8976bd5d72a270c2daed23 100644
--- a/src/share/classes/java/util/Scanner.java
+++ b/src/share/classes/java/util/Scanner.java
@@ -674,7 +674,6 @@ public final class Scanner implements Iterator
+ *
- * c.read(dst, null, null);
+ *
- * c.write(src, null, null);
*
*
* where operation is the name of the I/O operation (read or write for
@@ -48,7 +49,7 @@ import java.util.concurrent.Future; // javadoc
* interface may be used to check if the operation has completed, wait for its
* completion, and to retrieve the result. In the second form, a {@link
* CompletionHandler} is invoked to consume the result of the I/O operation when
- * it completes, fails, or is cancelled.
+ * it completes or fails.
*
* {@link Future}<V> operation(...)Future<V> operation(... A attachment, {@link CompletionHandler}<V,? super A> handler)void operation(... A attachment, {@link
+ * CompletionHandler}<V,? super A> handler)Cancellation
*
*
- * ch.{@link #open(Path,Set,ExecutorService,FileAttribute[]) open}(file, opts, null, new FileAttribute<?>[0]);
+ * ch.{@link #open(Path,Set,ExecutorService,FileAttribute[])
+ * open}(file, opts, null, new FileAttribute<?>[0]);
*
* where {@code opts} is a {@code Set} containing the options specified to
* this method.
@@ -405,10 +387,11 @@ public abstract class AsynchronousFileChannel
/**
* Acquires a lock on the given region of this channel's file.
*
- *
- * ch.{@link #lock(long,long,boolean,Object,CompletionHandler) lock}(0L, Long.MAX_VALUE, false, null, null)
+ * ch.{@link #lock(long,long,boolean) lock}(0L, Long.MAX_VALUE, false)
*
*
- * @return A {@code Future} object representing the pending result
+ * @return a {@code Future} object representing the pending result
*
* @throws OverlappingFileLockException
* If a lock is already held by this Java virtual machine, or there
@@ -538,7 +549,7 @@ public abstract class AsynchronousFileChannel
* If this channel was not opened for writing
*/
public final FutureScanner that produces values scanned
* from the specified file. Bytes from the file are converted into
* characters using the underlying platform's
@@ -694,7 +693,6 @@ public final class Scanner implements IteratorScanner that produces values scanned
* from the specified file. Bytes from the file are converted into
* characters using the specified charset.
diff --git a/src/share/classes/sun/nio/ch/AbstractFuture.java b/src/share/classes/sun/nio/ch/AbstractFuture.java
deleted file mode 100644
index f79dc7abbbfa2ea658c298d4bca20ba66e4fecb2..0000000000000000000000000000000000000000
--- a/src/share/classes/sun/nio/ch/AbstractFuture.java
+++ /dev/null
@@ -1,63 +0,0 @@
-/*
- * Copyright 2008-2009 Sun Microsystems, Inc. All Rights Reserved.
- * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
- *
- * This code is free software; you can redistribute it and/or modify it
- * under the terms of the GNU General Public License version 2 only, as
- * published by the Free Software Foundation. Sun designates this
- * particular file as subject to the "Classpath" exception as provided
- * by Sun in the LICENSE file that accompanied this code.
- *
- * This code is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
- * version 2 for more details (a copy is included in the LICENSE file that
- * accompanied this code).
- *
- * You should have received a copy of the GNU General Public License version
- * 2 along with this work; if not, write to the Free Software Foundation,
- * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
- *
- * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
- * CA 95054 USA or visit www.sun.com if you need additional information or
- * have any questions.
- */
-
-package sun.nio.ch;
-
-import java.nio.channels.AsynchronousChannel;
-import java.util.concurrent.Future;
-
-/**
- * Base implementation of Future used for asynchronous I/O
- */
-
-abstract class AbstractFuture