Класс FileChannel

java.lang.Object

java.nio.channels.spi.AbstractInterruptibleChannel

java.nio.channels.FileChannel

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

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

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

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

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

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

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

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

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

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

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

С момента:

1.4

См. также:

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

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

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

FileChannel()

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

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

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

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

begin, close, end, implCloseChannel, isOpen

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

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

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

isOpen

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

FileChannel

protected FileChannel()

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

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

open

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

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

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

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

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

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

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

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

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

open

public static FileChannel open(Path path, OpenOption... options) throws IOException

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

Вызов этого метода ведет себя точно так же, как вызов

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

где opts является набором параметров, указанных в массиве


 options

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

read

public abstract int read(ByteBuffer dst) throws IOException

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

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

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

чтение

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

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

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

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

чтение

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

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

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

запись

public abstract int write(ByteBuffer src) throws IOException

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

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

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

запись

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 - Если другой поток прерывает текущий поток во время операции записи, тем самым закрывая канал и устанавливая статус прерывания текущего потока; IOException - Если произошла какая-либо другая ошибка ввода-вывода

запись

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

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

Определено в:: write в интерфейсе GatheringByteChannel
Параметры:: srcs - Буферы, из которых должны быть извлечены байты
Возвращает:: Количество записанных байтов, возможно ноль
Исключения:: ClosedChannelException - Если этот канал закрыт; AsynchronousCloseException - Если другой поток закрывает этот канал во время операции записи; ClosedByInterruptException - Если другой поток прерывает текущий поток во время операции записи, тем самым закрывая канал и устанавливая статус прерывания текущего потока; 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 означает, что должны быть записаны обновления как содержимого файла, так и метаданных, что обычно требует как минимум одной дополнительной операции ввода-вывода. Действительно ли этот параметр оказывает влияние, зависит от операционной системы и поэтому не определено.

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

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

lock

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

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

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

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

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

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

Некоторые операционные системы не поддерживают совместные блокировки, в этом случае запрос на совместную блокировку автоматически преобразуется в запрос на исключительную блокировку. Можно проверить, является ли полученная блокировка совместной или исключительной, вызвав метод 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()
tryLock()
tryLock(long,long,boolean)

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:

lock(long,long,boolean)
tryLock()
tryLock(long,long,boolean)

tryLock

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

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

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

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

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

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

Parameters:

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

size - Размер заблокированной области; должна быть неотрицательной, и сумма position + size должна быть неотрицательной

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

Returns:

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

Throws:

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

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

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

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

See Also:

lock()
lock(long,long,boolean)
tryLock()

tryLock

public final FileLock tryLock() throws IOException

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

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

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

Returns:

Throws:

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

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

See Also:

lock()
lock(long,long,boolean)
tryLock(long,long,boolean)

© 1993, 2021, 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/17/docs/api/java.base/java/nio/channels/FileChannel.html