001 /* Buffer.java -- 002 Copyright (C) 2002, 2003, 2004 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 039 package java.nio; 040 041 import gnu.gcj.RawData; 042 043 /** 044 * @since 1.4 045 */ 046 public abstract class Buffer 047 { 048 int cap = 0; 049 int limit = 0; 050 int pos = 0; 051 int mark = -1; 052 RawData address; 053 054 /** 055 * Creates a new Buffer. 056 * 057 * Should be package private. 058 */ 059 Buffer (int capacity, int limit, int position, int mark) 060 { 061 if (capacity < 0) 062 throw new IllegalArgumentException (); 063 064 cap = capacity; 065 limit (limit); 066 position (position); 067 068 if (mark >= 0) 069 { 070 if (mark > pos) 071 throw new IllegalArgumentException (); 072 073 this.mark = mark; 074 } 075 } 076 077 /** 078 * Retrieves the capacity of the buffer. 079 * 080 * @return the capacity of the buffer 081 */ 082 public final int capacity () 083 { 084 return cap; 085 } 086 087 /** 088 * Clears the buffer. 089 * 090 * @return this buffer 091 */ 092 public final Buffer clear () 093 { 094 limit = cap; 095 pos = 0; 096 mark = -1; 097 return this; 098 } 099 100 /** 101 * Flips the buffer. 102 * 103 * @return this buffer 104 */ 105 public final Buffer flip () 106 { 107 limit = pos; 108 pos = 0; 109 mark = -1; 110 return this; 111 } 112 113 /** 114 * Tells whether the buffer has remaining data to read or not. 115 * 116 * @return true if the buffer contains remaining data to read, 117 * false otherwise 118 */ 119 public final boolean hasRemaining () 120 { 121 return remaining() > 0; 122 } 123 124 /** 125 * Tells whether this buffer is read only or not. 126 * 127 * @return true if the buffer is read only, false otherwise 128 */ 129 public abstract boolean isReadOnly (); 130 131 /** 132 * Retrieves the current limit of the buffer. 133 * 134 * @return the limit of the buffer 135 */ 136 public final int limit () 137 { 138 return limit; 139 } 140 141 /** 142 * Sets this buffer's limit. 143 * 144 * @param newLimit The new limit value; must be non-negative and no larger 145 * than this buffer's capacity. 146 * 147 * @return this buffer 148 * 149 * @exception IllegalArgumentException If the preconditions on newLimit 150 * do not hold. 151 */ 152 public final Buffer limit (int newLimit) 153 { 154 if ((newLimit < 0) || (newLimit > cap)) 155 throw new IllegalArgumentException (); 156 157 if (newLimit < mark) 158 mark = -1; 159 160 if (pos > newLimit) 161 pos = newLimit; 162 163 limit = newLimit; 164 return this; 165 } 166 167 /** 168 * Sets this buffer's mark at its position. 169 * 170 * @return this buffer 171 */ 172 public final Buffer mark () 173 { 174 mark = pos; 175 return this; 176 } 177 178 /** 179 * Retrieves the current position of this buffer. 180 * 181 * @return the current position of this buffer 182 */ 183 public final int position () 184 { 185 return pos; 186 } 187 188 /** 189 * Sets this buffer's position. If the mark is defined and larger than the 190 * new position then it is discarded. 191 * 192 * @param newPosition The new position value; must be non-negative and no 193 * larger than the current limit. 194 * 195 * @return this buffer 196 * 197 * @exception IllegalArgumentException If the preconditions on newPosition 198 * do not hold 199 */ 200 public final Buffer position (int newPosition) 201 { 202 if ((newPosition < 0) || (newPosition > limit)) 203 throw new IllegalArgumentException (); 204 205 if (newPosition <= mark) 206 mark = -1; 207 208 pos = newPosition; 209 return this; 210 } 211 212 /** 213 * Returns the number of elements between the current position and the limit. 214 * 215 * @return the number of remaining elements 216 */ 217 public final int remaining() 218 { 219 return limit - pos; 220 } 221 222 /** 223 * Resets this buffer's position to the previously-marked position. 224 * 225 * @return this buffer 226 * 227 * @exception InvalidMarkException If the mark has not been set. 228 */ 229 public final Buffer reset() 230 { 231 if (mark == -1) 232 throw new InvalidMarkException (); 233 234 pos = mark; 235 return this; 236 } 237 238 /** 239 * Rewinds this buffer. The position is set to zero and the mark 240 * is discarded. 241 * 242 * @return this buffer 243 */ 244 public final Buffer rewind() 245 { 246 pos = 0; 247 mark = -1; 248 return this; 249 } 250 251 /** 252 * Checks for underflow. This method is used internally to check 253 * whether a buffer has enough elements left to satisfy a read 254 * request. 255 * 256 * @exception BufferUnderflowException If there are no remaining 257 * elements in this buffer. 258 */ 259 final void checkForUnderflow() 260 { 261 if (!hasRemaining()) 262 throw new BufferUnderflowException(); 263 } 264 265 /** 266 * Checks for underflow. This method is used internally to check 267 * whether a buffer has enough elements left to satisfy a read 268 * request for a given number of elements. 269 * 270 * @param length The length of a sequence of elements. 271 * 272 * @exception BufferUnderflowException If there are not enough 273 * remaining elements in this buffer. 274 */ 275 final void checkForUnderflow(int length) 276 { 277 if (remaining() < length) 278 throw new BufferUnderflowException(); 279 } 280 281 /** 282 * Checks for overflow. This method is used internally to check 283 * whether a buffer has enough space left to satisfy a write 284 * request. 285 * 286 * @exception BufferOverflowException If there is no remaining 287 * space in this buffer. 288 */ 289 final void checkForOverflow() 290 { 291 if (!hasRemaining()) 292 throw new BufferOverflowException(); 293 } 294 295 /** 296 * Checks for overflow. This method is used internally to check 297 * whether a buffer has enough space left to satisfy a write 298 * request for a given number of elements. 299 * 300 * @param length The length of a sequence of elements. 301 * 302 * @exception BufferUnderflowException If there is not enough 303 * remaining space in this buffer. 304 */ 305 final void checkForOverflow(int length) 306 { 307 if (remaining() < length) 308 throw new BufferOverflowException(); 309 } 310 311 /** 312 * Checks if index is negative or not smaller than the buffer's 313 * limit. This method is used internally to check whether 314 * an indexed request can be fulfilled. 315 * 316 * @param index The requested position in the buffer. 317 * 318 * @exception IndexOutOfBoundsException If index is negative or not smaller 319 * than the buffer's limit. 320 */ 321 final void checkIndex(int index) 322 { 323 if (index < 0 324 || index >= limit ()) 325 throw new IndexOutOfBoundsException (); 326 } 327 328 /** 329 * Checks if buffer is read-only. This method is used internally to 330 * check if elements can be put into a buffer. 331 * 332 * @exception ReadOnlyBufferException If this buffer is read-only. 333 */ 334 final void checkIfReadOnly() 335 { 336 if (isReadOnly()) 337 throw new ReadOnlyBufferException (); 338 } 339 340 /** 341 * Checks whether an array is large enough to hold the given number of 342 * elements at the given offset. This method is used internally to 343 * check if an array is big enough. 344 * 345 * @param arraylength The length of the array. 346 * @param offset The offset within the array of the first byte to be read; 347 * must be non-negative and no larger than arraylength. 348 * @param length The number of bytes to be read from the given array; 349 * must be non-negative and no larger than arraylength - offset. 350 * 351 * @exception IndexOutOfBoundsException If the preconditions on the offset 352 * and length parameters do not hold 353 */ 354 static final void checkArraySize(int arraylength, int offset, int length) 355 { 356 if ((offset < 0) || 357 (length < 0) || 358 (arraylength < length + offset)) 359 throw new IndexOutOfBoundsException (); 360 } 361 }