Класс AsynchronousFileChannel

Асинхронный канал для чтения, записи и обработки файла.

Асинхронный файл-канал создается при открытии файла путем вызова одного из методов open определенных в этом классе. Файл содержит последовательность байтов переменной длины, которые можно читать и записывать, а также размер которого можно получить с помощью queried. Размер файла увеличивается при записи байтов за пределами его текущего размера; размер файла уменьшается при его truncated.

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

Кроме операций чтения и записи, этот класс определяет следующие операции:

• Обновления файла могут быть forced out на базовое устройство хранения, гарантируя, что данные не будут потеряны в случае сбоя системы.

• Область файла может быть locked для предотвращения доступа другими программами.

С каналом связан AsynchronousFileChannel пул потоков, в который отправляются задачи для обработки событий ввода-вывода и передачи обработчикам завершения, которые обрабатывают результаты операций ввода-вывода на канале. Обработчик завершения для операции ввода-вывода, инициированной на канале, гарантированно вызывается одним из потоков в пуле потоков (это гарантирует, что обработчик завершения выполняется потоком с ожидаемой идентичностью). В случае, когда операция ввода-вывода завершается немедленно, и инициирующий поток сам является потоком в пуле потоков, то обработчик завершения может быть вызван непосредственно инициирующим потоком. При создании AsynchronousFileChannel без указания пула потоков канал связывается с системным по умолчанию пулом потоков, который может быть общим для других каналов. Пул потоков по умолчанию настраивается системными свойствами, определенными классом AsynchronousChannelGroup.

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

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

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

AsynchronousFileChannel

protected AsynchronousFileChannel()

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

Методы

open

public static AsynchronousFileChannel open(Path file,
                                           Set<? extends OpenOption> options,
                                           ExecutorService executor,
                                           FileAttribute<?>... attrs)
                                    throws IOException

Параметры:

file - Путь к файлу для открытия или создания

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

executor - Пул потоков или null для связывания канала с предустановленным пулом потоков

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

Возвращает:

Новый асинхронный файловый канал

Исключения:

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

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

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

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

open

public static AsynchronousFileChannel open(Path file,
                                           OpenOption... options)
                                    throws IOException

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

Параметры:

file - Путь к файлу для открытия или создания

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

Возвращает:

Новый асинхронный файловый канал

Исключения:

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

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

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

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

size

public abstract long size()
                   throws IOException

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

Возвращает:

Текущий размер файла этого канала, измеренный в байтах

Исключения:

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

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

truncate

public abstract AsynchronousFileChannel truncate(long size)
                                          throws IOException

Параметры:

size - Новый размер, количество байтов, неотрицательное значение

Возвращает:

Этот файловый канал

Исключения:

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

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

IllegalArgumentException - Если новый размер отрицательный

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

force

public abstract void force(boolean metaData)
                    throws IOException

Параметры:

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

Исключения:

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

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

lock

public abstract <A> void lock(long position,
                              long size,
                              boolean shared,
                              A attachment,
                              CompletionHandler<FileLock,? super A> handler)

Type Parameters:

A - Тип вложения

Parameters:

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

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

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

attachment - Объект, который необходимо присоединить к операции ввода-вывода; может быть null

handler - Обработчик для обработки результата

Throws:

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

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

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

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

lock

public final <A> void lock(A attachment,
                           CompletionHandler<FileLock,? super A> handler)

ch.lock(0L, Long.MAX_VALUE, false, att, handler)

Type Parameters:

A - Тип вложения

Parameters:

attachment - Объект, который необходимо присоединить к операции ввода-вывода; может быть null

handler - Обработчик для обработки результата

Throws:

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

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

lock

public abstract Future<FileLock> lock(long position,
                                      long size,
                                      boolean shared)

Parameters:

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

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

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

Returns:

объект Future, представляющий ожидаемый результат

Throws:

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

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

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

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

lock

public final Future<FileLock> lock()

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

Returns:

объект Future, представляющий ожидаемый результат

Throws:

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

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

tryLock

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

Parameters:

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

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

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

Returns:

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

Throws:

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

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

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

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

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

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

See Also:

lock(Object,CompletionHandler), lock(long,long,boolean,Object,CompletionHandler), tryLock()

tryLock

public final FileLock tryLock()
                       throws IOException

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

Returns:

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

Throws:

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

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

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

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

See Also:

lock(Object,CompletionHandler), lock(long,long,boolean,Object,CompletionHandler), tryLock(long,long,boolean)

read

public abstract <A> void read(ByteBuffer dst,
                              long position,
                              A attachment,
                              CompletionHandler<Integer,? super A> handler)

Параметры типа:

A - Тип присоединённого объекта

Параметры:

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

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

attachment - Объект, который необходимо прикрепить к операции ввода-вывода; может быть null

handler - Обработчик для обработки результата

Исключения:

IllegalArgumentException - Если позиция отрицательная или буфер только для чтения

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

read

public abstract Future<Integer> read(ByteBuffer dst,
                                     long position)

Параметры:

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

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

Возвращает:

Объект Future представляющий ожидаемый результат

Исключения:

IllegalArgumentException - Если позиция отрицательная или буфер только для чтения

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

write

public abstract <A> void write(ByteBuffer src,
                               long position,
                               A attachment,
                               CompletionHandler<Integer,? super A> handler)

Параметры типа:

A - Тип присоединённого объекта

Параметры:

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

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

attachment - Объект, который необходимо прикрепить к операции ввода-вывода; может быть null

handler - Обработчик для обработки результата

Исключения:

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

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

write

public abstract Future<Integer> write(ByteBuffer src,
                                      long position)

Параметры:

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

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

Возвращает:

Объект Future представляющий ожидаемый результат

Исключения:

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

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