libjava/java/nio/ByteBuffer.java

   1 /* ByteBuffer.java --
   2    Copyright (C) 2002 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package java.nio;
  39
  40 import gnu.java.nio.ByteBufferImpl;
  41
  42 /**
  43  * @since 1.4
  44  */
  45 public abstract class ByteBuffer extends Buffer implements Comparable
  46 {
  47   private ByteOrder endian = ByteOrder.BIG_ENDIAN;
  48
  49   int offset;
  50   byte[] backing_buffer;
  51
  52   /**
  53    * Allocates a new direct byte buffer.
  54    */
  55   public static ByteBuffer allocateDirect (int capacity)
  56   {
  57     throw new Error ("direct buffers are not implemented");
  58   }
  59
  60   /**
  61    * Allocates a new byte buffer.
  62    */
  63   public static ByteBuffer allocate (int capacity)
  64   {
  65     return new ByteBufferImpl (capacity, 0, capacity);
  66   }
  67
  68   /**
  69    * Wraps a byte array into a buffer.
  70    *
  71    * @exception IndexOutOfBoundsException If the preconditions on the offset
  72    * and length parameters do not hold
  73    */
  74   final public static ByteBuffer wrap (byte[] array, int offset, int length)
  75   {
  76     return new ByteBufferImpl (array, offset, length);
  77   }
  78
  79   /**
  80    * Wraps a byte array into a buffer.
  81    */
  82   final public static ByteBuffer wrap (byte[] array)
  83   {
  84     return wrap (array, 0, array.length);
  85   }
  86
  87   ByteBuffer (int capacity, int limit, int position, int mark)
  88   {
  89     super (capacity, limit, position, mark);
  90   }
  91
  92   /**
  93    * This method transfers bytes from this buffer into
  94    * the given destination array.
  95    *
  96    * @param dst The destination array
  97    * @param offset The offset within the array of the first byte to be written;
  98    * must be non-negative and no larger than dst.length.
  99    * @param length The maximum number of bytes to be written to the given array;
 100    * must be non-negative and no larger than dst.length - offset.
 101    *
 102    * @exception BufferUnderflowException If there are fewer than length bytes
 103    * remaining in this buffer.
 104    * @exception IndexOutOfBoundsException - If the preconditions on the offset
 105    * and length parameters do not hold.
 106    */
 107   public ByteBuffer get (byte[] dst, int offset, int length)
 108   {
 109     if ((offset < 0)
 110         || (offset > dst.length)
 111         || (length < 0)
 112         || (length > (dst.length - offset)))
 113       throw new IndexOutOfBoundsException ();
 114
 115     for (int i = offset; i < offset + length; i++)
 116       {
 117         dst [i] = get();
 118       }
 119
 120     return this;
 121   }
 122
 123   /**
 124    * This method transfers bytes from this buffer into the given
 125    * destination array.
 126    *
 127    * @param dst The byte array to write into.
 128    *
 129    * @exception BufferUnderflowException If there are fewer than dst.length
 130    * bytes remaining in this buffer.
 131    */
 132   public ByteBuffer get (byte[] dst)
 133   {
 134     return get (dst, 0, dst.length);
 135   }
 136
 137   /**
 138    * Writes the content of src into the buffer.
 139    *
 140    * @param src The source data.
 141    *
 142    * @exception BufferOverflowException If there is insufficient space in this
 143    * buffer for the remaining bytes in the source buffer.
 144    * @exception IllegalArgumentException If the source buffer is this buffer.
 145    * @exception ReadOnlyBufferException If this buffer is read only.
 146    */
 147   public ByteBuffer put (ByteBuffer src)
 148   {
 149     if (src == this)
 150       throw new IllegalArgumentException ();
 151
 152     while (src.hasRemaining ())
 153       put (src.get ());
 154
 155     return this;
 156   }
 157
 158   /**
 159    * Writes the content of the the array src into the buffer.
 160    *
 161    * @param src The array to copy into the buffer.
 162    * @param offset The offset within the array of the first byte to be read;
 163    * must be non-negative and no larger than src.length.
 164    * @param length The number of bytes to be read from the given array;
 165    * must be non-negative and no larger than src.length - offset.
 166    *
 167    * @exception BufferOverflowException If there is insufficient space in this
 168    * buffer for the remaining bytes in the source buffer.
 169    * @exception IndexOutOfBoundsException If the preconditions on the offset
 170    * and length parameters do not hold.
 171    * @exception ReadOnlyBufferException If this buffer is read only.
 172    */
 173   public ByteBuffer put (byte[] src, int offset, int length)
 174   {
 175     if ((offset < 0) ||
 176         (offset > src.length) ||
 177         (length < 0) ||
 178         (length > src.length - offset))
 179       throw new IndexOutOfBoundsException ();
 180
 181     for (int i = offset; i < offset + length; i++)
 182       put (src [i]);
 183
 184     return this;
 185   }
 186
 187   /**
 188    * Writes the content of the the array src into the buffer.
 189    *
 190    * @param src The array to copy into the buffer.
 191    *
 192    * @exception BufferOverflowException If there is insufficient space in this
 193    * buffer for the remaining bytes in the source buffer.
 194    * @exception ReadOnlyBufferException If this buffer is read only.
 195    */
 196   public final ByteBuffer put (byte[] src)
 197   {
 198     return put (src, 0, src.length);
 199   }
 200
 201   /**
 202    * Tells whether or not this buffer is backed by an accessible byte array.
 203    */
 204   public final boolean hasArray ()
 205   {
 206     return (backing_buffer != null
 207              && !isReadOnly ());
 208   }
 209
 210   /**
 211    * Returns the byte array that backs this buffer.
 212    *
 213    * @exception ReadOnlyBufferException If this buffer is backed by an array
 214    * but is read-only.
 215    * @exception UnsupportedOperationException If this buffer is not backed
 216    * by an accessible array.
 217    */
 218   public final byte[] array ()
 219   {
 220     if (backing_buffer == null)
 221       throw new UnsupportedOperationException ();
 222
 223     if (isReadOnly ())
 224       throw new ReadOnlyBufferException ();
 225
 226     return backing_buffer;
 227   }
 228
 229   /**
 230    * Returns the offset within this buffer's backing array of the first element
 231    * of the buffer
 232    *
 233    * @exception ReadOnlyBufferException If this buffer is backed by an array
 234    * but is read-only.
 235    * @exception UnsupportedOperationException If this buffer is not backed
 236    * by an accessible array.
 237    */
 238   public final int arrayOffset ()
 239   {
 240     if (backing_buffer == null)
 241       throw new UnsupportedOperationException ();
 242
 243     if (isReadOnly ())
 244       throw new ReadOnlyBufferException ();
 245
 246     return offset;
 247   }
 248
 249   /**
 250    * Tells whether or not this buffer is equal to another object.
 251    */
 252   public boolean equals (Object obj)
 253   {
 254     if (obj != null &&
 255         obj instanceof ByteBuffer)
 256       {
 257         return compareTo (obj) == 0;
 258       }
 259
 260     return false;
 261   }
 262
 263   /**
 264    * Compares this buffer to another object.
 265    *
 266    * @exception ClassCastException If the argument is not a byte buffer
 267    */
 268   public int compareTo (Object obj)
 269   {
 270     ByteBuffer a = (ByteBuffer) obj;
 271
 272     if (a.remaining() != remaining())
 273       {
 274         return 1;
 275       }
 276
 277     if (! hasArray() ||
 278         ! a.hasArray())
 279       {
 280         return 1;
 281       }
 282
 283     int r = remaining();
 284     int i1 = position ();
 285     int i2 = a.position ();
 286
 287     for (int i = 0; i < r; i++)
 288       {
 289         int t = (int) (get (i1) - a.get (i2));
 290
 291         if (t != 0)
 292           {
 293             return (int) t;
 294           }
 295       }
 296
 297     return 0;
 298   }
 299
 300   /**
 301    * Retrieves this buffer's byte order.
 302    */
 303   public final ByteOrder order()
 304   {
 305     return endian;
 306   }
 307
 308   /**
 309    * Modifies this buffer's byte order.
 310    */
 311   public final ByteBuffer order (ByteOrder endian)
 312   {
 313     this.endian = endian;
 314     return this;
 315   }
 316
 317   /**
 318    * Reads the byte at this buffer's current position,
 319    * and then increments the position.
 320    *
 321    * @exception BufferUnderflowException If the buffer's current position
 322    * is not smaller than its limit.
 323    */
 324   public abstract byte get ();
 325
 326   /**
 327    * Relative put method.
 328    *
 329    * @exception BufferOverflowException If this buffer's current position is
 330    * not smaller than its limit.
 331    * @exception ReadOnlyBufferException If this buffer is read-only.
 332    */
 333   public abstract ByteBuffer put (byte b);
 334
 335   /**
 336    * Absolute get method.
 337    *
 338    * @exception IndexOutOfBoundsException FIXME
 339    */
 340   public abstract byte get (int index);
 341
 342   /**
 343    * Absolute put method.
 344    *
 345    * @exception ReadOnlyBufferException If this buffer is read-only
 346    * @exception IndexOutOfBoundsException FIXME
 347    */
 348   public abstract ByteBuffer put (int index, byte b);
 349
 350   /**
 351    * Compacts this buffer.
 352    *
 353    * @exception ReadOnlyBufferException If this buffer is read-only
 354    */
 355   public abstract ByteBuffer compact();
 356
 357   /**
 358    * Tells whether or not this buffer is direct.
 359    */
 360   public abstract boolean isDirect();
 361
 362   /**
 363    * Creates a new byte buffer whose content is a shared subsequence of this
 364    * buffer's content.
 365    */
 366   public abstract ByteBuffer slice();
 367
 368   /**
 369    * Creates a new byte buffer that shares this buffer's content.
 370    */
 371   public abstract ByteBuffer duplicate();
 372
 373   /**
 374    * Creates a new, read-only byte buffer that shares this buffer's content.
 375    */
 376   public abstract ByteBuffer asReadOnlyBuffer();
 377
 378   /**
 379    * Creates a view of this byte buffer as a short buffer.
 380    */
 381   public abstract ShortBuffer asShortBuffer();
 382
 383   /**
 384    * Creates a view of this byte buffer as a char buffer.
 385    */
 386   public abstract CharBuffer asCharBuffer();
 387
 388   /**
 389    * Creates a view of this byte buffer as an integer buffer.
 390    */
 391   public abstract IntBuffer asIntBuffer();
 392
 393   /**
 394    * Creates a view of this byte buffer as a long buffer.
 395    */
 396   public abstract LongBuffer asLongBuffer();
 397
 398   /**
 399    * Creates a view of this byte buffer as a float buffer.
 400    */
 401   public abstract FloatBuffer asFloatBuffer();
 402
 403   /**
 404    * Creates a view of this byte buffer as a double buffer.
 405    */
 406   public abstract DoubleBuffer asDoubleBuffer();
 407
 408   /**
 409    * Relative get method for reading a character value.
 410    *
 411    * @exception BufferUnderflowException  If there are fewer than two bytes
 412    * remaining in this buffer.
 413    */
 414   public abstract char getChar();
 415
 416   /**
 417    * Relative put method for writing a character value.
 418    *
 419    * @exception BufferOverflowException If this buffer's current position is
 420    * not smaller than its limit.
 421    */
 422   public abstract ByteBuffer putChar(char value);
 423
 424   /**
 425    * Absolute get method for reading a character value.
 426    *
 427    * @exception IndexOutOfBoundsException If there are fewer than two bytes
 428    * remaining in this buffer
 429    */
 430   public abstract char getChar(int index);
 431
 432   /**
 433    * Absolute put method for writing a character value.
 434    *
 435    * @exception IndexOutOfBoundsException If index is negative or not smaller
 436    * than the buffer's limit, minus one.
 437    */
 438   public abstract ByteBuffer putChar(int index, char value);
 439
 440   /**
 441    * Relative get method for reading a short value.
 442    *
 443    * @exception BufferUnderflowException If index is negative or not smaller
 444    * than the buffer's limit, minus one.
 445    */
 446   public abstract short getShort();
 447
 448   /**
 449    * Relative put method for writing a short value.
 450    *
 451    * @exception BufferOverflowException If this buffer's current position is
 452    * not smaller than its limit.
 453    */
 454   public abstract ByteBuffer putShort(short value);
 455
 456   /**
 457    * Absolute get method for reading a short value.
 458    *
 459    * @exception IndexOutOfBoundsException If there are fewer than two bytes
 460    * remaining in this buffer
 461    */
 462   public abstract short getShort(int index);
 463
 464   /**
 465    * Absolute put method for writing a short value.
 466    *
 467    * @exception IndexOutOfBoundsException If index is negative or not smaller
 468    * than the buffer's limit, minus one.
 469    */
 470   public abstract ByteBuffer putShort(int index, short value);
 471
 472   /**
 473    * Relative get method for reading an integer value.
 474    *
 475    * @exception BufferUnderflowException If there are fewer than four bytes
 476    * remaining in this buffer.
 477    */
 478   public abstract int getInt();
 479
 480   /**
 481    * Relative put method for writing an integer value.
 482    *
 483    * @exception BufferOverflowException If this buffer's current position is
 484    * not smaller than its limit.
 485    */
 486   public abstract ByteBuffer putInt(int value);
 487
 488   /**
 489    * Absolute get method for reading an integer value.
 490    *
 491    * @exception IndexOutOfBoundsException If index is negative or not smaller
 492    * than the buffer's limit, minus three.
 493    */
 494   public abstract int getInt(int index);
 495
 496   /**
 497    * Absolute put method for writing an integer value.
 498    *
 499    * @exception IndexOutOfBoundsException If index is negative or not smaller
 500    * than the buffer's limit, minus three.
 501    */
 502   public abstract ByteBuffer putInt(int index, int value);
 503
 504   /**
 505    * Relative get method for reading a long value.
 506    *
 507    * @exception BufferUnderflowException If there are fewer than eight bytes
 508    * remaining in this buffer.
 509    */
 510   public abstract long getLong();
 511
 512   /**
 513    * Relative put method for writing a long value.
 514    *
 515    * @exception BufferOverflowException If this buffer's current position is
 516    * not smaller than its limit.
 517    */
 518   public abstract ByteBuffer putLong(long value);
 519
 520   /**
 521    * Absolute get method for reading a long value.
 522    *
 523    * @exception IndexOutOfBoundsException If index is negative or not smaller
 524    * than the buffer's limit, minus seven.
 525    */
 526   public abstract long getLong(int index);
 527
 528   /**
 529    * Absolute put method for writing a float value.
 530    *
 531    * @exception IndexOutOfBoundsException If index is negative or not smaller
 532    * than the buffer's limit, minus seven.
 533    */
 534   public abstract ByteBuffer putLong(int index, long value);
 535
 536   /**
 537    * Relative get method for reading a float value.
 538    *
 539    * @exception BufferUnderflowException If there are fewer than four bytes
 540    * remaining in this buffer.
 541    */
 542   public abstract float getFloat();
 543
 544   /**
 545    * Relative put method for writing a float value.
 546    *
 547    * @exception BufferOverflowException If there are fewer than four bytes
 548    * remaining in this buffer.
 549    */
 550   public abstract ByteBuffer putFloat(float value);
 551
 552   /**
 553    * Absolute get method for reading a float value.
 554    *
 555    * @exception IndexOutOfBoundsException If index is negative or not smaller
 556    * than the buffer's limit, minus three.
 557    */
 558   public abstract float getFloat(int index);
 559
 560   /**
 561    * Relative put method for writing a float value.
 562    *
 563    * @exception IndexOutOfBoundsException If index is negative or not smaller
 564    * than the buffer's limit, minus three.
 565    */
 566   public abstract ByteBuffer putFloat(int index, float value);
 567
 568   /**
 569    * Relative get method for reading a double value.
 570    *
 571    * @exception BufferUnderflowException If there are fewer than eight bytes
 572    * remaining in this buffer.
 573    */
 574   public abstract double getDouble();
 575
 576   /**
 577    * Relative put method for writing a double value.
 578    *
 579    * @exception BufferOverflowException If this buffer's current position is
 580    * not smaller than its limit.
 581    */
 582   public abstract ByteBuffer putDouble(double value);
 583
 584   /**
 585    * Absolute get method for reading a double value.
 586    *
 587    * @exception IndexOutOfBoundsException If index is negative or not smaller
 588    * than the buffer's limit, minus seven.
 589    */
 590   public abstract double getDouble(int index);
 591
 592   /**
 593    * Absolute put method for writing a double value.
 594    *
 595    * @exception IndexOutOfBoundsException If index is negative or not smaller
 596    * than the buffer's limit, minus seven.
 597    */
 598   public abstract ByteBuffer putDouble(int index, double value);
 599
 600   /**
 601    * Returns a string summarizing the state of this buffer.
 602    */
 603   public String toString ()
 604   {
 605     return getClass ().getName () +
 606             "[pos=" + position () +
 607             " lim=" + limit () +
 608             " cap=" + capacity () + "]";
 609   }
 610 }