Класс Buffer

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

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

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

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

Для каждого примитивного типа, кроме boolean, существует подкласс этого класса.

Передача данных

Каждый подкласс этого класса определяет две категории операций get и put:

Относительные операции читают или записывают один или несколько элементов, начиная с текущей позиции, а затем увеличивают позицию на количество переданных элементов. Если запрошенная передача выходит за пределы лимита, относительная операция get выбрасывает исключение BufferUnderflowException, а относительная операция put выбрасывает исключение BufferOverflowException; в обоих случаях данные не передаются.

Абсолютные операции принимают явный индекс элемента и не изменяют позицию. Абсолютные операции get и put выбрасывают исключение IndexOutOfBoundsException, если аргумент-индекс выходит за пределы лимита.

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

Установка отметки и сброс

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

Инварианты

Для значений отметки, позиции, предела и ёмкости выполняется следующий инвариант:

0 <= mark <= position <= limit <= capacity

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

Дополнительные операции

Помимо методов для доступа к значениям позиции, предела и ёмкости, а также для установки отметки и сброса, этот класс определяет следующие операции над буферами:

• clear() подготавливает буфер к новой последовательности операций чтения из канала или относительных операций put: устанавливает предел равным ёмкости, а позицию — равной нулю.

• flip() подготавливает буфер к новой последовательности операций записи в канал или относительных операций get: устанавливает предел равным текущей позиции, а затем устанавливает позицию равной нулю.

• rewind() подготавливает буфер к повторному чтению уже содержащихся в нём данных: оставляет предел без изменений и устанавливает позицию равной нулю.

• Методы slice() и slice(index,length) создают подпоследовательность буфера: они оставляют предел и позицию без изменений.

• duplicate() создаёт поверхностную копию буфера: она оставляет предел и позицию без изменений.

Буферы только для чтения

Каждый буфер доступен для чтения, но не каждый буфер доступен для записи. Методы изменения данных каждого класса буферов определены как необязательные операции, которые при вызове для буфера только для чтения выбрасывают исключение ReadOnlyBufferException. Буфер только для чтения не позволяет изменять своё содержимое, но значения его отметки, позиции и предела можно изменять. Чтобы определить, доступен ли буфер только для чтения, можно вызвать его метод isReadOnly.

Потокобезопасность

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

Цепочка вызовов

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

    b.flip();
    b.position(23);
    b.limit(42);

    b.flip().position(23).limit(42);