模块  java.base
软件包  java.nio.channels

Class AsynchronousFileChannel

  • 实现的所有接口
    Closeable ， AutoCloseable ， AsynchronousChannel ， Channel 
    public abstract class AsynchronousFileChannel
extends Object
implements AsynchronousChannel
    用于读取，写入和操作文件的异步通道。

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

    异步文件通道在文件中没有当前位置 。 而是为每个启动异步操作的读写方法指定文件位置。 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

    • 构造方法详细信息

      • 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 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虚拟机已经拥有与所请求区域重叠的锁，或者已调用此方法来锁定重叠区域并且该操作尚未完成，则此方法将抛出OverlappingFileLockException 。

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

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

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

        参数类型
        A - 附件的类型
        参数
        position - 锁定区域开始的位置; 必须是非负面的
        size - 锁定区域的大小; 必须是非负数，总和position + size必须是非负数
        shared - true请求共享锁，在这种情况下，此通道必须打开才能读取（并可能写入）; false请求独占锁定，在这种情况下，此通道必须打开才能写入（并可能读取）
        attachment - 要附加到I / O操作的对象; 可以是null
        handler - 使用结果的处理程序
        异常
        OverlappingFileLockException - 如果此Java虚拟机已拥有与所请求区域重叠的锁，或者已存在暂挂尝试以锁定重叠区域
        IllegalArgumentException - 如果参数的前提条件不成立
        NonReadableChannelException - 如果 shared为true，但未打开此通道进行读取
        NonWritableChannelException - 如果 shared为false，但未打开此通道进行写入

      • 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为true，但未打开此通道进行读取
        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为true，但未打开此通道进行读取
        NonWritableChannelException - 如果 shared为false，但未打开此通道进行写入
        IOException - 如果发生其他一些I / O错误
        另请参见：
        lock(Object,CompletionHandler) ， lock(long,long,boolean,Object,CompletionHandler) ， tryLock()

      • 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 - 如果未打开此频道进行写入