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 }