Module java.base

软件包 java.nio.channels

Class AsynchronousFileChannel

java.lang.Object

java.nio.channels.AsynchronousFileChannel

All Implemented Interfaces:

Closeable ， AutoCloseable ， AsynchronousChannel ， Channel

public abstract class AsynchronousFileChannel
extends Object
implements AsynchronousChannel

用于读取，写入和操作文件的异步通道。

当通过调用此类定义的一个open方法打开文件时，将创建异步文件通道。 该文件包含一个可变长度的可读写字节序列，当前大小可以是queried 。 当字节写入超过其当前大小时，文件的大小增加; 文件大小在truncated时会减小 。

异步文件通道在文件中没有当前位置 。 而是将文件位置指定给启动异步操作的每个读写方法。 A CompletionHandler被指定为参数，并被调用以消耗I / O操作的结果。 此类还定义了启动异步操作的读取和写入方法，返回一个Future以表示待处理的操作结果。 Future可用于检查操作是否完成，等待其完成，并检索结果。

除了读写操作之外，此类还定义了以下操作：

• 对文件进行的更新可能是底层存储设备的forced out，以确保数据在系统崩溃时不会丢失。

• 一个文件的区域可能是locked反对其他程序的访问。

一个AsynchronousFileChannel与提交任务以处理I / O事件的线程池相关联，并分派到消耗通道上的I / O操作结果的完成处理程序。 在通道上启动的I / O操作的完成处理程序保证由线程池中的一个线程调用（这样可以确保完成处理程序由具有预期标识的线程运行）。 I / O操作立即完成，并且启动线程本身是线程池中的线程，则完成处理程序可以由启动线程直接调用。 当创建AsynchronousFileChannel而不指定线程池时，该通道与可能与其他通道共享的系统相关的默认线程池相关联。 默认线程池由AsynchronousChannelGroup类定义的系统属性配置。

这种类型的通道可以安全地被多个并发线程使用。 close方法可以随时被调用，由Channel接口指定。 这导致通道上的所有未完成的异步操作完成，异常AsynchronousCloseException 。 多个读写操作可能同时出现。 当多个读写操作未完成时，未指定I / O操作的顺序和调用完成处理程序的顺序; 它们并不特别保证按照操作开始的顺序执行。 读取或写入时使用的ByteBuffers对于多个并发I / O操作不能安全使用。 此外，在I / O操作开始之后，应注意确保缓冲区在操作完成后才被访问。

与FileChannel一样 ，由该类的实例提供的文件的视图保证与同一程序中的其他实例提供的同一文件的其他视图一致。 但是，由于此类的实例提供的视图可能与也可能不一致，这是由于底层操作系统执行的缓存和网络文件系统协议引起的延迟而由其他同时运行的程序所看到的视图。 无论这些其他程序的编写语言如何，以及它们是在同一台机器还是在其他机器上运行，都是如此。 任何这种不一致的确切性质是系统依赖性的，因此是未指定的。

从以下版本开始：

1.7

构造方法摘要

构造方法

Modifier	Constructor	描述
protected	AsynchronousFileChannel()	初始化此类的新实例。

方法摘要

Modifier and Type	方法	描述
abstract void	force(boolean metaData)	强制将此通道文件的任何更新写入包含该通道的存储设备。
Future<FileLock>	lock()	获取此通道文件的排他锁。
abstract Future<FileLock>	lock(long position, long size, boolean shared)	获取此通道文件的给定区域的锁定。
abstract <A> void	lock(long position, long size, boolean shared, A attachment, CompletionHandler<FileLock,? super A> handler)	获取此通道文件的给定区域的锁定。
<A> void	lock(A attachment, CompletionHandler<FileLock,? super A> handler)	获取此通道文件的排他锁。
static AsynchronousFileChannel	open(Path file, OpenOption... options)	打开或创建用于读取和/或写入的文件，返回异步文件通道以访问该文件。
static AsynchronousFileChannel	open(Path file, Set<? extends OpenOption> options, ExecutorService executor, FileAttribute<?>... attrs)	打开或创建用于读取和/或写入的文件，返回异步文件通道以访问该文件。
abstract Future<Integer>	read(ByteBuffer dst, long position)	从给定的文件位置开始，从该通道读取一个字节序列到给定的缓冲区。
abstract <A> void	read(ByteBuffer dst, long position, A attachment, CompletionHandler<Integer,? super A> handler)	从给定的文件位置开始，从该通道读取一个字节序列到给定的缓冲区。
abstract long	size()	返回此通道文件的当前大小。
abstract AsynchronousFileChannel	truncate(long size)	将此频道的文件截断为给定大小。
FileLock	tryLock()	尝试获取此频道文件的排他锁。
abstract FileLock	tryLock(long position, long size, boolean shared)	尝试获取此通道文件的给定区域的锁定。
abstract Future<Integer>	write(ByteBuffer src, long position)	从给定的缓冲区向给定的文件位置开始，向该通道写入一个字节序列。
abstract <A> void	write(ByteBuffer src, long position, A attachment, CompletionHandler<Integer,? super A> handler)	从给定的缓冲区向给定的文件位置开始，向该通道写入一个字节序列。

