Класс 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)`	Записывает последовательность байтов в этот канал из заданного буфера, начиная с заданной позиции в файле.

Методы, объявленные в классе 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 — Если произошла ошибка ввода-вывода
С:: 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 — Если произошла другая ошибка ввода-вывода

чтение

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

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

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

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

запись

public abstract int write(ByteBuffer src) throws IOException

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

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

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

запись

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

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

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

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

запись

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

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

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

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

позиция

public abstract long position() throws IOException

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

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

позиция

public abstract FileChannel position(long newPosition) throws IOException

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

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

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

размер

public abstract long size() throws IOException

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

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

усечение

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

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

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

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

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

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

Parameters:

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

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

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

Returns:

Картированный буфер байтов

Throws:

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

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

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

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

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

See Also:

map

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

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

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

Если указанный режим отображения — READ_ONLY, полученный сегмент будет только для чтения (см. MemorySegment.isReadOnly()).

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

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

Implementation Requirements:: Реализация по умолчанию этого метода выбрасывает UnsupportedOperationException.
Implementation Note:: При получении отображённого сегмента из только что созданного канала файла начальное состояние содержимого блока отображённой памяти, связанного с возвращаемым отображённым сегментом памяти, не определено и на нём нельзя полагаться.
Parameters:: mode - Режим отображения файла, см. map(FileChannel.MapMode, long, long); режим отображения может повлиять на поведение возвращаемого сегмента отображённой памяти (см. MemorySegment.force()); offset - Смещение (выраженное в байтах) в файле, с которого начинается отображаемый сегмент; size - Размер (в байтах) отображённой памяти, поддерживающей сегмент памяти; arena - Арена сегмента
Returns:: Новый сегмент отображённой памяти
Throws:: 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 - Если указан неподдерживаемый режим отображения
Since:: 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. Они не подходят для управления доступом к файлу несколькими потоками внутри одной виртуальной машины.

Parameters:

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

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

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

Returns:

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

Throws:

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

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

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

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

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

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

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

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

See Also:

lock

public final FileLock lock() throws IOException

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

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

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

Returns:

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

Throws:

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

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

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

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

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

See Also:

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.

Parameters:

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

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

Returns:

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

Throws:

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

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

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

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

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

See Also:

tryLock

public final FileLock tryLock() throws IOException

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

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

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

Returns:

Throws:

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

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

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

See Also:

© 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://download.java.net/java/early_access/jdk24/docs/api/java.base/java/nio/channels/FileChannel.html