Класс 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

См. также:

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

Модификатор и тип	Класс	Описание
`static class`	`FileChannel.MapMode`	Режим отображения файла.

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

FileChannel()

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

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

Модификатор и тип	Метод	Описание
`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`	`map(FileChannel.MapMode mode, long offset, long size, Arena 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)`	Записывает последовательность байтов в этот канал из указанного буфера, начиная с заданного положения в файле.

Методы, объявленные в классе AbstractInterruptibleChannel

begin, close, end, implCloseChannel, isOpen

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

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

Методы, объявленные в интерфейсе 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, могут быть указаны следующие параметры:

additional options
Параметр	Описание
`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 — если возникает ошибка ввода-вывода
С версии:: 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 — если возникает ошибка ввода-вывода
С версии:: 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

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

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

read

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

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

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

write

public abstract int write(ByteBuffer src) throws IOException

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

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

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

write

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

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

Определено в:: write в интерфейсе GatheringByteChannel
Параметры:: srcs — буферы, из которых нужно получить байты; offset — смещение в массиве буферов, указывающее на первый буфер, из которого нужно получить байты; должно быть неотрицательным и не превышать srcs.length; length — максимальное количество буферов для доступа; должно быть неотрицательным и не превышать srcs.length - offset
Возвращает:: Количество записанных байтов, возможно ноль
Исключения:: ClosedChannelException — если этот канал закрыт; AsynchronousCloseException — если другой поток закрывает этот канал во время операции записи; ClosedByInterruptException — если другой поток прерывает текущий поток во время операции записи, тем самым закрывая канал и устанавливая статус прерывания текущего потока; NonWritableChannelException — если этот канал открыт не для записи; IOException — если возникает другая ошибка ввода-вывода

write

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

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

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

position

public abstract long position() throws IOException

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

Определено в:: position в интерфейсе SeekableByteChannel
Возвращает:: Позицию файла в этом канале — неотрицательное целое число, обозначающее количество байтов от начала файла до текущей позиции
Исключения:: ClosedChannelException — если этот канал закрыт; IOException — если возникает другая ошибка ввода-вывода

position

public abstract FileChannel position(long newPosition) throws IOException

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

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

Определено в:: position в интерфейсе SeekableByteChannel
Параметры:: newPosition — новая позиция, неотрицательное целое число, обозначающее количество байтов от начала файла
Возвращает:: Этот файловый канал
Исключения:: ClosedChannelException — если этот канал закрыт; IllegalArgumentException — если новая позиция отрицательна; IOException — если возникает другая ошибка ввода-вывода

size

public abstract long size() throws IOException

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

Определено в:: size в интерфейсе SeekableByteChannel
Возвращает:: Текущий размер файла этого канала в байтах
Исключения:: ClosedChannelException — если этот канал закрыт; IOException — если возникает другая ошибка ввода-вывода

truncate

public abstract FileChannel truncate(long size) throws IOException

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

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

Определено в:: truncate в интерфейсе SeekableByteChannel
Параметры:: size — новый размер, неотрицательное количество байтов
Возвращает:: Этот файловый канал
Исключения:: NonWritableChannelException — если этот канал открыт не для записи; ClosedChannelException — если этот канал закрыт; IllegalArgumentException — если новый размер отрицателен; IOException — если возникает другая ошибка ввода-вывода

force

public abstract void force(boolean metaData) throws IOException

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

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

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

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

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

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

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

transferTo

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

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

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

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

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

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

transferFrom

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

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

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

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

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

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

read

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

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

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

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

write

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

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

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

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

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

map

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, возвращаемый этим методом, будет иметь позицию, равную нулю, а предел и ёмкость, равные size; его отметка будет неопределена. Буфер и представляемое им отображение будут оставаться действительными до тех пор, пока сам буфер не будет удалён сборщиком мусора.

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

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

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

Параметры:

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

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

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

Возвращает:

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

Выбрасывает:

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

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

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

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

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

См. также:

map

public MemorySegment map(FileChannel.MapMode mode, long offset, long size, Arena arena) throws IOException

Отображает область файла этого канала в новый сегмент отображённой памяти с указанными смещением, размером и ареной. Адрес возвращаемого сегмента памяти — это начальный адрес отображённой области вне кучи, на основе которой создан сегмент.

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

Если указан режим отображения 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; WrongThreadException — Если arena является ограниченной областью видимости арены и этот метод вызван из потока T, отличного от потока-владельца арены с ограниченной областью видимости; NonReadableChannelException — Если mode — это READ_ONLY или режим отображения, определяемый реализацией и требующий доступа для чтения, но этот канал открыт не для чтения; NonWritableChannelException — Если mode — это READ_WRITE, PRIVATE или режим отображения, определяемый реализацией и требующий доступа для записи, но этот канал открыт не для чтения и записи одновременно; IOException — Если возникает другая ошибка ввода-вывода; UnsupportedOperationException — Если указан неподдерживаемый режим отображения
С версии:: 22

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 должна быть неотрицательной. Нулевое значение означает блокировку всех байтов от указанной начальной позиции до конца файла независимо от того, будет ли файл впоследствии расширен или усечён

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, 2025, 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/25/docs/api/java.base/java/nio/channels/FileChannel.html