GNU Classpath (0.98) | |
Frames | No Frames |
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: }
GNU Classpath (0.98) |