src/share/classes/java/nio/Buffer.java

Print this page




   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.nio;
  27 

  28 
  29 /**
  30  * A container for data of a specific primitive type.
  31  *
  32  * <p> A buffer is a linear, finite sequence of elements of a specific
  33  * primitive type.  Aside from its content, the essential properties of a
  34  * buffer are its capacity, limit, and position: </p>
  35  *
  36  * <blockquote>
  37  *
  38  *   <p> A buffer's <i>capacity</i> is the number of elements it contains.  The
  39  *   capacity of a buffer is never negative and never changes.  </p>
  40  *
  41  *   <p> A buffer's <i>limit</i> is the index of the first element that should
  42  *   not be read or written.  A buffer's limit is never negative and is never
  43  *   greater than its capacity.  </p>
  44  *
  45  *   <p> A buffer's <i>position</i> is the index of the next element to be
  46  *   read or written.  A buffer's position is never negative and is never
  47  *   greater than its limit.  </p>


 155  * specified to return the buffer upon which they are invoked.  This allows
 156  * method invocations to be chained; for example, the sequence of statements
 157  *
 158  * <blockquote><pre>
 159  * b.flip();
 160  * b.position(23);
 161  * b.limit(42);</pre></blockquote>
 162  *
 163  * can be replaced by the single, more compact statement
 164  *
 165  * <blockquote><pre>
 166  * b.flip().position(23).limit(42);</pre></blockquote>
 167  *
 168  *
 169  * @author Mark Reinhold
 170  * @author JSR-51 Expert Group
 171  * @since 1.4
 172  */
 173 
 174 public abstract class Buffer {







 175 
 176     // Invariants: mark <= position <= limit <= capacity
 177     private int mark = -1;
 178     private int position = 0;
 179     private int limit;
 180     private int capacity;
 181 
 182     // Used only by direct buffers
 183     // NOTE: hoisted here for speed in JNI GetDirectBufferAddress
 184     long address;
 185 
 186     // Creates a new buffer with the given mark, position, limit, and capacity,
 187     // after checking invariants.
 188     //
 189     Buffer(int mark, int pos, int lim, int cap) {       // package-private
 190         if (cap < 0)
 191             throw new IllegalArgumentException("Negative capacity: " + cap);
 192         this.capacity = cap;
 193         limit(lim);
 194         position(pos);




   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.nio;
  27 
  28 import java.util.Spliterator;
  29 
  30 /**
  31  * A container for data of a specific primitive type.
  32  *
  33  * <p> A buffer is a linear, finite sequence of elements of a specific
  34  * primitive type.  Aside from its content, the essential properties of a
  35  * buffer are its capacity, limit, and position: </p>
  36  *
  37  * <blockquote>
  38  *
  39  *   <p> A buffer's <i>capacity</i> is the number of elements it contains.  The
  40  *   capacity of a buffer is never negative and never changes.  </p>
  41  *
  42  *   <p> A buffer's <i>limit</i> is the index of the first element that should
  43  *   not be read or written.  A buffer's limit is never negative and is never
  44  *   greater than its capacity.  </p>
  45  *
  46  *   <p> A buffer's <i>position</i> is the index of the next element to be
  47  *   read or written.  A buffer's position is never negative and is never
  48  *   greater than its limit.  </p>


 156  * specified to return the buffer upon which they are invoked.  This allows
 157  * method invocations to be chained; for example, the sequence of statements
 158  *
 159  * <blockquote><pre>
 160  * b.flip();
 161  * b.position(23);
 162  * b.limit(42);</pre></blockquote>
 163  *
 164  * can be replaced by the single, more compact statement
 165  *
 166  * <blockquote><pre>
 167  * b.flip().position(23).limit(42);</pre></blockquote>
 168  *
 169  *
 170  * @author Mark Reinhold
 171  * @author JSR-51 Expert Group
 172  * @since 1.4
 173  */
 174 
 175 public abstract class Buffer {
 176 
 177     /**
 178      * The characteristics of Spliterators that traverse and split elements
 179      * maintained in Buffers.
 180      */
 181     static final int SPLITERATOR_CHARACTERISTICS =
 182         Spliterator.SIZED | Spliterator.SUBSIZED | Spliterator.ORDERED;
 183 
 184     // Invariants: mark <= position <= limit <= capacity
 185     private int mark = -1;
 186     private int position = 0;
 187     private int limit;
 188     private int capacity;
 189 
 190     // Used only by direct buffers
 191     // NOTE: hoisted here for speed in JNI GetDirectBufferAddress
 192     long address;
 193 
 194     // Creates a new buffer with the given mark, position, limit, and capacity,
 195     // after checking invariants.
 196     //
 197     Buffer(int mark, int pos, int lim, int cap) {       // package-private
 198         if (cap < 0)
 199             throw new IllegalArgumentException("Negative capacity: " + cap);
 200         this.capacity = cap;
 201         limit(lim);
 202         position(pos);