java filechannel api_FileChannel

方法详细信息

open public static FileChannel open​(Path path,

Set extends OpenOption> options,

FileAttribute>... attrs)

throws IOException

打开或创建文件，返回文件通道以访问该文件。

options参数确定文件的打开方式。 READ和WRITE选项确定是否应打开文件以进行读取和/或写入。 如果数组中都没有包含任何选项(或APPEND选项)，则打开文件进行读取。 默认情况下，在文件开头处开始读取或写入。

除了READ和WRITE ，还可能出现以下选项：

additional options Option Description APPEND If this option is present then the file is opened for writing and each invocation of the channel's 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 READ or TRUNCATE_EXISTING options. 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. 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).

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

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

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

参数

path - 要打开或创建的文件的路径

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

attrs - 创建文件时要自动设置的文件属性的可选列表

结果

一个新的文件通道

异常

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

对于默认提供程序，如果打开文件进行读取，则调用SecurityManager.checkRead(String)方法来检查读取访问权限。

从以下版本开始：

1.7

open public static FileChannel open​(Path path,

OpenOption... options)

throws IOException

打开或创建文件，返回文件通道以访问该文件。

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

fc.open(file, opts, new FileAttribute>[0]);

其中opts是options数组中指定的一组选项。

参数

path - 要打开或创建的文件的路径

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

结果

一个新的文件通道

异常

path与不支持创建文件通道的提供程序关联，或者指定了不支持的打开选项

对于默认提供程序，如果打开文件进行读取，则调用SecurityManager.checkRead(String)方法来检查读取访问权限。

从以下版本开始：

1.7

read public abstract int read​(ByteBuffer dst)

throws IOException

从该通道读取一个字节序列到给定的缓冲区。

从该通道的当前文件位置开始读取字节，然后使用实际读取的字节数更新文件位置。

Specified by:

Specified by:

参数

dst - 要传输字节的缓冲区

结果

如果通道已到达流末尾，则读取的字节数(可能为零)或

-1

异常

read public abstract long read​(ByteBuffer[] dsts,

int offset,

int length)

throws IOException

从该通道读取一系列字节到给定缓冲区的子序列。

从该通道的当前文件位置开始读取字节，然后使用实际读取的字节数更新文件位置。

Specified by:

参数

dsts - 要传输字节的缓冲区

offset - 要传输字节的第一个缓冲区的缓冲区数组内的偏移量;

必须是非负数且不大于dsts.length

length - 要访问的最大缓冲区数;

必须是非负数且不大于dsts.length - offset

结果

如果通道已到达流末尾，则读取的字节数(可能为零)或

-1

异常

read public final long read​(ByteBuffer[] dsts)

throws IOException

从该通道读取一系列字节到给定的缓冲区。

从该通道的当前文件位置开始读取字节，然后使用实际读取的字节数更新文件位置。

Specified by:

参数

dsts - 要传输字节的缓冲区

结果

如果通道已到达流末尾，则读取的字节数(可能为零)或

-1

异常

write public abstract int write​(ByteBuffer src)

throws IOException

从给定缓冲区向该通道写入一个字节序列。

除非通道处于附加模式，否则从该通道的当前文件位置开始写入字节，在这种情况下，位置首先前进到文件的末尾。 如有必要，文件将生长以容纳写入的字节，然后使用实际写入的字节数更新文件位置。

Specified by:

Specified by:

参数

src - 要从中检索字节的缓冲区

结果

写入的字节数，可能为零

异常

write public abstract long write​(ByteBuffer[] srcs,

int offset,

int length)

throws IOException

从给定缓冲区的子序列向该通道写入一个字节序列。

除非通道处于附加模式，否则从该通道的当前文件位置开始写入字节，在这种情况下，位置首先前进到文件的末尾。 如有必要，文件将生长以容纳写入的字节，然后使用实际写入的字节数更新文件位置。

Specified by:

参数

srcs - 要从中检索字节的缓冲区

offset - 要从中检索字节的第一个缓冲区的缓冲区数组中的偏移量;

必须是非负数且不大于srcs.length

length - 要访问的最大缓冲区数;

必须是非负数且不大于srcs.length - offset

结果

写入的字节数，可能为零

异常

write public final long write​(ByteBuffer[] srcs)

throws IOException

从给定的缓冲区向该通道写入一个字节序列。

除非通道处于附加模式，否则从该通道的当前文件位置开始写入字节，在这种情况下，位置首先前进到文件的末尾。 如有必要，文件将生长以容纳写入的字节，然后使用实际写入的字节数更新文件位置。

Specified by:

