Merge "Java 6 java.nio.Buffer changes." into dalvik-dev

9 files changed, 57 insertions, 437 deletions

diff --git a/nio/src/main/java/java/nio/Buffer.java b/nio/src/main/java/java/nio/Buffer.java
index b4bdc1c..f6006e7 100644
--- a/nio/src/main/java/java/nio/Buffer.java
+++ b/nio/src/main/java/java/nio/Buffer.java
@@ -52,7 +52,7 @@ public abstract class Buffer {
     final static int UNSET_MARK = -1;
 
     /**
-     * The capacity of this buffer, which never change.
+     * The capacity of this buffer, which never changes.
      */
     final int capacity;
 
@@ -77,43 +77,12 @@ public abstract class Buffer {
 
     // BEGIN android-added
     /**
-     * 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 native code to avoid the need for costly
-     * 'instanceof' tests.
-     *
-     */
-    int _elementSizeShift;
-
-    /**
-     * Returns the array associated with this buffer, or null if none exists.
-     * Each typed subclass (ByteBuffer, CharBuffer, etc.) overrides this method
-     * to call its array() method with appropriate checks.
-     *
-     * @return a primitive array or null
-     */
-    Object _array() {
-        return null;
-    }
-
-    /**
-     * Returns the offset into the backing array, if one exists, otherwise 0.
-     * Each typed subclass (ByteBuffer, CharBuffer, etc.) overrides this method
-     * to call its arrayOffset() method with appropriate checks.
-     *
-     * @return the array offset, or 0
-     */
-    int _arrayOffset() {
-        return 0;
-    }
-
-    /**
      * For direct buffers, the effective address of the data.  This is set
      * on first use.  If the field is zero, this is either not a direct
      * buffer or the field has not been initialized, and you need to issue
      * the getEffectiveAddress() call and use the result of that.
      *
-     * This is strictly an optimization.
+     * This is an optimization used by the GetDirectBufferAddress JNI call.
      */
     int effectiveDirectAddress = 0;
     // END android-added
@@ -133,6 +102,44 @@ public abstract class Buffer {
     }
 
     /**
+     * Returns the array that backs this buffer (optional operation).
+     * The returned value is the actual array, not a copy, so modifications
+     * to the array write through to the buffer.
+     *
+     * <p>Subclasses should override this method with a covariant return type
+     * to provide the exact type of the array.
+     *
+     * <p>Use {@code hasArray} to ensure this method won't throw.
+     * (A separate call to {@code isReadOnly} is not necessary.)
+     *
+     * @return the array
+     * @throws ReadOnlyBufferException if the buffer is read-only
+     *         UnsupportedOperationException if the buffer does not expose an array
+     * @since 1.6
+     * @hide
+     */
+    public abstract Object array();
+
+    /**
+     * Returns the offset into the array returned by {@code array} of the first
+     * element of the buffer (optional operation). The backing array (if there is one)
+     * is not necessarily the same size as the buffer, and position 0 in the buffer is
+     * not necessarily the 0th element in the array. Use
+     * {@code buffer.array()[offset + buffer.arrayOffset()} to access element {@code offset}
+     * in {@code buffer}.
+     *
+     * <p>Use {@code hasArray} to ensure this method won't throw.
+     * (A separate call to {@code isReadOnly} is not necessary.)
+     *
+     * @return the offset
+     * @throws ReadOnlyBufferException if the buffer is read-only
+     *         UnsupportedOperationException if the buffer does not expose an array
+     * @since 1.6
+     * @hide
+     */
+    public abstract int arrayOffset();
+
+    /**
      * Returns the capacity of this buffer.
      * 
      * @return the number of elements that are contained in this buffer.
@@ -176,6 +183,16 @@ public abstract class Buffer {
     }
 
     /**
+     * Returns true if {@code array} and {@code arrayOffset} won't throw. This method does not
+     * return true for buffers not backed by arrays because the other methods would throw
+     * {@code UnsupportedOperationException}, nor does it return true for buffers backed by
+     * read-only arrays, because the other methods would throw {@code ReadOnlyBufferException}.
+     * @since 1.6
+     * @hide
+     */
+    public abstract boolean hasArray();
+
+    /**
      * Indicates if there are elements remaining in this buffer, that is if
      * {@code position < limit}.
      * 
@@ -187,6 +204,13 @@ public abstract class Buffer {
     }
 
     /**
+     * Returns true if this is a direct buffer.
+     * @since 1.6
+     * @hide
+     */
+    public abstract boolean isDirect();
+
+    /**
      * Indicates whether this buffer is read-only.
      * 
      * @return {@code true} if this buffer is read-only, {@code false}
diff --git a/nio/src/main/java/java/nio/ByteBuffer.java b/nio/src/main/java/java/nio/ByteBuffer.java
index 821bbed..cda213c 100644
--- a/nio/src/main/java/java/nio/ByteBuffer.java
+++ b/nio/src/main/java/java/nio/ByteBuffer.java
@@ -126,9 +126,6 @@ public abstract class ByteBuffer extends Buffer implements
      */
     ByteBuffer(int capacity) {
         super(capacity);
-        // BEGIN android-added
-        _elementSizeShift = 0;
-        // END android-added
     }
 
     /**
@@ -161,24 +158,6 @@ public abstract class ByteBuffer extends Buffer implements
         return protectedArrayOffset();
     }
 
-    // BEGIN android-added
-    @Override
-    Object _array() {
-        if (hasArray()) {
-            return array();
-        }
-        return null;
-    }
-
-    @Override
-    int _arrayOffset() {
-        if (hasArray()) {
-            return arrayOffset();
-        }
-        return 0;
-    }
-    // END android-added
-
     /**
      * Returns a char buffer which is based on the remaining content of this
      * byte buffer.
@@ -631,13 +610,6 @@ public abstract class ByteBuffer extends Buffer implements
      */
     public abstract short getShort(int index);
 
-    /**
-     * Indicates whether this buffer is based on a byte array and provides
-     * read/write access.
-     * 
-     * @return {@code true} if this buffer is based on a byte array and provides
-     *         read/write access, {@code false} otherwise.
-     */
     public final boolean hasArray() {
         return protectedHasArray();
     }
diff --git a/nio/src/main/java/java/nio/CharBuffer.java b/nio/src/main/java/java/nio/CharBuffer.java
index ea31234..6f48101 100644
--- a/nio/src/main/java/java/nio/CharBuffer.java
+++ b/nio/src/main/java/java/nio/CharBuffer.java
@@ -153,59 +153,16 @@ public abstract class CharBuffer extends Buffer implements
      */
     CharBuffer(int capacity) {
         super(capacity);
-        // BEGIN android-added
-        _elementSizeShift = 1;
-        // END android-added
     }
 
-    /**
-     * Returns the char array which this buffer is based on, if there is one.
-     * 
-     * @return the char array which this buffer is based on.
-     * @exception ReadOnlyBufferException
-     *                if this buffer is based on an array, but it is read-only.
-     * @exception UnsupportedOperationException
-     *                if this buffer is not based on an array.
-     */
     public final char[] array() {
         return protectedArray();
     }
 
-    /**
-     * Returns the offset of the char array which this buffer is based on, if
-     * there is one.
-     * <p>
-     * The offset is the index of the array corresponds to the zero position of
-     * the buffer.
-     *
-     * @return the offset of the char array which this buffer is based on.
-     * @exception ReadOnlyBufferException
-     *                if this buffer is based on an array but it is read-only.
-     * @exception UnsupportedOperationException
-     *                if this buffer is not based on an array.
-     */
     public final int arrayOffset() {
         return protectedArrayOffset();
     }
 
-    // BEGIN android-added
-    @Override
-    Object _array() {
-        if (hasArray()) {
-            return array();
-        }
-        return null;
-    }
-
-    @Override
-    int _arrayOffset() {
-        if (hasArray()) {
-            return arrayOffset();
-        }
-        return 0;
-    }
-    // END android-added
-
     /**
      * Returns a read-only buffer that shares its content with this buffer.
      * <p>
@@ -404,12 +361,6 @@ public abstract class CharBuffer extends Buffer implements
      */
     public abstract char get(int index);
 
-    /**
-     * Indicates whether this buffer is based on a char array and is read/write.
-     *
-     * @return {@code true} if this buffer is based on a byte array and provides
-     *         read/write access, {@code false} otherwise.
-     */
     public final boolean hasArray() {
         return protectedHasArray();
     }
diff --git a/nio/src/main/java/java/nio/DoubleBuffer.java b/nio/src/main/java/java/nio/DoubleBuffer.java
index 3bea69e..4bac004 100644
--- a/nio/src/main/java/java/nio/DoubleBuffer.java
+++ b/nio/src/main/java/java/nio/DoubleBuffer.java
@@ -103,59 +103,16 @@ public abstract class DoubleBuffer extends Buffer implements
      */
     DoubleBuffer(int capacity) {
         super(capacity);
-        // BEGIN android-added
-        _elementSizeShift = 3;
-        // END android-added
     }
 
-    /**
-     * Returns the double array which this buffer is based on, if there is one.
-     * 
-     * @return the double array which this buffer is based on.
-     * @exception ReadOnlyBufferException
-     *                if this buffer is based on an array but it is read-only.
-     * @exception UnsupportedOperationException
-     *                if this buffer is not based on an array.
-     */
     public final double[] array() {
         return protectedArray();
     }
 
-    /**
-     * Returns the offset of the double array which this buffer is based on, if
-     * there is one.
-     * <p>
-     * The offset is the index of the array corresponding to the zero position
-     * of the buffer.
-     *
-     * @return the offset of the double array which this buffer is based on.
-     * @exception ReadOnlyBufferException
-     *                if this buffer is based on an array, but it is read-only.
-     * @exception UnsupportedOperationException
-     *                if this buffer is not based on an array.
-     */
     public final int arrayOffset() {
         return protectedArrayOffset();
     }
 
-    // BEGIN android-added
-    @Override
-    Object _array() {
-        if (hasArray()) {
-            return array();
-        }
-        return null;
-    }
-
-    @Override
-    int _arrayOffset() {
-        if (hasArray()) {
-            return arrayOffset();
-        }
-        return 0;
-    }
-    // END android-added
-
     /**
      * Returns a read-only buffer that shares its content with this buffer.
      * <p>
@@ -344,13 +301,6 @@ public abstract class DoubleBuffer extends Buffer implements
      */
     public abstract double get(int index);
 
-    /**
-     * Indicates whether this buffer is based on a double array and is
-     * read/write.
-     *
-     * @return {@code true} if this buffer is based on a double array and
-     *         provides read/write access, {@code false} otherwise.
-     */
     public final boolean hasArray() {
         return protectedHasArray();
     }
diff --git a/nio/src/main/java/java/nio/FloatBuffer.java b/nio/src/main/java/java/nio/FloatBuffer.java
index 15239b1..eca4cb4 100644
--- a/nio/src/main/java/java/nio/FloatBuffer.java
+++ b/nio/src/main/java/java/nio/FloatBuffer.java
@@ -105,57 +105,16 @@ public abstract class FloatBuffer extends Buffer implements
      */
     FloatBuffer(int capacity) {
         super(capacity);
-        // BEGIN android-added
-        _elementSizeShift = 2;
-        // END android-added
     }
 
-    /**
-     * Returns the float array which this buffer is based on, if there is one.
-     * 
-     * @return the float array which this buffer is based on.
-     * @exception ReadOnlyBufferException
-     *                if this buffer is based on an array, but it is read-only.
-     * @exception UnsupportedOperationException
-     *                if this buffer is not based on an array.
-     */
     public final float[] array() {
         return protectedArray();
     }
 
-    /**
-     * Returns the offset of the float array which this buffer is based on, if
-     * there is one.
-     * <p>
-     * The offset is the index of the array and corresponds to the zero position
-     * of the buffer.
-     *
-     * @return the offset of the float array which this buffer is based on.
-     * @exception ReadOnlyBufferException
-     *                if this buffer is based on an array, but it is read-only.
-     * @exception UnsupportedOperationException
-     *                if this buffer is not based on an array.
-     */
     public final int arrayOffset() {
         return protectedArrayOffset();
     }
 
-    // BEGIN android-added
-    @Override Object _array() {
-        if (hasArray()) {
-            return array();
-        }
-        return null;
-    }
-
-    @Override int _arrayOffset() {
-        if (hasArray()) {
-            return arrayOffset();
-        }
-        return 0;
-    }
-    // END android-added
-
     /**
      * Returns a read-only buffer that shares its content with this buffer.
      * <p>
@@ -344,13 +303,6 @@ public abstract class FloatBuffer extends Buffer implements
      */
     public abstract float get(int index);
 
-    /**
-     * Indicates whether this buffer is based on a float array and is
-     * read/write.
-     *
-     * @return {@code true} if this buffer is based on a float array and
-     *         provides read/write access, {@code false} otherwise.
-     */
     public final boolean hasArray() {
         return protectedHasArray();
     }
diff --git a/nio/src/main/java/java/nio/IntBuffer.java b/nio/src/main/java/java/nio/IntBuffer.java
index d95783b..055e0ef 100644
--- a/nio/src/main/java/java/nio/IntBuffer.java
+++ b/nio/src/main/java/java/nio/IntBuffer.java
@@ -102,57 +102,16 @@ public abstract class IntBuffer extends Buffer implements Comparable<IntBuffer>
      */
     IntBuffer(int capacity) {
         super(capacity);
-        // BEGIN android-added
-        _elementSizeShift = 2;
-        // END android-added
     }
 
-    /**
-     * Returns the int array which this buffer is based on, if there is one.
-     * 
-     * @return the int array which this buffer is based on.
-     * @exception ReadOnlyBufferException
-     *                if this buffer is based on an array, but it is read-only.
-     * @exception UnsupportedOperationException
-     *                if this buffer is not based on an array.
-     */
     public final int[] array() {
         return protectedArray();
     }
 
-    /**
-     * Returns the offset of the int array which this buffer is based on, if
-     * there is one.
-     * <p>
-     * The offset is the index of the array corresponds to the zero position of
-     * the buffer.
-     *
-     * @return the offset of the int array which this buffer is based on.
-     * @exception ReadOnlyBufferException
-     *                if this buffer is based on an array, but it is read-only.
-     * @exception UnsupportedOperationException
-     *                if this buffer is not based on an array.
-     */
     public final int arrayOffset() {
         return protectedArrayOffset();
     }
 
-    // BEGIN android-added
-    @Override Object _array() {
-        if (hasArray()) {
-            return array();
-        }
-        return null;
-    }
-
-    @Override int _arrayOffset() {
-        if (hasArray()) {
-            return arrayOffset();
-        }
-        return 0;
-    }
-    // END android-added
-
     /**
      * Returns a read-only buffer that shares its content with this buffer.
      * <p>
@@ -332,12 +291,6 @@ public abstract class IntBuffer extends Buffer implements Comparable<IntBuffer>
      */
     public abstract int get(int index);
 
-    /**
-     * Indicates whether this buffer is based on a int array and is read/write.
-     *
-     * @return {@code true} if this buffer is based on a int array and provides
-     *         read/write access, {@code false} otherwise.
-     */
     public final boolean hasArray() {
         return protectedHasArray();
     }
diff --git a/nio/src/main/java/java/nio/LongBuffer.java b/nio/src/main/java/java/nio/LongBuffer.java
index eecbf5e..68bf9fe 100644
--- a/nio/src/main/java/java/nio/LongBuffer.java
+++ b/nio/src/main/java/java/nio/LongBuffer.java
@@ -104,57 +104,16 @@ public abstract class LongBuffer extends Buffer implements
      */
     LongBuffer(int capacity) {
         super(capacity);
-        // BEGIN android-added
-        _elementSizeShift = 3;
-        // END android-added
     }
 
-    /**
-     * Returns the long array which this buffer is based on, if there is one.
-     * 
-     * @return the long array which this buffer is based on.
-     * @exception ReadOnlyBufferException
-     *                if this buffer is based on an array, but it is read-only.
-     * @exception UnsupportedOperationException
-     *                if this buffer is not based on an array.
-     */
     public final long[] array() {
         return protectedArray();
     }
 
-    /**
-     * Returns the offset of the long array which this buffer is based on, if
-     * there is one.
-     * <p>
-     * The offset is the index of the array and corresponds to the zero position
-     * of the buffer.
-     *
-     * @return the offset of the long array which this buffer is based on.
-     * @exception ReadOnlyBufferException
-     *                if this buffer is based on an array, but it is read-only.
-     * @exception UnsupportedOperationException
-     *                if this buffer is not based on an array.
-     */
     public final int arrayOffset() {
         return protectedArrayOffset();
     }
 
-    // BEGIN android-added
-    @Override Object _array() {
-        if (hasArray()) {
-            return array();
-        }
-        return null;
-    }
-
-    @Override int _arrayOffset() {
-        if (hasArray()) {
-            return arrayOffset();
-        }
-        return 0;
-    }
-    // END android-added
-
     /**
      * Returns a read-only buffer that shares its content with this buffer.
      * <p>
@@ -335,12 +294,6 @@ public abstract class LongBuffer extends Buffer implements
      */
     public abstract long get(int index);
 
-    /**
-     * Indicates whether this buffer is based on a long array and is read/write.
-     *
-     * @return {@code true} if this buffer is based on a long array and provides
-     *         read/write access, {@code false} otherwise.
-     */
     public final boolean hasArray() {
         return protectedHasArray();
     }
diff --git a/nio/src/main/java/java/nio/NIOAccess.java b/nio/src/main/java/java/nio/NIOAccess.java
deleted file mode 100644
index 979ee19..0000000
--- a/nio/src/main/java/java/nio/NIOAccess.java
+++ /dev/null
@@ -1,87 +0,0 @@
-/*
- * Copyright (C) 2007 The Android Open Source Project
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package java.nio;
-
-import org.apache.harmony.luni.platform.PlatformAddress;
-import org.apache.harmony.nio.internal.DirectBuffer;
-
-/**
- * A class allowing native code to access the underlying data of
- * an NIO Buffer, breaking encapsulation in the name of efficiency.
- */
-class NIOAccess {
-
-    /**
-     * Returns the underlying native pointer to the data of the given
-     * Buffer starting at the Buffer's current position, or 0 if the
-     * Buffer is not backed by native heap storage. Note that this is
-     * different than what the Harmony implementation calls a "base
-     * address."
-     *
-     * @param Buffer b the Buffer to be queried
-     * @return the native pointer to the Buffer's data at its current
-     * position, or 0 if there is none
-     */
-    static long getBasePointer(Buffer b) {
-        if (b instanceof DirectBuffer) {
-            PlatformAddress address = ((DirectBuffer) b).getEffectiveAddress();
-            if (address == null) {
-                return 0L;
-            }
-            return address.toInt() + (b.position() << b._elementSizeShift);
-        }
-        return 0L;
-    }
-
-    /**
-     * Returns the number of bytes remaining in the given Buffer. That is,
-     * this scales <code>remaining()</code> by the byte-size of elements
-     * of this Buffer.
-     *
-     * @param Buffer b the Buffer to be queried
-     * @return the number of remaining bytes
-     */
-    static int getRemainingBytes(Buffer b) {
-        return (b.limit - b.position) << b._elementSizeShift;
-    }
-
-    /**
-     * Returns the underlying Java array containing the data of the
-     * given Buffer, or null if the Buffer is not backed by a Java array.
-     *
-     * @param Buffer b the Buffer to be queried
-     * @return the Java array containing the Buffer's data, or null if
-     * there is none
-     */
-    static Object getBaseArray(Buffer b) {
-        return b._array();
-    }
-
-    /**
-     * Returns the offset in bytes from the start of the underlying
-     * Java array object containing the data of the given Buffer to
-     * the actual start of the data. This method is only meaningful if
-     * getBaseArray() returns non-null.
-     *
-     * @param Buffer b the Buffer to be queried
-     * @return the data offset in bytes to the start of this Buffer's data
-     */
-    static int getBaseArrayOffset(Buffer b) {
-        return b._arrayOffset() << b._elementSizeShift;
-    }
-}
-
diff --git a/nio/src/main/java/java/nio/ShortBuffer.java b/nio/src/main/java/java/nio/ShortBuffer.java
index 22d1b25..01ff83a 100644
--- a/nio/src/main/java/java/nio/ShortBuffer.java
+++ b/nio/src/main/java/java/nio/ShortBuffer.java
@@ -104,57 +104,16 @@ public abstract class ShortBuffer extends Buffer implements
      */
     ShortBuffer(int capacity) {
         super(capacity);
-        // BEGIN android-added
-        _elementSizeShift = 1;
-        // END android-added
     }
 
-    /**
-     * Returns the short array which this buffer is based on, if there is one.
-     * 
-     * @return the short array which this buffer is based on.
-     * @exception ReadOnlyBufferException
-     *                if this buffer is based on an array, but it is read-only.
-     * @exception UnsupportedOperationException
-     *                if this buffer is not based on an array.
-     */
     public final short[] array() {
         return protectedArray();
     }
 
-    /**
-     * Returns the offset of the short array which this buffer is based on, if
-     * there is one.
-     * <p>
-     * The offset is the index of the array corresponding to the zero position
-     * of the buffer.
-     *
-     * @return the offset of the short array which this buffer is based on.
-     * @exception ReadOnlyBufferException
-     *                if this buffer is based on an array, but it is read-only.
-     * @exception UnsupportedOperationException
-     *                if this buffer is not based on an array.
-     */
     public final int arrayOffset() {
         return protectedArrayOffset();
     }
 
-    // BEGIN android-added
-    @Override Object _array() {
-        if (hasArray()) {
-            return array();
-        }
-        return null;
-    }
-
-    @Override int _arrayOffset() {
-        if (hasArray()) {
-            return arrayOffset();
-        }
-        return 0;
-    }
-    // END android-added
-
     /**
      * Returns a read-only buffer that shares its content with this buffer.
      * <p>
@@ -333,13 +292,6 @@ public abstract class ShortBuffer extends Buffer implements
      */
     public abstract short get(int index);
 
-    /**
-     * Indicates whether this buffer is based on a short array and is
-     * read/write.
-     *
-     * @return {@code true} if this buffer is based on a short array and
-     *         provides read/write access, {@code false} otherwise.
-     */
     public final boolean hasArray() {
         return protectedHasArray();
     }