/* * Copyright (C) 2014 The Android Open Source Project * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.nio; import java.util.Spliterator; /** * A container for data of a specific primitive type. * *
A buffer is a linear, finite sequence of elements of a specific * primitive type. Aside from its content, the essential properties of a * buffer are its capacity, limit, and position:
* ** ** *A buffer's capacity is the number of elements it contains. The * capacity of a buffer is never negative and never changes.
* *A buffer's limit is the index of the first element that should * not be read or written. A buffer's limit is never negative and is never * greater than its capacity.
* *A buffer's position is the index of the next element to be * read or written. A buffer's position is never negative and is never * greater than its limit.
* *
There is one subclass of this class for each non-boolean primitive type. * * *
Each subclass of this class defines two categories of get and * put operations:
* ** ** *Relative operations read or write one or more elements starting * at the current position and then increment the position by the number of * elements transferred. If the requested transfer exceeds the limit then a * relative get operation throws a {@link BufferUnderflowException} * and a relative put operation throws a {@link * BufferOverflowException}; in either case, no data is transferred.
* *Absolute operations take an explicit element index and do not * affect the position. Absolute get and put operations throw * an {@link IndexOutOfBoundsException} if the index argument exceeds the * limit.
* *
Data may also, of course, be transferred in to or out of a buffer by the * I/O operations of an appropriate channel, which are always relative to the * current position. * * *
A buffer's mark is the index to which its position will be reset * when the {@link #reset reset} method is invoked. The mark is not always * defined, but when it is defined it is never negative and is never greater * than the position. If the mark is defined then it is discarded when the * position or the limit is adjusted to a value smaller than the mark. If the * mark is not defined then invoking the {@link #reset reset} method causes an * {@link InvalidMarkException} to be thrown. * * *
The following invariant holds for the mark, position, limit, and * capacity values: * *
* 0 <= * mark <= * position <= * limit <= * capacity ** *
A newly-created buffer always has a position of zero and a mark that is * undefined. The initial limit may be zero, or it may be some other value * that depends upon the type of the buffer and the manner in which it is * constructed. Each element of a newly-allocated buffer is initialized * to zero. * * *
In addition to methods for accessing the position, limit, and capacity * values and for marking and resetting, this class also defines the following * operations upon buffers: * *
{@link #clear} makes a buffer ready for a new sequence of * channel-read or relative put operations: It sets the limit to the * capacity and the position to zero.
{@link #flip} makes a buffer ready for a new sequence of * channel-write or relative get operations: It sets the limit to the * current position and then sets the position to zero.
{@link #rewind} makes a buffer ready for re-reading the data that * it already contains: It leaves the limit unchanged and sets the position * to zero.
Every buffer is readable, but not every buffer is writable. The * mutation methods of each buffer class are specified as optional * operations that will throw a {@link ReadOnlyBufferException} when * invoked upon a read-only buffer. A read-only buffer does not allow its * content to be changed, but its mark, position, and limit values are mutable. * Whether or not a buffer is read-only may be determined by invoking its * {@link #isReadOnly isReadOnly} method. * * *
Buffers are not safe for use by multiple concurrent threads. If a * buffer is to be used by more than one thread then access to the buffer * should be controlled by appropriate synchronization. * * *
Methods in this class that do not otherwise have a value to return are * specified to return the buffer upon which they are invoked. This allows * method invocations to be chained; for example, the sequence of statements * *
* * can be replaced by the single, more compact statement * ** b.flip(); * b.position(23); * b.limit(42);
* * @author Mark Reinhold * @author JSR-51 Expert Group * @since 1.4 */ public abstract class Buffer { /** * The characteristics of Spliterators that traverse and split elements * maintained in Buffers. */ static final int SPLITERATOR_CHARACTERISTICS = Spliterator.SIZED | Spliterator.SUBSIZED | Spliterator.ORDERED; // Invariants: mark <= position <= limit <= capacity private int mark = -1; int position = 0; private int limit; private int capacity; // Used only by direct buffers // NOTE: hoisted here for speed in JNI GetDirectBufferAddress long address; /** * The log base 2 of the element size of this buffer. Each typed subclass * (ByteBuffer, CharBuffer, etc.) is responsible for initializing this * value. The value is used by JNI code in frameworks/base/ to avoid the * need for costly 'instanceof' tests. */ final int _elementSizeShift; // Creates a new buffer with the given mark, position, limit, and capacity, // after checking invariants. // Buffer(int mark, int pos, int lim, int cap, int elementSizeShift) { // package-private if (cap < 0) throw new IllegalArgumentException("Negative capacity: " + cap); this.capacity = cap; limit(lim); position(pos); if (mark >= 0) { if (mark > pos) throw new IllegalArgumentException("mark > position: (" + mark + " > " + pos + ")"); this.mark = mark; } _elementSizeShift = elementSizeShift; } /** * Returns this buffer's capacity. * * @return The capacity of this buffer */ public final int capacity() { return capacity; } /** * Returns this buffer's position. * * @return The position of this buffer */ public final int position() { return position; } /** * Sets this buffer's position. If the mark is defined and larger than the * new position then it is discarded. * * @param newPosition The new position value; must be non-negative * and no larger than the current limit * @return This buffer * @throws IllegalArgumentException If the preconditions on newPosition do not hold */ public final Buffer position(int newPosition) { if ((newPosition > limit) || (newPosition < 0)) throw new IllegalArgumentException("Bad position " + newPosition + "/" + limit); position = newPosition; if (mark > position) mark = -1; return this; } /** * Returns this buffer's limit. * * @return The limit of this buffer */ public final int limit() { return limit; } /** * Sets this buffer's limit. If the position is larger than the new limit * then it is set to the new limit. If the mark is defined and larger than * the new limit then it is discarded. * * @param newLimit The new limit value; must be non-negative * and no larger than this buffer's capacity * @return This buffer * @throws IllegalArgumentException If the preconditions on newLimit do not hold */ public final Buffer limit(int newLimit) { if ((newLimit > capacity) || (newLimit < 0)) throw new IllegalArgumentException(); limit = newLimit; if (position > limit) position = limit; if (mark > limit) mark = -1; return this; } /** * Sets this buffer's mark at its position. * * @return This buffer */ public final Buffer mark() { mark = position; return this; } /** * Resets this buffer's position to the previously-marked position. * ** b.flip().position(23).limit(42);
Invoking this method neither changes nor discards the mark's * value.
* * @return This buffer * @throws InvalidMarkException If the mark has not been set */ public final Buffer reset() { int m = mark; if (m < 0) throw new InvalidMarkException(); position = m; return this; } /** * Clears this buffer. The position is set to zero, the limit is set to * the capacity, and the mark is discarded. * *Invoke this method before using a sequence of channel-read or * put operations to fill this buffer. For example: * *
* ** buf.clear(); // Prepare buffer for reading * in.read(buf); // Read data
This method does not actually erase the data in the buffer, but it * is named as if it did because it will most often be used in situations * in which that might as well be the case.
* * @return This buffer */ public final Buffer clear() { position = 0; limit = capacity; mark = -1; return this; } /** * Flips this buffer. The limit is set to the current position and then * the position is set to zero. If the mark is defined then it is * discarded. * *After a sequence of channel-read or put operations, invoke * this method to prepare for a sequence of channel-write or relative * get operations. For example: * *
* ** 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
This method is often used in conjunction with the {@link * java.nio.ByteBuffer#compact compact} method when transferring data from * one place to another.
* * @return This buffer */ public final Buffer flip() { limit = position; position = 0; mark = -1; return this; } /** * Rewinds this buffer. The position is set to zero and the mark is * discarded. * *Invoke this method before a sequence of channel-write or get * operations, assuming that the limit has already been set * appropriately. For example: * *
* * @return This buffer */ public final Buffer rewind() { position = 0; mark = -1; return this; } /** * Returns the number of elements between the current position and the * limit. * * @return The number of elements remaining in this buffer */ public final int remaining() { return limit - position; } /** * Tells whether there are any elements between the current position and * the limit. * * @return true if, and only if, there is at least one element * remaining in this buffer */ public final boolean hasRemaining() { return position < limit; } /** * Tells whether or not this buffer is read-only. * * @return true if, and only if, this buffer is read-only */ public abstract boolean isReadOnly(); /** * Tells whether or not this buffer is backed by an accessible * array. * ** out.write(buf); // Write remaining data * buf.rewind(); // Rewind buffer * buf.get(array); // Copy data into array
If this method returns true then the {@link #array() array} * and {@link #arrayOffset() arrayOffset} methods may safely be invoked. *
* * @return true if, and only if, this buffer * is backed by an array and is not read-only * @since 1.6 */ public abstract boolean hasArray(); /** * Returns the array that backs this * buffer (optional operation). * *This method is intended to allow array-backed buffers to be * passed to native code more efficiently. Concrete subclasses * provide more strongly-typed return values for this method. * *
Modifications to this buffer's content will cause the returned * array's content to be modified, and vice versa. * *
Invoke the {@link #hasArray hasArray} method before invoking this * method in order to ensure that this buffer has an accessible backing * array.
* * @return The array that backs this buffer * @throws ReadOnlyBufferException If this buffer is backed by an array but is read-only * @throws UnsupportedOperationException If this buffer is not backed by an accessible array * @since 1.6 */ public abstract Object array(); /** * Returns the offset within this buffer's backing array of the first * element of the buffer (optional operation). * *If this buffer is backed by an array then buffer position p * corresponds to array index p + arrayOffset(). * *
Invoke the {@link #hasArray hasArray} method before invoking this * method in order to ensure that this buffer has an accessible backing * array.
* * @return The offset within this buffer's array * of the first element of the buffer * @throws ReadOnlyBufferException If this buffer is backed by an array but is read-only * @throws UnsupportedOperationException If this buffer is not backed by an accessible array * @since 1.6 */ public abstract int arrayOffset(); /** * Tells whether or not this buffer is * direct. * * @return true if, and only if, this buffer is direct * @since 1.6 */ public abstract boolean isDirect(); // -- Package-private methods for bounds checking, etc. -- /** * Checks the current position against the limit, throwing a {@link * BufferUnderflowException} if it is not smaller than the limit, and then * increments the position. * * @return The current position value, before it is incremented */ final int nextGetIndex() { // package-private if (position >= limit) throw new BufferUnderflowException(); return position++; } final int nextGetIndex(int nb) { // package-private if (limit - position < nb) throw new BufferUnderflowException(); int p = position; position += nb; return p; } /** * Checks the current position against the limit, throwing a {@link * BufferOverflowException} if it is not smaller than the limit, and then * increments the position. * * @return The current position value, before it is incremented */ final int nextPutIndex() { // package-private if (position >= limit) throw new BufferOverflowException(); return position++; } final int nextPutIndex(int nb) { // package-private if (limit - position < nb) throw new BufferOverflowException(); int p = position; position += nb; return p; } /** * Checks the given index against the limit, throwing an {@link * IndexOutOfBoundsException} if it is not smaller than the limit * or is smaller than zero. */ final int checkIndex(int i) { // package-private if ((i < 0) || (i >= limit)) // Android-changed: Add bounds details to exception. throw new IndexOutOfBoundsException( "index=" + i + " out of bounds (limit=" + limit + ")"); return i; } final int checkIndex(int i, int nb) { // package-private if ((i < 0) || (nb > limit - i)) // Android-changed: Add bounds details to exception. throw new IndexOutOfBoundsException( "index=" + i + " out of bounds (limit=" + limit + ", nb=" + nb + ")"); return i; } final int markValue() { // package-private return mark; } final void truncate() { // package-private mark = -1; position = 0; limit = 0; capacity = 0; } final void discardMark() { // package-private mark = -1; } static void checkBounds(int off, int len, int size) { // package-private if ((off | len | (off + len) | (size - (off + len))) < 0) // Android-changed: Add bounds details to exception. throw new IndexOutOfBoundsException( "off=" + off + ", len=" + len + " out of bounds (size=" + size + ")"); } /** * For testing only. This field is accessed directly via JNI from frameworks code. * * @hide */ public int getElementSizeShift() { return _elementSizeShift; } }