参数

srcs - 要从中检索字节的缓冲区

结果

写入的字节数，可能为零

异常

position public abstract long position()

throws IOException

返回此通道的文件位置。

Specified by:

结果

此通道的文件位置，一个非负整数，计算从文件开头到当前位置的字节数

异常

position public abstract FileChannel position​(long newPosition)

throws IOException

设置此通道的文件位置。

将位置设置为大于文件当前大小的值是合法的，但不会更改文件的大小。 稍后尝试在这样的位置读取字节将立即返回文件结束指示。 稍后尝试在这样的位置写入字节将导致文件增长以容纳新字节; 未指定前一个文件结尾和新写入字节之间的任何字节的值。

Specified by:

参数

newPosition - 新位置，一个非负整数，用于计算文件开头的字节数

结果

这个文件频道

异常

size public abstract long size()

throws IOException

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

Specified by:

结果

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

异常

truncate public abstract FileChannel truncate​(long size)

throws IOException

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

如果给定大小小于文件的当前大小，则文件将被截断，丢弃文件新端之外的任何字节。 如果给定大小大于或等于文件的当前大小，则不修改该文件。 在任何一种情况下，如果此通道的文件位置大于给定大小，则将其设置为该大小。

force public abstract void force​(boolean metaData)

throws IOException

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

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

如果文件不驻留在本地设备上，则不会进行此类保证。

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

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

此方法仅保证强制通过此类中定义的方法对此通道的文件进行更改。 它可能会也可能不会强制通过修改通过调用map方法获得的mapped byte buffer的内容进行更改 。 调用映射字节缓冲区的force方法将强制写入对缓冲区内容的更改。

参数

metaData - 如果是true则需要使用此方法强制更改文件的内容和要写入存储的元数据;

否则，只需强制内容更改即可写入

异常

transferTo public abstract long transferTo​(long position,

long count,

WritableByteChannel target)

throws IOException

将字节从此通道的文件传输到给定的可写字节通道。

尝试从该通道文件中的给定position开始读取最多count个字节，并将它们写入目标通道。 调用此方法可能会也可能不会传输所有请求的字节; 是否这样做取决于渠道的性质和状态。 如果此通道的文件包含从给定的position开始的少于count字节，或者目标通道是非阻塞且其输出缓冲区中的count字节少于position ，则传输的字节数少于所请求的字节数。

此方法不会修改此通道的位置。 如果给定位置大于文件的当前大小，则不传输任何字节。 如果目标通道有一个位置，则从该位置开始写入字节，然后该位置按写入的字节数递增。

此方法可能比从此通道读取并写入目标通道的简单循环更有效。 许多操作系统可以直接从文件系统缓存向目标通道传输字节，而无需实际复制它们。

参数

position - 文件在转移开始时的位置;

必须是非负面的

count - 要传输的最大字节数;

必须是非负面的

target - 目标通道

结果

实际传输的字节数，可能为零

异常

transferFrom public abstract long transferFrom​(ReadableByteChannel src,

long position,

long count)

throws IOException

从给定的可读字节通道将字节传输到此通道的文件中。

尝试从源通道读取最多count个字节，并从给定的position开始将它们写入此通道的文件。 调用此方法可能会也可能不会传输所有请求的字节; 是否这样做取决于渠道的性质和状态。 如果源通道剩余少于count个字节，或者源通道非阻塞且输入缓冲区中立即可用的字节数少于count少于count字节数。

此方法不会修改此通道的位置。 如果给定位置大于文件的当前大小，则不传输任何字节。 如果源通道有一个位置，则从该位置开始读取字节，然后将位置增加读取的字节数。

此方法可能比从源通道读取并写入此通道的简单循环更有效。 许多操作系统可以直接从源通道将字节传输到文件系统缓存中，而无需实际复制它们。

参数

src - 源通道

position - 文件在转移开始时的位置;

必须是非负面的

count - 要传输的最大字节数;

必须是非负面的

结果

实际传输的字节数，可能为零

异常

read public abstract int read​(ByteBuffer dst,

long position)

throws IOException

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

此方法的工作方式与read(ByteBuffer)方法相同，不同之处在于从给定文件位置开始而不是在通道的当前位置读取字节。 此方法不会修改此通道的位置。 如果给定位置大于文件的当前大小，则不读取任何字节。

参数

dst - 要传输字节的缓冲区

position - 要开始传输的文件位置;

必须是非负面的

结果

如果给定位置大于或等于文件的当前大小，则读取的字节数(可能为零)或

-1

异常

write public abstract int write​(ByteBuffer src,

long position)

