Automatic sources dropoff on 2020-06-10 18:32:38.095721 The change is generated with prebuilt drop tool. Change-Id: I24cbf6ba6db262a1ae1445db1427a08fee35b3b4
diff --git a/java/nio/Buffer.java b/java/nio/Buffer.java new file mode 100644 index 0000000..e517560 --- /dev/null +++ b/java/nio/Buffer.java
@@ -0,0 +1,601 @@ +/* + * 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. + * + * <p> 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: </p> + * + * <blockquote> + * + * <p> A buffer's <i>capacity</i> is the number of elements it contains. The + * capacity of a buffer is never negative and never changes. </p> + * + * <p> A buffer's <i>limit</i> 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. </p> + * + * <p> A buffer's <i>position</i> 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. </p> + * + * </blockquote> + * + * <p> There is one subclass of this class for each non-boolean primitive type. + * + * + * <h2> Transferring data </h2> + * + * <p> Each subclass of this class defines two categories of <i>get</i> and + * <i>put</i> operations: </p> + * + * <blockquote> + * + * <p> <i>Relative</i> 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 <i>get</i> operation throws a {@link BufferUnderflowException} + * and a relative <i>put</i> operation throws a {@link + * BufferOverflowException}; in either case, no data is transferred. </p> + * + * <p> <i>Absolute</i> operations take an explicit element index and do not + * affect the position. Absolute <i>get</i> and <i>put</i> operations throw + * an {@link IndexOutOfBoundsException} if the index argument exceeds the + * limit. </p> + * + * </blockquote> + * + * <p> 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. + * + * + * <h2> Marking and resetting </h2> + * + * <p> A buffer's <i>mark</i> 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. + * + * + * <h2> Invariants </h2> + * + * <p> The following invariant holds for the mark, position, limit, and + * capacity values: + * + * <blockquote> + * <tt>0</tt> <tt><=</tt> + * <i>mark</i> <tt><=</tt> + * <i>position</i> <tt><=</tt> + * <i>limit</i> <tt><=</tt> + * <i>capacity</i> + * </blockquote> + * + * <p> 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. + * + * + * <h2> Clearing, flipping, and rewinding </h2> + * + * <p> 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: + * + * <ul> + * + * <li><p> {@link #clear} makes a buffer ready for a new sequence of + * channel-read or relative <i>put</i> operations: It sets the limit to the + * capacity and the position to zero. </p></li> + * + * <li><p> {@link #flip} makes a buffer ready for a new sequence of + * channel-write or relative <i>get</i> operations: It sets the limit to the + * current position and then sets the position to zero. </p></li> + * + * <li><p> {@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. </p></li> + * + * </ul> + * + * + * <h2> Read-only buffers </h2> + * + * <p> Every buffer is readable, but not every buffer is writable. The + * mutation methods of each buffer class are specified as <i>optional + * operations</i> 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. + * + * + * <h2> Thread safety </h2> + * + * <p> 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. + * + * + * <h2> Invocation chaining </h2> + * + * <p> 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 + * + * <blockquote><pre> + * b.flip(); + * b.position(23); + * b.limit(42);</pre></blockquote> + * + * can be replaced by the single, more compact statement + * + * <blockquote><pre> + * b.flip().position(23).limit(42);</pre></blockquote> + * + * + * @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; + // Android-changed: position field non-private for use by Android's nio implementation classes. + int position = 0; + private int limit; + private int capacity; + + // Used only by direct buffers + // NOTE: hoisted here for speed in JNI GetDirectBufferAddress + long address; + + // Android-added: _elementSizeShift field for NIOAccess class and framework native code. + /** + * 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. + // + // Android-added: _elementSizeShift field for NIOAccess class and framework native code. + 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; + } + // Android-added: _elementSizeShift field for NIOAccess class and framework native code. + _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 <tt>newPosition</tt> do not hold + */ + public Buffer position(int newPosition) { + if ((newPosition > limit) || (newPosition < 0)) + // Android-changed: Improved error message. + 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 <tt>newLimit</tt> do not hold + */ + public 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 Buffer mark() { + mark = position; + return this; + } + + /** + * Resets this buffer's position to the previously-marked position. + * + * <p> Invoking this method neither changes nor discards the mark's + * value. </p> + * + * @return This buffer + * + * @throws InvalidMarkException + * If the mark has not been set + */ + public 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. + * + * <p> Invoke this method before using a sequence of channel-read or + * <i>put</i> operations to fill this buffer. For example: + * + * <blockquote><pre> + * buf.clear(); // Prepare buffer for reading + * in.read(buf); // Read data</pre></blockquote> + * + * <p> 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. </p> + * + * @return This buffer + */ + public 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. + * + * <p> After a sequence of channel-read or <i>put</i> operations, invoke + * this method to prepare for a sequence of channel-write or relative + * <i>get</i> operations. For example: + * + * <blockquote><pre> + * 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</pre></blockquote> + * + * <p> This method is often used in conjunction with the {@link + * java.nio.ByteBuffer#compact compact} method when transferring data from + * one place to another. </p> + * + * @return This buffer + */ + public Buffer flip() { + limit = position; + position = 0; + mark = -1; + return this; + } + + /** + * Rewinds this buffer. The position is set to zero and the mark is + * discarded. + * + * <p> Invoke this method before a sequence of channel-write or <i>get</i> + * operations, assuming that the limit has already been set + * appropriately. For example: + * + * <blockquote><pre> + * out.write(buf); // Write remaining data + * buf.rewind(); // Rewind buffer + * buf.get(array); // Copy data into array</pre></blockquote> + * + * @return This buffer + */ + public 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 <tt>true</tt> 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 <tt>true</tt> 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. + * + * <p> If this method returns <tt>true</tt> then the {@link #array() array} + * and {@link #arrayOffset() arrayOffset} methods may safely be invoked. + * </p> + * + * @return <tt>true</tt> 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 <i>(optional operation)</i>. + * + * <p> 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. + * + * <p> Modifications to this buffer's content will cause the returned + * array's content to be modified, and vice versa. + * + * <p> Invoke the {@link #hasArray hasArray} method before invoking this + * method in order to ensure that this buffer has an accessible backing + * array. </p> + * + * @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 <i>(optional operation)</i>. + * + * <p> If this buffer is backed by an array then buffer position <i>p</i> + * corresponds to array index <i>p</i> + <tt>arrayOffset()</tt>. + * + * <p> Invoke the {@link #hasArray hasArray} method before invoking this + * method in order to ensure that this buffer has an accessible backing + * array. </p> + * + * @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 + * <a href="ByteBuffer.html#direct"><i>direct</i></a>. + * + * @return <tt>true</tt> 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 + ")"); + } + + // Android-added: getElementSizeShift() method for testing. + /** + * For testing only. This field is accessed directly via JNI from frameworks code. + * + * @hide + */ + public int getElementSizeShift() { + return _elementSizeShift; + } + +}