151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski/* 22c87ad3a45cecf9e344487cad1abfdebe79f2c7cNarayan Kamath * Copyright (C) 2014 The Android Open Source Project 36f07fc6c80a7e85fdfffbc2ac4e15b53cdd04a3eYi Kong * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. 451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This code is free software; you can redistribute it and/or modify it 751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * under the terms of the GNU General Public License version 2 only, as 851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * published by the Free Software Foundation. Oracle designates this 951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * particular file as subject to the "Classpath" exception as provided 1051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * by Oracle in the LICENSE file that accompanied this code. 1151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 1251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This code is distributed in the hope that it will be useful, but WITHOUT 1351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * version 2 for more details (a copy is included in the LICENSE file that 1651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * accompanied this code). 1751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 1851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * You should have received a copy of the GNU General Public License version 1951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 2 along with this work; if not, write to the Free Software Foundation, 2051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 2251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or visit www.oracle.com if you need additional information or have any 2451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * questions. 2551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 2651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 2751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskipackage java.nio; 2851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 296f07fc6c80a7e85fdfffbc2ac4e15b53cdd04a3eYi Kongimport java.util.Spliterator; 3051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 3151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski/** 3251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * A container for data of a specific primitive type. 3351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 3451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> A buffer is a linear, finite sequence of elements of a specific 3551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * primitive type. Aside from its content, the essential properties of a 3651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * buffer are its capacity, limit, and position: </p> 3751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 3851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <blockquote> 3951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 40190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * <p> A buffer's <i>capacity</i> is the number of elements it contains. The 41190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * capacity of a buffer is never negative and never changes. </p> 4251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 43190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * <p> A buffer's <i>limit</i> is the index of the first element that should 44190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * not be read or written. A buffer's limit is never negative and is never 45190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * greater than its capacity. </p> 4651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 47190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * <p> A buffer's <i>position</i> is the index of the next element to be 48190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * read or written. A buffer's position is never negative and is never 49190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * greater than its limit. </p> 5051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 5151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </blockquote> 5251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 5351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> There is one subclass of this class for each non-boolean primitive type. 5451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 5551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 5651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <h4> Transferring data </h4> 5751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 5851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Each subclass of this class defines two categories of <i>get</i> and 5951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <i>put</i> operations: </p> 6051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 6151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <blockquote> 6251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 63190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * <p> <i>Relative</i> operations read or write one or more elements starting 64190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * at the current position and then increment the position by the number of 65190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * elements transferred. If the requested transfer exceeds the limit then a 66190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * relative <i>get</i> operation throws a {@link BufferUnderflowException} 67190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * and a relative <i>put</i> operation throws a {@link 68190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * BufferOverflowException}; in either case, no data is transferred. </p> 6951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 70190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * <p> <i>Absolute</i> operations take an explicit element index and do not 71190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * affect the position. Absolute <i>get</i> and <i>put</i> operations throw 72190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * an {@link IndexOutOfBoundsException} if the index argument exceeds the 73190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * limit. </p> 7451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 7551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </blockquote> 7651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 7751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Data may also, of course, be transferred in to or out of a buffer by the 7851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * I/O operations of an appropriate channel, which are always relative to the 7951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * current position. 8051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 8151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 8251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <h4> Marking and resetting </h4> 8351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 8451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> A buffer's <i>mark</i> is the index to which its position will be reset 8551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * when the {@link #reset reset} method is invoked. The mark is not always 8651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * defined, but when it is defined it is never negative and is never greater 8751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * than the position. If the mark is defined then it is discarded when the 8851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * position or the limit is adjusted to a value smaller than the mark. If the 8951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * mark is not defined then invoking the {@link #reset reset} method causes an 9051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link InvalidMarkException} to be thrown. 9151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 9251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 9351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <h4> Invariants </h4> 9451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 9551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> The following invariant holds for the mark, position, limit, and 9651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * capacity values: 9751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 9851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <blockquote> 99190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * <tt>0</tt> <tt><=</tt> 100190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * <i>mark</i> <tt><=</tt> 101190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * <i>position</i> <tt><=</tt> 102190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * <i>limit</i> <tt><=</tt> 103190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * <i>capacity</i> 10451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </blockquote> 10551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 10651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> A newly-created buffer always has a position of zero and a mark that is 10751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * undefined. The initial limit may be zero, or it may be some other value 10851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * that depends upon the type of the buffer and the manner in which it is 10951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * constructed. Each element of a newly-allocated buffer is initialized 11051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to zero. 11151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 11251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 11351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <h4> Clearing, flipping, and rewinding </h4> 11451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 11551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> In addition to methods for accessing the position, limit, and capacity 11651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * values and for marking and resetting, this class also defines the following 11751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * operations upon buffers: 11851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 11951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <ul> 12051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 121190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * <li><p> {@link #clear} makes a buffer ready for a new sequence of 122190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * channel-read or relative <i>put</i> operations: It sets the limit to the 123190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * capacity and the position to zero. </p></li> 12451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 125190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * <li><p> {@link #flip} makes a buffer ready for a new sequence of 126190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * channel-write or relative <i>get</i> operations: It sets the limit to the 127190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * current position and then sets the position to zero. </p></li> 12851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 129190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * <li><p> {@link #rewind} makes a buffer ready for re-reading the data that 130190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * it already contains: It leaves the limit unchanged and sets the position 131190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * to zero. </p></li> 13251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 13351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </ul> 13451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 13551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 13651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <h4> Read-only buffers </h4> 13751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 13851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Every buffer is readable, but not every buffer is writable. The 13951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * mutation methods of each buffer class are specified as <i>optional 14051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * operations</i> that will throw a {@link ReadOnlyBufferException} when 14151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * invoked upon a read-only buffer. A read-only buffer does not allow its 14251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * content to be changed, but its mark, position, and limit values are mutable. 14351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Whether or not a buffer is read-only may be determined by invoking its 14451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link #isReadOnly isReadOnly} method. 14551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 14651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 14751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <h4> Thread safety </h4> 14851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 14951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Buffers are not safe for use by multiple concurrent threads. If a 15051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * buffer is to be used by more than one thread then access to the buffer 15151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * should be controlled by appropriate synchronization. 15251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 15351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 15451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <h4> Invocation chaining </h4> 15551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 15651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Methods in this class that do not otherwise have a value to return are 15751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * specified to return the buffer upon which they are invoked. This allows 15851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * method invocations to be chained; for example, the sequence of statements 15951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 16051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <blockquote><pre> 16151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * b.flip(); 16251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * b.position(23); 16351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * b.limit(42);</pre></blockquote> 16451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 16551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * can be replaced by the single, more compact statement 16651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 16751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <blockquote><pre> 16851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * b.flip().position(23).limit(42);</pre></blockquote> 16951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 17051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @author Mark Reinhold 17151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @author JSR-51 Expert Group 17251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @since 1.4 17351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 17451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 17551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskipublic abstract class Buffer { 17651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 1776f07fc6c80a7e85fdfffbc2ac4e15b53cdd04a3eYi Kong /** 1786f07fc6c80a7e85fdfffbc2ac4e15b53cdd04a3eYi Kong * The characteristics of Spliterators that traverse and split elements 1796f07fc6c80a7e85fdfffbc2ac4e15b53cdd04a3eYi Kong * maintained in Buffers. 1806f07fc6c80a7e85fdfffbc2ac4e15b53cdd04a3eYi Kong */ 1816f07fc6c80a7e85fdfffbc2ac4e15b53cdd04a3eYi Kong static final int SPLITERATOR_CHARACTERISTICS = 1826f07fc6c80a7e85fdfffbc2ac4e15b53cdd04a3eYi Kong Spliterator.SIZED | Spliterator.SUBSIZED | Spliterator.ORDERED; 1836f07fc6c80a7e85fdfffbc2ac4e15b53cdd04a3eYi Kong 18451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski // Invariants: mark <= position <= limit <= capacity 18551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski private int mark = -1; 186648446e24ad82c2c660e158be8f32faabf082420Piotr Jastrzebski int position = 0; 18751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski private int limit; 18851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski private int capacity; 18951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 19051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski // Used only by direct buffers 19151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski // NOTE: hoisted here for speed in JNI GetDirectBufferAddress 19251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski long address; 19351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 194648446e24ad82c2c660e158be8f32faabf082420Piotr Jastrzebski /** 195648446e24ad82c2c660e158be8f32faabf082420Piotr Jastrzebski * The log base 2 of the element size of this buffer. Each typed subclass 196648446e24ad82c2c660e158be8f32faabf082420Piotr Jastrzebski * (ByteBuffer, CharBuffer, etc.) is responsible for initializing this 197648446e24ad82c2c660e158be8f32faabf082420Piotr Jastrzebski * value. The value is used by JNI code in frameworks/base/ to avoid the 198648446e24ad82c2c660e158be8f32faabf082420Piotr Jastrzebski * need for costly 'instanceof' tests. 199648446e24ad82c2c660e158be8f32faabf082420Piotr Jastrzebski */ 200648446e24ad82c2c660e158be8f32faabf082420Piotr Jastrzebski final int _elementSizeShift; 201648446e24ad82c2c660e158be8f32faabf082420Piotr Jastrzebski 20251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski // Creates a new buffer with the given mark, position, limit, and capacity, 20351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski // after checking invariants. 20451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski // 205648446e24ad82c2c660e158be8f32faabf082420Piotr Jastrzebski Buffer(int mark, int pos, int lim, int cap, int elementSizeShift) { // package-private 20651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if (cap < 0) 20751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski throw new IllegalArgumentException("Negative capacity: " + cap); 20851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski this.capacity = cap; 20951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski limit(lim); 21051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski position(pos); 21151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if (mark >= 0) { 21251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if (mark > pos) 21351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski throw new IllegalArgumentException("mark > position: (" 214190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera + mark + " > " + pos + ")"); 21551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski this.mark = mark; 21651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 217648446e24ad82c2c660e158be8f32faabf082420Piotr Jastrzebski _elementSizeShift = elementSizeShift; 21851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 21951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 22051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 22151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns this buffer's capacity. </p> 22251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 223190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return The capacity of this buffer 22451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 22551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public final int capacity() { 22651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return capacity; 22751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 22851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 22951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 23051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns this buffer's position. </p> 23151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 232190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return The position of this buffer 23351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 23451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public final int position() { 23551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return position; 23651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 23751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 23851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 23951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sets this buffer's position. If the mark is defined and larger than the 24051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * new position then it is discarded. </p> 24151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 242190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @param newPosition The new position value; must be non-negative 243190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * and no larger than the current limit 244190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return This buffer 245190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @throws IllegalArgumentException If the preconditions on <tt>newPosition</tt> do not hold 24651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 24751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public final Buffer position(int newPosition) { 24851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if ((newPosition > limit) || (newPosition < 0)) 249eec452a0b9656e6188591e305bc5e044737d70a2Piotr Jastrzebski throw new IllegalArgumentException("Bad position " + newPosition + "/" + limit); 25051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski position = newPosition; 25151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if (mark > position) mark = -1; 25251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return this; 25351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 25451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 25551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 25651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns this buffer's limit. </p> 25751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 258190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return The limit of this buffer 25951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 26051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public final int limit() { 26151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return limit; 26251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 26351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 26451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 26551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sets this buffer's limit. If the position is larger than the new limit 26651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * then it is set to the new limit. If the mark is defined and larger than 26751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the new limit then it is discarded. </p> 26851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 269190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @param newLimit The new limit value; must be non-negative 270190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * and no larger than this buffer's capacity 271190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return This buffer 272190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @throws IllegalArgumentException If the preconditions on <tt>newLimit</tt> do not hold 27351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 27451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public final Buffer limit(int newLimit) { 27551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if ((newLimit > capacity) || (newLimit < 0)) 27651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski throw new IllegalArgumentException(); 27751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski limit = newLimit; 27851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if (position > limit) position = limit; 27951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if (mark > limit) mark = -1; 28051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return this; 28151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 28251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 28351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 28451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sets this buffer's mark at its position. </p> 28551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 286190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return This buffer 28751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 28851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public final Buffer mark() { 28951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski mark = position; 29051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return this; 29151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 29251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 29351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 29451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Resets this buffer's position to the previously-marked position. 29551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 29651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Invoking this method neither changes nor discards the mark's 29751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * value. </p> 29851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 299190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return This buffer 300190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @throws InvalidMarkException If the mark has not been set 30151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 30251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public final Buffer reset() { 30351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski int m = mark; 30451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if (m < 0) 30551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski throw new InvalidMarkException(); 30651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski position = m; 30751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return this; 30851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 30951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 31051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 31151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Clears this buffer. The position is set to zero, the limit is set to 31251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the capacity, and the mark is discarded. 31351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 31451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Invoke this method before using a sequence of channel-read or 31551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <i>put</i> operations to fill this buffer. For example: 31651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 31751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <blockquote><pre> 31851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * buf.clear(); // Prepare buffer for reading 31951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * in.read(buf); // Read data</pre></blockquote> 32051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 32151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> This method does not actually erase the data in the buffer, but it 32251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is named as if it did because it will most often be used in situations 32351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * in which that might as well be the case. </p> 32451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 325190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return This buffer 32651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 32751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public final Buffer clear() { 32851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski position = 0; 32951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski limit = capacity; 33051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski mark = -1; 33151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return this; 33251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 33351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 33451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 33551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Flips this buffer. The limit is set to the current position and then 33651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the position is set to zero. If the mark is defined then it is 33751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * discarded. 33851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 33951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> After a sequence of channel-read or <i>put</i> operations, invoke 34051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * this method to prepare for a sequence of channel-write or relative 34151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <i>get</i> operations. For example: 34251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 34351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <blockquote><pre> 34451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * buf.put(magic); // Prepend header 34551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * in.read(buf); // Read data into rest of buffer 34651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * buf.flip(); // Flip buffer 34751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * out.write(buf); // Write header + data to channel</pre></blockquote> 34851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 34951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> This method is often used in conjunction with the {@link 35051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * java.nio.ByteBuffer#compact compact} method when transferring data from 35151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * one place to another. </p> 35251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 353190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return This buffer 35451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 35551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public final Buffer flip() { 35651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski limit = position; 35751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski position = 0; 35851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski mark = -1; 35951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return this; 36051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 36151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 36251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 36351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Rewinds this buffer. The position is set to zero and the mark is 36451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * discarded. 36551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 36651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Invoke this method before a sequence of channel-write or <i>get</i> 36751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * operations, assuming that the limit has already been set 36851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * appropriately. For example: 36951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 37051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <blockquote><pre> 37151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * out.write(buf); // Write remaining data 37251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * buf.rewind(); // Rewind buffer 37351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * buf.get(array); // Copy data into array</pre></blockquote> 37451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 375190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return This buffer 37651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 37751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public final Buffer rewind() { 37851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski position = 0; 37951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski mark = -1; 38051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return this; 38151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 38251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 38351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 38451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the number of elements between the current position and the 38551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * limit. </p> 38651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 387190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return The number of elements remaining in this buffer 38851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 38951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public final int remaining() { 39051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return limit - position; 39151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 39251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 39351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 39451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Tells whether there are any elements between the current position and 39551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the limit. </p> 39651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 397190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return <tt>true</tt> if, and only if, there is at least one element 398190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * remaining in this buffer 39951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 40051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public final boolean hasRemaining() { 40151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return position < limit; 40251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 40351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 40451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 40551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Tells whether or not this buffer is read-only. </p> 40651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 407190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return <tt>true</tt> if, and only if, this buffer is read-only 40851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 40951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract boolean isReadOnly(); 41051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 41151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 41251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Tells whether or not this buffer is backed by an accessible 41351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * array. 41451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 41551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> If this method returns <tt>true</tt> then the {@link #array() array} 41651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * and {@link #arrayOffset() arrayOffset} methods may safely be invoked. 41751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </p> 41851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 419190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return <tt>true</tt> if, and only if, this buffer 420190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * is backed by an array and is not read-only 42151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @since 1.6 42251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 42351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract boolean hasArray(); 42451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 42551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 42651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the array that backs this 42751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * buffer <i>(optional operation)</i>. 42851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 42951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> This method is intended to allow array-backed buffers to be 43051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * passed to native code more efficiently. Concrete subclasses 43151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * provide more strongly-typed return values for this method. 43251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 43351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Modifications to this buffer's content will cause the returned 43451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * array's content to be modified, and vice versa. 43551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 43651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Invoke the {@link #hasArray hasArray} method before invoking this 43751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * method in order to ensure that this buffer has an accessible backing 43851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * array. </p> 43951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 440190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return The array that backs this buffer 441190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @throws ReadOnlyBufferException If this buffer is backed by an array but is read-only 442190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @throws UnsupportedOperationException If this buffer is not backed by an accessible array 44351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @since 1.6 44451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 44551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract Object array(); 44651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 44751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 44851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the offset within this buffer's backing array of the first 44951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * element of the buffer <i>(optional operation)</i>. 45051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 45151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> If this buffer is backed by an array then buffer position <i>p</i> 45251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * corresponds to array index <i>p</i> + <tt>arrayOffset()</tt>. 45351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 45451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Invoke the {@link #hasArray hasArray} method before invoking this 45551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * method in order to ensure that this buffer has an accessible backing 45651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * array. </p> 45751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 458190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return The offset within this buffer's array 459190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * of the first element of the buffer 460190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @throws ReadOnlyBufferException If this buffer is backed by an array but is read-only 461190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @throws UnsupportedOperationException If this buffer is not backed by an accessible array 46251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @since 1.6 46351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 46451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract int arrayOffset(); 46551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 46651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 46751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Tells whether or not this buffer is 46851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <a href="ByteBuffer.html#direct"><i>direct</i></a>. </p> 46951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 470190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return <tt>true</tt> if, and only if, this buffer is direct 47151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @since 1.6 47251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 47351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract boolean isDirect(); 47451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 47551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 47651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski // -- Package-private methods for bounds checking, etc. -- 47751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 47851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 47951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Checks the current position against the limit, throwing a {@link 48051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * BufferUnderflowException} if it is not smaller than the limit, and then 48151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * increments the position. </p> 48251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 483190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return The current position value, before it is incremented 48451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 48551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski final int nextGetIndex() { // package-private 48651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if (position >= limit) 48751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski throw new BufferUnderflowException(); 48851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return position++; 48951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 49051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 49151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski final int nextGetIndex(int nb) { // package-private 49251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if (limit - position < nb) 49351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski throw new BufferUnderflowException(); 49451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski int p = position; 49551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski position += nb; 49651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return p; 49751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 49851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 49951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 50051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Checks the current position against the limit, throwing a {@link 50151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * BufferOverflowException} if it is not smaller than the limit, and then 50251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * increments the position. </p> 50351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 504190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera * @return The current position value, before it is incremented 50551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 50651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski final int nextPutIndex() { // package-private 50751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if (position >= limit) 50851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski throw new BufferOverflowException(); 50951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return position++; 51051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 51151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 51251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski final int nextPutIndex(int nb) { // package-private 51351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if (limit - position < nb) 51451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski throw new BufferOverflowException(); 51551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski int p = position; 51651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski position += nb; 51751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return p; 51851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 51951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 52051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 52151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Checks the given index against the limit, throwing an {@link 52251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * IndexOutOfBoundsException} if it is not smaller than the limit 52351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or is smaller than zero. 52451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 52551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski final int checkIndex(int i) { // package-private 52651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if ((i < 0) || (i >= limit)) 527b5b4f1b5e735178328ef6b65443f456c52ced594Narayan Kamath // Android changed : Add bounds details to exception. 528b5b4f1b5e735178328ef6b65443f456c52ced594Narayan Kamath throw new IndexOutOfBoundsException( 529190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera "index=" + i + " out of bounds (limit=" + limit + ")"); 53051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return i; 53151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 53251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 53351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski final int checkIndex(int i, int nb) { // package-private 53451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if ((i < 0) || (nb > limit - i)) 535b5b4f1b5e735178328ef6b65443f456c52ced594Narayan Kamath // Android changed : Add bounds details to exception. 536b5b4f1b5e735178328ef6b65443f456c52ced594Narayan Kamath throw new IndexOutOfBoundsException( 537190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera "index=" + i + " out of bounds (limit=" + limit + ", nb=" + nb + ")"); 53851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return i; 53951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 54051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 54151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski final int markValue() { // package-private 54251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return mark; 54351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 54451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 54551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski final void truncate() { // package-private 54651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski mark = -1; 54751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski position = 0; 54851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski limit = 0; 54951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski capacity = 0; 55051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 55151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 55251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski final void discardMark() { // package-private 55351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski mark = -1; 55451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 55551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 55651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski static void checkBounds(int off, int len, int size) { // package-private 55751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if ((off | len | (off + len) | (size - (off + len))) < 0) 558b5b4f1b5e735178328ef6b65443f456c52ced594Narayan Kamath // Android changed : Add bounds details to exception. 559b5b4f1b5e735178328ef6b65443f456c52ced594Narayan Kamath throw new IndexOutOfBoundsException( 560190a49036750b8bb6c979d958ed56aa3fb4f408aShubham Ajmera "off=" + off + ", len=" + len + " out of bounds (size=" + size + ")"); 56151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 56251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 563e7bb4dadbf37b10c55b134df0734ebf2a9353e43Narayan Kamath /** 564e7bb4dadbf37b10c55b134df0734ebf2a9353e43Narayan Kamath * For testing only. This field is accessed directly via JNI from frameworks code. 565e7bb4dadbf37b10c55b134df0734ebf2a9353e43Narayan Kamath * 566e7bb4dadbf37b10c55b134df0734ebf2a9353e43Narayan Kamath * @hide 567e7bb4dadbf37b10c55b134df0734ebf2a9353e43Narayan Kamath */ 568e7bb4dadbf37b10c55b134df0734ebf2a9353e43Narayan Kamath public int getElementSizeShift() { 569e7bb4dadbf37b10c55b134df0734ebf2a9353e43Narayan Kamath return _elementSizeShift; 570e7bb4dadbf37b10c55b134df0734ebf2a9353e43Narayan Kamath } 571e7bb4dadbf37b10c55b134df0734ebf2a9353e43Narayan Kamath 57251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski} 573