libjava/classpath/java/nio/Buffer.java

   1 /* Buffer.java --
   2    Copyright (C) 2002, 2003, 2004  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., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 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
  39 package java.nio;
  40
  41 import gnu.classpath.Pointer;
  42
  43 /**
  44  * @since 1.4
  45  */
  46 public abstract class Buffer
  47 {
  48   private final int cap;
  49   int limit;
  50   int pos;
  51   int mark;
  52   final Pointer address;
  53
  54   /**
  55    * Creates a new Buffer.
  56    *
  57    * Should be package private.
  58    */
  59   Buffer (int capacity, int limit, int position, int mark, Pointer address)
  60   {
  61     this.address = address;
  62
  63     if (capacity < 0)
  64       throw new IllegalArgumentException ();
  65
  66     cap = capacity;
  67     limit (limit);
  68     position (position);
  69
  70     if (mark >= 0)
  71     {
  72       if (mark > pos)
  73         throw new IllegalArgumentException ();
  74
  75       this.mark = mark;
  76     }
  77     else
  78     {
  79       this.mark = -1;
  80     }
  81   }
  82
  83   /**
  84    * Retrieves the capacity of the buffer.
  85    *
  86    * @return the capacity of the buffer
  87    */
  88   public final int capacity ()
  89   {
  90     return cap;
  91   }
  92
  93   /**
  94    * Clears the buffer.
  95    *
  96    * @return this buffer
  97    */
  98   public final Buffer clear ()
  99   {
 100     limit = cap;
 101     pos = 0;
 102     mark = -1;
 103     return this;
 104   }
 105
 106   /**
 107    * Flips the buffer.
 108    *
 109    * @return this buffer
 110    */
 111   public final Buffer flip ()
 112   {
 113     limit = pos;
 114     pos = 0;
 115     mark = -1;
 116     return this;
 117   }
 118
 119   /**
 120    * Tells whether the buffer has remaining data to read or not.
 121    *
 122    * @return true if the buffer contains remaining data to read,
 123    * false otherwise
 124    */
 125   public final boolean hasRemaining ()
 126   {
 127     return remaining() > 0;
 128   }
 129
 130   /**
 131    * Tells whether this buffer is read only or not.
 132    *
 133    * @return true if the buffer is read only, false otherwise
 134    */
 135   public abstract boolean isReadOnly ();
 136
 137   /**
 138    * Retrieves the current limit of the buffer.
 139    *
 140    * @return the limit of the buffer
 141    */
 142   public final int limit ()
 143   {
 144     return limit;
 145   }
 146
 147   /**
 148    * Sets this buffer's limit.
 149    *
 150    * @param newLimit The new limit value; must be non-negative and no larger
 151    * than this buffer's capacity.
 152    *
 153    * @return this buffer
 154    *
 155    * @exception IllegalArgumentException If the preconditions on newLimit
 156    * do not hold.
 157    */
 158   public final Buffer limit (int newLimit)
 159   {
 160     if ((newLimit < 0) || (newLimit > cap))
 161       throw new IllegalArgumentException ();
 162
 163     if (newLimit < mark)
 164         mark = -1;
 165
 166     if (pos > newLimit)
 167         pos = newLimit;
 168
 169     limit = newLimit;
 170     return this;
 171   }
 172
 173   /**
 174    * Sets this buffer's mark at its position.
 175    *
 176    * @return this buffer
 177    */
 178   public final Buffer mark ()
 179   {
 180     mark = pos;
 181     return this;
 182   }
 183
 184   /**
 185    * Retrieves the current position of this buffer.
 186    *
 187    * @return the current position of this buffer
 188    */
 189   public final int position ()
 190   {
 191     return pos;
 192   }
 193
 194   /**
 195    * Sets this buffer's position. If the mark is defined and larger than the
 196    * new position then it is discarded.
 197    *
 198    * @param newPosition The new position value; must be non-negative and no
 199    * larger than the current limit.
 200    *
 201    * @return this buffer
 202    *
 203    * @exception IllegalArgumentException If the preconditions on newPosition
 204    * do not hold
 205    */
 206   public final Buffer position (int newPosition)
 207   {
 208     if ((newPosition < 0) || (newPosition > limit))
 209       throw new IllegalArgumentException ();
 210
 211     if (newPosition <= mark)
 212         mark = -1;
 213
 214     pos = newPosition;
 215     return this;
 216   }
 217
 218   /**
 219    * Returns the number of elements between the current position and the limit.
 220    *
 221    * @return the number of remaining elements
 222    */
 223   public final int remaining()
 224   {
 225     return limit - pos;
 226   }
 227
 228   /**
 229    * Resets this buffer's position to the previously-marked position.
 230    *
 231    * @return this buffer
 232    *
 233    * @exception InvalidMarkException If the mark has not been set.
 234    */
 235   public final Buffer reset()
 236   {
 237     if (mark == -1)
 238       throw new InvalidMarkException ();
 239
 240     pos = mark;
 241     return this;
 242   }
 243
 244   /**
 245    * Rewinds this buffer. The position is set to zero and the mark
 246    * is discarded.
 247    *
 248    * @return this buffer
 249    */
 250   public final Buffer rewind()
 251   {
 252     pos = 0;
 253     mark = -1;
 254     return this;
 255   }
 256
 257   /**
 258    * Checks for underflow. This method is used internally to check
 259    * whether a buffer has enough elements left to satisfy a read
 260    * request.
 261    *
 262    * @exception BufferUnderflowException If there are no remaining
 263    * elements in this buffer.
 264    */
 265   final void checkForUnderflow()
 266   {
 267     if (!hasRemaining())
 268       throw new BufferUnderflowException();
 269   }
 270
 271   /**
 272    * Checks for underflow. This method is used internally to check
 273    * whether a buffer has enough elements left to satisfy a read
 274    * request for a given number of elements.
 275    *
 276    * @param length The length of a sequence of elements.
 277    *
 278    * @exception BufferUnderflowException If there are not enough
 279    * remaining elements in this buffer.
 280    */
 281   final void checkForUnderflow(int length)
 282   {
 283     if (remaining() < length)
 284       throw new BufferUnderflowException();
 285   }
 286
 287   /**
 288    * Checks for overflow. This method is used internally to check
 289    * whether a buffer has enough space left to satisfy a write
 290    * request.
 291    *
 292    * @exception BufferOverflowException If there is no remaining
 293    * space in this buffer.
 294    */
 295   final void checkForOverflow()
 296   {
 297     if (!hasRemaining())
 298       throw new BufferOverflowException();
 299   }
 300
 301   /**
 302    * Checks for overflow. This method is used internally to check
 303    * whether a buffer has enough space left to satisfy a write
 304    * request for a given number of elements.
 305    *
 306    * @param length The length of a sequence of elements.
 307    *
 308    * @exception BufferUnderflowException If there is not enough
 309    * remaining space in this buffer.
 310    */
 311   final void checkForOverflow(int length)
 312   {
 313     if (remaining() < length)
 314       throw new BufferOverflowException();
 315   }
 316
 317   /**
 318    * Checks if index is negative or not smaller than the buffer's
 319    * limit. This method is used internally to check whether
 320    * an indexed request can be fulfilled.
 321    *
 322    * @param index The requested position in the buffer.
 323    *
 324    * @exception IndexOutOfBoundsException If index is negative or not smaller
 325    * than the buffer's limit.
 326    */
 327   final void checkIndex(int index)
 328   {
 329     if (index < 0
 330         || index >= limit ())
 331       throw new IndexOutOfBoundsException ();
 332   }
 333
 334   /**
 335    * Checks if buffer is read-only. This method is used internally to
 336    * check if elements can be put into a buffer.
 337    *
 338    * @exception ReadOnlyBufferException If this buffer is read-only.
 339    */
 340   final void checkIfReadOnly()
 341   {
 342     if (isReadOnly())
 343       throw new ReadOnlyBufferException ();
 344   }
 345
 346   /**
 347    * Checks whether an array is large enough to hold the given number of
 348    * elements at the given offset. This method is used internally to
 349    * check if an array is big enough.
 350    *
 351    * @param arraylength The length of the array.
 352    * @param offset The offset within the array of the first byte to be read;
 353    * must be non-negative and no larger than arraylength.
 354    * @param length The number of bytes to be read from the given array;
 355    * must be non-negative and no larger than arraylength - offset.
 356    *
 357    * @exception IndexOutOfBoundsException If the preconditions on the offset
 358    * and length parameters do not hold
 359    */
 360   static final void checkArraySize(int arraylength, int offset, int length)
 361   {
 362     if ((offset < 0) ||
 363         (length < 0) ||
 364         (arraylength < length + offset))
 365       throw new IndexOutOfBoundsException ();
 366   }
 367
 368   /**
 369    * Returns the backing array of this buffer, if this buffer has one.
 370    * Modification to the array are directly visible in this buffer and vice
 371    * versa.
 372    *
 373    * <p>
 374    * If this is a read-only buffer, then a {@link ReadOnlyBufferException} is
 375    * thrown because exposing the array would allow to circumvent the read-only
 376    * property. If this buffer doesn't have an array, then an
 377    * {@link UnsupportedOperationException} is thrown. Applications should check
 378    * if this buffer supports a backing array by calling {@link #hasArray}
 379    * first.</p>
 380    *
 381    * @return the backing array of this buffer
 382    *
 383    * @throws ReadOnlyBufferException when this buffer is read only
 384    * @throws UnsupportedOperationException when this buffer does not provide
 385    *         a backing array
 386    *
 387    * @since 1.6
 388    */
 389   public abstract Object array();
 390
 391   /**
 392    * Returns <code>true</code> if this buffer can provide a backing array,
 393    * <code>false</code> otherwise. When <code>true</code>, application code
 394    * can call {@link #array()} to access this backing array.
 395    *
 396    * @return <code>true</code> if this buffer can provide a backing array,
 397    *         <code>false</code> otherwise
 398    *
 399    * @since 1.6
 400    */
 401   public abstract boolean hasArray();
 402
 403   /**
 404    * For buffers that are backed by a Java array, this returns the offset
 405    * into that array at which the buffer content starts.
 406    *
 407    * @return the offset into the backing array at which the buffer content
 408    *         starts
 409    * @throws ReadOnlyBufferException when this buffer is read only
 410    * @throws UnsupportedOperationException when this buffer does not provide
 411    *         a backing array
 412    *
 413    * @since 1.6
 414    */
 415   public abstract int arrayOffset();
 416
 417   /**
 418    * Returns <code>true</code> when this buffer is direct, <code>false</code>
 419    * otherwise. A direct buffer is usually backed by a raw memory area instead
 420    * of a Java array.
 421    *
 422    * @return <code>true</code> when this buffer is direct, <code>false</code>
 423    *         otherwise
 424    *
 425    * @since 1.6
 426    */
 427   public abstract boolean isDirect();
 428 }