Methods inherited from interface java.nio.channels.AsynchronousChannel

close

Methods inherited from interface java.nio.channels.Channel

isOpen

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

构造方法详细信息

AsynchronousFileChannel

protected AsynchronousFileChannel()

初始化此类的新实例。

方法详细信息

open

public static AsynchronousFileChannel open(Path file,
                                           Set<? extends OpenOption> options,
                                           ExecutorService executor,
                                           FileAttribute<?>... attrs)
                                    throws IOException

打开或创建用于读取和/或写入的文件，返回异步文件通道以访问该文件。

options参数确定文件的打开方式。 READ和WRITE选项确定文件是否应打开以进行读取和/或写入。 如果数组中没有包含任何选项，则打开一个现有文件进行阅读。

除了READ和WRITE ，还可能存在以下选项：

additional options Option Description 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. 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. 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 CREATE_NEW option is also present or the file is opened only for reading. 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 close method. If the close method is not invoked then a best effort attempt is made to delete the file when the Java virtual machine terminates. 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. 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). DSYNC Requires that every update to the file's content be written synchronously to the underlying storage device. (see Synchronized I/O file integrity).

实施还可以支持其他选项。

executor参数是ExecutorService ，其中提交的任务用于处理I / O事件，并为结果通道启动的操作调度完成结果。 这些任务的性质是高度实现具体的，并且在配置Executor时应该小心。 最小应该支持一个无界的工作队列，不应该在execute方法的调用者线程上运行任务。 在通道打开时关闭执行程序服务会导致未指定的行为。

attrs参数是文件file-attributes的可选数组，用于在创建文件时以原子方式进行设置。

新的信道是通过调用创建newFileChannel上创建该提供商方法Path 。

参数

file - 打开或创建文件的路径

options - 指定文件打开方式的选项

executor - 将通道与默认线程池关联的线程池或 null

attrs - 创建文件时以原子方式设置的文件属性的可选列表

结果

一个新的异步文件通道

异常

IllegalArgumentException - 如果集合包含无效的选项组合

UnsupportedOperationException - 如果 file与不支持创建异步文件通道的提供程序关联，或者指定了不支持的打开选项，或者数组包含创建文件时无法原子设置的属性

IOException - 如果发生I / O错误

SecurityException - 如果安装了一个安全管理器，并且它拒绝执行所需的未指定的权限。 在默认提供程序的情况下，如果打开文件进行阅读，则调用SecurityManager.checkRead(String)方法来检查读访问。 如果打开文件写入，则调用SecurityManager.checkWrite(String)方法来检查写访问

open

public static AsynchronousFileChannel open(Path file,
                                           OpenOption... options)
                                    throws IOException

打开或创建用于读取和/或写入的文件，返回异步文件通道以访问该文件。

调用此方法的行为方式与调用完全相同

  ch.open(file, opts, null, new FileAttribute<?>[0]); 

其中opts是一个Set其中包含为此方法指定的选项。

所产生的通道与默认线程池相关联，任务被提交到处理I / O事件并发送到完成处理程序，该处理程序消耗在最终通道上执行的异步操作的结果。

参数

file - 打开或创建文件的路径

options - 指定文件打开方式的选项

结果

一个新的异步文件通道

异常

IllegalArgumentException - 如果集合包含无效的选项组合

UnsupportedOperationException - 如果 file与不支持创建文件通道的提供程序相关联，或者指定了不支持的打开选项

IOException - 如果发生I / O错误

SecurityException - 如果安装了一个安全管理器，并且它拒绝实现所需的未指定的权限。 在默认提供程序的情况下，如果文件打开以供阅读，则调用SecurityManager.checkRead(String)方法来检查读访问。 如果打开文件写入，则调用SecurityManager.checkWrite(String)方法来检查写访问

