/*
 * Copyright (c) 2000, 2018, 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 jdk.internal.HotSpotIntrinsicCandidate;
import jdk.internal.access.JavaNioAccess;
import jdk.internal.access.SharedSecrets;
import jdk.internal.misc.Unsafe;

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>
 * {@code 0} {@code <=}
 * <i>mark</i> {@code <=}
 * <i>position</i> {@code <=}
 * <i>limit</i> {@code <=}
 * <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> Additional operations </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>
 *
 * <li><p> {@link #slice} creates a subsequence of a buffer: It leaves the
 * limit and the position unchanged. </p></li>
 *
 * <li><p> {@link #duplicate} creates a shallow copy of a buffer: It leaves
 * the limit and the position unchanged. </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 {
 // Cached unsafe-access object
 static final Unsafe UNSAFE = Unsafe.getUnsafe();

 /**
 * 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;
 private int position = 0;
 private int limit;
 private int capacity;

 // Used by heap byte buffers or direct buffers with Unsafe access
 // For heap byte buffers this field will be the address relative to the
 // array base address and offset into that array. The address might
 // not align on a word boundary for slices, nor align at a long word
 // (8 byte) boundary for byte[] allocations on 32-bit systems.
 // For direct buffers it is the start address of the memory region. The
 // address might not align on a word boundary for slices, nor when created
 // using JNI, see NewDirectByteBuffer(void*, long).
 // Should ideally be declared final
 // NOTE: hoisted here for speed in JNI GetDirectBufferAddress
 long address;

 // Creates a new buffer with the given mark, position, limit, and capacity,
 // after checking invariants.
 //
 Buffer(int mark, int pos, int lim, int cap) { // package-private
 if (cap < 0)
 throw createCapacityException(cap);
 this.capacity = cap;
 limit(lim);
 position(pos);
 if (mark >= 0) {
 if (mark > pos)
 throw new IllegalArgumentException("mark > position: ("
 + mark + " > " + pos + ")");
 this.mark = mark;
 }
 }

 /**
 * Returns an {@code IllegalArgumentException} indicating that the source
 * and target are the same {@code Buffer}. Intended for use in
 * {@code put(src)} when the parameter is the {@code Buffer} on which the
 * method is being invoked.
 *
 * @return IllegalArgumentException
 * With a message indicating equal source and target buffers
 */
 static IllegalArgumentException createSameBufferException() {
 return new IllegalArgumentException("The source buffer is this buffer");
 }

 /**
 * Verify that the capacity is nonnegative.
 *
 * @param capacity
 * The new buffer's capacity, in $type$s
 *
 * @throws IllegalArgumentException
 * If the {@code capacity} is a negative integer
 */
 static IllegalArgumentException createCapacityException(int capacity) {
 assert capacity < 0 : "capacity expected to be negative";
 return new IllegalArgumentException("capacity < 0: ("
 + capacity + " < 0)");
 }

 /**
 * 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 {@code newPosition} do not hold
 */
 public Buffer position(int newPosition) {
 if (newPosition > limit | newPosition < 0)
 throw createPositionException(newPosition);
 position = newPosition;
 if (mark > position) mark = -1;
 return this;
 }

 /**
 * Verify that {@code 0 < newPosition <= limit}
 *
 * @param newPosition
 * The new position value
 *
 * @throws IllegalArgumentException
 * If the specified position is out of bounds.
 */
 private IllegalArgumentException createPositionException(int newPosition) {
 String msg = null;

 if (newPosition > limit) {
 msg = "newPosition > limit: (" + newPosition + " > " + limit + ")";
 } else { // assume negative
 assert newPosition < 0 : "newPosition expected to be negative";
 msg = "newPosition < 0: (" + newPosition + " < 0)";
 }

 return new IllegalArgumentException(msg);
 }

 /**
 * 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 {@code newLimit} do not hold
 */
 public Buffer limit(int newLimit) {
 if (newLimit > capacity | newLimit < 0)
 throw createLimitException(newLimit);
 limit = newLimit;
 if (position > limit) position = limit;
 if (mark > limit) mark = -1;
 return this;
 }

 /**
 * Verify that {@code 0 < newLimit <= capacity}
 *
 * @param newLimit
 * The new limit value
 *
 * @throws IllegalArgumentException
 * If the specified limit is out of bounds.
 */
 private IllegalArgumentException createLimitException(int newLimit) {
 String msg = null;

 if (newLimit > capacity) {
 msg = "newLimit > capacity: (" + newLimit + " > " + capacity + ")";
 } else { // assume negative
 assert newLimit < 0 : "newLimit expected to be negative";
 msg = "newLimit < 0: (" + newLimit + " < 0)";
 }

 return new IllegalArgumentException(msg);
 }

 /**
 * 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 {@code 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 {@code 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.
 *
 * <p> If this method returns {@code true} then the {@link #array() array}
 * and {@link #arrayOffset() arrayOffset} methods may safely be invoked.
 * </p>
 *
 * @return {@code 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&nbsp;&nbsp;<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&nbsp;&nbsp;<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>&nbsp;+&nbsp;{@code arrayOffset()}.
 *
 * <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 {@code true} if, and only if, this buffer is direct
 *
 * @since 1.6
 */
 public abstract boolean isDirect();

 /**
 * Creates a new buffer whose content is a shared subsequence of
 * this buffer's content.
 *
 * <p> The content of the new buffer will start at this buffer's current
 * position. Changes to this buffer's content will be visible in the new
 * buffer, and vice versa; the two buffers' position, limit, and mark
 * values will be independent.
 *
 * <p> The new buffer's position will be zero, its capacity and its limit
 * will be the number of elements remaining in this buffer, its mark will be
 * undefined. The new buffer will be direct if, and only if, this buffer is
 * direct, and it will be read-only if, and only if, this buffer is
 * read-only. </p>
 *
 * @return The new buffer
 *
 * @since 9
 */
 public abstract Buffer slice();

 /**
 * Creates a new buffer that shares this buffer's content.
 *
 * <p> The content of the new buffer will be that of this buffer. Changes
 * to this buffer's content will be visible in the new buffer, and vice
 * versa; the two buffers' position, limit, and mark values will be
 * independent.
 *
 * <p> The new buffer's capacity, limit, position and mark values will be
 * identical to those of this buffer. The new buffer will be direct if, and
 * only if, this buffer is direct, and it will be read-only if, and only if,
 * this buffer is read-only. </p>
 *
 * @return The new buffer
 *
 * @since 9
 */
 public abstract Buffer duplicate();


 // -- Package-private methods for bounds checking, etc. --

 /**
 *
 * @return the base reference, paired with the address
 * field, which in combination can be used for unsafe access into a heap
 * buffer or direct byte buffer (and views of).
 */
 abstract Object base();

 /**
 * 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.
 */
 @HotSpotIntrinsicCandidate
 final int checkIndex(int i) { // package-private
 if ((i < 0) || (i >= limit))
 throw new IndexOutOfBoundsException();
 return i;
 }

 final int checkIndex(int i, int nb) { // package-private
 if ((i < 0) || (nb > limit - i))
 throw new IndexOutOfBoundsException();
 return i;
 }

 final int markValue() { // package-private
 return mark;
 }

 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)
 throw new IndexOutOfBoundsException();
 }

 static {
 // setup access to this package in SharedSecrets
 SharedSecrets.setJavaNioAccess(
 new JavaNioAccess() {
 @Override
 public JavaNioAccess.BufferPool getDirectBufferPool() {
 return Bits.BUFFER_POOL;
 }
 });
 }

}