/**
* Opens or creates a file for reading and/or writing, returning an asynchronous file channel to
* access the file.
*
* <p>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.
*
* <p>In addition to {@code READ} and {@code WRITE}, the following options may be present:
*
* <table border=1 cellpadding=5 summary="">
* <tr> <th>Option</th> <th>Description</th> </tr>
* <tr>
* <td> {@link StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING} </td>
* <td> 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.</td>
* </tr>
* <tr>
* <td> {@link StandardOpenOption#CREATE_NEW CREATE_NEW} </td>
* <td> 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. </td>
* </tr>
* <tr>
* <td > {@link StandardOpenOption#CREATE CREATE} </td>
* <td> 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. </td>
* </tr>
* <tr>
* <td > {@link StandardOpenOption#DELETE_ON_CLOSE DELETE_ON_CLOSE} </td>
* <td> When this option is present then the implementation makes a
* <em>best effort</em> attempt to delete the file when closed by the
* the {@link #close close} method. If the {@code close} method is not
* invoked then a <em>best effort</em> attempt is made to delete the file
* when the Java virtual machine terminates. </td>
* </tr>
* <tr>
* <td>{@link StandardOpenOption#SPARSE SPARSE} </td>
* <td> When creating a new file this option is a <em>hint</em> that the
* new file will be sparse. This option is ignored when not creating
* a new file. </td>
* </tr>
* <tr>
* <td> {@link StandardOpenOption#SYNC SYNC} </td>
* <td> Requires that every update to the file's content or metadata be
* written synchronously to the underlying storage device. (see <a
* href="../file/package-summary.html#integrity"> Synchronized I/O file
* integrity</a>). </td>
* <tr>
* <tr>
* <td> {@link StandardOpenOption#DSYNC DSYNC} </td>
* <td> Requires that every update to the file's content be written
* synchronously to the underlying storage device. (see <a
* href="../file/package-summary.html#integrity"> Synchronized I/O file
* integrity</a>). </td>
* </tr>
* </table>
*
* <p>An implementation may also support additional options.
*
* <p>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. Shutting down the executor service while the channel is open results in
* unspecified behavior.
*
* <p>The {@code attrs} parameter is an optional array of file {@link FileAttribute
* file-attributes} to set atomically when creating the file.
*
* <p>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<? extends OpenOption> options,
ExecutorService executor,
FileAttribute<?>... attrs)
throws IOException {
FileSystemProvider provider = file.getFileSystem().provider();
return provider.newAsynchronousFileChannel(file, options, executor, attrs);
}
