Класс FileChannel

java.lang.Object

java.nio.channels.spi.AbstractInterruptibleChannel

java.nio.channels.FileChannel

Все реализованные интерфейсы:: Closeable, AutoCloseable, ByteChannel, Channel, GatheringByteChannel, InterruptibleChannel, ReadableByteChannel, ScatteringByteChannel, SeekableByteChannel, WritableByteChannel

public abstract class FileChannel extends AbstractInterruptibleChannel implements SeekableByteChannel, GatheringByteChannel, ScatteringByteChannel

Канал для чтения, записи, отображения и манипулирования файлом.

Канал файла — это SeekableByteChannel, подключенный к файлу. Он имеет текущую позицию внутри файла, которую можно как queried, так и modified. Сам файл содержит последовательность байтов переменной длины, которые можно читать и записывать, и чей текущий size можно запросить. Размер файла увеличивается при записи байтов за пределы его текущего размера; размер файла уменьшается при truncated. Файл также может иметь некоторую связанную метаданные, такие как разрешения на доступ, тип содержимого и время последнего изменения; в этом классе не определены методы доступа к метаданным.

В дополнение к обычным операциям чтения, записи и закрытия байтовых каналов, этот класс определяет следующие операции, специфичные для файлов:

Байты могут быть read или written в абсолютной позиции в файле таким образом, что не влияет на текущую позицию канала.
Область файла может быть mapped непосредственно в память; для больших файлов это часто намного эффективнее, чем вызов обычных read или write методов.
Обновления файла могут быть forced out на базовом устройстве хранения, гарантируя, что данные не потеряны в случае сбоя системы.
Байты могут быть переданы из файла to some other channel, и vice versa, что может быть оптимизировано многими операционными системами в очень быструю передачу непосредственно в или из кэша файловой системы.
Область файла может быть locked от доступа другими программами.

Каналы файлов безопасны для использования несколькими потоками. Метод close можно вызывать в любое время, как указано в интерфейсе Channel. Одновременно может выполняться только одна операция, которая включает позицию канала или может изменить размер файла; попытки инициировать вторую такую операцию, пока первая еще выполняется, приведут к блокированию до завершения первой операции. Другие операции, особенно те, которые принимают явную позицию, могут выполняться одновременно; фактически ли они это делают, зависит от базовой реализации и поэтому не определено.

Вид файла, предоставляемый экземпляром этого класса, гарантированно согласуется с другими видами того же файла, предоставляемыми другими экземплярами в той же программе. Однако вид, предоставляемый экземпляром этого класса, может или не может быть согласован с видами, которые видят другие выполняющиеся одновременно программы, из-за кэширования, выполняемого базовой операционной системой, и задержек, вызванных сетевыми файловыми протоколами. Это верно независимо от языка, на котором написаны эти другие программы, и от того, работают ли они на той же машине или на другой. Точный характер таких несоответствий зависит от системы и поэтому не определен.

Канал файла создается путем вызова одного из методов open, определенных в этом классе. Канал файла также можно получить из существующего FileInputStream, FileOutputStream или RandomAccessFile объекта, вызвав метод объекта getChannel, который возвращает канал файла, подключенный к тому же базовому файлу. В тех случаях, когда канал файла получен из существующего потока или файла случайного доступа, состояние канала файла тесно связано с состоянием объекта, чей метод getChannel вернул канал. Изменение позиции канала, как явно, так и при чтении или записи байтов, изменит позицию файла исходного объекта, и наоборот. Изменение длины файла через канал файла изменит длину, видимую через исходный объект, и наоборот. Изменение содержимого файла путем записи байтов изменит содержимое, видимое исходным объектом, и наоборот. Закрытие канала закроет исходный объект.

В разных местах в этом классе указано, что требуется экземпляр, который "открыт для чтения", "открыт для записи" или "открыт для чтения и записи". Канал, полученный через метод getChannel экземпляра FileInputStream, будет открыт для чтения. Канал, полученный через метод getChannel экземпляра FileOutputStream, будет открыт для записи. И наконец, канал, полученный через метод getChannel экземпляра RandomAccessFile, будет открыт для чтения, если экземпляр был создан с режимом "r" и будет открыт для чтения и записи, если экземпляр был создан с режимом "rw".

Канал файла, открытый для записи, может быть в режиме дописывания, например, если он был получен из потока вывода файла, созданного путем вызова конструктора FileOutputStream(File,boolean) и передачи true для второго параметра. В этом режиме каждый вызов операции записи относительно сначала перемещает позицию в конец файла, а затем записывает запрошенные данные. Осуществляется ли перемещение позиции и запись данных в единую атомарную операцию, зависит от системы и поэтому не определено. В этом режиме поведение метода записи по заданной позиции также зависит от системы.

С тех пор:

1.4

См. также:

Краткое описание вложенных классов

Modifier and Type	Class	Description
`static class`	`FileChannel.MapMode`	Режим отображения файлов.

Краткое описание конструкторов

FileChannel()

Modifier	Конструктор	Description
`protected`	Инициализирует новый экземпляр этого класса.

Краткое описание методов