throws IOException

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

此方法的工作方式与write(ByteBuffer)方法相同，不同之处在于从给定文件位置开始而不是在通道的当前位置开始写入字节。 此方法不会修改此通道的位置。 如果给定位置大于文件的当前大小，则文件将增长以容纳新字节; 未指定前一个文件结尾和新写入字节之间的任何字节的值。

参数

src - 要从中传输字节的缓冲区

position - 传输开始的文件位置;

必须是非负面的

结果

写入的字节数，可能为零

异常

map public abstract MappedByteBuffer map​(FileChannel.MapMode mode,

long position,

long size)

throws IOException

将此频道文件的某个区域直接映射到内存中。

文件的区域可以以三种模式之一映射到存储器中：

读/写：对结果缓冲区所做的更改最终会传播到文件中; 它们可能会或可能不会被映射到同一文件的其他程序看到。

专用：对生成的缓冲区所做的更改不会传播到文件，也不会对映射了同一文件的其他程序可见; 相反，它们将导致创建缓冲区的修改部分的私有副本。

对于只读映射，必须打开此通道才能读取; 对于读/写或私有映射，必须已打开此通道以进行读取和写入。

此方法返回的mapped byte buffer的位置为零，限制和容量为size ; 它的标记将是不确定的。 缓冲区及其表示的映射将保持有效，直到缓冲区本身被垃圾收集。

映射一旦建立，就不依赖于用于创建映射的文件通道。 特别是，关闭通道对映射的有效性没有影响。

内存映射文件的许多细节本质上依赖于底层操作系统，因此未指定。 未指定请求的区域未完全包含在此通道的文件中时此方法的行为。 是否通过此程序或其他程序对基础文件的内容或大小所做的更改传播到缓冲区是未指定的。 未指定缓冲区更改传播到文件的速率。

对于大多数操作系统，将文件映射到内存比通过通常的read和write方法读取或写入几十千字节的数据更昂贵。 从性能的角度来看，通常只需要将相对较大的文件映射到内存中。

lock public abstract FileLock lock​(long position,

long size,

boolean shared)

throws IOException

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

调用此方法将阻塞，直到可以锁定该区域，关闭此通道，或者中断调用线程，以先到者为准。

如果在调用此方法期间此通道被另一个线程关闭，则将抛出AsynchronousCloseException 。

如果在等待获取锁定时调用线程被中断，则将设置其中断状态并抛出FileLockInterruptionException 。 如果在调用此方法时设置了调用程序的中断状态，则会立即抛出该异常; 线程的中断状态不会改变。

由position和size参数指定的区域不需要包含在实际底层文件中，甚至不要包含在实际底层文件中。 锁定区域的大小是固定的; 如果锁定区域最初包含文件的末尾并且文件超出该区域，那么该文件的新部分将不会被锁定。 如果预计文件的大小会增加并且需要锁定整个文件，则应锁定从零开始并且不小于文件的预期最大大小的区域。

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

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

参数

position - 锁定区域开始的位置;

必须是非负面的

size - 锁定区域的大小;

必须为非负数，且总和position + size必须为非负数

shared - true请求共享锁，在这种情况下，此通道必须打开才能读取(并可能写入);

false请求独占锁定，在这种情况下，此通道必须打开才能写入(并可能读取)

结果

表示新获取的锁的锁对象

异常

shared是

false但此信道未开通以进行写入

另请参见：

lock public final FileLock lock()

throws IOException

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

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

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

tryLock public abstract FileLock tryLock​(long position,

long size,

boolean shared)

throws IOException

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

此方法不会阻止。 调用始终立即返回，要么已获取所请求区域的锁定，要么未能执行此操作。 如果由于另一个程序持有重叠锁而无法获取锁定，则返回null 。 如果由于任何其他原因而无法获取锁定，则会抛出相应的异常。

由position和size参数指定的区域不需要包含在实际底层文件中，甚至不要包含在实际底层文件中。 锁定区域的大小是固定的; 如果锁定区域最初包含文件的末尾并且文件超出该区域，那么该文件的新部分将不会被锁定。 如果预计文件的大小会增加并且需要锁定整个文件，则应锁定从零开始并且不小于文件的预期最大大小的区域。

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

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

参数

position - 锁定区域开始的位置;

必须是非负面的

size - 锁定区域的大小;

必须为非负数，且总和position + size必须为非负数

shared -

true请求共享锁，

false请求独占锁

结果

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

null

异常

另请参见：

tryLock public final FileLock tryLock()

throws IOException

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

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

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

结果

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

null

异常

另请参见：