size

public abstract long size()
                   throws IOException

返回此通道文件的当前大小。

结果

该通道文件的当前大小，以字节为单位

异常

ClosedChannelException - 如果此通道关闭

IOException - 如果发生其他I / O错误

truncate

public abstract AsynchronousFileChannel truncate(long size)
                                          throws IOException

将此频道的文件截断为给定大小。

如果给定的大小小于文件的当前大小，则文件将被截断，丢弃超出文件新端的任何字节。 如果给定的大小大于或等于文件的当前大小，则该文件不会被修改。

参数

size - 新的大小，非负字节数

结果

此文件通道

异常

NonWritableChannelException - 如果此通道未打开以进行写入

ClosedChannelException - 如果此通道关闭

IllegalArgumentException - 如果新的大小为负数

IOException - 如果发生其他I / O错误

force

public abstract void force(boolean metaData)
                    throws IOException

强制将此通道文件的任何更新写入包含该通道的存储设备。

如果此通道的文件驻留在本地存储设备上，那么当该方法返回时，保证自创建该通道以来创建或自从上次调用该方法以来对文件所做的所有更改都将写入该设备。 这对于确保系统崩溃时不会丢失关键信息非常有用。

如果文件不在本地设备上，则不会提供此类保证。

metaData参数可用于限制此方法执行所需的I / O操作数。 传递此参数的false表示仅对文件内容的更新需要写入存储; 通过true表示，必须写入文件的内容和元数据的更新，通常需要至少一个I / O操作。 该参数实际上是否具有任何效果取决于底层操作系统，因此未指定。

调用此方法可能会导致I / O操作发生，即使通道仅打开读取。 例如，某些操作系统将最后访问时间作为文件的元数据的一部分进行维护，并且每次读取文件时都会更新此时间。 这是否实际上是系统依赖的，因此是未指定的。

此方法只能通过此类中定义的方法强制对此通道文件进行的更改。

参数

metaData - 如果是true则需要这种方法来强制更改文件的内容和要写入存储的元数据; 否则，它只需要强制更改内容

异常

ClosedChannelException - 如果此频道关闭

IOException - 如果发生其他I / O错误

lock

public abstract <A> void lock(long position,
                              long size,
                              boolean shared,
                              A attachment,
                              CompletionHandler<FileLock,? super A> handler)

获取此通道文件的给定区域的锁定。

该方法启动一个操作，以获取此通道文件的给定区域的锁定。 handler参数是在获取锁定时调用的完成处理程序（或操作失败）。 结果传递给完成处理程序是由此产生的FileLock 。

由position和size参数指定的区域不需要包含在实际的底层文件内，甚至不重叠。 锁定区域的大小固定; 如果锁定区域最初包含文件的结尾，并且文件增长超出该区域，那么该文件的新部分将不会被该锁覆盖。 如果文件的大小增加，并且整个文件都需要锁定，则应该锁定从零开始并且不小于文件的预期最大大小的区域。 双参数lock(Object,CompletionHandler)方法简单地锁定大小为Long.MAX_VALUE的区域。 如果与Java请求区域重叠的锁已被该Java虚拟机保存，或者已调用此方法来锁定重叠区域，并且该操作尚未完成，则此方法将抛出OverlappingFileLockException 。

某些操作系统不支持以异步方式获取文件锁的机制。 因此，实现可以获取后台线程中的文件锁或从相关线程池中的线程执行的任务获取。 如果有许多锁定操作未完成，那么可能会在Java虚拟机中消耗线程无限期。

某些操作系统不支持共享锁，在这种情况下，共享锁的请求将自动转换为独占锁的请求。 新获取的锁是共享的还是独占的都可以通过调用生成的锁对象的isShared方法进行测试。

文件锁代表整个Java虚拟机。 它们不适用于通过同一虚拟机中的多个线程控制对文件的访问。

参数类型

A - 附件的类型

参数

position - 锁定区域要启动的位置; 必须是非负的

size - 锁定区域的大小; 必须是非负数，并且position + size的总和必须是非负数

shared - true请求共享锁，在这种情况下，该通道必须打开才能读取（可能写入）; false要求排他锁，在这种情况下，该频道必须开放写作（可能阅读）

attachment - 要附加到I / O操作的对象; 可以是null

handler - 消费结果的处理程序

异常

OverlappingFileLockException - 如果与该请求区域重叠的锁已由该Java虚拟机保存，或者已经有一个挂起尝试锁定重叠区域