Modifier and Type	Метод	Description
`abstract void`	`force(boolean metaData)`	Вынуждает запись любых обновлений файла этого канала на устройство хранения, которое его содержит.
`final FileLock`	`lock()`	Получает эксклюзивную блокировку файла этого канала.
`abstract FileLock`	`lock(long position, long size, boolean shared)`	Получает блокировку заданного региона файла этого канала.
`abstract MappedByteBuffer`	`map(FileChannel.MapMode mode, long position, long size)`	Отображает область файла этого канала непосредственно в память.
`MemorySegment^PREVIEW`	`map(FileChannel.MapMode mode, long offset, long size, Arena^PREVIEW arena)`	Предварительный просмотр. Отображает область файла этого канала в новый сегмент отображенной памяти с заданным смещением, размером и ареной.
`static FileChannel`	`open(Path path, OpenOption... options)`	Открывает или создаёт файл, возвращая канал файла для доступа к файлу.
`static FileChannel`	`open(Path path, Set<? extends OpenOption> options, FileAttribute<?>... attrs)`	Открывает или создаёт файл, возвращая канал файла для доступа к файлу.
`abstract long`	`position()`	Возвращает позицию файла этого канала.
`abstract FileChannel`	`position(long newPosition)`	Устанавливает позицию файла этого канала.
`abstract int`	`read(ByteBuffer dst)`	Читает последовательность байтов из этого канала в заданный буфер.
`final long`	`read(ByteBuffer[] dsts)`	Читает последовательность байтов из этого канала в заданные буферы.
`abstract long`	`read(ByteBuffer[] dsts, int offset, int length)`	Читает последовательность байтов из этого канала в подпоследовательность заданных буферов.
`abstract int`	`read(ByteBuffer dst, long position)`	Читает последовательность байтов из этого канала в заданный буфер, начиная с заданной позиции файла.
`abstract long`	`size()`	Возвращает текущий размер файла этого канала.
`abstract long`	`transferFrom(ReadableByteChannel src, long position, long count)`	Переносит байты в файл этого канала из заданного читаемого канала байтов.
`abstract long`	`transferTo(long position, long count, WritableByteChannel target)`	Переносит байты из файла этого канала в заданный записываемый канал байтов.
`abstract FileChannel`	`truncate(long size)`	Обрезает файл этого канала до заданного размера.
`final FileLock`	`tryLock()`	Попытка получить эксклюзивную блокировку файла этого канала.
`abstract FileLock`	`tryLock(long position, long size, boolean shared)`	Попытка получить блокировку заданного региона файла этого канала.
`abstract int`	`write(ByteBuffer src)`	Записывает последовательность байтов в этот канал из заданного буфера.
`final long`	`write(ByteBuffer[] srcs)`	Записывает последовательность байтов в этот канал из заданных буферов.
`abstract long`	`write(ByteBuffer[] srcs, int offset, int length)`	Записывает последовательность байтов в этот канал из подпоследовательности заданных буферов.
`abstract int`	`write(ByteBuffer src, long position)`	Записывает последовательность байтов в этот канал из заданного буфера, начиная с заданной позиции файла.

Методы, объявленные в классе java.nio.channels.spi.AbstractInterruptibleChannel

begin, close, end, implCloseChannel, isOpen

Методы, объявленные в классе java.lang.Object

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

Методы, объявленные в интерфейсе java.nio.channels.Channel

isOpen

Подробное описание конструкторов

FileChannel

protected FileChannel()

Инициализирует новый экземпляр этого класса.

Подробное описание методов

open

public static FileChannel open(Path path, Set<? extends OpenOption> options, FileAttribute<?>... attrs) throws IOException

Открывает или создаёт файл, возвращая канал файла для доступа к файлу.

Параметр options определяет, как открывается файл. Параметры READ и WRITE определяют, должен ли файл открываться для чтения и/или записи. Если ни один из параметров (или параметр APPEND) не содержится в массиве, то файл открывается для чтения. По умолчанию чтение или запись начинается в начале файла.

В дополнение к READ и WRITE, могут быть указаны следующие параметры:

дополнительные параметры
Параметр	Описание
`APPEND`	Если этот параметр указан, то файл открывается для записи, и каждое обращение к методу канала `write` сначала перемещает позицию к концу файла, а затем записывает запрошенные данные. То, выполняются ли перемещение позиции и запись данных в одной атомарной операции, зависит от системы и не определено. Эффект записи в определённой позиции при указании этого параметра не определён. Этот параметр не может использоваться совместно с параметрами `READ` или `TRUNCATE_EXISTING`.
`TRUNCATE_EXISTING`	Если этот параметр указан, то существующий файл обрезается до размера 0 байт. Этот параметр игнорируется, когда файл открывается только для чтения.
`CREATE_NEW`	Если этот параметр указан, то создаётся новый файл, что приводит к ошибке, если файл уже существует. При создании файла проверка существования файла и создание файла, если он не существует, является атомарной относительно других операций с файловой системой. Этот параметр игнорируется, когда файл открывается только для чтения.
`CREATE`	Если этот параметр указан, то существующий файл открывается, если он существует, в противном случае создаётся новый файл. При создании файла проверка существования файла и создание файла, если он не существует, является атомарной относительно других операций с файловой системой. Этот параметр игнорируется, если также указан параметр `CREATE_NEW` или файл открывается только для чтения.
`DELETE_ON_CLOSE`	При указании этого параметра реализация делает попытку удалить файл при закрытии с помощью метода `close`. Если метод `close` не вызывается, то делается попытка удалить файл при завершении работы виртуальной машины Java.
`SPARSE`	При создании нового файла этот параметр является подсказкой, что новый файл будет разреженным. Этот параметр игнорируется, если новый файл не создаётся.
`SYNC`	Требуется, чтобы каждое обновление содержимого или метаданных файла синхронно записывалось на подлежащее устройство хранения. (см. Целостность синхронизированных ввода-вывода файлов).
`DSYNC`	Требуется, чтобы каждое обновление содержимого файла синхронно записывалось на подлежащее устройство хранения. (см. Целостность синхронизированных ввода-вывода файлов).

