File object
* will never change.
*
+ * The {@code java.nio.file} + * package defines interfaces and classes for the Java virtual machine to access + * files, file attributes, and file systems. This API may be used to overcome + * many of the limitations of the {@code java.io.File} class. + * The {@link #toPath toPath} method may be used to obtain a {@link + * Path} that uses the abstract path represented by a {@code File} object to + * locate a file. The resulting {@code Path} provides more efficient and + * extensive access to file attributes, additional file operations, and I/O + * exceptions to help diagnose errors when an operation on a file fails. + * * @author unascribed * @since JDK1.0 */ @@ -573,6 +585,7 @@ public class File * read access to the file * * @since JDK1.1 + * @see Path#toRealPath */ public String getCanonicalPath() throws IOException { return fs.canonicalize(fs.resolve(this)); @@ -597,6 +610,7 @@ public class File * read access to the file * * @since 1.2 + * @see Path#toRealPath */ public File getCanonicalFile() throws IOException { String canonPath = getCanonicalPath(); @@ -663,6 +677,14 @@ public class File * system is converted into an abstract pathname in a virtual machine on a * different operating system. * + *
Note that when this abstract pathname represents a UNC pathname then
+ * all components of the UNC (including the server name component) are encoded
+ * in the {@code URI} path. The authority component is undefined, meaning
+ * that it is represented as {@code null}. The {@link Path} class defines the
+ * {@link Path#toUri toUri} method to encode the server name in the authority
+ * component of the resulting {@code URI}. The {@link #toPath toPath} method
+ * may be used to obtain a {@code Path} representing this abstract pathname.
+ *
* @return An absolute, hierarchical URI with a scheme equal to
* "file", a path representing this abstract pathname,
* and undefined authority, query, and fragment components
@@ -764,6 +786,8 @@ public class File
* If a security manager exists and its {@link
* java.lang.SecurityManager#checkRead(java.lang.String)}
* method denies read access to the file
+ *
+ * @see Attributes#readBasicFileAttributes
*/
public boolean isDirectory() {
SecurityManager security = System.getSecurityManager();
@@ -788,6 +812,8 @@ public class File
* If a security manager exists and its {@link
* java.lang.SecurityManager#checkRead(java.lang.String)}
* method denies read access to the file
+ *
+ * @see Attributes#readBasicFileAttributes
*/
public boolean isFile() {
SecurityManager security = System.getSecurityManager();
@@ -836,6 +862,8 @@ public class File
* If a security manager exists and its {@link
* java.lang.SecurityManager#checkRead(java.lang.String)}
* method denies read access to the file
+ *
+ * @see Attributes#readBasicFileAttributes
*/
public long lastModified() {
SecurityManager security = System.getSecurityManager();
@@ -858,6 +886,8 @@ public class File
* If a security manager exists and its {@link
* java.lang.SecurityManager#checkRead(java.lang.String)}
* method denies read access to the file
+ *
+ * @see Attributes#readBasicFileAttributes
*/
public long length() {
SecurityManager security = System.getSecurityManager();
@@ -907,6 +937,12 @@ public class File
* this pathname denotes a directory, then the directory must be empty in
* order to be deleted.
*
+ *
Note that the {@link Path} class defines the {@link Path#delete
+ * delete} method to throw an {@link IOException} when a file cannot be
+ * deleted. This is useful for error reporting and to diagnose why a file
+ * cannot be deleted. The {@link #toPath toPath} method may be used to
+ * obtain a {@code Path} representing this abstract pathname.
+ *
* @return true if and only if the file or directory is
* successfully deleted; false otherwise
*
@@ -973,6 +1009,13 @@ public class File
* will appear in any specific order; they are not, in particular,
* guaranteed to appear in alphabetical order.
*
+ *
Note that the {@link Path} class defines the {@link
+ * Path#newDirectoryStream newDirectoryStream} method to open a directory
+ * and iterate over the names of the files in the directory. This may use
+ * less resources when working with very large directories. The {@link
+ * #toPath toPath} method may be used to obtain a {@code Path} representing
+ * this abstract pathname.
+ *
* @return An array of strings naming the files and directories in the
* directory denoted by this abstract pathname. The array will be
* empty if the directory is empty. Returns {@code null} if
@@ -1024,13 +1067,13 @@ public class File
if ((names == null) || (filter == null)) {
return names;
}
- ArrayList v = new ArrayList();
+ List Note that the {@link Path} class defines the {@link
+ * Path#newDirectoryStream newDirectoryStream} method to open a directory
+ * and iterate over the names of the files in the directory. This may use
+ * less resources when working with very large directories. The {@link
+ * #toPath toPath} method may be used to obtain a {@code Path} representing
+ * this abstract pathname.
+ *
* @return An array of abstract pathnames denoting the files and
* directories in the directory denoted by this abstract pathname.
* The array will be empty if the directory is empty. Returns
@@ -1157,6 +1207,12 @@ public class File
/**
* Creates the directory named by this abstract pathname.
*
+ * Note that the {@link Path} class defines the {@link Path#createDirectory
+ * createDirectory} method to throw an {@link IOException} when a directory
+ * cannot be created. This is useful for error reporting and to diagnose why
+ * a directory cannot be created. The {@link #toPath toPath} method may be
+ * used to obtain a {@code Path} representing this abstract pathname.
+ *
* @return Note that the {@link Path} class defines the {@link Path#moveTo
+ * moveTo} method to move or rename a file in a platform independent manner.
+ * The {@link #toPath toPath} method may be used to obtain a {@code Path}
+ * representing this abstract pathname.
+ *
* @param dest The new abstract pathname for the named file
*
* @return The {@link Attributes Attributes} class defines methods that operate
+ * on file attributes including file permissions. This may be used when
+ * finer manipulation of file permissions is required.
+ *
* @param writable
* If The {@link Attributes Attributes} class defines methods that operate
+ * on file attributes including file permissions. This may be used when
+ * finer manipulation of file permissions is required.
+ *
* @param readable
* If The {@link Attributes Attributes} class defines methods that operate
+ * on file attributes including file permissions. This may be used when
+ * finer manipulation of file permissions is required.
+ *
* @param executable
* If When the value of the {@code deleteOnExit} method is {@code true}
+ * then the resulting file is requested to be deleted when the Java virtual
+ * machine terminates as if by invoking the {@link #deleteOnExit deleteOnExit}
+ * method.
+ *
+ * The {@code attrs} parameter is an optional array of {@link FileAttribute
+ * attributes} to set atomically when creating the file. Each attribute is
+ * identified by its {@link FileAttribute#name name}. If more than one attribute
+ * of the same name is included in the array then all but the last occurrence
+ * is ignored.
+ *
+ * @param prefix
+ * The prefix string to be used in generating the file's
+ * name; must be at least three characters long
+ * @param suffix
+ * The suffix string to be used in generating the file's
+ * name; may be {@code null}, in which case the suffix
+ * {@code ".tmp"} will be used
+ * @param deleteOnExit
+ * {@code true} if the file denoted by resulting pathname be
+ * deleted when the Java virtual machine terminates
+ * @param attrs
+ * An optional list of file attributes to set atomically when creating
+ * the file
+ *
+ * @return An abstract pathname denoting a newly-created empty file
+ *
+ * @throws IllegalArgumentException
+ * If the If this abstract pathname is the empty abstract pathname then this
+ * method returns a {@code Path} that may be used to access to the current
+ * user directory.
+ *
+ * @return A {@code Path} constructed from this abstract path. The resulting
+ * {@code Path} is associated with the {@link FileSystems#getDefault
+ * default-filesystem}.
+ *
+ * @throws InvalidPathException
+ * If a {@code Path} object cannot be constructed from the abstract
+ * path (see {@link java.nio.file.FileSystem#getPath FileSystem.getPath})
+ *
+ * @since 1.7
+ */
+ public Path toPath() {
+ if (filePath == null) {
+ synchronized (this) {
+ if (filePath == null) {
+ if (path.length() == 0) {
+ // assume default file system treats "." as current directory
+ filePath = Paths.get(".");
+ } else {
+ filePath = Paths.get(path);
+ }
+ }
+ }
+ }
+ return filePath;
+ }
}
diff --git a/jdk/src/share/classes/java/io/FilePermission.java b/jdk/src/share/classes/java/io/FilePermission.java
index 9758e35de6027ac6eaba45b073dd16fdea68aee2..88c98fbddf3948868f03aebfcefd0b59c96cc4cb 100644
--- a/jdk/src/share/classes/java/io/FilePermission.java
+++ b/jdk/src/share/classes/java/io/FilePermission.java
@@ -1,5 +1,5 @@
/*
- * Copyright 1997-2005 Sun Microsystems, Inc. All Rights Reserved.
+ * Copyright 1997-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
@@ -29,7 +29,6 @@ import java.security.*;
import java.util.Enumeration;
import java.util.List;
import java.util.ArrayList;
-import java.util.StringTokenizer;
import java.util.Vector;
import java.util.Collections;
import java.io.ObjectStreamField;
@@ -58,7 +57,8 @@ import sun.security.util.SecurityConstants;
*
* The actions to be granted are passed to the constructor in a string containing
* a list of one or more comma-separated keywords. The possible keywords are
- * "read", "write", "execute", and "delete". Their meaning is defined as follows:
+ * "read", "write", "execute", "delete", and "readlink". Their meaning is
+ * defined as follows:
*
*
* The actions string is converted to lowercase before processing.
@@ -114,11 +119,15 @@ public final class FilePermission extends Permission implements Serializable {
* Delete action.
*/
private final static int DELETE = 0x8;
+ /**
+ * Read link action.
+ */
+ private final static int READLINK = 0x10;
/**
- * All actions (read,write,execute,delete)
+ * All actions (read,write,execute,delete,readlink)
*/
- private final static int ALL = READ|WRITE|EXECUTE|DELETE;
+ private final static int ALL = READ|WRITE|EXECUTE|DELETE|READLINK;
/**
* No actions.
*/
@@ -235,7 +244,7 @@ public final class FilePermission extends Permission implements Serializable {
* path is the pathname of a file or directory, and actions
* contains a comma-separated list of the desired actions granted on the
* file or directory. Possible actions are
- * "read", "write", "execute", and "delete".
+ * "read", "write", "execute", "delete", and "readlink".
*
* A pathname that ends in "/*" (where "/" is
* the file separator character, The value of this socket option is an {@code Integer}, the least
- * significant 8 bits of which represents the value of the ToS octet in IP
- * packets sent by sockets to an {@link StandardProtocolFamily#INET IPv4}
- * socket. The interpretation of the ToS octet is network specific and
- * is not defined by this class. Further information on the ToS octet can be
- * found in RFC 1349
- * and RFC 2474. The
- * value of the socket option is a hint. An implementation may
- * ignore the value, or ignore specific values.
+ * The value of this socket option is an {@code Integer} representing
+ * the value of the ToS octet in IP packets sent by sockets to an {@link
+ * StandardProtocolFamily#INET IPv4} socket. The interpretation of the ToS
+ * octet is network specific and is not defined by this class. Further
+ * information on the ToS octet can be found in RFC 1349 and RFC 2474. The value
+ * of the socket option is a hint. An implementation may ignore the
+ * value, or ignore specific values.
*
* The initial/default value of the TOS field in the ToS octet is
* implementation specific but will typically be {@code 0}. For
@@ -235,6 +244,8 @@ public final class StandardSocketOption {
* The behavior of this socket option on a stream-oriented socket, or an
* {@link StandardProtocolFamily#INET6 IPv6} socket, is not defined in this
* release.
+ *
+ * @see DatagramSocket#setTrafficClass
*/
public static final SocketOption Some channels may not allow more than one read or write to be outstanding
+ * at any given time. If a thread invokes a read method before a previous read
+ * operation has completed then a {@link ReadPendingException} will be thrown.
+ * Similarly, if a write method is invoked before a previous write has completed
+ * then {@link WritePendingException} is thrown. Whether or not other kinds of
+ * I/O operations may proceed concurrently with a read operation depends upon
+ * the type of the channel.
+ *
+ * Note that {@link java.nio.ByteBuffer ByteBuffers} are not safe for use by
+ * multiple concurrent threads. When a read or write operation is initiated then
+ * care must be taken to ensure that the buffer is not accessed until the
+ * operation completes.
+ *
+ * @see Channels#newInputStream(AsynchronousByteChannel)
+ * @see Channels#newOutputStream(AsynchronousByteChannel)
+ *
+ * @since 1.7
+ */
+
+public interface AsynchronousByteChannel
+ extends AsynchronousChannel
+{
+ /**
+ * 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.
+ *
+ * Suppose that a byte sequence of length n is read, where
+ * 0 < n <= r.
+ * This byte sequence will be transferred into the buffer so that the first
+ * byte in the sequence is at index p and the last byte is at index
+ * p + n - 1,
+ * where p is the buffer's position at the moment the read is
+ * performed. Upon completion the buffer's position will be equal to
+ * 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.
+ *
+ * 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
+ *
+ * @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
+ */
+ 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 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 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.
+ *
+ * Suppose that a byte sequence of length n is written, where
+ * 0 < n <= r.
+ * This byte sequence will be transferred from the buffer starting at index
+ * p, where p is the buffer's position at the moment the
+ * write is performed; the index of the last byte written will be
+ * p + n - 1.
+ * Upon completion the buffer's position will be equal to
+ * 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.
+ *
+ * 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
+ *
+ * @throws WritePendingException
+ * If the channel does not allow more than one write to be outstanding
+ * and a previous write has not completed
+ */
+ Future An invocation of this method of the form c.write(src)
+ * behaves in exactly the same manner as the invocation
+ * In the first form, the methods defined by the {@link Future Future}
+ * 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.
+ *
+ * A channel that implements this interface is asynchronously
+ * closeable: If an I/O operation is outstanding on the channel and the
+ * channel's {@link #close close} method is invoked, then the I/O operation
+ * fails with the exception {@link AsynchronousCloseException}.
+ *
+ * Asynchronous channels are safe for use by multiple concurrent threads.
+ * Some channel implementations may support concurrent reading and writing, but
+ * may not allow more than one read and one write operation to be outstanding at
+ * any given time.
+ *
+ * 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
+ * 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.
+ *
+ * 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.
+ *
+ * @since 1.7
+ */
+
+public interface AsynchronousChannel
+ extends Channel
+{
+ /**
+ * Closes this channel.
+ *
+ * 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
+ * operations complete immediately with cause {@link ClosedChannelException}.
+ *
+ * This method otherwise behaves exactly as specified by the {@link
+ * Channel} interface.
+ *
+ * @throws IOException
+ * If an I/O error occurs
+ */
+ @Override
+ void close() throws IOException;
+}
diff --git a/jdk/src/share/classes/java/nio/channels/AsynchronousChannelGroup.java b/jdk/src/share/classes/java/nio/channels/AsynchronousChannelGroup.java
new file mode 100644
index 0000000000000000000000000000000000000000..1199e16b51f8641e1d8591f6154c98c225284586
--- /dev/null
+++ b/jdk/src/share/classes/java/nio/channels/AsynchronousChannelGroup.java
@@ -0,0 +1,344 @@
+/*
+ * Copyright 2007-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 java.nio.channels;
+
+import java.nio.channels.spi.AsynchronousChannelProvider;
+import java.io.IOException;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.ThreadFactory;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * A grouping of asynchronous channels for the purpose of resource sharing.
+ *
+ * An asynchronous channel group encapsulates the mechanics required to
+ * handle the completion of I/O operations initiated by {@link AsynchronousChannel
+ * asynchronous channels} that are bound to the group. A group has an associated
+ * thread pool to which tasks are submitted to handle I/O events and dispatch to
+ * {@link CompletionHandler completion-handlers} that consume the result of
+ * asynchronous operations performed on channels in the group. In addition to
+ * handling I/O events, the pooled threads may also execute other tasks required
+ * to support the execution of asynchronous I/O operations.
+ *
+ * An asynchronous channel group is created by invoking the {@link
+ * #withFixedThreadPool withFixedThreadPool} or {@link #withCachedThreadPool
+ * withCachedThreadPool} methods defined here. Channels are bound to a group by
+ * specifying the group when constructing the channel. The associated thread
+ * pool is owned by the group; termination of the group results in the
+ * shutdown of the associated thread pool.
+ *
+ * In addition to groups created explicitly, the Java virtual machine
+ * maintains a system-wide default group that is constructed
+ * automatically. Asynchronous channels that do not specify a group at
+ * construction time are bound to the default group. The default group has an
+ * associated thread pool that creates new threads as needed. The default group
+ * may be configured by means of system properties defined in the table below.
+ * Where the {@link java.util.concurrent.ThreadFactory ThreadFactory} for the
+ * default group is not configured then the pooled threads of the default group
+ * are {@link Thread#isDaemon daemon} threads.
+ *
+ * The completion handler for an I/O operation initiated on a channel bound
+ * to a group is guaranteed to be invoked by one of the pooled threads in the
+ * group. This ensures that the completion handler is run by a thread with the
+ * expected identity.
+ *
+ * Where an I/O operation completes immediately, and the initiating thread
+ * is one of the pooled threads in the group then the completion handler may
+ * be invoked directly by the initiating thread. To avoid stack overflow, an
+ * implementation may impose a limit as to the number of activations on the
+ * thread stack. Some I/O operations may prohibit invoking the completion
+ * handler directly by the initiating thread (see {@link
+ * AsynchronousServerSocketChannel#accept(Object,CompletionHandler) accept}).
+ *
+ * The {@link #shutdown() shutdown} method is used to initiate an orderly
+ * shutdown of a group. An orderly shutdown marks the group as shutdown;
+ * further attempts to construct a channel that binds to the group will throw
+ * {@link ShutdownChannelGroupException}. Whether or not a group is shutdown can
+ * be tested using the {@link #isShutdown() isShutdown} method. Once shutdown,
+ * the group terminates when all asynchronous channels that are bound to
+ * the group are closed, all actively executing completion handlers have run to
+ * completion, and resources used by the group are released. No attempt is made
+ * to stop or interrupt threads that are executing completion handlers. The
+ * {@link #isTerminated() isTerminated} method is used to test if the group has
+ * terminated, and the {@link #awaitTermination awaitTermination} method can be
+ * used to block until the group has terminated.
+ *
+ * The {@link #shutdownNow() shutdownNow} method can be used to initiate a
+ * forceful shutdown of the group. In addition to the actions performed
+ * by an orderly shutdown, the {@code shutdownNow} method closes all open channels
+ * in the group as if by invoking the {@link AsynchronousChannel#close close}
+ * method.
+ *
+ * @since 1.7
+ *
+ * @see AsynchronousSocketChannel#open(AsynchronousChannelGroup)
+ * @see AsynchronousServerSocketChannel#open(AsynchronousChannelGroup)
+ */
+
+public abstract class AsynchronousChannelGroup {
+ private final AsynchronousChannelProvider provider;
+
+ /**
+ * Initialize a new instance of this class.
+ *
+ * @param provider
+ * The asynchronous channel provider for this group
+ */
+ protected AsynchronousChannelGroup(AsynchronousChannelProvider provider) {
+ this.provider = provider;
+ }
+
+ /**
+ * Returns the provider that created this channel group.
+ *
+ * @return The provider that created this channel group
+ */
+ public final AsynchronousChannelProvider provider() {
+ return provider;
+ }
+
+ /**
+ * Creates an asynchronous channel group with a fixed thread pool.
+ *
+ * The resulting asynchronous channel group reuses a fixed number of
+ * threads. At any point, at most {@code nThreads} threads will be active
+ * processing tasks that are submitted to handle I/O events and dispatch
+ * completion results for operations initiated on asynchronous channels in
+ * the group.
+ *
+ * The group is created by invoking the {@link
+ * AsynchronousChannelProvider#openAsynchronousChannelGroup(int,ThreadFactory)
+ * openAsynchronousChannelGroup(int,ThreadFactory)} method of the system-wide
+ * default {@link AsynchronousChannelProvider} object.
+ *
+ * @param nThreads
+ * The number of threads in the pool
+ * @param threadFactory
+ * The factory to use when creating new threads
+ *
+ * @return A new asynchronous channel group
+ *
+ * @throws IllegalArgumentException
+ * If {@code nThreads <= 0}
+ * @throws IOException
+ * If an I/O error occurs
+ */
+ public static AsynchronousChannelGroup withFixedThreadPool(int nThreads,
+ ThreadFactory threadFactory)
+ throws IOException
+ {
+ return AsynchronousChannelProvider.provider()
+ .openAsynchronousChannelGroup(nThreads, threadFactory);
+ }
+
+ /**
+ * Creates an asynchronous channel group with a given thread pool that
+ * creates new threads as needed.
+ *
+ * The {@code executor} parameter is an {@code ExecutorService} that
+ * creates new threads as needed to execute tasks that are submitted to
+ * handle I/O events and dispatch completion results for operations initiated
+ * on asynchronous channels in the group. It may reuse previously constructed
+ * threads when they are available.
+ *
+ * The {@code initialSize} parameter may be used by the implementation
+ * as a hint as to the initial number of tasks it may submit. For
+ * example, it may be used to indictae the initial number of threads that
+ * wait on I/O events.
+ *
+ * The executor is intended to be used exclusively by the resulting
+ * asynchronous channel group. Termination of the group results in the
+ * orderly {@link ExecutorService#shutdown shutdown} of the executor
+ * service. Shutting down the executor service by other means results in
+ * unspecified behavior.
+ *
+ * The group is created by invoking the {@link
+ * AsynchronousChannelProvider#openAsynchronousChannelGroup(ExecutorService,int)
+ * openAsynchronousChannelGroup(ExecutorService,int)} method of the system-wide
+ * default {@link AsynchronousChannelProvider} object.
+ *
+ * @param executor
+ * The thread pool for the resulting group
+ * @param initialSize
+ * A value {@code >=0} or a negative value for implementation
+ * specific default
+ *
+ * @return A new asynchronous channel group
+ *
+ * @throws IOException
+ * If an I/O error occurs
+ *
+ * @see java.util.concurrent.Executors#newCachedThreadPool
+ */
+ public static AsynchronousChannelGroup withCachedThreadPool(ExecutorService executor,
+ int initialSize)
+ throws IOException
+ {
+ return AsynchronousChannelProvider.provider()
+ .openAsynchronousChannelGroup(executor, initialSize);
+ }
+
+ /**
+ * Creates an asynchronous channel group with a given thread pool.
+ *
+ * The {@code executor} parameter is an {@code ExecutorService} that
+ * executes tasks submitted to dispatch completion results for operations
+ * initiated on asynchronous channels in the group.
+ *
+ * Care should be taken when configuring the executor service. It
+ * should support direct handoff or unbounded queuing of
+ * submitted tasks, and the thread that invokes the {@link
+ * ExecutorService#execute execute} method should never invoke the task
+ * directly. An implementation may mandate additional constraints.
+ *
+ * The executor is intended to be used exclusively by the resulting
+ * asynchronous channel group. Termination of the group results in the
+ * orderly {@link ExecutorService#shutdown shutdown} of the executor
+ * service. Shutting down the executor service by other means results in
+ * unspecified behavior.
+ *
+ * The group is created by invoking the {@link
+ * AsynchronousChannelProvider#openAsynchronousChannelGroup(ExecutorService,int)
+ * openAsynchronousChannelGroup(ExecutorService,int)} method of the system-wide
+ * default {@link AsynchronousChannelProvider} object with an {@code
+ * initialSize} of {@code 0}.
+ *
+ * @param executor
+ * The thread pool for the resulting group
+ *
+ * @return A new asynchronous channel group
+ *
+ * @throws IOException
+ * If an I/O error occurs
+ */
+ public static AsynchronousChannelGroup withThreadPool(ExecutorService executor)
+ throws IOException
+ {
+ return AsynchronousChannelProvider.provider()
+ .openAsynchronousChannelGroup(executor, 0);
+ }
+
+ /**
+ * Tells whether or not this asynchronous channel group is shutdown.
+ *
+ * @return {@code true} if this asynchronous channel group is shutdown or
+ * has been marked for shutdown.
+ */
+ public abstract boolean isShutdown();
+
+ /**
+ * Tells whether or not this group has terminated.
+ *
+ * Where this method returns {@code true}, then the associated thread
+ * pool has also {@link ExecutorService#isTerminated terminated}.
+ *
+ * @return {@code true} if this group has terminated
+ */
+ public abstract boolean isTerminated();
+
+ /**
+ * Initiates an orderly shutdown of the group.
+ *
+ * This method marks the group as shutdown. Further attempts to construct
+ * channel that binds to this group will throw {@link ShutdownChannelGroupException}.
+ * The group terminates when all asynchronous channels in the group are
+ * closed, all actively executing completion handlers have run to completion,
+ * and all resources have been released. This method has no effect if the
+ * group is already shutdown.
+ */
+ public abstract void shutdown();
+
+ /**
+ * Shuts down the group and closes all open channels in the group.
+ *
+ * In addition to the actions performed by the {@link #shutdown() shutdown}
+ * method, this method invokes the {@link AsynchronousChannel#close close}
+ * method on all open channels in the group. This method does not attempt to
+ * stop or interrupt threads that are executing completion handlers. The
+ * group terminates when all actively executing completion handlers have run
+ * to completion and all resources have been released. This method may be
+ * invoked at any time. If some other thread has already invoked it, then
+ * another invocation will block until the first invocation is complete,
+ * after which it will return without effect.
+ *
+ * @throws IOException
+ * If an I/O error occurs
+ */
+ public abstract void shutdownNow() throws IOException;
+
+ /**
+ * Awaits termination of the group.
+
+ * This method blocks until the group has terminated, or the timeout
+ * occurs, or the current thread is interrupted, whichever happens first.
+ *
+ * @param timeout
+ * The maximum time to wait, or zero or less to not wait
+ * @param unit
+ * The time unit of the timeout argument
+ *
+ * @return {@code true} if the group has terminated; {@code false} if the
+ * timeout elapsed before termination
+ *
+ * @throws InterruptedException
+ * If interrupted while waiting
+ */
+ public abstract boolean awaitTermination(long timeout, TimeUnit unit)
+ throws InterruptedException;
+}
diff --git a/jdk/src/share/classes/java/nio/channels/AsynchronousDatagramChannel.java b/jdk/src/share/classes/java/nio/channels/AsynchronousDatagramChannel.java
new file mode 100644
index 0000000000000000000000000000000000000000..6a9d9f09715862a1b1fb4b757fd113b7be4a24eb
--- /dev/null
+++ b/jdk/src/share/classes/java/nio/channels/AsynchronousDatagramChannel.java
@@ -0,0 +1,718 @@
+/*
+ * Copyright 2007-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 java.nio.channels;
+
+import java.nio.channels.spi.*;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.Future;
+import java.io.IOException;
+import java.net.SocketOption;
+import java.net.SocketAddress;
+import java.net.ProtocolFamily;
+import java.nio.ByteBuffer;
+
+/**
+ * An asynchronous channel for datagram-oriented sockets.
+ *
+ * An asynchronous datagram channel is created by invoking one of the {@link
+ * #open open} methods defined by this class. It is not possible to create a channel
+ * for an arbitrary, pre-existing datagram socket. A newly-created asynchronous
+ * datagram channel is open but not connected. It need not be connected in order
+ * for the {@link #send send} and {@link #receive receive} methods to be used.
+ * A datagram channel may be connected, by invoking its {@link #connect connect}
+ * method, in order to avoid the overhead of the security checks that are otherwise
+ * performed as part of every send and receive operation when a security manager
+ * is set. The channel must be connected in order to use the {@link #read read}
+ * and {@link #write write} methods, since those methods do not accept or return
+ * socket addresses. Once connected, an asynchronous datagram channel remains
+ * connected until it is disconnected or closed.
+ *
+ * Socket options are configured using the {@link #setOption(SocketOption,Object)
+ * setOption} method. An asynchronous datagram channel to an Internet Protocol
+ * (IP) socket supports the following options:
+ * Asynchronous datagram channels allow more than one read/receive and
+ * write/send to be oustanding at any given time.
+ *
+ * Usage Example:
+ * The new channel is created by invoking the {@link
+ * java.nio.channels.spi.AsynchronousChannelProvider#openAsynchronousDatagramChannel
+ * openAsynchronousDatagramChannel} method on the {@link
+ * java.nio.channels.spi.AsynchronousChannelProvider} object that created
+ * the given group (or the default provider where {@code group} is {@code
+ * null}).
+ *
+ * The {@code family} parameter is used to specify the {@link ProtocolFamily}.
+ * If the datagram channel is to be used for Internet Protocol {@link
+ * MulticastChannel multicasting} then this parameter should correspond to
+ * the address type of the multicast groups that this channel will join.
+ *
+ * @param family
+ * The protocol family, or {@code null} to use the default protocol
+ * family
+ * @param group
+ * The group to which the newly constructed channel should be bound,
+ * or {@code null} for the default group
+ *
+ * @return A new asynchronous datagram channel
+ *
+ * @throws UnsupportedOperationException
+ * If the specified protocol family is not supported. For example,
+ * suppose the parameter is specified as {@link
+ * java.net.StandardProtocolFamily#INET6 INET6} but IPv6 is not
+ * enabled on the platform.
+ * @throws ShutdownChannelGroupException
+ * The specified group is shutdown
+ * @throws IOException
+ * If an I/O error occurs
+ */
+ public static AsynchronousDatagramChannel open(ProtocolFamily family,
+ AsynchronousChannelGroup group)
+ throws IOException
+ {
+ AsynchronousChannelProvider provider = (group == null) ?
+ AsynchronousChannelProvider.provider() : group.provider();
+ return provider.openAsynchronousDatagramChannel(family, group);
+ }
+
+ /**
+ * Opens an asynchronous datagram channel.
+ *
+ * This method returns an asynchronous datagram channel that is
+ * bound to the default group. This method is equivalent to evaluating
+ * the expression:
+ * Where the channel is connected to an Internet Protocol socket address
+ * then the return value from this method is of type {@link
+ * java.net.InetSocketAddress}.
+ *
+ * @return The remote address; {@code null} if the channel's socket is not
+ * connected
+ *
+ * @throws ClosedChannelException
+ * If the channel is closed
+ * @throws IOException
+ * If an I/O error occurs
+ */
+ public abstract SocketAddress getRemoteAddress() throws IOException;
+
+ /**
+ * Connects this channel's socket.
+ *
+ * The channel's socket is configured so that it only receives
+ * datagrams from, and sends datagrams to, the given remote peer
+ * address. Once connected, datagrams may not be received from or sent to
+ * any other address. A datagram socket remains connected until it is
+ * explicitly disconnected or until it is closed.
+ *
+ * This method performs exactly the same security checks as the {@link
+ * java.net.DatagramSocket#connect connect} method of the {@link
+ * java.net.DatagramSocket} class. That is, if a security manager has been
+ * installed then this method verifies that its {@link
+ * java.lang.SecurityManager#checkAccept checkAccept} and {@link
+ * java.lang.SecurityManager#checkConnect checkConnect} methods permit
+ * datagrams to be received from and sent to, respectively, the given
+ * remote address.
+ *
+ * This method may be invoked at any time. Whether it has any effect
+ * on outstanding read or write operations is implementation specific and
+ * therefore not specified.
+ *
+ * @param remote
+ * The remote address to which this channel is to be connected
+ *
+ * @return This datagram channel
+ *
+ * @throws ClosedChannelException
+ * If this channel is closed
+ *
+ * @throws SecurityException
+ * If a security manager has been installed
+ * and it does not permit access to the given remote address
+ *
+ * @throws IOException
+ * If some other I/O error occurs
+ */
+ public abstract AsynchronousDatagramChannel connect(SocketAddress remote)
+ throws IOException;
+
+ /**
+ * Disconnects this channel's socket.
+ *
+ * The channel's socket is configured so that it can receive datagrams
+ * from, and sends datagrams to, any remote address so long as the security
+ * manager, if installed, permits it.
+ *
+ * This method may be invoked at any time. Whether it has any effect
+ * on outstanding read or write operations is implementation specific and
+ * therefore not specified.
+ *
+ * @return This datagram channel
+ *
+ * @throws IOException
+ * If some other I/O error occurs
+ */
+ public abstract AsynchronousDatagramChannel disconnect() throws IOException;
+
+ /**
+ * 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.
+ *
+ * The datagram is transferred into the given byte buffer starting at
+ * its current position, as if by a regular {@link AsynchronousByteChannel#read
+ * read} operation. If there are fewer bytes remaining in the buffer
+ * than are required to hold the datagram then the remainder of the datagram
+ * is silently discarded.
+ *
+ * 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.
+ *
+ * When a security manager has been installed and the channel is not
+ * connected, then it verifies that the source's address and port number are
+ * permitted by the security manager's {@link SecurityManager#checkAccept
+ * checkAccept} method. The permission check is performed with privileges that
+ * are restricted by the calling context of this method. If the permission
+ * check fails then the operation completes with a {@link SecurityException}.
+ * The overhead of this security check can be avoided by first connecting the
+ * socket via the {@link #connect connect} method.
+ *
+ * @param dst
+ * The buffer into which the datagram is to be transferred
+ * @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 or the buffer is read-only
+ * @throws ShutdownChannelGroupException
+ * If a handler is specified, and the channel group is shutdown
+ */
+ 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 is equivalent to invoking {@link
+ * #receive(ByteBuffer,long,TimeUnit,Object,CompletionHandler)} with a
+ * timeout of {@code 0L}.
+ *
+ * @param dst
+ * The buffer into which the datagram is to be transferred
+ * @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 buffer is read-only
+ * @throws ShutdownChannelGroupException
+ * If a handler is specified, and the channel group is shutdown
+ */
+ 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}.
+ *
+ * @param dst
+ * The buffer into which the datagram is to be transferred
+ *
+ * @return a {@code Future} object representing the pending result
+ *
+ * @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.
+ *
+ * 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 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.
+ *
+ * @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
+ *
+ * @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 channel's socket is connected and 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 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}.
+ *
+ * @param src
+ * The buffer containing the datagram to be sent
+ * @param target
+ * The address to which the datagram is to be sent
+ *
+ * @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 channel's socket is connected and 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
+ */
+ 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 may only be invoked if this channel is connected, and it
+ * only accepts datagrams from the peer that the channel is connected too.
+ * The datagram is transferred into the given byte buffer starting at
+ * its current position and exactly as specified in the {@link
+ * AsynchronousByteChannel} interface. If there are fewer bytes
+ * remaining in the buffer than are required to hold the datagram then the
+ * remainder of the datagram is silently discarded.
+ *
+ * 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 dst
+ * The buffer into which the datagram is to be transferred
+ * @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 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
+ */
+ 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 is created when a file is opened by invoking
+ * one of the {@link #open open} methods defined by this class. The file contains
+ * a variable-length sequence of bytes that can be read and written and whose
+ * current size can be {@link #size() queried}. The size of the file increases
+ * when bytes are written beyond its current size; the size of the file decreases
+ * when it is {@link #truncate truncated}.
+ *
+ * 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.
+ *
+ * In addition to read and write operations, this class defines the
+ * following operations: Updates made to a file may be {@link #force forced
+ * out} to the underlying storage device, ensuring that data are not
+ * lost in the event of a system crash. A region of a file may be {@link FileLock 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
+ * completion handler for an I/O operation initiated on a channel is guaranteed
+ * to be invoked by one threads in the thread pool (This ensures that the
+ * completion handler is run by a thread with the expected identity).
+ * Where an I/O operation completes immediately, and the initiating thread is
+ * itself a thread in the thread pool, then the completion handler may be invoked
+ * directly by the initiating thread. When an {@code AsynchronousFileChannel} is
+ * created without specifying a thread pool then the channel is associated with
+ * a system-dependent and default thread pool that may be shared with other
+ * channels. The default thread pool is configured by the system properties
+ * defined by the {@link AsynchronousChannelGroup} class.
+ *
+ * Channels of this type are safe for use by multiple concurrent threads. The
+ * {@link Channel#close close} method may be invoked at any time, as specified
+ * by the {@link Channel} interface. This causes all outstanding asynchronous
+ * operations on the channel to complete with the exception {@link
+ * AsynchronousCloseException}. Multiple read and write operations may be
+ * outstanding at the same time. When multiple read and write operations are
+ * outstanding then the ordering of the I/O operations, and the order that the
+ * completion handlers are invoked, is not specified; they are not, in particular,
+ * guaranteed to execute in the order that the operations were initiated. The
+ * {@link java.nio.ByteBuffer ByteBuffers} used when reading or writing are not
+ * safe for use by multiple concurrent I/O operations. Furthermore, after an I/O
+ * operation is initiated then care should be taken to ensure that the buffer is
+ * not accessed until after the operation has completed.
+ *
+ * As with {@link FileChannel}, the view of a file provided by an instance of
+ * this class is guaranteed to be consistent with other views of the same file
+ * provided by other instances in the same program. The view provided by an
+ * instance of this class may or may not, however, be consistent with the views
+ * seen by other concurrently-running programs due to caching performed by the
+ * underlying operating system and delays induced by network-filesystem protocols.
+ * This is true regardless of the language in which these other programs are
+ * written, and whether they are running on the same machine or on some other
+ * machine. The exact nature of any such inconsistencies are system-dependent
+ * and are therefore unspecified.
+ *
+ * @since 1.7
+ */
+
+public abstract class AsynchronousFileChannel
+ implements AsynchronousChannel
+{
+ /**
+ * Initializes a new instance of this class.
+ */
+ 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.
+ *
+ * The {@code options} parameter determines how the file is opened.
+ * The {@link StandardOpenOption#READ READ} and {@link StandardOpenOption#WRITE
+ * WRITE} options determines if the file should be opened for reading and/or
+ * writing. If neither option is contained in the array then an existing file
+ * is opened for reading.
+ *
+ * In addition to {@code READ} and {@code WRITE}, the following options
+ * may be present:
+ *
+ * An implementation may also support additional options.
+ *
+ * The {@code executor} parameter is the {@link ExecutorService} to
+ * which tasks are submitted to handle I/O events and dispatch completion
+ * results for operations initiated on resulting channel.
+ * The nature of these tasks is highly implementation specific and so care
+ * 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.
+ *
+ * The {@code attrs} parameter is an optional array of file {@link
+ * FileAttribute file-attributes} to set atomically when creating the file.
+ *
+ * The new channel is created by invoking the {@link
+ * FileSystemProvider#newFileChannel newFileChannel} method on the
+ * provider that created the {@code Path}.
+ *
+ * @param file
+ * The path of the file to open or create
+ * @param options
+ * Options specifying how the file is opened
+ * @param executor
+ * The thread pool or {@code null} to associate the channel with
+ * the default thread pool
+ * @param attrs
+ * An optional list of file attributes to set atomically when
+ * creating the file
+ *
+ * @return A new asynchronous file channel
+ *
+ * @throws IllegalArgumentException
+ * If the set contains an invalid combination of options
+ * @throws UnsupportedOperationException
+ * If the {@code file} is associated with a provider that does not
+ * support creating asynchronous file channels, or an unsupported
+ * open option is specified, or the array contains an attribute that
+ * cannot be set atomically when creating the file
+ * @throws IOException
+ * If an I/O error occurs
+ * @throws SecurityException
+ * If a security manager is installed and it denies an
+ * unspecified permission required by the implementation.
+ * In the case of the default provider, the {@link
+ * SecurityManager#checkRead(String)} method is invoked to check
+ * read access if the file is opened for reading. The {@link
+ * SecurityManager#checkWrite(String)} method is invoked to check
+ * write access if the file is opened for writing
+ */
+ public static AsynchronousFileChannel open(Path file,
+ Set options,
+ ExecutorService executor,
+ FileAttribute... attrs)
+ throws IOException
+ {
+ FileSystemProvider provider = file.getFileSystem().provider();
+ return provider.newAsynchronousFileChannel(file, options, executor, attrs);
+ }
+
+ private static final FileAttribute[] NO_ATTRIBUTES = new FileAttribute[0];
+
+ /**
+ * Opens or creates a file for reading and/or writing, returning an
+ * asynchronous file channel to access the file.
+ *
+ * An invocation of this method behaves in exactly the same way as the
+ * invocation
+ * The resulting channel is associated with default thread pool to which
+ * tasks are submitted to handle I/O events and dispatch to completion
+ * handlers that consume the result of asynchronous operations performed on
+ * the resulting channel.
+ *
+ * @param file
+ * The path of the file to open or create
+ * @param options
+ * Options specifying how the file is opened
+ *
+ * @return A new asynchronous file channel
+ *
+ * @throws IllegalArgumentException
+ * If the set contains an invalid combination of options
+ * @throws UnsupportedOperationException
+ * If the {@code file} is associated with a provider that does not
+ * support creating file channels, or an unsupported open option is
+ * specified
+ * @throws IOException
+ * If an I/O error occurs
+ * @throws SecurityException
+ * If a security manager is installed and it denies an
+ * unspecified permission required by the implementation.
+ * In the case of the default provider, the {@link
+ * SecurityManager#checkRead(String)} method is invoked to check
+ * read access if the file is opened for reading. The {@link
+ * SecurityManager#checkWrite(String)} method is invoked to check
+ * write access if the file is opened for writing
+ */
+ public static AsynchronousFileChannel open(Path file, OpenOption... options)
+ throws IOException
+ {
+ Set If the given size is less than the file's current size then the file
+ * is truncated, discarding any bytes beyond the new end of the file. If
+ * the given size is greater than or equal to the file's current size then
+ * the file is not modified. If this channel's file resides on a local storage device then when
+ * this method returns it is guaranteed that all changes made to the file
+ * since this channel was created, or since this method was last invoked,
+ * will have been written to that device. This is useful for ensuring that
+ * critical information is not lost in the event of a system crash.
+ *
+ * If the file does not reside on a local device then no such guarantee
+ * is made.
+ *
+ * The {@code metaData} parameter can be used to limit the number of
+ * I/O operations that this method is required to perform. Passing
+ * {@code false} for this parameter indicates that only updates to the
+ * file's content need be written to storage; passing {@code true}
+ * indicates that updates to both the file's content and metadata must be
+ * written, which generally requires at least one more I/O operation.
+ * Whether this parameter actually has any effect is dependent upon the
+ * underlying operating system and is therefore unspecified.
+ *
+ * Invoking this method may cause an I/O operation to occur even if the
+ * channel was only opened for reading. Some operating systems, for
+ * example, maintain a last-access time as part of a file's metadata, and
+ * this time is updated whenever the file is read. Whether or not this is
+ * actually done is system-dependent and is therefore unspecified.
+ *
+ * This method is only guaranteed to force changes that were made to
+ * this channel's file via the methods defined in this class.
+ *
+ * @param metaData
+ * If {@code true} then this method is required to force changes
+ * to both the file's content and metadata to be written to
+ * storage; otherwise, it need only force content changes to be
+ * written
+ *
+ * @throws ClosedChannelException
+ * If this channel is closed
+ *
+ * @throws IOException
+ * If some other I/O error occurs
+ */
+ public abstract void force(boolean metaData) throws IOException;
+
+ /**
+ * Acquires a lock on the given region of this channel's file.
+ *
+ * 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.
+ *
+ * The region specified by the {@code position} and {@code size}
+ * parameters need not be contained within, or even overlap, the actual
+ * underlying file. Lock regions are fixed in size; if a locked region
+ * initially contains the end of the file and the file grows beyond the
+ * region then the new portion of the file will not be covered by the lock.
+ * If a file is expected to grow in size and a lock on the entire file is
+ * required then a region starting at zero, and no smaller than the
+ * expected maximum size of the file, should be locked. The two-argument
+ * {@link #lock(Object,CompletionHandler)} method simply locks a region
+ * of size {@link Long#MAX_VALUE}. If a lock that overlaps the requested
+ * region is already held by this Java virtual machine, or this method has
+ * been invoked to lock an overlapping region and that operation has not
+ * completed, then this method throws {@link OverlappingFileLockException}.
+ *
+ * Some operating systems do not support a mechanism to acquire a file
+ * lock in an asynchronous manner. Consequently an implementation may
+ * acquire the file lock in a background thread or from a task executed by
+ * a thread in the associated thread pool. If there are many lock operations
+ * outstanding then it may consume threads in the Java virtual machine for
+ * indefinite periods.
+ *
+ * Some operating systems do not support shared locks, in which case a
+ * request for a shared lock is automatically converted into a request for
+ * an exclusive lock. Whether the newly-acquired lock is shared or
+ * exclusive may be tested by invoking the resulting lock object's {@link
+ * FileLock#isShared() isShared} method.
+ *
+ * File locks are held on behalf of the entire Java virtual machine.
+ * They are not suitable for controlling access to a file by multiple
+ * threads within the same virtual machine.
+ *
+ * @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)
+ * @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 OverlappingFileLockException
+ * If a lock that overlaps the requested region is already held by
+ * this Java virtual machine, or there is already a pending attempt
+ * to lock an overlapping region
+ * @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
+ * @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.
+ *
+ * An invocation of this method of the form {@code ch.lock(att,handler)}
+ * behaves in exactly the same way as the invocation
+ * 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.
+ *
+ * An invocation of this method behaves in exactly the same way as the
+ * invocation
+ * This method does not block. An invocation always returns immediately,
+ * either having acquired a lock on the requested region or having failed to
+ * do so. If it fails to acquire a lock because an overlapping lock is held
+ * by another program then it returns {@code null}. If it fails to acquire
+ * a lock for any other reason then an appropriate exception is thrown.
+ *
+ * @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,
+ * {@code false} to request an exclusive lock
+ *
+ * @return A lock object representing the newly-acquired lock,
+ * or {@code null} if the lock could not be acquired
+ * because another program holds an overlapping lock
+ *
+ * @throws IllegalArgumentException
+ * If the preconditions on the parameters do not hold
+ * @throws ClosedChannelException
+ * If this channel is closed
+ * @throws OverlappingFileLockException
+ * If a lock that overlaps the requested region is already held by
+ * this Java virtual machine, or if another thread is already
+ * blocked in this method and is attempting to lock an overlapping
+ * region of the same file
+ * @throws NonReadableChannelException
+ * If {@code shared} is true this channel but was not opened for reading
+ * @throws NonWritableChannelException
+ * If {@code shared} is false but this channel was not opened for writing
+ *
+ * @throws IOException
+ * If some other I/O error occurs
+ *
+ * @see #lock(Object,CompletionHandler)
+ * @see #lock(long,long,boolean,Object,CompletionHandler)
+ * @see #tryLock()
+ */
+ public abstract FileLock tryLock(long position, long size, boolean shared)
+ throws IOException;
+
+ /**
+ * Attempts to acquire an exclusive lock on this channel's file.
+ *
+ * An invocation of this method of the form {@code ch.tryLock()}
+ * 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.
+ *
+ * This method works in the same manner as the {@link
+ * AsynchronousByteChannel#read(ByteBuffer,Object,CompletionHandler)}
+ * 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
+ * @param position
+ * The file position at which the transfer is to begin;
+ * must be non-negative
+ * @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 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
+ * 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}.
+ *
+ * @param dst
+ * The buffer into which bytes are to be transferred
+ * @param position
+ * The file position at which the transfer is to begin;
+ * must be non-negative
+ *
+ * @return A {@code Future} object representing the pending result
+ *
+ * @throws IllegalArgumentException
+ * If the position is negative or the buffer is read-only
+ * @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.
+ * 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
+ * @param position
+ * The file position at which the transfer is to begin;
+ * must be non-negative
+ * @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 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 is equivalent to invoking {@link
+ * #write(ByteBuffer,long,Object,CompletionHandler)} with the {@code attachment}
+ * and handler parameters set to {@code null}.
+ *
+ * @param src
+ * The buffer from which bytes are to be transferred
+ * @param position
+ * The file position at which the transfer is to begin;
+ * must be non-negative
+ *
+ * @return A {@code Future} object representing the pending result
+ *
+ * @throws IllegalArgumentException
+ * If the position is negative
+ * @throws NonWritableChannelException
+ * If this channel was not opened for writing
+ */
+ public final Future An asynchronous server-socket channel is created by invoking the
+ * {@link #open open} method of this class.
+ * A newly-created asynchronous server-socket channel is open but not yet bound.
+ * It can be bound to a local address and configured to listen for connections
+ * by invoking the {@link #bind(SocketAddress,int) bind} method. Once bound,
+ * the {@link #accept(Object,CompletionHandler) accept} method
+ * is used to initiate the accepting of connections to the channel's socket.
+ * An attempt to invoke the accept method on an unbound channel will
+ * cause a {@link NotYetBoundException} to be thrown.
+ *
+ * Channels of this type are safe for use by multiple concurrent threads
+ * though at most one accept operation can be outstanding at any time.
+ * If a thread initiates an accept operation before a previous accept operation
+ * has completed then an {@link AcceptPendingException} will be thrown.
+ *
+ * Socket options are configured using the {@link #setOption(SocketOption,Object)
+ * setOption} method. Channels of this type support the following options:
+ * Usage Example:
+ * The new channel is created by invoking the {@link
+ * java.nio.channels.spi.AsynchronousChannelProvider#openAsynchronousServerSocketChannel
+ * openAsynchronousServerSocketChannel} method on the {@link
+ * java.nio.channels.spi.AsynchronousChannelProvider} object that created
+ * the given group. If the group parameter is null then the
+ * resulting channel is created by the system-wide default provider, and
+ * bound to the default group.
+ *
+ * @param group
+ * The group to which the newly constructed channel should be bound,
+ * or null for the default group
+ *
+ * @return A new asynchronous server socket channel
+ *
+ * @throws ShutdownChannelGroupException
+ * If the channel group is shutdown
+ * @throws IOException
+ * If an I/O error occurs
+ */
+ public static AsynchronousServerSocketChannel open(AsynchronousChannelGroup group)
+ throws IOException
+ {
+ AsynchronousChannelProvider provider = (group == null) ?
+ AsynchronousChannelProvider.provider() : group.provider();
+ return provider.openAsynchronousServerSocketChannel(group);
+ }
+
+ /**
+ * Opens an asynchronous server-socket channel.
+ *
+ * This method returns an asynchronous server socket channel that is
+ * bound to the default group. This method is equivalent to evaluating
+ * the expression:
+ * An invocation of this method is equivalent to the following:
+ * This method is used to establish an association between the socket and
+ * a local address. Once an association is established then the socket remains
+ * bound until the associated channel is closed.
+ *
+ * The {@code backlog} parameter is the maximum number of pending
+ * connections on the socket. Its exact semantics are implementation specific.
+ * In particular, an implementation may impose a maximum length or may choose
+ * to ignore the parameter altogther. If the {@code backlog} parameter has
+ * the value {@code 0}, or a negative value, then an implementation specific
+ * default is used.
+ *
+ * @param local
+ * The local address to bind the socket, or {@code null} to bind
+ * to an automatically assigned socket address
+ * @param backlog
+ * The maximum number of pending connections
+ *
+ * @return This channel
+ *
+ * @throws AlreadyBoundException
+ * If the socket is already bound
+ * @throws UnsupportedAddressTypeException
+ * If the type of the given address is not supported
+ * @throws SecurityException
+ * If a security manager has been installed and its {@link
+ * SecurityManager#checkListen checkListen} method denies the operation
+ * @throws ClosedChannelException
+ * If the channel is closed
+ * @throws IOException
+ * If some other I/O error occurs
+ */
+ public abstract AsynchronousServerSocketChannel bind(SocketAddress local, int backlog)
+ throws IOException;
+
+ /**
+ * @throws IllegalArgumentException {@inheritDoc}
+ * @throws ClosedChannelException {@inheritDoc}
+ * @throws IOException {@inheritDoc}
+ */
+ public abstract 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.
+ *
+ * When a new connection is accepted then the resulting {@code
+ * AsynchronousSocketChannel} will be bound to the same {@link
+ * AsynchronousChannelGroup} as this channel. If the group is {@link
+ * AsynchronousChannelGroup#isShutdown shutdown} and a connection is accepted,
+ * then the connection is closed, and the operation completes with an {@code
+ * IOException} and cause {@link ShutdownChannelGroupException}.
+ *
+ * To allow for concurrent handling of new connections, the completion
+ * handler is not invoked directly by the initiating thread when a new
+ * connection is accepted immediately (see Threading).
+ *
+ * If a security manager has been installed then it verifies that the
+ * address and port number of the connection's remote endpoint are permitted
+ * by the security manager's {@link SecurityManager#checkAccept checkAccept}
+ * method. The permission check is performed with privileges that are restricted
+ * by the calling context of this method. If the permission check fails then
+ * the connection is closed and the operation completes with a {@link
+ * SecurityException}.
+ *
+ * @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
+ *
+ * @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
+ */
+ 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}.
+ *
+ * @return an 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 Asynchronous socket channels are created in one of two ways. A newly-created
+ * {@code AsynchronousSocketChannel} is created by invoking one of the {@link
+ * #open open} methods defined by this class. A newly-created channel is open but
+ * not yet connected. A connected {@code AsynchronousSocketChannel} is created
+ * when a connection is made to the socket of an {@link AsynchronousServerSocketChannel}.
+ * It is not possible to create an asynchronous socket channel for an arbitrary,
+ * pre-existing {@link java.net.Socket socket}.
+ *
+ * A newly-created channel is connected by invoking its {@link #connect connect}
+ * method; once connected, a channel remains connected until it is closed. Whether
+ * or not a socket channel is connected may be determined by invoking its {@link
+ * #getRemoteAddress getRemoteAddress} method. An attempt to invoke an I/O
+ * operation upon an unconnected channel will cause a {@link NotYetConnectedException}
+ * to be thrown.
+ *
+ * Channels of this type are safe for use by multiple concurrent threads.
+ * They support concurrent reading and writing, though at most one read operation
+ * and one write operation can be outstanding at any time.
+ * If a thread initiates a read operation before a previous read operation has
+ * completed then a {@link ReadPendingException} will be thrown. Similarly, an
+ * attempt to initiate a write operation before a previous write has completed
+ * will throw a {@link WritePendingException}.
+ *
+ * Socket options are configured using the {@link #setOption(SocketOption,Object)
+ * setOption} method. Asynchronous socket channels support the following options:
+ * The {@link #read(ByteBuffer,long,TimeUnit,Object,CompletionHandler) read}
+ * and {@link #write(ByteBuffer,long,TimeUnit,Object,CompletionHandler) write}
+ * methods defined by this class allow a timeout to be specified when initiating
+ * a read or write operation. If the timeout elapses before an operation completes
+ * then the operation completes with the exception {@link
+ * InterruptedByTimeoutException}. A timeout may leave the channel, or the
+ * underlying connection, in an inconsistent state. Where the implementation
+ * cannot guarantee that bytes have not been read from the channel then it puts
+ * the channel into an implementation specific error state. A subsequent
+ * attempt to initiate a {@code read} operation causes an unspecified runtime
+ * exception to be thrown. Similarly if a {@code write} operation times out and
+ * the implementation cannot guarantee bytes have not been written to the
+ * channel then further attempts to {@code write} to the channel cause an
+ * unspecified runtime exception to be thrown. When a timeout elapses then the
+ * state of the {@link ByteBuffer}, or the sequence of buffers, for the I/O
+ * operation is not defined. Buffers should be discarded or at least care must
+ * be taken to ensure that the buffers are not accessed while the channel remains
+ * open.
+ *
+ * @since 1.7
+ */
+
+public abstract class AsynchronousSocketChannel
+ implements AsynchronousByteChannel, NetworkChannel
+{
+ private final AsynchronousChannelProvider provider;
+
+ /**
+ * Initializes a new instance of this class.
+ */
+ protected AsynchronousSocketChannel(AsynchronousChannelProvider provider) {
+ this.provider = provider;
+ }
+
+ /**
+ * Returns the provider that created this channel.
+ */
+ public final AsynchronousChannelProvider provider() {
+ return provider;
+ }
+
+ /**
+ * Opens an asynchronous socket channel.
+ *
+ * The new channel is created by invoking the {@link
+ * AsynchronousChannelProvider#openAsynchronousSocketChannel
+ * openAsynchronousSocketChannel} method on the {@link
+ * AsynchronousChannelProvider} that created the group. If the group parameter
+ * is {@code null} then the resulting channel is created by the system-wide
+ * default provider, and bound to the default group.
+ *
+ * @param group
+ * The group to which the newly constructed channel should be bound,
+ * or {@code null} for the default group
+ *
+ * @return A new asynchronous socket channel
+ *
+ * @throws ShutdownChannelGroupException
+ * If the channel group is shutdown
+ * @throws IOException
+ * If an I/O error occurs
+ */
+ public static AsynchronousSocketChannel open(AsynchronousChannelGroup group)
+ throws IOException
+ {
+ AsynchronousChannelProvider provider = (group == null) ?
+ AsynchronousChannelProvider.provider() : group.provider();
+ return provider.openAsynchronousSocketChannel(group);
+ }
+
+ /**
+ * Opens an asynchronous socket channel.
+ *
+ * This method returns an asynchronous socket channel that is bound to
+ * the default group.This method is equivalent to evaluating the
+ * expression:
+ * Once shutdown for reading then further reads on the channel will
+ * return {@code -1}, the end-of-stream indication. If the input side of the
+ * connection is already shutdown then invoking this method has no effect.
+ * The effect on an outstanding read operation is system dependent and
+ * therefore not specified. The effect, if any, when there is data in the
+ * socket receive buffer that has not been read, or data arrives subsequently,
+ * is also system dependent.
+ *
+ * @return The channel
+ *
+ * @throws NotYetConnectedException
+ * If this channel is not yet connected
+ * @throws ClosedChannelException
+ * If this channel is closed
+ * @throws IOException
+ * If some other I/O error occurs
+ */
+ public abstract AsynchronousSocketChannel shutdownInput() throws IOException;
+
+ /**
+ * Shutdown the connection for writing without closing the channel.
+ *
+ * Once shutdown for writing then further attempts to write to the
+ * channel will throw {@link ClosedChannelException}. If the output side of
+ * the connection is already shutdown then invoking this method has no
+ * effect. The effect on an outstanding write operation is system dependent
+ * and therefore not specified.
+ *
+ * @return The channel
+ *
+ * @throws NotYetConnectedException
+ * If this channel is not yet connected
+ * @throws ClosedChannelException
+ * If this channel is closed
+ * @throws IOException
+ * If some other I/O error occurs
+ */
+ public abstract AsynchronousSocketChannel shutdownOutput() throws IOException;
+
+ // -- state --
+
+ /**
+ * Returns the remote address to which this channel's socket is connected.
+ *
+ * Where the channel is bound and connected to an Internet Protocol
+ * socket address then the return value from this method is of type {@link
+ * java.net.InetSocketAddress}.
+ *
+ * @return The remote address; {@code null} if the channel's socket is not
+ * connected
+ *
+ * @throws ClosedChannelException
+ * If the channel is closed
+ * @throws IOException
+ * If an I/O error occurs
+ */
+ public abstract SocketAddress getRemoteAddress() throws IOException;
+
+ // -- asynchronous operations --
+
+ /**
+ * Connects this channel.
+ *
+ * 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 performs exactly the same security checks as the {@link
+ * java.net.Socket} class. That is, if a security manager has been
+ * installed then this method verifies that its {@link
+ * java.lang.SecurityManager#checkConnect checkConnect} method permits
+ * connecting to the address and port number of the given remote endpoint.
+ *
+ * @param remote
+ * The remote address to which this channel is to be connected
+ * @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 AlreadyConnectedException
+ * If this channel is already connected
+ * @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
+ * @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}.
+ *
+ * @param remote
+ * The remote address to which this channel is to be connected
+ *
+ * @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 AlreadyConnectedException
+ * If this channel is already connected
+ * @throws ConnectionPendingException
+ * If a connection operation is already in progress on this channel
+ * @throws SecurityException
+ * 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.
+ *
+ * If a timeout is specified and the timeout elapses before the operation
+ * completes then the operation completes with the exception {@link
+ * InterruptedByTimeoutException}. Where a timeout occurs, and the
+ * implementation cannot guarantee that bytes have not been read, or will not
+ * be read from the channel into the given buffer, then further attempts to
+ * read from the channel will cause an unspecific runtime exception to be
+ * thrown.
+ *
+ * Otherwise this method works in the same manner as the {@link
+ * AsynchronousByteChannel#read(ByteBuffer,Object,CompletionHandler)}
+ * method.
+ *
+ * @param dst
+ * The buffer into which bytes are to be transferred
+ * @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 {@code timeout} parameter is negative or the buffer is
+ * read-only
+ * @throws ReadPendingException
+ * If a read operation is already in progress on this channel
+ * @throws NotYetConnectedException
+ * If this channel is not yet connected
+ * @throws ShutdownChannelGroupException
+ * If a handler is specified, and the channel group is shutdown
+ */
+ 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
+ * subsequence of the given buffer array, that is,
+ *
+ * Suppose that a byte sequence of length n is read, where
+ * 0 < n <= r.
+ * Up to the first dsts[offset].remaining() bytes of this sequence
+ * are transferred into buffer dsts[offset], up to the next
+ * dsts[offset+1].remaining() bytes are transferred into buffer
+ * dsts[offset+1], and so forth, until the entire byte sequence
+ * is transferred into the given buffers. As many bytes as possible are
+ * transferred into each buffer, hence the final position of each updated
+ * buffer, except the last updated buffer, is guaranteed to be equal to
+ * that buffer's limit. The underlying operating system may impose a limit
+ * on the number of buffers that may be used in an I/O operation. Where the
+ * number of buffers (with bytes 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 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
+ * implementation cannot guarantee that bytes have not been read, or will not
+ * be read from the channel into the given buffers, then further attempts to
+ * read from the channel will cause an unspecific runtime exception to be
+ * thrown.
+ *
+ * @param dsts
+ * The buffers into which bytes are to be transferred
+ * @param offset
+ * The offset within the buffer array of the first buffer into which
+ * bytes are to be transferred; must be non-negative and no larger than
+ * {@code dsts.length}
+ * @param length
+ * The maximum number of buffers to be accessed; must be non-negative
+ * and no larger than {@code dsts.length - offset}
+ * @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 IndexOutOfBoundsException
+ * If the pre-conditions for the {@code offset} and {@code length}
+ * parameter aren't met
+ * @throws IllegalArgumentException
+ * If the {@code timeout} parameter is negative, or a buffer is
+ * read-only
+ * @throws ReadPendingException
+ * If a read operation is already in progress on this channel
+ * @throws NotYetConnectedException
+ * If this channel is not yet connected
+ * @throws ShutdownChannelGroupException
+ * If a handler is specified, and the channel group is shutdown
+ */
+ 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.
+ *
+ * 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
+ * implementation cannot guarantee that bytes have not been written, or will
+ * not be written to the channel from the given buffer, then further attempts
+ * to write to the channel will cause an unspecific runtime exception to be
+ * thrown.
+ *
+ * Otherwise this method works in the same manner as the {@link
+ * AsynchronousByteChannel#write(ByteBuffer,Object,CompletionHandler)}
+ * method.
+ *
+ * @param src
+ * The buffer from which bytes are to be retrieved
+ * @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 {@code timeout} parameter is negative
+ * @throws WritePendingException
+ * If a write operation is already in progress on this channel
+ * @throws NotYetConnectedException
+ * If this channel is not yet connected
+ * @throws ShutdownChannelGroupException
+ * If a handler is specified, and the channel group is shutdown
+ */
+ 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
+ * subsequence of the given buffer array, that is,
+ *
+ * Suppose that a byte sequence of length n is written, where
+ * 0 < n <= r.
+ * Up to the first srcs[offset].remaining() bytes of this sequence
+ * are written from buffer srcs[offset], up to the next
+ * srcs[offset+1].remaining() bytes are written from buffer
+ * srcs[offset+1], and so forth, until the entire byte sequence is
+ * written. As many bytes as possible are written from each buffer, hence
+ * the final position of each updated buffer, except the last updated
+ * buffer, is guaranteed to be equal to that buffer's limit. The underlying
+ * operating system may impose a limit on the number of buffers that may be
+ * used in an I/O operation. Where the number of buffers (with bytes
+ * 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
+ * implementation cannot guarantee that bytes have not been written, or will
+ * not be written to the channel from the given buffers, then further attempts
+ * to write to the channel will cause an unspecific runtime exception to be
+ * thrown.
+ *
+ * @param srcs
+ * The buffers from which bytes are to be retrieved
+ * @param offset
+ * The offset within the buffer array of the first buffer from which
+ * bytes are to be retrieved; must be non-negative and no larger
+ * than {@code srcs.length}
+ * @param length
+ * The maximum number of buffers to be accessed; must be non-negative
+ * and no larger than {@code srcs.length - offset}
+ * @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 IndexOutOfBoundsException
+ * If the pre-conditions for the {@code offset} and {@code length}
+ * parameter aren't met
+ * @throws IllegalArgumentException
+ * If the {@code timeout} parameter is negative
+ * @throws WritePendingException
+ * If a write operation is already in progress on this channel
+ * @throws NotYetConnectedException
+ * If this channel is not yet connected
+ * @throws ShutdownChannelGroupException
+ * If a handler is specified, and the channel group is shutdown
+ */
+ public abstract Future The stream will not be buffered, and it will not support the {@link
+ * InputStream#mark mark} or {@link InputStream#reset reset} methods. The
+ * stream will be safe for access by multiple concurrent threads. Closing
+ * the stream will in turn cause the channel to be closed. The stream will not be buffered. The stream will be safe for access
+ * by multiple concurrent threads. Closing the stream will in turn cause
+ * the channel to be closed. The asynchronous channels defined in this package allow a completion
+ * 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.
+ *
+ * @param Socket options are configured using the {@link #setOption(SocketOption,Object)
- * setOption} method. Datagram channels support the following options:
+ * setOption} method. A datagram channel to an Internet Protocol socket supports
+ * the following options:
* A file channel has a current position within its file which can
- * be both {@link #position() queried {@note revised}
+ * 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
* of bytes that can be read and written and whose current {@link #size
- * Bytes may be {@link #read(ByteBuffer, long) Bytes may be {@link #read(ByteBuffer, long) read} or
+ * {@link #write(ByteBuffer, long) written} at an absolute
* position in a file in a way that does not affect the channel's current
* position. A region of a file may be {@link #map A region of a file may be {@link #map mapped}
* directly into memory; for large files this is often much more efficient
* than invoking the usual read or write methods.
* Updates made to a file may be {@link #force Updates made to a file may be {@link #force forced
+ * out} to the underlying storage device, ensuring that data are not
* lost in the event of a system crash. Bytes can be transferred from a file {@link #transferTo Bytes can be transferred from a file {@link #transferTo to
+ * some other channel}, and {@link #transferFrom vice
+ * versa}, in a way that can be optimized by many operating systems
* into a very fast transfer directly to or from the filesystem cache.
* A region of a file may be {@link FileLock A region of a file may be {@link FileLock locked}
* against access by other programs. This class does not define methods for opening existing files or for
- * creating new ones; such methods may be added in a future release. In this
- * release a file channel can be obtained from an existing {@link
- * java.io.FileInputStream#getChannel FileInputStream}, {@link
+ * A file channel is created by invoking one of the {@link #open open}
+ * methods defined by this class. A file channel can also be obtained from an
+ * existing {@link java.io.FileInputStream#getChannel FileInputStream}, {@link
* java.io.FileOutputStream#getChannel FileOutputStream}, or {@link
* java.io.RandomAccessFile#getChannel RandomAccessFile} object by invoking
* that object's getChannel method, which returns a file channel that
- * is connected to the same underlying file.
- *
- * The state of a file channel is intimately connected to that of the
- * object whose getChannel method returned the channel. Changing the
- * channel's position, whether explicitly or by reading or writing bytes, will
- * change the file position of the originating object, and vice versa.
- * Changing the file's length via the file channel will change the length seen
- * via the originating object, and vice versa. Changing the file's content by
- * writing bytes will change the content seen by the originating object, and
- * vice versa.
+ * is connected to the same underlying file. Where the file channel is obtained
+ * from an existing stream or random access file then the state of the file
+ * channel is intimately connected to that of the object whose getChannel
+ * method returned the channel. Changing the channel's position, whether
+ * explicitly or by reading or writing bytes, will change the file position of
+ * the originating object, and vice versa. Changing the file's length via the
+ * file channel will change the length seen via the originating object, and vice
+ * versa. Changing the file's content by writing bytes will change the content
+ * seen by the originating object, and vice versa.
*
- * At various points this class specifies that an
+ * At various points this class specifies that an
* instance that is "open for reading," "open for writing," or "open for
* reading and writing" is required. A channel obtained via the {@link
* java.io.FileInputStream#getChannel getChannel} method of a {@link
@@ -127,7 +132,7 @@ import java.nio.channels.spi.AbstractInterruptibleChannel;
* was created with mode "r" and will be open for reading and writing
* if the instance was created with mode "rw".
*
- * A file channel that is open for writing may be in
+ * A file channel that is open for writing may be in
* append mode, for example if it was obtained from a file-output stream
* that was created by invoking the {@link
* java.io.FileOutputStream#FileOutputStream(java.io.File,boolean)
@@ -138,7 +143,6 @@ import java.nio.channels.spi.AbstractInterruptibleChannel;
* of the data are done in a single atomic operation is system-dependent and
* therefore unspecified.
*
- *
* @see java.io.FileInputStream#getChannel()
* @see java.io.FileOutputStream#getChannel()
* @see java.io.RandomAccessFile#getChannel()
@@ -147,18 +151,190 @@ import java.nio.channels.spi.AbstractInterruptibleChannel;
* @author Mike McCloskey
* @author JSR-51 Expert Group
* @since 1.4
+ * @updated 1.7
*/
public abstract class FileChannel
extends AbstractInterruptibleChannel
- implements ByteChannel, GatheringByteChannel, ScatteringByteChannel
+ implements SeekableByteChannel, GatheringByteChannel, ScatteringByteChannel
{
-
/**
* Initializes a new instance of this class.
*/
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.
+ * The {@link StandardOpenOption#READ READ} and {@link StandardOpenOption#WRITE
+ * WRITE} options determine if the file should be opened for reading and/or
+ * writing. If neither option (or the {@link StandardOpenOption#APPEND APPEND}
+ * option) is contained in the array then the file is opened for reading.
+ * By default reading or writing commences at the beginning of the file.
+ *
+ * In the addition to {@code READ} and {@code WRITE}, the following
+ * options may be present:
+ *
+ * An implementation may also support additional options.
+ *
+ * The {@code attrs} parameter is an optional array of file {@link
+ * FileAttribute file-attributes} to set atomically when creating the file.
+ *
+ * The new channel is created by invoking the {@link
+ * FileSystemProvider#newFileChannel newFileChannel} method on the
+ * provider that created the {@code Path}.
+ *
+ * @param file
+ * The path of the file to open or create
+ * @param options
+ * Options specifying how the file is opened
+ * @param attrs
+ * An optional list of file attributes to set atomically when
+ * creating the file
+ *
+ * @return A new file channel
+ *
+ * @throws IllegalArgumentException
+ * If the set contains an invalid combination of options
+ * @throws UnsupportedOperationException
+ * If the {@code file} is associated with a provider that does not
+ * support creating file channels, or an unsupported open option is
+ * specified, or the array contains an attribute that cannot be set
+ * atomically when creating the file
+ * @throws IOException
+ * If an I/O error occurs
+ * @throws SecurityException
+ * If a security manager is installed and it denies an
+ * unspecified permission required by the implementation.
+ * In the case of the default provider, the {@link
+ * SecurityManager#checkRead(String)} method is invoked to check
+ * read access if the file is opened for reading. The {@link
+ * SecurityManager#checkWrite(String)} method is invoked to check
+ * write access if the file is opened for writing
+ *
+ * @since 1.7
+ */
+ public static FileChannel open(Path file,
+ Set options,
+ FileAttribute... attrs)
+ throws IOException
+ {
+ FileSystemProvider provider = file.getFileSystem().provider();
+ return provider.newFileChannel(file, options, attrs);
+ }
+
+ 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
+ * invocation
+ * This method is only guaranteed to force changes that were made to
* this channel's file via the methods defined in this class. It may or
* may not force changes that were made by modifying the content of a
- * {@link MappedByteBuffer mapped byte buffer The {@link MappedByteBuffer mapped byte buffer The {@link MappedByteBuffer mapped byte buffer}
* returned by this method will have a position of zero and a limit and
* capacity of size; its mark will be undefined. The buffer and
* the mapping that it represents will remain valid until the buffer itself
@@ -717,6 +893,8 @@ public abstract class FileChannel
* The size of the region to be mapped; must be non-negative and
* no greater than {@link java.lang.Integer#MAX_VALUE}
*
+ * @return The mapped byte buffer
+ *
* @throws NonReadableChannelException
* If the mode is {@link MapMode#READ_ONLY READ_ONLY} but
* this channel was not opened for reading
diff --git a/jdk/src/share/classes/java/nio/channels/FileLock.java b/jdk/src/share/classes/java/nio/channels/FileLock.java
index 921922242d77503b92842be020ba3e4a2ecb6bc5..b0ec37f1ba5a78f2c7a1b425fceb9d5686a6a232 100644
--- a/jdk/src/share/classes/java/nio/channels/FileLock.java
+++ b/jdk/src/share/classes/java/nio/channels/FileLock.java
@@ -1,5 +1,5 @@
/*
- * Copyright 2001 Sun Microsystems, Inc. All Rights Reserved.
+ * Copyright 2001-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
@@ -27,14 +27,16 @@ package java.nio.channels;
import java.io.IOException;
-
/**
* A token representing a lock on a region of a file.
*
* A file-lock object is created each time a lock is acquired on a file via
* one of the {@link FileChannel#lock(long,long,boolean) lock} or {@link
- * FileChannel#tryLock(long,long,boolean) tryLock} methods of the {@link
- * FileChannel} class.
+ * FileChannel#tryLock(long,long,boolean) tryLock} methods of the
+ * {@link FileChannel} class, or the {@link
+ * AsynchronousFileChannel#lock(long,long,boolean,Object,CompletionHandler) lock}
+ * or {@link AsynchronousFileChannel#tryLock(long,long,boolean) tryLock}
+ * methods of the {@link AsynchronousFileChannel} class.
*
* A file-lock object is initially valid. It remains valid until the lock
* is released by invoking the {@link #release release} method, by closing the
@@ -70,8 +72,7 @@ import java.io.IOException;
* File-lock objects are safe for use by multiple concurrent threads.
*
*
- *
- * This file-locking API is intended to map directly to the native locking
* facility of the underlying operating system. Thus the locks held on a file
@@ -93,7 +94,7 @@ import java.io.IOException;
*
* On some systems, acquiring a mandatory lock on a region of a file
* prevents that region from being {@link java.nio.channels.FileChannel#map
- * On some systems, closing a channel releases all locks held by the Java
@@ -113,11 +114,12 @@ import java.io.IOException;
* @author Mark Reinhold
* @author JSR-51 Expert Group
* @since 1.4
+ * @updated 1.7
*/
public abstract class FileLock {
- private final FileChannel channel;
+ private final Channel channel;
private final long position;
private final long size;
private final boolean shared;
@@ -159,11 +161,66 @@ public abstract class FileLock {
}
/**
- * Returns the file channel upon whose file this lock is held. This method has been superseded by the {@link #acquiredBy acquiredBy}
+ * method.
+ *
+ * @return The file channel, or {@code null} if the file lock was not
+ * acquired by a file channel.
*/
public final FileChannel channel() {
+ return (channel instanceof FileChannel) ? (FileChannel)channel : null;
+ }
+
+ /**
+ * {@note new}
+ * Returns the channel upon whose file this lock was acquired.
+ *
+ * @return The channel upon whose file this lock was acquired.
+ *
+ * @since 1.7
+ */
+ public Channel acquiredBy() {
return channel;
}
diff --git a/jdk/src/share/classes/java/nio/channels/MembershipKey.java b/jdk/src/share/classes/java/nio/channels/MembershipKey.java
index 0d2fc52bc4de195ca11c30016a1da39b807015df..804e6724ad0c40ed898cf820d406001febbefc59 100644
--- a/jdk/src/share/classes/java/nio/channels/MembershipKey.java
+++ b/jdk/src/share/classes/java/nio/channels/MembershipKey.java
@@ -1,5 +1,5 @@
/*
- * Copyright 2007-2008 Sun Microsystems, Inc. All Rights Reserved.
+ * Copyright 2007-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
@@ -28,7 +28,6 @@ package java.nio.channels;
import java.net.InetAddress;
import java.net.NetworkInterface;
import java.io.IOException;
-import java.util.List;
/**
* A token representing the membership of an Internet Protocol (IP) multicast
@@ -38,7 +37,7 @@ import java.util.List;
* to the group, or it may be source-specific, meaning that it
* represents a membership that receives only datagrams from a specific source
* address. Whether or not a membership key is source-specific may be determined
- * by invoking its {@link #getSourceAddress() getSourceAddress} method.
+ * by invoking its {@link #sourceAddress() sourceAddress} method.
*
* A membership key is valid upon creation and remains valid until the
* membership is dropped by invoking the {@link #drop() drop} method, or
@@ -93,11 +92,8 @@ public abstract class MembershipKey {
* If the multicast group membership is already invalid then invoking this
* method has no effect. Once a multicast group membership is invalid,
* it remains invalid forever.
- *
- * @throws IOException
- * If an I/O error occurs
*/
- public abstract void drop() throws IOException;
+ public abstract void drop();
/**
* Block multicast datagrams from the given source address.
@@ -140,10 +136,8 @@ public abstract class MembershipKey {
* @throws IllegalStateException
* If the given source address is not currently blocked or the
* membership key is no longer valid
- * @throws IOException
- * If an I/O error occurs
*/
- public abstract MembershipKey unblock(InetAddress source) throws IOException;
+ public abstract MembershipKey unblock(InetAddress source);
/**
* Returns the channel for which this membership key was created. This
@@ -152,7 +146,7 @@ public abstract class MembershipKey {
*
* @return the channel
*/
- public abstract MulticastChannel getChannel();
+ public abstract MulticastChannel channel();
/**
* Returns the multicast group for which this membership key was created.
@@ -161,7 +155,7 @@ public abstract class MembershipKey {
*
* @return the multicast group
*/
- public abstract InetAddress getGroup();
+ public abstract InetAddress group();
/**
* Returns the network interface for which this membership key was created.
@@ -170,7 +164,7 @@ public abstract class MembershipKey {
*
* @return the network interface
*/
- public abstract NetworkInterface getNetworkInterface();
+ public abstract NetworkInterface networkInterface();
/**
* Returns the source address if this membership key is source-specific,
@@ -179,5 +173,5 @@ public abstract class MembershipKey {
* @return The source address if this membership key is source-specific,
* otherwise {@code null}
*/
- public abstract InetAddress getSourceAddress();
+ public abstract InetAddress sourceAddress();
}
diff --git a/jdk/src/share/classes/java/nio/channels/MulticastChannel.java b/jdk/src/share/classes/java/nio/channels/MulticastChannel.java
index 440dd2a8b85a6eaa76eb2b4e7b754cdff1d2c01a..1cacf98e69c8393e537f1833a795be4f7c26f6ff 100644
--- a/jdk/src/share/classes/java/nio/channels/MulticastChannel.java
+++ b/jdk/src/share/classes/java/nio/channels/MulticastChannel.java
@@ -1,5 +1,5 @@
/*
- * Copyright 2007-2008 Sun Microsystems, Inc. All Rights Reserved.
+ * Copyright 2007-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
@@ -122,6 +122,22 @@ import java.net.StandardSocketOption; // javadoc
public interface MulticastChannel
extends NetworkChannel
{
+ /**
+ * Closes this channel.
+ *
+ * If the channel is a member of a multicast group then the membership
+ * is {@link MembershipKey#drop dropped}. Upon return, the {@link
+ * MembershipKey membership-key} will be {@link MembershipKey#isValid
+ * invalid}.
+ *
+ * This method otherwise behaves exactly as specified by the {@link
+ * Channel} interface.
+ *
+ * @throws IOException
+ * If an I/O error occurs
+ */
+ @Override void close() throws IOException;
+
/**
* Joins a multicast group to begin receiving all datagrams sent to the group,
* returning a membership key.
@@ -130,7 +146,7 @@ public interface MulticastChannel
* interface to receive all datagrams then the membership key, representing
* that membership, is returned. Otherwise this channel joins the group and
* the resulting new membership key is returned. The resulting membership key
- * is not {@link MembershipKey#getSourceAddress source-specific}.
+ * is not {@link MembershipKey#sourceAddress source-specific}.
*
* A multicast channel may join several multicast groups, including
* the same group on more than one interface. An implementation may impose a
@@ -150,6 +166,8 @@ public interface MulticastChannel
* @throws IllegalStateException
* If the channel already has source-specific membership of the
* group on the interface
+ * @throws UnsupportedOperationException
+ * If the channel's socket is not an Internet Protocol socket
* @throws ClosedChannelException
* If this channel is closed
* @throws IOException
@@ -170,7 +188,7 @@ public interface MulticastChannel
* interface to receive datagrams from the given source address then the
* membership key, representing that membership, is returned. Otherwise this
* channel joins the group and the resulting new membership key is returned.
- * The resulting membership key is {@link MembershipKey#getSourceAddress
+ * The resulting membership key is {@link MembershipKey#sourceAddress
* source-specific}.
*
* Membership is cumulative and this method may be invoked
@@ -196,7 +214,8 @@ public interface MulticastChannel
* If the channel is currently a member of the group on the given
* interface to receive all datagrams
* @throws UnsupportedOperationException
- * If the underlying operation system does not support source filtering
+ * If the channel's socket is not an Internet Protocol socket or
+ * source filtering is not supported
* @throws ClosedChannelException
* If this channel is closed
* @throws IOException
diff --git a/jdk/src/share/classes/java/nio/channels/NetworkChannel.java b/jdk/src/share/classes/java/nio/channels/NetworkChannel.java
index fae642fcbdbe5263af754c847757296e39e0d417..103427759e757ce34cc3cf9ec1f55b02e4388e34 100644
--- a/jdk/src/share/classes/java/nio/channels/NetworkChannel.java
+++ b/jdk/src/share/classes/java/nio/channels/NetworkChannel.java
@@ -1,5 +1,5 @@
/*
- * Copyright 2007-2008 Sun Microsystems, Inc. All Rights Reserved.
+ * Copyright 2007-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
@@ -95,9 +95,10 @@ public interface NetworkChannel
* java.net.InetSocketAddress}.
*
* @return The socket address that the socket is bound to, or {@code null}
- * if the channel is not {@link #isOpen open} or the channel's socket
- * is not bound
+ * if the channel's socket is not bound
*
+ * @throws ClosedChannelException
+ * If the channel is closed
* @throws IOException
* If an I/O error occurs
*/
@@ -114,9 +115,10 @@ public interface NetworkChannel
*
* @return This channel
*
+ * @throws UnsupportedOperationException
+ * If the socket option is not supported by this channel
* @throws IllegalArgumentException
- * If the socket option is not supported by this channel, or
- * the value is not a valid value for this socket option
+ * If the value is not a valid value for this socket option
* @throws ClosedChannelException
* If this channel is closed
* @throws IOException
@@ -135,7 +137,7 @@ public interface NetworkChannel
* @return The value of the socket option. A value of {@code null} may be
* a valid value for some socket options.
*
- * @throws IllegalArgumentException
+ * @throws UnsupportedOperationException
* If the socket option is not supported by this channel
* @throws ClosedChannelException
* If this channel is closed
@@ -154,5 +156,5 @@ public interface NetworkChannel
*
* @return A set of the socket options supported by this channel
*/
- Set A seekable byte channel is connected to an entity, typically a file,
+ * that contains a variable-length sequence of bytes that can be read and
+ * written. The current position can be {@link #position() queried} and
+ * {@link #position(long) modified}. The channel also provides access to
+ * the current size of the entity to which the channel is connected. The
+ * size increases when bytes are written beyond its current size; the size
+ * decreases when it is {@link #truncate truncated}.
+ *
+ * The {@link #position(long) position} and {@link #truncate truncate} methods
+ * which do not otherwise have a value to return are specified to return the
+ * channel upon which they are invoked. This allows method invocations to be
+ * chained. Implementations of this interface should specialize the return type
+ * so that method invocations on the implementation class can be chained.
+ *
+ * @since 1.7
+ * @see java.nio.file.FileRef#newByteChannel
+ */
+
+public interface SeekableByteChannel
+ extends ByteChannel
+{
+ /**
+ * Reads a sequence of bytes from this channel into the given buffer.
+ *
+ * Bytes are read starting at this channel's current position, and
+ * then the position is updated with the number of bytes actually read.
+ * Otherwise this method behaves exactly as specified in the {@link
+ * ReadableByteChannel} interface.
+ */
+ @Override
+ int read(ByteBuffer dst) throws IOException;
+
+ /**
+ * Writes a sequence of bytes to this channel from the given buffer.
+ *
+ * Bytes are written starting at this channel's current position, unless
+ * the channel is connected to an entity such as a file that is opened with
+ * the {@link java.nio.file.StandardOpenOption#APPEND APPEND} option, in
+ * which case the position is first advanced to the end. The entity to which
+ * the channel is connected is grown, if necessary, to accommodate the
+ * written bytes, and then the position is updated with the number of bytes
+ * actually written. Otherwise this method behaves exactly as specified by
+ * the {@link WritableByteChannel} interface.
+ */
+ @Override
+ int write(ByteBuffer src) throws IOException;
+
+ /**
+ * Returns this channel's position.
+ *
+ * @return This channel's position,
+ * a non-negative integer counting the number of bytes
+ * from the beginning of the entity to the current position
+ *
+ * @throws ClosedChannelException
+ * If this channel is closed
+ * @throws IOException
+ * If some other I/O error occurs
+ */
+ long position() throws IOException;
+
+ /**
+ * Sets this channel's position.
+ *
+ * Setting the position to a value that is greater than the current size
+ * is legal but does not change the size of the entity. A later attempt to
+ * read bytes at such a position will immediately return an end-of-file
+ * indication. A later attempt to write bytes at such a position will cause
+ * the entity to grow to accommodate the new bytes; the values of any bytes
+ * between the previous end-of-file and the newly-written bytes are
+ * unspecified.
+ *
+ * Setting the channel's position is not recommended when connected to
+ * an entity, typically a file, that is opened with the {@link
+ * java.nio.file.StandardOpenOption#APPEND APPEND} option. When opened for
+ * append, the position is first advanced to the end before writing.
+ *
+ * @param newPosition
+ * The new position, a non-negative integer counting
+ * the number of bytes from the beginning of the entity
+ *
+ * @return This channel
+ *
+ * @throws ClosedChannelException
+ * If this channel is closed
+ * @throws IllegalArgumentException
+ * If the new position is negative
+ * @throws IOException
+ * If some other I/O error occurs
+ */
+ SeekableByteChannel position(long newPosition) throws IOException;
+
+ /**
+ * Returns the current size of entity to which this channel is connected.
+ *
+ * @return The current size, measured in bytes
+ *
+ * @throws ClosedChannelException
+ * If this channel is closed
+ * @throws IOException
+ * If some other I/O error occurs
+ */
+ long size() throws IOException;
+
+ /**
+ * Truncates the entity, to which this channel is connected, to the given
+ * size.
+ *
+ * If the given size is less than the current size then the entity is
+ * truncated, discarding any bytes beyond the new end. If the given size is
+ * greater than or equal to the current size then the entity is not modified.
+ * In either case, if the current position is greater than the given size
+ * then it is set to that size.
+ *
+ * An implementation of this interface may prohibit truncation when
+ * connected to an entity, typically a file, opened with the {@link
+ * java.nio.file.StandardOpenOption#APPEND APPEND} option.
+ *
+ * @param size
+ * The new size, a non-negative byte count
+ *
+ * @return This channel
+ *
+ * @throws NonWritableChannelException
+ * If this channel was not opened for writing
+ * @throws ClosedChannelException
+ * If this channel is closed
+ * @throws IllegalArgumentException
+ * If the new size is negative
+ * @throws IOException
+ * If some other I/O error occurs
+ */
+ SeekableByteChannel truncate(long size) throws IOException;
+}
diff --git a/jdk/src/share/classes/java/nio/channels/ServerSocketChannel.java b/jdk/src/share/classes/java/nio/channels/ServerSocketChannel.java
index 84ea062c9f08b8cb2d2f2c60882f96ae193fc18d..5be9bc7cb15a82d2e854ac559326f2c896793b0d 100644
--- a/jdk/src/share/classes/java/nio/channels/ServerSocketChannel.java
+++ b/jdk/src/share/classes/java/nio/channels/ServerSocketChannel.java
@@ -1,5 +1,5 @@
/*
- * Copyright 2000-2008 Sun Microsystems, Inc. All Rights Reserved.
+ * Copyright 2000-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
@@ -29,7 +29,8 @@ import java.io.IOException;
import java.net.ServerSocket;
import java.net.SocketOption;
import java.net.SocketAddress;
-import java.nio.channels.spi.*;
+import java.nio.channels.spi.AbstractSelectableChannel;
+import java.nio.channels.spi.SelectorProvider;
/**
* A selectable channel for stream-oriented listening sockets.
@@ -195,6 +196,7 @@ public abstract class ServerSocketChannel
throws IOException;
/**
+ * @throws UnsupportedOperationException {@inheritDoc}
* @throws IllegalArgumentException {@inheritDoc}
* @throws ClosedChannelException {@inheritDoc}
* @throws IOException {@inheritDoc}
diff --git a/jdk/src/share/classes/java/nio/channels/SocketChannel.java b/jdk/src/share/classes/java/nio/channels/SocketChannel.java
index 2e96bd2e4ceafe3f8f72e76163f6b3d1ad2b5fd7..975048df0c022949de9f1ed69fb110e18445a247 100644
--- a/jdk/src/share/classes/java/nio/channels/SocketChannel.java
+++ b/jdk/src/share/classes/java/nio/channels/SocketChannel.java
@@ -1,5 +1,5 @@
/*
- * Copyright 2000-2008 Sun Microsystems, Inc. All Rights Reserved.
+ * Copyright 2000-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
@@ -30,7 +30,8 @@ import java.net.Socket;
import java.net.SocketOption;
import java.net.SocketAddress;
import java.nio.ByteBuffer;
-import java.nio.channels.spi.*;
+import java.nio.channels.spi.AbstractSelectableChannel;
+import java.nio.channels.spi.SelectorProvider;
/**
* A selectable channel for stream-oriented connecting sockets.
@@ -212,7 +213,7 @@ public abstract class SocketChannel
/**
* @throws ConnectionPendingException
- * If a non-blocking connection operation is already in progress on
+ * If a non-blocking connect operation is already in progress on
* this channel
* @throws AlreadyBoundException {@inheritDoc}
* @throws UnsupportedAddressTypeException {@inheritDoc}
@@ -226,6 +227,7 @@ public abstract class SocketChannel
throws IOException;
/**
+ * @throws UnsupportedOperationException {@inheritDoc}
* @throws IllegalArgumentException {@inheritDoc}
* @throws ClosedChannelException {@inheritDoc}
* @throws IOException {@inheritDoc}
@@ -432,15 +434,17 @@ public abstract class SocketChannel
* socket address then the return value from this method is of type {@link
* java.net.InetSocketAddress}.
*
- * @return The remote address; {@code null} if the channel is not {@link
- * #isOpen open} or the channel's socket is not connected
+ * @return The remote address; {@code null} if the channel's socket is not
+ * connected
*
+ * @throws ClosedChannelException
+ * If the channel is closed
* @throws IOException
* If an I/O error occurs
*
* @since 1.7
*/
- public abstract SocketAddress getConnectedAddress() throws IOException;
+ public abstract SocketAddress getRemoteAddress() throws IOException;
// -- ByteChannel operations --
diff --git a/jdk/src/share/classes/java/nio/channels/exceptions b/jdk/src/share/classes/java/nio/channels/exceptions
index 04cfbe03e29a89d57b2ff375a57bfce1744e7212..fed9f72ab2e068642926f5467b61dda42434a3eb 100644
--- a/jdk/src/share/classes/java/nio/channels/exceptions
+++ b/jdk/src/share/classes/java/nio/channels/exceptions
@@ -1,5 +1,5 @@
#
-# Copyright 2000-2008 Sun Microsystems, Inc. All Rights Reserved.
+# Copyright 2000-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
@@ -150,6 +150,21 @@ gen OverlappingFileLockException "
SINCE=1.7
+SUPER=java.io.IOException
+
+gen InterruptedByTimeoutException "
+ * Checked exception received by a thread when a timeout elapses before an
+ * asynchronous operation completes." \
+ -4268008601014042947L
+
+SUPER=IllegalArgumentException
+
+gen IllegalChannelGroupException "
+ * Unchecked exception thrown when an attempt is made to open a channel
+ * in a group that was not created by the same provider. " \
+ -2495041211157744253L
+
+
SUPER=IllegalStateException
gen AlreadyBoundException "
@@ -157,3 +172,23 @@ gen AlreadyBoundException "
* network oriented channel that is already bound." \
6796072983322737592L
+gen AcceptPendingException "
+ * Unchecked exception thrown when an attempt is made to initiate an accept
+ * operation on a channel and a previous accept operation has not completed." \
+ 2721339977965416421L
+
+gen ReadPendingException "
+ * Unchecked exception thrown when an attempt is made to read from an
+ * asynchronous socket channel and a previous read has not completed." \
+ 1986315242191227217L
+
+gen WritePendingException "
+ * Unchecked exception thrown when an attempt is made to write to an
+ * asynchronous socket channel and a previous write has not completed." \
+ 7031871839266032276L
+
+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." \
+ -3903801676350154157L
diff --git a/jdk/src/share/classes/java/nio/channels/package-info.java b/jdk/src/share/classes/java/nio/channels/package-info.java
index e8c2a929d4b9f4273cff66a59cd8d0e2728fa0e7..47a1cb5f97928b316961c33070bc1c6abdd0b453 100644
--- a/jdk/src/share/classes/java/nio/channels/package-info.java
+++ b/jdk/src/share/classes/java/nio/channels/package-info.java
@@ -1,5 +1,5 @@
/*
- * Copyright 2001-2008 Sun Microsystems, Inc. All Rights Reserved.
+ * Copyright 2001-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
@@ -46,6 +46,10 @@
* Asynchronous I/O Description {@link java.nio.channels.AsynchronousChannel Asynchronous channels} are a
+ * special type of channel capable of asynchronous I/O operations. Asynchronous
+ * channels are non-blocking and define methods to initiate asynchronous
+ * operations, returning a {@link java.util.concurrent.Future} representing the
+ * pending result of each operation. The {@code Future} can be used to poll or
+ * wait for the result of the operation. Asynchronous I/O operations can also
+ * specify a {@link java.nio.channels.CompletionHandler} to invoke when the
+ * operation completes. A completion handler is user provided code that is executed
+ * to consume the result of I/O operation.
+ *
+ * This package defines asynchronous-channel classes that are connected to
+ * a stream-oriented connecting or listening socket, or a datagram-oriented socket.
+ * It also defines the {@link java.nio.channels.AsynchronousFileChannel} class
+ * for asynchronous reading, writing, and manipulating a file. As with the {@link
+ * java.nio.channels.FileChannel} it supports operations to truncate the file
+ * to a specific size, force updates to the file to be written to the storage
+ * device, or acquire locks on the whole file or on a specific region of the file.
+ * Unlike the {@code FileChannel} it does not define methods for mapping a
+ * region of the file directly into memory. Where memory mapped I/O is required,
+ * then a {@code FileChannel} can be used.
+ *
+ * Asynchronous channels are bound to an asynchronous channel group for the
+ * purpose of resource sharing. A group has an associated {@link
+ * java.util.concurrent.ExecutorService} to which tasks are submitted to handle
+ * I/O events and dispatch to completion handlers that consume the result of
+ * asynchronous operations performed on channels in the group. The group can
+ * optionally be specified when creating the channel or the channel can be bound
+ * to a default group. Sophisticated users may wish to create their
+ * own asynchronous channel groups or configure the {@code ExecutorService}
+ * that will be used for the default group.
+ *
+ * As with selectors, the implementatin of asynchronous channels can be
+ * replaced by "plugging in" an alternative definition or instance of the {@link
+ * java.nio.channels.spi.AsynchronousChannelProvider} class defined in the
+ * {@link java.nio.channels.spi} package. It is not expected that many
+ * developers will actually make use of this facility; it is provided primarily
+ * so that sophisticated users can take advantage of operating-system-specific
+ * asynchronous I/O mechanisms when very high performance is required.
+ *
* Unless otherwise noted, passing a null argument to a constructor
* or method in any class or interface in this package will cause a {@link
* java.lang.NullPointerException NullPointerException} to be thrown.
*
* @since 1.4
+ * @updated 1.7
* @author Mark Reinhold
* @author JSR-51 Expert Group
*/
diff --git a/jdk/src/share/classes/java/nio/channels/spi/AsynchronousChannelProvider.java b/jdk/src/share/classes/java/nio/channels/spi/AsynchronousChannelProvider.java
new file mode 100644
index 0000000000000000000000000000000000000000..941364876ed060471f6691f3a64f4116e741f692
--- /dev/null
+++ b/jdk/src/share/classes/java/nio/channels/spi/AsynchronousChannelProvider.java
@@ -0,0 +1,264 @@
+/*
+ * Copyright 2007-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 java.nio.channels.spi;
+
+import java.nio.channels.*;
+import java.net.ProtocolFamily;
+import java.io.IOException;
+import java.util.Iterator;
+import java.util.ServiceLoader;
+import java.util.ServiceConfigurationError;
+import java.util.concurrent.*;
+import java.security.AccessController;
+import java.security.PrivilegedAction;
+
+/**
+ * Service-provider class for asynchronous channels.
+ *
+ * An asynchronous channel provider is a concrete subclass of this class that
+ * has a zero-argument constructor and implements the abstract methods specified
+ * below. A given invocation of the Java virtual machine maintains a single
+ * system-wide default provider instance, which is returned by the {@link
+ * #provider() provider} method. The first invocation of that method will locate
+ * the default provider as specified below.
+ *
+ * All of the methods in this class are safe for use by multiple concurrent
+ * threads. The first invocation of this method locates the default provider
+ * object as follows: If the system property
+ * java.nio.channels.spi.AsynchronousChannelProvider is defined
+ * then it is taken to be the fully-qualified name of a concrete provider class.
+ * The class is loaded and instantiated; if this process fails then an
+ * unspecified error is thrown. If a provider class has been installed in a jar file that is
+ * visible to the system class loader, and that jar file contains a
+ * provider-configuration file named
+ * java.nio.channels.spi.AsynchronousChannelProvider in the resource
+ * directory META-INF/services, then the first class name
+ * specified in that file is taken. The class is loaded and
+ * instantiated; if this process fails then an unspecified error is
+ * thrown. Finally, if no provider has been specified by any of the above
+ * means then the system-default provider class is instantiated and the
+ * result is returned. Subsequent invocations of this method return the provider that was
+ * returned by the first invocation. true if and only if the directory was
* created; false otherwise
*
@@ -1222,6 +1278,11 @@ public class File
* already exists. The return value should always be checked to make sure
* that the rename operation was successful.
*
+ * true if and only if the renaming succeeded;
@@ -1304,10 +1365,14 @@ public class File
return fs.setReadOnly(this);
}
- /**
+ /**
* Sets the owner's or everybody's write permission for this abstract
* pathname.
*
+ * true, sets the access permission to allow write
* operations; if false to disallow write operations
@@ -1371,6 +1436,10 @@ public class File
* Sets the owner's or everybody's read permission for this abstract
* pathname.
*
+ * true, sets the access permission to allow read
* operations; if false to disallow read operations
@@ -1440,6 +1509,10 @@ public class File
* Sets the owner's or everybody's execute permission for this abstract
* pathname.
*
+ * true, sets the access permission to allow execute
* operations; if false to disallow execute operations
@@ -1678,44 +1751,44 @@ public class File
/* -- Temporary files -- */
- private static final Object tmpFileLock = new Object();
+ private static class TemporaryDirectory {
+ private TemporaryDirectory() { }
- private static int counter = -1; /* Protected by tmpFileLock */
+ static final String valueAsString = fs.normalize(
+ AccessController.doPrivileged(new GetPropertyAction("java.io.tmpdir")));
+ static final File valueAsFile =
+ new File(valueAsString, fs.prefixLength(valueAsString));
- private static File generateFile(String prefix, String suffix, File dir)
- throws IOException
- {
- if (counter == -1) {
- counter = new Random().nextInt() & 0xffff;
+ // file name generation
+ private static final SecureRandom random = new SecureRandom();
+ static File generateFile(String prefix, String suffix, File dir) {
+ long n = random.nextLong();
+ if (n == Long.MIN_VALUE) {
+ n = 0; // corner case
+ } else {
+ n = Math.abs(n);
+ }
+ return new File(dir, prefix + Long.toString(n) + suffix);
}
- counter++;
- return new File(dir, prefix + Integer.toString(counter) + suffix);
- }
- private static String tmpdir; /* Protected by tmpFileLock */
-
- private static String getTempDir() {
- if (tmpdir == null)
- tmpdir = fs.normalize(
- AccessController.doPrivileged(
- new GetPropertyAction("java.io.tmpdir")));
- return tmpdir;
- }
-
- private static boolean checkAndCreate(String filename, SecurityManager sm)
- throws IOException
- {
- if (sm != null) {
- try {
- sm.checkWrite(filename);
- } catch (AccessControlException x) {
- /* Throwing the original AccessControlException could disclose
- the location of the default temporary directory, so we
- re-throw a more innocuous SecurityException */
- throw new SecurityException("Unable to create temporary file");
- }
+ // default file permissions
+ static final FileAttributeprefix argument contains fewer than three
+ * characters
+ * @throws UnsupportedOperationException
+ * If the array contains an attribute that cannot be set atomically
+ * when creating the file
+ * @throws IOException
+ * If a file could not be created
+ * @throws SecurityException
+ * If a security manager exists and its {@link
+ * java.lang.SecurityManager#checkWrite(java.lang.String)}
+ * method does not allow a file to be created. When the {@code
+ * deleteOnExit} parameter has the value {@code true} then the
+ * security manager's {@link
+ * java.lang.SecurityManager#checkDelete(java.lang.String)} is
+ * invoked to check delete access to the file.
+ * @since 1.7
+ */
+ public static File createTempFile(String prefix,
+ String suffix,
+ boolean deleteOnExit,
+ FileAttribute... attrs)
+ throws IOException
+ {
+ if (prefix.length() < 3)
+ throw new IllegalArgumentException("Prefix string too short");
+ suffix = (suffix == null) ? ".tmp" : suffix;
+
+ // special case POSIX environments so that 0600 is used as the file mode
+ if (TemporaryDirectory.isPosix) {
+ if (attrs.length == 0) {
+ // no attributes so use default permissions
+ attrs = new FileAttribute[1];
+ attrs[0] = TemporaryDirectory.defaultPosixFilePermissions;
+ } else {
+ // check if posix permissions given; if not use default
+ boolean hasPermissions = false;
+ for (int i=0; i
+ * Subsequent invocations of this method return the same {@code Path}.
+ *
+ *
+ * {@link FileSystems#getDefault FileSystems.getDefault}().{@link FileSystem#getPath getPath}(this.{@link #getPath getPath}());
+ *
*
* File.delete to
* be called. Corresponds to SecurityManager.checkDelete.
+ * File.separatorChar)
@@ -425,6 +434,8 @@ public final class FilePermission extends Permission implements Serializable {
return EXECUTE;
} else if (actions == SecurityConstants.FILE_DELETE_ACTION) {
return DELETE;
+ } else if (actions == SecurityConstants.FILE_READLINK_ACTION) {
+ return READLINK;
}
char[] a = actions.toCharArray();
@@ -485,6 +496,18 @@ public final class FilePermission extends Permission implements Serializable {
matchlen = 6;
mask |= DELETE;
+ } else if (i >= 7 && (a[i-7] == 'r' || a[i-7] == 'R') &&
+ (a[i-6] == 'e' || a[i-6] == 'E') &&
+ (a[i-5] == 'a' || a[i-5] == 'A') &&
+ (a[i-4] == 'd' || a[i-4] == 'D') &&
+ (a[i-3] == 'l' || a[i-3] == 'L') &&
+ (a[i-2] == 'i' || a[i-2] == 'I') &&
+ (a[i-1] == 'n' || a[i-1] == 'N') &&
+ (a[i] == 'k' || a[i] == 'K'))
+ {
+ matchlen = 8;
+ mask |= READLINK;
+
} else {
// parse error
throw new IllegalArgumentException(
@@ -529,7 +552,7 @@ public final class FilePermission extends Permission implements Serializable {
/**
* Return the canonical string representation of the actions.
* Always returns present actions in the following order:
- * read, write, execute, delete.
+ * read, write, execute, delete, readlink.
*
* @return the canonical string representation of the actions.
*/
@@ -561,14 +584,20 @@ public final class FilePermission extends Permission implements Serializable {
sb.append("delete");
}
+ if ((mask & READLINK) == READLINK) {
+ if (comma) sb.append(',');
+ else comma = true;
+ sb.append("readlink");
+ }
+
return sb.toString();
}
/**
* Returns the "canonical string representation" of the actions.
* That is, this method always returns present actions in the following order:
- * read, write, execute, delete. For example, if this FilePermission object
- * allows both write and read actions, a call to getActions
+ * read, write, execute, delete, readlink. For example, if this FilePermission
+ * object allows both write and read actions, a call to getActions
* will return the string "read,write".
*
* @return the canonical string representation of the actions.
@@ -678,7 +707,7 @@ final class FilePermissionCollection extends PermissionCollection
implements Serializable {
// Not serialized; see serialization section at end of class
- private transient List perms;
+ private transient List
+ *
+ * @param dst
+ * The buffer into which bytes are to be transferred
+ *
+ * @return A Future representing the result of the operation
+ *
+ * @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
+ */
+ Future
+ * c.read(dst, null, null);
+ *
+ * @param src
+ * The buffer from which bytes are to be retrieved
+ *
+ * @return A Future representing the result of the operation
+ *
+ * @throws WritePendingException
+ * If the channel does not allow more than one write to be outstanding
+ * and a previous write has not completed
+ */
+ Future
+ * c.write(src, null, null);
+ *
+ *
+ * where operation is the name of the I/O operation (read or write for
+ * example), V is the result type of the I/O operation, and A is
+ * the type of an object attached to the I/O operation to provide context when
+ * consuming the result. The attachment is important for cases where a
+ * state-less {@code CompletionHandler} is used to consume the result
+ * of many I/O operations.
+ *
+ * {@link Future}<V> operation(...)Future<V> operation(... A attachment, {@link CompletionHandler}<V,? super A> handler)Cancellation
+ *
+ *
+ *
+ *
+ *
+ *
+ * System property
+ * Description
+ *
+ *
+ *
+ * {@code java.nio.channels.DefaultThreadPool.threadFactory}
+ * The value of this property is taken to be the fully-qualified name
+ * of a concrete {@link java.util.concurrent.ThreadFactory ThreadFactory}
+ * class. The class is loaded using the system class loader and instantiated.
+ * The factory's {@link java.util.concurrent.ThreadFactory#newThread
+ * newThread} method is invoked to create each thread for the default
+ * group's thread pool. If the process to load and instantiate the value
+ * of the property fails then an unspecified error is thrown during the
+ * construction of the default group.
+ *
+ *
+ * {@code java.nio.channels.DefaultThreadPool.initialSize}
+ * The value of the {@code initialSize} parameter for the default
+ * group (see {@link #withCachedThreadPool withCachedThreadPool}).
+ * The value of the property is taken to be the {@code String}
+ * representation of an {@code Integer} that is the initial size parameter.
+ * If the value cannot be parsed as an {@code Integer} it causes an
+ * unspecified error to be thrown during the construction of the default
+ * group.
+ * Threading
+ *
+ * Shutdown and Termination
+ *
+ *
+ *
+ * Additional (implementation specific) options may also be supported.
+ *
+ *
+ *
+ *
+ *
+ * Option Name
+ * Description
+ *
+ *
+ * {@link java.net.StandardSocketOption#SO_SNDBUF SO_SNDBUF}
+ * The size of the socket send buffer
+ *
+ *
+ * {@link java.net.StandardSocketOption#SO_RCVBUF SO_RCVBUF}
+ * The size of the socket receive buffer
+ *
+ *
+ * {@link java.net.StandardSocketOption#SO_REUSEADDR SO_REUSEADDR}
+ * Re-use address
+ *
+ *
+ * {@link java.net.StandardSocketOption#SO_BROADCAST SO_BROADCAST}
+ * Allow transmission of broadcast datagrams
+ *
+ *
+ * {@link java.net.StandardSocketOption#IP_TOS IP_TOS}
+ * The Type of Service (ToS) octet in the Internet Protocol (IP) header
+ *
+ *
+ * {@link java.net.StandardSocketOption#IP_MULTICAST_IF IP_MULTICAST_IF}
+ * The network interface for Internet Protocol (IP) multicast datagrams
+ *
+ *
+ * {@link java.net.StandardSocketOption#IP_MULTICAST_TTL
+ * IP_MULTICAST_TTL}
+ * The time-to-live for Internet Protocol (IP) multicast
+ * datagrams
+ *
+ *
+ * {@link java.net.StandardSocketOption#IP_MULTICAST_LOOP
+ * IP_MULTICAST_LOOP}
+ * Loopback for Internet Protocol (IP) multicast datagrams
+ *
+ * final AsynchronousDatagramChannel dc = AsynchronousDatagramChannel.open()
+ * .bind(new InetSocketAddress(4000));
+ *
+ * // 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 (...) { ... }
+ * }
+ * public void failed(Throwable exc, ByteBuffer buffer) {
+ * ...
+ * }
+ * public void cancelled(ByteBuffer buffer) {
+ * ...
+ * }
+ * });
+ *
+ *
+ * @since 1.7
+ */
+
+public abstract class AsynchronousDatagramChannel
+ implements AsynchronousByteChannel, MulticastChannel
+{
+ private final AsynchronousChannelProvider provider;
+
+ /**
+ * Initializes a new instance of this class.
+ */
+ protected AsynchronousDatagramChannel(AsynchronousChannelProvider provider) {
+ this.provider = provider;
+ }
+
+ /**
+ * Returns the provider that created this channel.
+ */
+ public final AsynchronousChannelProvider provider() {
+ return provider;
+ }
+
+ /**
+ * Opens an asynchronous datagram channel.
+ *
+ *
+ *
+ * @return A new asynchronous datagram channel
+ *
+ * @throws IOException
+ * If an I/O error occurs
+ */
+ public static AsynchronousDatagramChannel open()
+ throws IOException
+ {
+ return open(null, null);
+ }
+
+ // -- Socket-specific operations --
+
+ /**
+ * @throws AlreadyBoundException {@inheritDoc}
+ * @throws UnsupportedAddressTypeException {@inheritDoc}
+ * @throws ClosedChannelException {@inheritDoc}
+ * @throws IOException {@inheritDoc}
+ * @throws SecurityException
+ * If a security manager has been installed and its {@link
+ * SecurityManager#checkListen checkListen} method denies the
+ * operation
+ */
+ @Override
+ public abstract AsynchronousDatagramChannel bind(SocketAddress local)
+ throws IOException;
+
+ /**
+ * @throws IllegalArgumentException {@inheritDoc}
+ * @throws ClosedChannelException {@inheritDoc}
+ * @throws IOException {@inheritDoc}
+ */
+ @Override
+ public abstract
+ * open((ProtocolFamily)null, (AsynchronousChannelGroup)null);
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ * Option Description
+ *
+ * {@link StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING}
+ * When opening an existing file, the file is first truncated to a
+ * size of 0 bytes. This option is ignored when the file is opened only
+ * for reading.
+ *
+ *
+ * {@link StandardOpenOption#CREATE_NEW CREATE_NEW}
+ * If this option is present then a new file is created, failing if
+ * the file already exists. When creating a file the check for the
+ * existence of the file and the creation of the file if it does not exist
+ * is atomic with respect to other file system operations. This option is
+ * ignored when the file is opened only for reading.
+ *
+ *
+ * {@link StandardOpenOption#CREATE CREATE}
+ * If this option is present then an existing file is opened if it
+ * exists, otherwise a new file is created. When creating a file the check
+ * for the existence of the file and the creation of the file if it does
+ * not exist is atomic with respect to other file system operations. This
+ * option is ignored if the {@code CREATE_NEW} option is also present or
+ * the file is opened only for reading.
+ *
+ *
+ * {@link StandardOpenOption#DELETE_ON_CLOSE DELETE_ON_CLOSE}
+ * When this option is present then the implementation makes a
+ * best effort attempt to delete the file when closed by the
+ * the {@link #close close} method. If the {@code close} method is not
+ * invoked then a best effort attempt is made to delete the file
+ * when the Java virtual machine terminates.
+ *
+ *
+ * {@link StandardOpenOption#SPARSE SPARSE}
+ * When creating a new file this option is a hint that the
+ * new file will be sparse. This option is ignored when not creating
+ * a new file.
+ *
+ * {@link StandardOpenOption#SYNC SYNC}
+ * Requires that every update to the file's content or metadata be
+ * written synchronously to the underlying storage device. (see Synchronized I/O file
+ * integrity).
+ *
+ *
+ *
+ * {@link StandardOpenOption#DSYNC DSYNC}
+ * Requires that every update to the file's content be written
+ * synchronously to the underlying storage device. (see Synchronized I/O file
+ * integrity).
+ *
+ * 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.
+ *
+ *
+ * ch.{@link #lock(long,long,boolean,Object,CompletionHandler) lock}(0L, Long.MAX_VALUE, false, att, handler)
+ *
+ *
+ * @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 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
+ * ch.{@link #lock(long,long,boolean,Object,CompletionHandler) lock}(0L, Long.MAX_VALUE, false, null, null)
+ *
+ *
+ * @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 NonWritableChannelException
+ * If this channel was not opened for writing
+ */
+ public final Future
+ * ch.{@link #tryLock(long,long,boolean) tryLock}(0L, Long.MAX_VALUE, false)
+ *
+ * @return A lock object representing the newly-acquired lock,
+ * or {@code null} if the lock could not be acquired
+ * because another program holds an overlapping lock
+ *
+ * @throws ClosedChannelException
+ * If this channel is closed
+ * @throws OverlappingFileLockException
+ * If a lock that overlaps the requested region is already held by
+ * this Java virtual machine, or if another thread is already
+ * blocked in this method and is attempting to lock an overlapping
+ * region
+ * @throws NonWritableChannelException
+ * If {@code shared} is false but this channel was not opened for writing
+ *
+ * @throws IOException
+ * If some other I/O error occurs
+ *
+ * @see #lock(Object,CompletionHandler)
+ * @see #lock(long,long,boolean,Object,CompletionHandler)
+ * @see #tryLock(long,long,boolean)
+ */
+ public final FileLock tryLock() throws IOException {
+ return tryLock(0L, Long.MAX_VALUE, false);
+ }
+
+ /**
+ * Reads a sequence of bytes from this channel into the given buffer,
+ * starting at the given file position.
+ *
+ *
+ *
+ * Additional (implementation specific) options may also be supported.
+ *
+ *
+ *
+ *
+ *
+ * Option Name
+ * Description
+ *
+ *
+ * {@link java.net.StandardSocketOption#SO_RCVBUF SO_RCVBUF}
+ * The size of the socket receive buffer
+ *
+ *
+ * {@link java.net.StandardSocketOption#SO_REUSEADDR SO_REUSEADDR}
+ * Re-use address
+ *
+ * final AsynchronousServerSocketChannel listener =
+ * AsynchronousServerSocketChannel.open().bind(new InetSocketAddress(5000));
+ *
+ * listener.accept(null, new CompletionHandler<AsynchronousSocketChannel,Void>() {
+ * public void completed(AsynchronousSocketChannel ch, Void att) {
+ * // accept the next connection
+ * listener.accept(null, this);
+ *
+ * // handle this connection
+ * handle(ch);
+ * }
+ * public void failed(Throwable exc, Void att) {
+ * ...
+ * }
+ * public void cancelled(Void att) {
+ * ...
+ * }
+ * });
+ *
+ *
+ * @since 1.7
+ */
+
+public abstract class AsynchronousServerSocketChannel
+ implements AsynchronousChannel, NetworkChannel
+{
+ private final AsynchronousChannelProvider provider;
+
+ /**
+ * Initializes a new instance of this class.
+ */
+ protected AsynchronousServerSocketChannel(AsynchronousChannelProvider provider) {
+ this.provider = provider;
+ }
+
+ /**
+ * Returns the provider that created this channel.
+ */
+ public final AsynchronousChannelProvider provider() {
+ return provider;
+ }
+
+ /**
+ * Opens an asynchronous server-socket channel.
+ *
+ *
+ *
+ * @return A new asynchronous server socket channel
+ *
+ * @throws IOException
+ * If an I/O error occurs
+ */
+ public static AsynchronousServerSocketChannel open()
+ throws IOException
+ {
+ return open(null);
+ }
+
+ /**
+ * Binds the channel's socket to a local address and configures the socket to
+ * listen for connections.
+ *
+ *
+ * open((AsynchronousChannelGroup)null);
+ *
+ *
+ * @param local
+ * The local address to bind the socket, or null to bind
+ * to an automatically assigned socket address
+ *
+ * @return This channel
+ *
+ * @throws AlreadyBoundException {@inheritDoc}
+ * @throws UnsupportedAddressTypeException {@inheritDoc}
+ * @throws SecurityException {@inheritDoc}
+ * @throws ClosedChannelException {@inheritDoc}
+ * @throws IOException {@inheritDoc}
+ */
+ public final AsynchronousServerSocketChannel bind(SocketAddress local)
+ throws IOException
+ {
+ return bind(local, 0);
+ }
+
+ /**
+ * Binds the channel's socket to a local address and configures the socket to
+ * listen for connections.
+ *
+ *
+ * bind(local, 0);
+ *
+ *
+ * Additional (implementation specific) options may also be supported.
+ *
+ *
+ *
+ *
+ *
+ * Option Name
+ * Description
+ *
+ *
+ * {@link java.net.StandardSocketOption#SO_SNDBUF SO_SNDBUF}
+ * The size of the socket send buffer
+ *
+ *
+ * {@link java.net.StandardSocketOption#SO_RCVBUF SO_RCVBUF}
+ * The size of the socket receive buffer
+ *
+ *
+ * {@link java.net.StandardSocketOption#SO_KEEPALIVE SO_KEEPALIVE}
+ * Keep connection alive
+ *
+ *
+ * {@link java.net.StandardSocketOption#SO_REUSEADDR SO_REUSEADDR}
+ * Re-use address
+ *
+ *
+ * {@link java.net.StandardSocketOption#TCP_NODELAY TCP_NODELAY}
+ * Disable the Nagle algorithm
+ * Timeouts
+ *
+ *
+ *
+ * @return A new asynchronous socket channel
+ *
+ * @throws IOException
+ * If an I/O error occurs
+ */
+ public static AsynchronousSocketChannel open()
+ throws IOException
+ {
+ return open(null);
+ }
+
+
+ // -- socket options and related --
+
+ /**
+ * @throws ConnectionPendingException
+ * If a connection operation is already in progress on this channel
+ * @throws AlreadyBoundException {@inheritDoc}
+ * @throws UnsupportedAddressTypeException {@inheritDoc}
+ * @throws ClosedChannelException {@inheritDoc}
+ * @throws IOException {@inheritDoc}
+ */
+ @Override
+ public abstract AsynchronousSocketChannel bind(SocketAddress local)
+ throws IOException;
+
+ /**
+ * @throws IllegalArgumentException {@inheritDoc}
+ * @throws ClosedChannelException {@inheritDoc}
+ * @throws IOException {@inheritDoc}
+ */
+ @Override
+ public abstract
+ * open((AsynchronousChannelGroup)null);
+ *
+ *
+ * at the moment that the read is attempted.
+ *
+ *
+ * dsts[offset].remaining()
+ * + dsts[offset+1].remaining()
+ * + ... + dsts[offset+length-1].remaining()
+ *
+ * at the moment that the write is attempted.
+ *
+ *
+ * srcs[offset].remaining()
+ * + srcs[offset+1].remaining()
+ * + ... + srcs[offset+length-1].remaining()
*
*
@@ -211,6 +213,7 @@ public abstract class DatagramChannel
throws IOException;
/**
+ * @throws UnsupportedOperationException {@inheritDoc}
* @throws IllegalArgumentException {@inheritDoc}
* @throws ClosedChannelException {@inheritDoc}
* @throws IOException {@inheritDoc}
@@ -220,7 +223,6 @@ public abstract class DatagramChannel
public abstract
* } and {@link #position(long)
- * modified}. The file itself contains a variable-length sequence
+ * size} can be queried. The size of the file increases
+ * size} can be queried. The size of the file increases
* when bytes are written beyond its current size; the size of the file
* decreases when it is {@link #truncate truncated}. The
* file may also have some associated metadata such as access
@@ -50,27 +57,27 @@ import java.nio.channels.spi.AbstractInterruptibleChannel;
*
* read
*
- *
} or
- * {@link #write(ByteBuffer, long) written} at an absolute
+ * mapped}
+ * forced
- * out} to the underlying storage device, ensuring that data are not
+ * to
- * some other channel}, and {@link #transferFrom vice
- * versa}, in a way that can be optimized by many operating systems
+ * locked}
+ *
+ *
+ *
+ *
+ * Option Description
+ *
+ * {@link StandardOpenOption#APPEND APPEND}
+ * If this option is present then the file is opened for writing and
+ * each invocation of the channel's {@code write} method first advances
+ * the position to the end of the file and then writes the requested
+ * data. Whether the advancement of the position and the writing of the
+ * data are done in a single atomic operation is system-dependent and
+ * therefore unspecified. This option may not be used in conjunction
+ * with the {@code READ} or {@code TRUNCATE_EXISTING} options.
+ *
+ *
+ * {@link StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING}
+ * If this option is present then the existing file is truncated to
+ * a size of 0 bytes. This option is ignored when the file is opened only
+ * for reading.
+ *
+ *
+ * {@link StandardOpenOption#CREATE_NEW CREATE_NEW}
+ * If this option is present then a new file is created, failing if
+ * the file already exists. When creating a file the check for the
+ * existence of the file and the creation of the file if it does not exist
+ * is atomic with respect to other file system operations. This option is
+ * ignored when the file is opened only for reading.
+ *
+ *
+ * {@link StandardOpenOption#CREATE CREATE}
+ * If this option is present then an existing file is opened if it
+ * exists, otherwise a new file is created. When creating a file the check
+ * for the existence of the file and the creation of the file if it does
+ * not exist is atomic with respect to other file system operations. This
+ * option is ignored if the {@code CREATE_NEW} option is also present or
+ * the file is opened only for reading.
+ *
+ *
+ * {@link StandardOpenOption#DELETE_ON_CLOSE DELETE_ON_CLOSE}
+ * When this option is present then the implementation makes a
+ * best effort attempt to delete the file when closed by the
+ * the {@link #close close} method. If the {@code close} method is not
+ * invoked then a best effort attempt is made to delete the file
+ * when the Java virtual machine terminates.
+ *
+ *
+ * {@link StandardOpenOption#SPARSE SPARSE}
+ * When creating a new file this option is a hint that the
+ * new file will be sparse. This option is ignored when not creating
+ * a new file.
+ *
+ * {@link StandardOpenOption#SYNC SYNC}
+ * Requires that every update to the file's content or metadata be
+ * written synchronously to the underlying storage device. (see Synchronized I/O file
+ * integrity).
+ *
+ *
+ *
+ * {@link StandardOpenOption#DSYNC DSYNC}
+ * Requires that every update to the file's content be written
+ * synchronously to the underlying storage device. (see Synchronized I/O file
+ * integrity).
+ *
+ * fc.{@link #open(Path,Set,FileAttribute[]) open}(file, options, new FileAttribute<?>[0]);
+ *
+ *
+ * @param file
+ * The path of the file to open or create
+ * @param options
+ * Options specifying how the file is opened
+ *
+ * @return A new file channel
+ *
+ * @throws IllegalArgumentException
+ * If the set contains an invalid combination of options
+ * @throws UnsupportedOperationException
+ * If the {@code file} is associated with a provider that does not
+ * support creating file channels, or an unsupported open option is
+ * specified
+ * @throws IOException
+ * If an I/O error occurs
+ * @throws SecurityException
+ * If a security manager is installed and it denies an
+ * unspecified permission required by the implementation.
+ * In the case of the default provider, the {@link
+ * SecurityManager#checkRead(String)} method is invoked to check
+ * read access if the file is opened for reading. The {@link
+ * SecurityManager#checkWrite(String)} method is invoked to check
+ * write access if the file is opened for writing
+ *
+ * @since 1.7
+ */
+ public static FileChannel open(Path file, OpenOption... options)
+ throws IOException
+ {
+ Set} obtained by
+ * {@link MappedByteBuffer mapped byte buffer} obtained by
* invoking the {@link #map map} method. Invoking the {@link
* MappedByteBuffer#force force} method of the mapped byte buffer will
* force changes made to the buffer's content to be written. }
+ * mapped into memory Platform dependencies
+ * Platform dependencies
*
* }, and vice versa. Programs that combine
+ * mapped into memory}, and vice versa. Programs that combine
* locking and mapping should be prepared for this combination to fail.
*
* Can read/write to/from a buffer {@link java.nio.channels.SeekableByteChannel}
* A {@code ByteChannel} connected to an entity that contains a variable-length sequence of bytes {@link java.nio.channels.AsynchronousChannel}
+ * Supports asynchronous I/O operations. {@link java.nio.channels.AsynchronousByteChannel}
+ * Can read and write bytes asynchronously {@link java.nio.channels.NetworkChannel}
* A channel to a network socket {@link java.nio.channels.MulticastChannel}
@@ -218,12 +222,70 @@
* directly; custom channel classes should extend the appropriate {@link
* java.nio.channels.SelectableChannel} subclasses defined in this package.
*
+ *
+ *
+ *
+ *
+ *
+ *
{@link java.nio.channels.AsynchronousFileChannel}
+ * An asynchronous channel for reading, writing, and manipulating a file {@link java.nio.channels.AsynchronousSocketChannel}
+ * An asynchronous channel to a stream-oriented connecting socket {@link java.nio.channels.AsynchronousServerSocketChannel}
+ * An asynchronous channel to a stream-oriented listening socket {@link java.nio.channels.AsynchronousDatagramChannel}
+ * An asynchronous channel to a datagram-oriented socket {@link java.nio.channels.CompletionHandler}
+ * A handler for consuming the result of an asynchronous operation {@link java.nio.channels.AsynchronousChannelGroup}
+ * A grouping of asynchronous channels for the purpose of resource sharing
*
+ *
+ *
+ *
+ *