Класс Buffer

Контейнер для данных определенного примитивного типа.

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

Емкость буфера — количество элементов, которое он содержит. Емкость буфера никогда не отрицательная и никогда не меняется.

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

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

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

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

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

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

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

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

Пометка и сброс

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

Инварианты

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

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

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

Очистка, переворот и сброс

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

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

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

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

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

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

Безопасность потоков

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

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

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

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

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

Методы

capacity

public final int capacity()

Возвращает емкость этого буфера.

Возвращает:

Емкость этого буфера

position

public final int position()

Возвращает текущую позицию этого буфера.

Возвращает:

Позицию этого буфера

position

public final Buffer position(int newPosition)

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

Параметры:

newPosition - Новое значение позиции; должно быть неотрицательным и не больше текущего предела

Возвращает:

Этот буфер

Выбрасывает:

IllegalArgumentException - Если условия на newPosition не выполнены

limit

public final int limit()

Возвращает предел этого буфера.

Возвращает:

Предел этого буфера

limit

public final Buffer limit(int newLimit)

Устанавливает предел этого буфера. Если позиция больше нового предела, она устанавливается равной новому пределу. Если метка определена и больше нового предела, она отбрасывается.

Параметры:

newLimit - Новое значение предела; должно быть неотрицательным и не больше емкости этого буфера

Возвращает:

Этот буфер

Выбрасывает:

IllegalArgumentException - Если условия на newLimit не выполнены

mark

public final Buffer mark()

Устанавливает метку этого буфера в его текущей позиции.

Возвращает:

Этот буфер

reset

public final Buffer reset()

Возвращает:

Этот буфер

Выбрасывает:

InvalidMarkException - Если метка не была установлена

clear

public final Buffer clear()

buf.clear();     // Prepare buffer for reading
in.read(buf);    // Read data

Возвращает:

Этот буфер

flip

public final Buffer flip()

buf.put(magic);    // Prepend header
in.read(buf);      // Read data into rest of buffer
buf.flip();        // Flip buffer
out.write(buf);    // Write header + data to channel

Возвращает:

Этот буфер

rewind

public final Buffer rewind()

out.write(buf);    // Write remaining data
buf.rewind();      // Rewind buffer
buf.get(array);    // Copy data into array

Возвращает:

Этот буфер

remaining

public final int remaining()

Возвращает количество элементов между текущей позицией и пределом.

Возвращает:

Количество элементов, оставшихся в этом буфере

hasRemaining

public final boolean hasRemaining()

Определяет, есть ли элементы между текущей позицией и пределом.

Возвращает:

true если и только если в этом буфере есть как минимум один оставшийся элемент

isReadOnly

public abstract boolean isReadOnly()

Определяет, является ли этот буфер только для чтения.

Возвращает:

true если и только если этот буфер является только для чтения

hasArray

public abstract boolean hasArray()

Возвращает:

true если и только если этот буфер поддерживается массивом и не является только для чтения

С:

1.6

array

public abstract Object array()

Возвращает:

Массив, поддерживающий этот буфер

Выбрасывает:

ReadOnlyBufferException - Если этот буфер поддерживается массивом, но является только для чтения

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

С:

1.6

arrayOffset

public abstract int arrayOffset()

Возвращает:

Смещение в массиве буфера первого элемента буфера

Выбрасывает:

ReadOnlyBufferException - Если этот буфер поддерживается массивом, но является только для чтения

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

С:

1.6

isDirect

public abstract boolean isDirect()

Определяет, является ли этот буфер прямым.

Возвращает:

true если и только если этот буфер прямой

С:

1.6