构造方法详细信息

• 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()

• tryLock

  public final FileLock tryLock()
                         throws IOException

  尝试获取此频道文件的独占锁定。

  调用ch.tryLock()形式的此方法的行为与调用的方式完全相同

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

  结果

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

  异常

  ClosedChannelException - 如果此频道已关闭

  OverlappingFileLockException - 如果此Java虚拟机已经拥有与所请求区域重叠的锁，或者此方法中已阻止另一个线程并且正在尝试锁定重叠区域

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

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