Реализация может также поддерживать дополнительные параметры.

Параметр attrs — это необязательный массив атрибутов файла file-attributes, которые устанавливаются атомарно при создании файла.

Новый канал создаётся путём вызова метода newFileChannel поставщика, который создал Path.

Параметры:: path - Путь к файлу, который необходимо открыть или создать; options - Параметры, определяющие, как открывается файл; attrs - Необязательный список атрибутов файла, которые устанавливаются атомарно при создании файла
Возвращает:: Новый канал файла
Исключения:: IllegalArgumentException - Если набор содержит недопустимое сочетание параметров; UnsupportedOperationException - Если path связан с поставщиком, который не поддерживает создание каналов файлов, или указан неподдерживаемый параметр открытия, или массив содержит атрибут, который не может быть установлен атомарно при создании файла; FileAlreadyExistsException - Если файл с таким именем уже существует, и указан параметр CREATE_NEW, и файл открывается для записи (необязательное специальное исключение); IOException - Если произошла ошибка ввода-вывода; SecurityException - Если установлен менеджер безопасности и он отклоняет неопределённое разрешение, необходимое реализации. В случае с поставщиком по умолчанию, вызывается метод SecurityManager.checkRead(String) для проверки доступа на чтение, если файл открывается для чтения. Метод SecurityManager.checkWrite(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 - Параметры, определяющие, как открывается файл
Возвращает:: Новый канал файла
Исключения:: IllegalArgumentException - Если набор содержит недопустимое сочетание параметров; UnsupportedOperationException - Если path связан с поставщиком, который не поддерживает создание каналов файлов, или указан неподдерживаемый параметр открытия; FileAlreadyExistsException - Если файл с таким именем уже существует, и указан параметр CREATE_NEW, и файл открывается для записи (необязательное специальное исключение); IOException - Если произошла ошибка ввода-вывода; SecurityException - Если установлен менеджер безопасности и он отклоняет неопределённое разрешение, необходимое реализации. В случае с поставщиком по умолчанию, вызывается метод SecurityManager.checkRead(String) для проверки доступа на чтение, если файл открывается для чтения. Метод SecurityManager.checkWrite(String) вызывается для проверки доступа на запись, если файл открывается для записи
С тех пор:: 1.7

read

public abstract int read(ByteBuffer dst) throws IOException

Считывает последовательность байтов из этого канала в указанный буфер.

Байты считываются, начиная с текущей позиции файла в этом канале, а затем позиция файла обновляется количеством фактически прочитанных байтов. В противном случае этот метод ведёт себя точно так же, как указано в интерфейсе ReadableByteChannel.

Определено в:: read в интерфейсе ReadableByteChannel
Определено в:: read в интерфейсе SeekableByteChannel
Параметры:: dst - Буфер, в который должны быть переданы байты
Возвращает:: Количество прочитанных байтов, возможно ноль, или -1, если канал достиг конца потока
Исключения:: ClosedChannelException - Если этот канал закрыт; AsynchronousCloseException - Если другой поток закрывает этот канал во время операции чтения; ClosedByInterruptException - Если другой поток прерывает текущий поток во время операции чтения, тем самым закрывая канал и устанавливая состояние прерывания текущего потока; NonReadableChannelException - Если этот канал не был открыт для чтения; IOException - Если произошла другая ошибка ввода-вывода

read

public abstract long read(ByteBuffer[] dsts, int offset, int length) throws IOException

Считывает последовательность байтов из этого канала в подпоследовательность заданных буферов.

Байты считываются, начиная с текущей позиции файла в этом канале, а затем позиция файла обновляется числом фактически прочитанных байтов. В противном случае этот метод ведет себя точно так же, как указано в интерфейсе ScatteringByteChannel.

Specified by:: read в интерфейсе ScatteringByteChannel
Parameters:: dsts - Буферы, в которые будут передаваться байты; offset - Смещение в массиве буферов первого буфера, в который будут передаваться байты; должно быть неотрицательным и не больше dsts.length; length - Максимальное количество буферов для доступа; должно быть неотрицательным и не больше dsts.length - offset
Returns:: Количество прочитанных байтов, возможно ноль, или -1 если канал достиг конца потока
Throws:: ClosedChannelException - Если этот канал закрыт; AsynchronousCloseException - Если другой поток закрывает этот канал во время операции чтения; ClosedByInterruptException - Если другой поток прерывает текущий поток во время операции чтения, тем самым закрывая канал и устанавливая статус прерывания текущего потока; NonReadableChannelException - Если этот канал не был открыт для чтения; IOException - Если произошла какая-либо другая ошибка ввода-вывода

read

public final long read(ByteBuffer[] dsts) throws IOException

Считывает последовательность байтов из этого канала в заданные буферы.

Specified by:: read в интерфейсе ScatteringByteChannel
Parameters:: dsts - Буферы, в которые будут передаваться байты
Returns:: Количество прочитанных байтов, возможно ноль, или -1 если канал достиг конца потока
Throws:: ClosedChannelException - Если этот канал закрыт; AsynchronousCloseException - Если другой поток закрывает этот канал во время операции чтения; ClosedByInterruptException - Если другой поток прерывает текущий поток во время операции чтения, тем самым закрывая канал и устанавливая статус прерывания текущего потока; NonReadableChannelException - Если этот канал не был открыт для чтения; IOException - Если произошла какая-либо другая ошибка ввода-вывода

write

public abstract int write(ByteBuffer src) throws IOException

Записывает последовательность байтов в этот канал из заданного буфера.

Байты записываются, начиная с текущей позиции файла в этом канале, если канал не находится в режиме добавления, в противном случае позиция сначала перемещается в конец файла. Файл увеличивается, если необходимо, для размещения записанных байтов, а затем позиция файла обновляется числом фактически записанных байтов. В противном случае этот метод ведет себя точно так же, как указано в интерфейсе WritableByteChannel.

Specified by:: write в интерфейсе SeekableByteChannel
Specified by:: write в интерфейсе WritableByteChannel
Parameters:: src - Буфер, из которого должны быть извлечены байты
Returns:: Количество записанных байтов, возможно ноль
Throws:: ClosedChannelException - Если этот канал закрыт; AsynchronousCloseException - Если другой поток закрывает этот канал во время операции записи; ClosedByInterruptException - Если другой поток прерывает текущий поток во время операции записи, тем самым закрывая канал и устанавливая статус прерывания текущего потока; NonWritableChannelException - Если этот канал не был открыт для записи; IOException - Если произошла какая-либо другая ошибка ввода-вывода

write

public abstract long write(ByteBuffer[] srcs, int offset, int length) throws IOException

Записывает последовательность байтов в этот канал из подпоследовательности заданных буферов.

Specified by:: write в интерфейсе GatheringByteChannel
Parameters:: srcs - Буферы, из которых должны быть извлечены байты; offset - Смещение в массиве буферов первого буфера, из которого должны быть извлечены байты; должно быть неотрицательным и не больше srcs.length; length - Максимальное количество буферов для доступа; должно быть неотрицательным и не больше srcs.length - offset
Returns:: Количество записанных байтов, возможно ноль
Throws:: ClosedChannelException - Если этот канал закрыт; AsynchronousCloseException - Если другой поток закрывает этот канал во время операции записи; ClosedByInterruptException - Если другой поток прерывает текущий поток во время операции записи, тем самым закрывая канал и устанавливая статус прерывания текущего потока; NonWritableChannelException - Если этот канал не был открыт для записи; IOException - Если произошла какая-либо другая ошибка ввода-вывода

write

public final long write(ByteBuffer[] srcs) throws IOException

Записывает последовательность байтов в этот канал из заданных буферов.

Specified by:: write в интерфейсе GatheringByteChannel
Parameters:: srcs - Буферы, из которых должны быть извлечены байты
Returns:: Количество записанных байтов, возможно ноль
Throws:: ClosedChannelException - Если этот канал закрыт; AsynchronousCloseException - Если другой поток закрывает этот канал во время операции записи; ClosedByInterruptException - Если другой поток прерывает текущий поток во время операции записи, тем самым закрывая канал и устанавливая статус прерывания текущего потока; NonWritableChannelException - Если этот канал не был открыт для записи; IOException - Если произошла какая-либо другая ошибка ввода-вывода

position

public abstract long position() throws IOException

Возвращает позицию файла этого канала.

Specified by:: position в интерфейсе SeekableByteChannel
Returns:: Позиция файла этого канала, неотрицательное целое число, подсчитывающее количество байтов с начала файла до текущей позиции
Throws:: ClosedChannelException - Если этот канал закрыт; IOException - Если произошла какая-либо другая ошибка ввода-вывода

position

public abstract FileChannel position(long newPosition) throws IOException

Устанавливает позицию файла этого канала.

Установка позиции на значение, большее текущего размера файла, допустима, но не изменяет размер файла. Позднее попытка чтения байтов в такой позиции сразу же вернёт указание на конец файла. Позднее попытка записи байтов в такую позицию приведет к увеличению файла для размещения новых байтов; значения любых байтов между предыдущим концом файла и новыми записанными байтами не определены.

Specified by:: position в интерфейсе SeekableByteChannel
Parameters:: newPosition - Новая позиция, неотрицательное целое число, подсчитывающее количество байтов с начала файла
Returns:: Этот канал файла
Throws:: ClosedChannelException - Если этот канал закрыт; IllegalArgumentException - Если новая позиция отрицательна; IOException - Если произошла какая-либо другая ошибка ввода-вывода

size

public abstract long size() throws IOException

Возвращает текущий размер файла этого канала.

Specified by:: size в интерфейсе SeekableByteChannel
Returns:: Текущий размер файла этого канала, измеренный в байтах
Throws:: ClosedChannelException - Если этот канал закрыт; IOException - Если произошла какая-либо другая ошибка ввода-вывода

truncate

public abstract FileChannel truncate(long size) throws IOException

Усекает файл этого канала до указанного размера.

Если заданный размер меньше текущего размера файла, то файл усекается, отбрасывая любые байты после нового конца файла. Если заданный размер больше или равен текущему размеру файла, то файл не изменяется. В любом случае, если позиция файла этого канала больше заданного размера, она устанавливается на этот размер.

Specified by:: truncate в интерфейсе SeekableByteChannel
Parameters:: size - Новый размер, количество байтов
Returns:: Этот канал файла
Throws:: NonWritableChannelException - Если этот канал не был открыт для записи; ClosedChannelException - Если этот канал закрыт; IllegalArgumentException - Если новый размер отрицательный; IOException - Если произошла какая-либо другая ошибка ввода-вывода

END_OF_DOCUMENT_MARKER

force

public abstract void force(boolean metaData) throws IOException

Принудительно записывает любые обновления файла этого канала на устройство хранения, на котором он находится.

Если файл этого канала находится на локальном устройстве хранения, то по возвращении этого метода гарантируется, что все изменения, внесенные в файл с момента создания этого канала или с момента последнего вызова этого метода, будут записаны на это устройство. Это полезно для обеспечения того, чтобы критически важная информация не была потеряна в случае сбоя системы.

Если файл не находится на локальном устройстве, то такая гарантия не предоставляется.

Параметр metaData может использоваться для ограничения числа операций ввода-вывода, которые должен выполнить этот метод. Передача значения false для этого параметра указывает, что в хранилище необходимо записать только обновления содержимого файла; передача значения true указывает, что необходимо записать обновления как содержимого, так и метаданных файла, что, как правило, требует как минимум еще одной операции ввода-вывода. Действительно ли этот параметр оказывает какое-либо влияние зависит от операционной системы и поэтому не определено.

Вызов этого метода может вызвать операцию ввода-вывода даже в том случае, если канал был открыт только для чтения. Некоторые операционные системы, например, хранят время последнего доступа в качестве части метаданных файла, и это время обновляется всякий раз, когда файл читается. Производится ли это на самом деле зависит от системы и поэтому не определено.

Этот метод гарантирует принудительное выполнение только тех изменений, которые были внесены в файл этого канала с помощью методов, определенных в этом классе, или методов, определенных в FileOutputStream или RandomAccessFile при получении канала с помощью метода getChannel. Он может или может не принудительно выполнить изменения, внесенные путем изменения содержимого mapped byte buffer, полученного путем вызова метода map. Вызов метода force отображаемого буфера байтов принудительно запишет изменения, внесенные в содержимое буфера.

Parameters:: metaData - Если true, то этот метод должен принудительно записать в хранилище изменения как содержимого, так и метаданных файла; в противном случае, он должен только принудительно записать изменения содержимого.
Throws:: ClosedChannelException - Если этот канал закрыт; IOException - Если произошла какая-то другая ошибка ввода-вывода

transferTo

public abstract long transferTo(long position, long count, WritableByteChannel target) throws IOException

Переносит байты из файла этого канала в заданный канал записи байтов.

Предпринимается попытка прочитать до count байтов, начиная с заданного position в файле этого канала, и записать их в целевой канал. Вызов этого метода может или не может передать все запрошенные байты; выполняется ли это зависит от природы и состояния каналов. Меньше запрошенного числа байтов передаётся, если файл этого канала содержит меньше чем count байтов, начиная с заданного position, или если целевой канал неблокирующий и имеет меньше чем count байтов в буфере вывода.

Этот метод не изменяет положение этого канала. Если заданное положение больше или равно текущему размеру файла, то байты не передаются. Если у целевого канала есть позиция, то байты записываются, начиная с этой позиции, а затем позиция увеличивается на количество записанных байтов.

Этот метод потенциально намного эффективнее, чем простой цикл, который считывает из этого канала и записывает в целевой канал. Многие операционные системы могут напрямую передавать байты из кэша файловой системы в целевой канал, не копируя их.

Parameters:: position - Позиция в файле, с которой должен начаться перенос; должна быть неотрицательной; count - Максимальное количество байтов для передачи; должно быть неотрицательным; target - Целевой канал
Returns:: Количество байтов, возможно ноль, которые были фактически переданы
Throws:: IllegalArgumentException - Если условия на параметрах не соблюдаются; NonReadableChannelException - Если этот канал не был открыт для чтения; NonWritableChannelException - Если целевой канал не был открыт для записи; ClosedChannelException - Если этот канал или целевой канал закрыты; AsynchronousCloseException - Если другой поток закрывает любой из каналов во время переноса; ClosedByInterruptException - Если другой поток прерывает текущий поток во время переноса, тем самым закрывая оба канала и устанавливая статус прерывания текущего потока; IOException - Если произошла какая-то другая ошибка ввода-вывода

transferFrom

public abstract long transferFrom(ReadableByteChannel src, long position, long count) throws IOException

Переносит байты в файл этого канала из заданного канала чтения байтов.

Предпринимается попытка прочитать до count байтов из исходного канала и записать их в файл этого канала, начиная с заданного position. Вызов этого метода может или не может передать все запрошенные байты; выполняется ли это зависит от природы и состояния каналов. Меньше запрошенного числа байтов будет передано, если в исходном канале осталось меньше чем count байтов, или если исходный канал неблокирующий и в его буфере ввода доступно меньше чем count байтов. Если в источнике достигнут конец потока, байты не передаются и возвращается ноль.

Этот метод не изменяет положение этого канала. Если заданное положение больше или равно текущему размеру файла, то размер файла будет увеличен для размещения новых байтов; значения любых байтов между предыдущим концом файла и вновь записанными байтами не определены. Если у исходного канала есть позиция, то байты считываются, начиная с этой позиции, а затем позиция увеличивается на количество прочитанных байтов.

Этот метод потенциально намного эффективнее, чем простой цикл, который читает из исходного канала и записывает в этот канал. Многие операционные системы могут напрямую передавать байты из исходного канала в кэш файловой системы, не копируя их.

Parameters:: src - Источник канала; position - Позиция файла, с которой должен начаться перенос; должна быть неотрицательной; count - Максимальное количество байтов для передачи; должно быть неотрицательным
Returns:: Количество байтов, возможно ноль, которые были фактически переданы
Throws:: IllegalArgumentException - Если условия на параметрах не соблюдаются; NonReadableChannelException - Если исходный канал не был открыт для чтения; NonWritableChannelException - Если этот канал не был открыт для записи; ClosedChannelException - Если этот канал или исходный канал закрыты; AsynchronousCloseException - Если другой поток закрывает любой из каналов во время переноса; ClosedByInterruptException - Если другой поток прерывает текущий поток во время переноса, тем самым закрывая оба канала и устанавливая статус прерывания текущего потока; IOException - Если произошла какая-то другая ошибка ввода-вывода

read

public abstract int read(ByteBuffer dst, long position) throws IOException

Считывает последовательность байтов из этого канала в заданный буфер, начиная с заданной позиции файла.

Этот метод работает так же, как метод read(ByteBuffer), за исключением того, что байты считываются, начиная с заданной позиции файла, а не с текущей позиции канала. Этот метод не изменяет позицию этого канала. Если заданная позиция больше или равна текущему размеру файла, то байты не считываются.

Parameters:: dst - Буфер, в который будут перенесены байты; position - Позиция файла, с которой должен начаться перенос; должна быть неотрицательной
Returns:: Количество прочитанных байтов, возможно ноль, или -1 если заданная позиция больше или равна текущему размеру файла
Throws:: IllegalArgumentException - Если позиция отрицательная или буфер только для чтения; NonReadableChannelException - Если этот канал не был открыт для чтения; ClosedChannelException - Если этот канал закрыт; AsynchronousCloseException - Если другой поток закрывает этот канал во время операции чтения; ClosedByInterruptException - Если другой поток прерывает текущий поток во время операции чтения, тем самым закрывая канал и устанавливая статус прерывания текущего потока; IOException - Если произошла какая-то другая ошибка ввода-вывода

запись

public abstract int write(ByteBuffer src, long position) throws IOException

Записывает последовательность байтов в этот канал из заданного буфера, начиная с заданной позиции файла.

Этот метод работает аналогично методу write(ByteBuffer), за исключением того, что байты записываются, начиная с заданной позиции файла, а не с текущей позиции канала. Этот метод не изменяет позицию этого канала. Если заданная позиция больше или равна текущему размеру файла, то файл будет увеличен для размещения новых байтов; значения любых байтов между предыдущим концом файла и вновь записанными байтами не определены.

Если файл открыт в режиме приложения, то результат вызова этого метода не определён.

Параметры:: src - Буфер, из которого будут передаваться байты; position - Позиция файла, с которой должен начаться обмен; должна быть неотрицательной
Возвращаемое значение:: Количество записанных байтов, возможно ноль
Исключения:: IllegalArgumentException - Если позиция отрицательна; NonWritableChannelException - Если этот канал не был открыт для записи; ClosedChannelException - Если этот канал закрыт; AsynchronousCloseException - Если другой поток закрывает этот канал во время выполнения операции записи; ClosedByInterruptException - Если другой поток прерывает текущий поток во время выполнения операции записи, тем самым закрывая канал и устанавливая статус прерывания текущего потока; IOException - Если произошла другая ошибка ввода-вывода

карта

public abstract MappedByteBuffer map(FileChannel.MapMode mode, long position, long size) throws IOException

Отображает область файла этого канала непосредственно в память.

Параметр mode указывает, как область файла отображается и может иметь следующие режимы:

Только чтение: любая попытка изменить полученный буфер приведет к сбрасыванию ReadOnlyBufferException. (MapMode.READ_ONLY)
Чтение/запись: изменения, внесенные в результирующий буфер, в конечном итоге будут перенесены в файл; они могут быть или не быть видимыми для других программ, которые отобразили тот же файл. (MapMode.READ_WRITE)
Приватный: изменения, внесенные в результирующий буфер, не будут перенесены в файл и не будут видны другим программам, которые отобразили тот же файл; вместо этого они приведут к созданию частных копий изменённых участков буфера. (MapMode.PRIVATE)

Реализация может поддерживать дополнительные режимы отображения.

Для отображения только для чтения этот канал должен быть открыт для чтения; для отображения чтения/записи или частного отображения этот канал должен быть открыт для чтения и записи.

mapped byte buffer, возвращаемый этим методом, будет иметь позицию 0 и предел и емкость size; его метка будет неопределённой. Буфер и отображение, которое он представляет, останутся действительными до тех пор, пока сам буфер не будет удалён сборщиком мусора.

Отображение, после его создания, не зависит от канала файла, который использовался для его создания. Закрытие канала, в частности, не влияет на действительность отображения.

Многие подробности отображения файлов в памяти по своей природе зависят от базовой операционной системы и поэтому не определены. Поведение этого метода в случае, если запрашиваемая область не полностью содержится в файле этого канала, не определено. Не определено, переносятся ли внесенные этим или другим процессом изменения в содержимое или размер базового файла в буфер. Скорость переноса изменений из буфера в файл не определена.

Для большинства операционных систем отображение файла в память более затратно, чем чтение или запись нескольких десятков килобайтов данных с помощью обычных методов read и write. С точки зрения производительности это обычно целесообразно только для относительно больших файлов.

Параметры:

mode - Одна из констант READ_ONLY, READ_WRITE или PRIVATE, определённых в классе FileChannel.MapMode, соответственно, для отображения файла только для чтения, для чтения/записи или в частном порядке (copy-on-write), или специфичного для реализации режима отображения

position - Позиция в файле, с которой должна начинаться отображаемая область; должна быть неотрицательной

size - Размер отображаемой области; должен быть неотрицательным и не превышать Integer.MAX_VALUE

Возвращаемое значение:

Отображённый буфер байтов

Исключения:

NonReadableChannelException - Если mode равен READ_ONLY или специфическому для реализации режиму отображения, требующему доступ для чтения, но этот канал не был открыт для чтения

NonWritableChannelException - Если mode равен READ_WRITE, PRIVATE или специфическому для реализации режиму отображения, требующему доступ для записи, но этот канал не был открыт как для чтения, так и для записи

IllegalArgumentException - Если условия на параметры не соблюдены

UnsupportedOperationException - Если указан неподдерживаемый режим отображения

IOException - Если произошла другая ошибка ввода-вывода

См. также:

карта

public MemorySegmentPREVIEW map(FileChannel.MapMode mode, long offset, long size, ArenaPREVIEW arena) throws IOException

map — это предварительная версия API платформы Java.

Программы могут использовать map только при включенных функциях предварительной версии.

Функции предварительной версии могут быть удалены в будущих выпусках или обновлены до постоянных функций платформы Java.

Отображает область файла этого канала в новый сегмент отображённой памяти с заданным смещением, размером и ареной. Адрес^{ПРЕДПРОСМОТР} возвращённого сегмента памяти — это начальный адрес отображённой вне кучи области, поддерживающей сегмент.

Жизненный цикл возвращённого сегмента контролируется предоставленной ареной. Например, если предоставленная арена является закрываемой ареной, возвращённый сегмент будет размапирован при закрытии^{ПРЕДПРОСМОТР} предоставленной закрываемой арены.

Если указанный режим отображения равен READ_ONLY, результирующий сегмент будет только для чтения (см. MemorySegment.isReadOnly()^{ПРЕДПРОСМОТР}).

Содержимое сегмента отображённой памяти может изменяться в любое время, например, если содержимое соответствующей области отображаемого файла изменяется этим (или другим) приложением. Происходит ли такое изменение и когда — зависит от операционной системы и поэтому не определено.

Весь или часть сегмента отображённой памяти может стать недоступным в любое время, например, если отображаемый файл усечён. Попытка доступа к недоступной области сегмента отображённой памяти не изменит содержимое сегмента и вызовет неопределённое исключение либо в момент доступа, либо в какой-то момент позднее. Поэтому настоятельно рекомендуется принять надлежащие меры предосторожности, чтобы избежать изменения отображаемого файла этим (или другим) приложением, кроме чтения или записи содержимого файла.

Требования к реализации:: Стандартная реализация этого метода выбрасывает UnsupportedOperationException.
Примечание для реализации:: При получении отображённого сегмента из только что созданного канала файла начальное состояние содержимого блока отображённой памяти, связанной с возвращённым сегментом отображённой памяти, не определено и не должно использоваться.
Параметры:: mode - Режим отображения файла, см. map(FileChannel.MapMode, long, long); режим отображения может повлиять на поведение возвращённого сегмента отображённой памяти (см. MemorySegment.force()^{ПРЕДПРОСМОТР}).; offset - Смещение (выраженное в байтах) в файле, с которого должен начинаться отображаемый сегмент.; size - Размер отображаемой памяти, поддерживающей сегмент памяти.; arena - Арена сегмента.
Возвращаемое значение:: Новый сегмент отображённой памяти.
Исключения:: IllegalArgumentException - Если offset < 0, size < 0 или offset + size выходит за пределы диапазона long.; IllegalStateException - Если arena.isAlive() == false.; IllegalStateException - Если arena.isAlive() == false.; WrongThreadException - Если арена с ограниченным объёмом и этот метод вызван из потока T, отличного от потока-владельца арены с ограниченным объёмом.; NonReadableChannelException - Если mode равен READ_ONLY или специфическому для реализации режиму отображения, требующему доступ для чтения, но этот канал не был открыт для чтения.; NonWritableChannelException - Если mode равен READ_WRITE, PRIVATE или специфическому для реализации режиму отображения, требующему доступ для записи, но этот канал не был открыт как для чтения, так и для записи.; IOException - Если произошла другая ошибка ввода-вывода.; UnsupportedOperationException - Если указан неподдерживаемый режим отображения.
См. также:: 19

lock

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

Захватывает блокировку заданного региона файла этого канала.

Вызов этого метода будет блокировать выполнение, пока регион не будет заблокирован, этот канал не будет закрыт или вызывающая нить не будет прервана, что произойдёт первым.

Если этот канал закрывается другой нитью во время вызова этого метода, будет брошено исключение AsynchronousCloseException.

Если вызывающая нить прерывается во время ожидания получения блокировки, то флаг прерывания этой нити будет установлен, и будет брошено исключение FileLockInterruptionException. Если флаг прерывания вызывающей нити установлен при вызове этого метода, то это исключение будет брошено немедленно; флаг прерывания нити не будет изменён.

Область, заданная параметрами position и size, может не содержаться в, и даже не пересекаться с, фактическим базовым файлом. Регионы блокировки имеют фиксированный размер; если заблокированный регион изначально содержит конец файла, и файл расширится за пределы региона, то новая часть файла не будет покрыта блокировкой. Если ожидается, что размер файла увеличится, и требуется блокировка всего файла, то регион, начинающийся с нуля и не меньший, чем ожидаемый максимальный размер файла, следует заблокировать. Метод lock() без аргументов просто блокирует регион размером Long.MAX_VALUE. Если position неотрицательно, а size равно нулю, то возвращается блокировка размером Long.MAX_VALUE - position.

Некоторые операционные системы не поддерживают совместные блокировки, в этом случае запрос на совместную блокировку автоматически преобразуется в запрос на эксклюзивную блокировку. Можно ли проверить, является ли полученная блокировка совместной или эксклюзивной, вызвав метод isShared результата объекта блокировки.

Блокировки файлов выполняются от имени всей виртуальной машины Java. Они не подходят для управления доступом к файлу несколькими нитями в одной виртуальной машине.

Параметры:

position - Позиция начала заблокированного региона; должна быть неотрицательной

size - Размер заблокированного региона; должен быть неотрицательным, и сумма position + size должна быть неотрицательной. Значение 0 означает блокировку всех байтов от указанной начальной позиции до конца файла, независимо от того, будет ли файл впоследствии расширен или укорочен

shared - true для запроса совместной блокировки, в этом случае этот канал должен быть открыт для чтения (и, возможно, записи); false для запроса эксклюзивной блокировки, в этом случае этот канал должен быть открыт для записи (и, возможно, чтения)

Возвращает:

Объект блокировки, представляющий вновь полученную блокировку

Исключения:

IllegalArgumentException - Если условия на параметры не выполнены

ClosedChannelException - Если этот канал закрыт

AsynchronousCloseException - Если другой поток закрывает этот канал, пока вызывающая нить заблокирована в этом методе

FileLockInterruptionException - Если вызывающая нить прерывается, пока заблокирована в этом методе

OverlappingFileLockException - Если блокировка, перекрывающая запрашиваемый регион, уже удерживается этой виртуальной машиной Java, или если другая нить уже заблокирована в этом методе и пытается заблокировать перекрывающийся регион

NonReadableChannelException - Если shared - true, но этот канал не был открыт для чтения

NonWritableChannelException - Если shared - false, но этот канал не был открыт для записи

IOException - Если произошла какая-то другая ошибка ввода-вывода

См. также:

lock

public final FileLock lock() throws IOException

Захватывает эксклюзивную блокировку файла этого канала.

Вызов этого метода в форме fc.lock() ведет себя точно так же, как вызов

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

Возвращает:

Объект блокировки, представляющий вновь полученную блокировку

Исключения:

ClosedChannelException - Если этот канал закрыт

AsynchronousCloseException - Если другой поток закрывает этот канал, пока вызывающая нить заблокирована в этом методе

FileLockInterruptionException - Если вызывающая нить прерывается, пока заблокирована в этом методе

NonWritableChannelException - Если этот канал не был открыт для записи

IOException - Если произошла какая-то другая ошибка ввода-вывода

См. также:

tryLock

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

Попытка получить блокировку заданного региона файла этого канала.

Этот метод не блокируется. Вызов всегда возвращает немедленно, либо получив блокировку на запрашиваемый регион, либо не сумев это сделать. Если попытка получить блокировку терпит неудачу из-за того, что другая программа держит перекрывающуюся блокировку, то она возвращает null. Если она терпит неудачу по любой другой причине, то выбрасывается соответствующее исключение.

Область, заданная параметрами position и size, может не содержаться в, и даже не пересекаться с, фактическим базовым файлом. Регионы блокировки имеют фиксированный размер; если заблокированный регион изначально содержит конец файла, и файл расширится за пределы региона, то новая часть файла не будет покрыта блокировкой. Если ожидается, что размер файла увеличится, и требуется блокировка всего файла, то регион, начинающийся с нуля и не меньший, чем ожидаемый максимальный размер файла, следует заблокировать. Метод tryLock() без аргументов просто блокирует регион размером Long.MAX_VALUE. Если position неотрицательно, а size равно нулю, то возвращается блокировка размером Long.MAX_VALUE - position.

Параметры:

position - Позиция начала заблокированного региона; должна быть неотрицательной

shared - true для запроса совместной блокировки, false для запроса эксклюзивной блокировки

Возвращает:

Объект блокировки, представляющий вновь полученную блокировку, или null если блокировка не может быть получена, потому что другая программа держит перекрывающуюся блокировку

Исключения:

IllegalArgumentException - Если условия на параметры не выполнены

ClosedChannelException - Если этот канал закрыт

NonReadableChannelException - Если shared - true, но этот канал не был открыт для чтения

NonWritableChannelException - Если shared - false, но этот канал не был открыт для записи

IOException - Если произошла какая-то другая ошибка ввода-вывода

См. также:

tryLock

public final FileLock tryLock() throws IOException

Попытка получить эксклюзивную блокировку файла этого канала.

Вызов этого метода в форме fc.tryLock() ведет себя точно так же, как вызов

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

Возвращает:

Исключения:

ClosedChannelException - Если этот канал закрыт

NonWritableChannelException - Если этот канал не был открыт для записи

IOException - Если произошла какая-то другая ошибка ввода-вывода

См. также:

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/nio/channels/FileChannel.html