Source for java.nio.Buffer

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