Класс FileChannel

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

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

Конструкторы

FileChannel

protected FileChannel()

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

Методы

open

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

Параметры:

path - Путь к файлу, который нужно открыть или создать

options - Параметры, определяющие, как открыть файл

attrs - Необязательный список атрибутов файла, которые необходимо атомарно установить при создании файла

Возвращает:

Новый канал файла

Исключения:

IllegalArgumentException - Если набор содержит недопустимую комбинацию параметров

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

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]);

Параметры:

path - Путь к файлу, который нужно открыть или создать

options - Параметры, определяющие, как открыть файл

Возвращает:

Новый канал файла

Исключения:

IllegalArgumentException - Если набор содержит недопустимую комбинацию параметров

UnsupportedOperationException - Если path ассоциирован с поставщиком, который не поддерживает создание каналов файлов, или указан неподдерживаемый параметр открытия

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

SecurityException - Если установлен менеджер безопасности и он отклоняет не указанное разрешение, необходимое реализации. В случае с поставщиком по умолчанию, вызывается метод SecurityManager.checkRead(String) для проверки доступа на чтение, если файл открывается для чтения. Вызывается метод SecurityManager.checkWrite(String) для проверки доступа на запись, если файл открывается для записи

С:

1.7

read

public abstract int read(ByteBuffer dst)
                  throws IOException

Определено:

read в интерфейсе ReadableByteChannel

Определено:

read в интерфейсе SeekableByteChannel

Параметры:

dst - Буфер, в который должны быть переданы байты

Возвращает:

Количество прочитанных байтов, возможно ноль, или -1 если канал достиг конца потока

Исключения:

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

AsynchronousCloseException - Если другой поток закрывает этот канал во время операции чтения

ClosedByInterruptException - Если другой поток прерывает текущий поток во время операции чтения, тем самым закрывая канал и устанавливая статус прерывания текущего потока

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

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

read

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

Указано в:

read в интерфейсе ScatteringByteChannel

Параметры:

dsts - Буферы, в которые будут переданы байты

Возвращает:

Количество считанных байтов, возможно ноль, или -1 если канал достиг конца потока

Исключение:

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

AsynchronousCloseException - Если другой поток закрывает этот канал во время операции чтения

ClosedByInterruptException - Если другой поток прерывает текущий поток во время операции чтения, тем самым закрывая канал и устанавливая статус прерывания текущего потока

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

write

public abstract int write(ByteBuffer src)
                   throws IOException

Указано в:

write в интерфейсе SeekableByteChannel

Указано в:

write в интерфейсе WritableByteChannel

Параметры:

src - Буфер, из которого необходимо извлечь байты

Возвращает:

Количество записанных байтов, возможно ноль

Исключение:

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

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

ClosedByInterruptException - Если другой поток прерывает текущий поток во время операции записи, тем самым закрывая канал и устанавливая статус прерывания текущего потока

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

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

write

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

Указано в:

write в интерфейсе GatheringByteChannel

Параметры:

srcs - Буферы, из которых необходимо извлечь байты

Возвращает:

Количество записанных байтов, возможно ноль

Исключение:

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

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

ClosedByInterruptException - Если другой поток прерывает текущий поток во время операции записи, тем самым закрывая канал и устанавливая статус прерывания текущего потока

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

Исключение:

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

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

transferTo

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

Параметры:

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

count - Максимальное количество байтов для переноса; должно быть неотрицательным

target - Целевой канал

Возвращает:

Количество байтов, возможно ноль, которые были фактически перенесены

Исключение:

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

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

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

ClosedChannelException - Если этот канал или целевой канал закрыты

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

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

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

transferFrom

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

Параметры:

src - Исходный канал

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

count - Максимальное количество байтов для переноса; должно быть неотрицательным

Возвращает:

Количество байтов, возможно ноль, которые были фактически перенесены

Исключение:

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

NonReadableChannelException - Если исходный канал не был открыт для чтения

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

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

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

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

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

read

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

Параметры:

dst - Буфер, в который будут перенесены байты

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

Возвращает:

Количество прочитанных байтов, возможно ноль, или -1 если заданное положение больше или равно текущему размеру файла

Исключение:

IllegalArgumentException - Если положение отрицательное

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

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

AsynchronousCloseException - Если другой поток закрывает этот канал во время операции чтения

ClosedByInterruptException - Если другой поток прерывает текущий поток во время операции чтения, тем самым закрывая канал и устанавливая состояние прерывания текущего потока

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

write

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

Параметры:

src - Буфер, из которого будут перенесены байты

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

Возвращает:

Количество записанных байтов, возможно ноль

Исключение:

IllegalArgumentException - Если положение отрицательное

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

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

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

ClosedByInterruptException - Если другой поток прерывает текущий поток во время операции записи, тем самым закрывая канал и устанавливая состояние прерывания текущего потока

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

map

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

Параметры:

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

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

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

Возвращает:

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

Исключение:

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

NonWritableChannelException - Если mode равен READ_WRITE или PRIVATE, но этот канал не был открыт для чтения и записи

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

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

См. также:

FileChannel.MapMode, MappedByteBuffer

lock

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

Параметры:

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

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

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

Возвращает:

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

Исключение:

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

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

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

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

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

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

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

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

См. также:

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

lock

public final FileLock lock()
                    throws IOException

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

Возвращает:

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

Исключение:

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

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

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

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

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

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

См. также:

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

tryLock

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

Параметры:

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

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

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

Возвращает:

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

Исключение:

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

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

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

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

См. также:

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

tryLock

public final FileLock tryLock()
                       throws IOException

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

Возвращает:

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

Исключение:

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

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

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

См. также:

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