IllegalArgumentException - 如果参数的前提条件不成立

NonReadableChannelException - 如果 shared是真的，但这个频道没有打开阅读

NonWritableChannelException - 如果 shared为假，但此通道未打开以进行写入

lock

public final <A> void lock(A attachment,
                           CompletionHandler<FileLock,? super A> handler)

获取此通道文件的排他锁。

该方法启动一个操作，以获取此通道文件的给定区域的锁定。 handler参数是一个完成处理程序，在获取锁定时（或操作失败）时调用该处理程序。 结果传递给完成处理程序是由此产生的FileLock 。

这种ch.lock(att,handler)形式的方法的调用与调用的方式完全相同

  ch.lock(0L, Long.MAX_VALUE, false, att, handler) 

参数类型

A - 附件的类型

参数

attachment - 要附加到I / O操作的对象; 可以是null

handler - 消费结果的处理程序

异常

OverlappingFileLockException - 如果此Java虚拟机已经保留了锁定，或者已经有一个暂停尝试锁定一个区域

NonWritableChannelException - 如果此通道未打开以进行写入

lock

public abstract Future<FileLock> lock(long position,
                                      long size,
                                      boolean shared)

获取此通道文件的给定区域的锁定。

该方法启动一个操作，以获取此通道文件的给定区域的锁定。 该方法的行为方式与lock(long, long, boolean, Object, CompletionHandler)方法完全相同，不同之处在于，该方法不是指定完成处理程序，而是返回表示待处理结果的Future 。 Future的get方法在成功完成后返回FileLock 。

参数

position - 锁定区域要启动的位置; 必须是非负的

size - 锁定区域的大小; 必须是非负数，并且position + size必须为非负数

shared - true以请求共享锁，在这种情况下，该通道必须打开才能读取（可能写入）; false要求排他锁，在这种情况下，此通道必须打开以进行写入（可能读取）

结果

表示待处理结果的 Future对象

异常

OverlappingFileLockException - 如果此Java虚拟机已经保留了锁定，或者已经有一个暂停尝试锁定一个区域

IllegalArgumentException - 如果参数的前提条件不成立

NonReadableChannelException - 如果 shared是真的，但这个频道没有打开阅读

NonWritableChannelException - 如果 shared为false，但此通道未打开以进行写入

lock

public final Future<FileLock> lock()

获取此通道文件的排他锁。

此方法启动一个操作来获取该通道文件的排他锁。 该方法返回一个Future表示该操作的待处理结果。 Future的get方法在成功完成后返回FileLock 。

调用此方法的行为方式与调用完全相同

  ch.lock(0L, Long.MAX_VALUE, false) 

结果

表示待处理结果的 Future对象

异常

OverlappingFileLockException - 如果该Java虚拟机已经保留了锁定，或者已经有一个暂停尝试锁定一个区域

NonWritableChannelException - 如果此通道未打开以进行写入

tryLock

public abstract FileLock tryLock(long position,
                                 long size,
                                 boolean shared)
                          throws IOException

尝试获取此通道文件的给定区域的锁定。

此方法不阻止。 调用总是立即返回，要么获取了请求的区域的锁定，要么没有这样做。 如果由于重叠锁由另一个程序持有而无法获取锁定，则它将返回null 。 如果由于任何其他原因无法获取锁，则抛出适当的异常。

参数

position - 锁定区域要启动的位置; 必须是非负的

size - 锁定区域的大小; 必须是非负数，并且position + size的和必须是非负数

shared - true要求共享锁 false请求独占锁

结果

表示新获取的锁的锁定对象，如果由于另一个程序持有重叠的锁而无法获取锁， null

异常

IllegalArgumentException - 如果参数的前提条件不成立

ClosedChannelException - 如果此通道关闭

OverlappingFileLockException - 如果与该请求区域重叠的锁已由该Java虚拟机保留，或者该方法中已阻止另一个线程，并尝试锁定同一文件的重叠区域

NonReadableChannelException - 如果 shared是真的，但这个频道没有打开阅读

NonWritableChannelException - 如果 shared为假，但此通道未打开以进行写入

IOException - 如果发生其他I / O错误

另请参见：

lock(Object,CompletionHandler) ， lock(long,long,boolean,Object,CompletionHandler) ， tryLock()

tryLock

public final FileLock tryLock()
                       throws IOException

尝试获取此频道文件的排他锁。

这种ch.tryLock()形式的方法的调用与调用的方式完全相同

  ch.tryLock(0L, Long.MAX_VALUE, false) 

结果

表示新获取的锁的锁定对象，如果由于另一个程序持有重叠锁而无法获取锁， null

异常

ClosedChannelException - 如果此通道关闭

OverlappingFileLockException - 如果与该请求区域重叠的锁已由该Java虚拟机保存，或者在此方法中已阻止另一个线程，并尝试锁定重叠区域

NonWritableChannelException - 如果 shared为假，但此通道未打开以进行写入

IOException - 如果发生其他I / O错误

另请参见：

lock(Object,CompletionHandler) ， lock(long,long,boolean,Object,CompletionHandler) ， tryLock(long,long,boolean)

read

public abstract <A> void read(ByteBuffer dst,
                              long position,
                              A attachment,
                              CompletionHandler<Integer,? super A> handler)

从给定的文件位置开始，从该通道读取一个字节序列到给定的缓冲区。

该方法从给定的文件位置开始从该通道读取字节序列到给定的缓冲区。 读取的结果是读取的字节数或-1如果给定位置大于或等于尝试读取时文件的大小。

该方法的工作方式与AsynchronousByteChannel.read(ByteBuffer,Object,CompletionHandler)方法相同，只是从给定文件位置开始读取字节。 如果给定的文件位置大于尝试读取时的文件大小，则不会读取任何字节。

参数类型

A - 附件的类型

参数

dst - 要传输字节的缓冲区

position - 传输开始的文件位置; 必须是非负的

attachment - 要附加到I / O操作的对象; 可以是null

handler - 消费结果的处理程序

异常

IllegalArgumentException - 如果位置为负或缓冲区为只读

NonReadableChannelException - 如果此频道未打开阅读

read

public abstract Future<Integer> read(ByteBuffer dst,
                                     long position)

从给定的文件位置开始，从该通道读取一个字节序列到给定的缓冲区。

该方法从给定的文件位置开始从该通道读取字节序列到给定的缓冲区。 此方法返回一个Future表示该操作的待处理结果。 Future的get方法返回读取的字节数或-1如果给定的位置大于或等于在尝试读取时文件的大小。

该方法的工作方式与AsynchronousByteChannel.read(ByteBuffer)方法相同，只是从给定的文件位置开始读取字节。 如果给定的文件位置大于尝试读取时的文件大小，则不会读取任何字节。

参数

dst - 要传输字节的缓冲区

position - 传输开始的文件位置; 必须是非负的

结果

表示待处理结果的 Future对象

异常

IllegalArgumentException - 如果位置为负或缓冲区为只读

NonReadableChannelException - 如果此频道未打开阅读

write

public abstract <A> void write(ByteBuffer src,
                               long position,
                               A attachment,
                               CompletionHandler<Integer,? super A> handler)

从给定的缓冲区向给定的文件位置开始，向该通道写入一个字节序列。

该方法的工作方式与AsynchronousByteChannel.write(ByteBuffer,Object,CompletionHandler)方法相同，只是字节从给定的文件位置开始写入。 如果给定的位置大于文件的大小，则在尝试写入时，该文件将生长以适应新的字节; 未指定上一个文件结尾和新写入的字节之间的任何字节的值。

参数类型

A - 附件的类型

参数

src - 要传输字节的缓冲区

position - 传输开始的文件位置; 必须是非负的

attachment - 要附加到I / O操作的对象; 可以是null

handler - 消费结果的处理程序

异常

IllegalArgumentException - 如果位置为负

NonWritableChannelException - 如果此通道未打开以进行写入

write

public abstract Future<Integer> write(ByteBuffer src,
                                      long position)

从给定的缓冲区向给定的文件位置开始，向该通道写入一个字节序列。

该方法从给定的缓冲区开始向该通道写入字节序列，从给定的文件位置开始。 该方法返回一个Future表示写操作的挂起结果。 Future的get方法返回写入的字节数。

该方法的工作方式与AsynchronousByteChannel.write(ByteBuffer)方法相同，只是字节从给定的文件位置开始写入。 如果给定的位置大于文件的大小，则在尝试写入时，该文件将生长以适应新的字节; 未指定上一个文件结尾和新写入的字节之间的任何字节的值。

参数

src - 要传输字节的缓冲区

position - 传输开始的文件位置; 必须是非负的

结果

表示待处理结果的 Future对象

异常

IllegalArgumentException - 如果位置为负

NonWritableChannelException - 如果此通道未打开以进行写入