1 /*
2 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.nio;
27
28 import java.util.Spliterator;
29
30 /**
31 * A container for data of a specific primitive type.
32 *
33 * <p> A buffer is a linear, finite sequence of elements of a specific
34 * primitive type. Aside from its content, the essential properties of a
35 * buffer are its capacity, limit, and position: </p>
36 *
37 * <blockquote>
38 *
39 * <p> A buffer's <i>capacity</i> is the number of elements it contains. The
40 * capacity of a buffer is never negative and never changes. </p>
41 *
42 * <p> A buffer's <i>limit</i> is the index of the first element that should
43 * not be read or written. A buffer's limit is never negative and is never
44 * greater than its capacity. </p>
45 *
46 * <p> A buffer's <i>position</i> is the index of the next element to be
47 * read or written. A buffer's position is never negative and is never
48 * greater than its limit. </p>
49 *
50 * </blockquote>
51 *
52 * <p> There is one subclass of this class for each non-boolean primitive type.
53 *
54 *
55 * <h2> Transferring data </h2>
56 *
57 * <p> Each subclass of this class defines two categories of <i>get</i> and
58 * <i>put</i> operations: </p>
59 *
60 * <blockquote>
61 *
62 * <p> <i>Relative</i> operations read or write one or more elements starting
63 * at the current position and then increment the position by the number of
64 * elements transferred. If the requested transfer exceeds the limit then a
65 * relative <i>get</i> operation throws a {@link BufferUnderflowException}
66 * and a relative <i>put</i> operation throws a {@link
67 * BufferOverflowException}; in either case, no data is transferred. </p>
68 *
69 * <p> <i>Absolute</i> operations take an explicit element index and do not
70 * affect the position. Absolute <i>get</i> and <i>put</i> operations throw
71 * an {@link IndexOutOfBoundsException} if the index argument exceeds the
72 * limit. </p>
73 *
74 * </blockquote>
75 *
76 * <p> Data may also, of course, be transferred in to or out of a buffer by the
77 * I/O operations of an appropriate channel, which are always relative to the
78 * current position.
79 *
80 *
81 * <h2> Marking and resetting </h2>
82 *
83 * <p> A buffer's <i>mark</i> is the index to which its position will be reset
84 * when the {@link #reset reset} method is invoked. The mark is not always
85 * defined, but when it is defined it is never negative and is never greater
86 * than the position. If the mark is defined then it is discarded when the
87 * position or the limit is adjusted to a value smaller than the mark. If the
88 * mark is not defined then invoking the {@link #reset reset} method causes an
89 * {@link InvalidMarkException} to be thrown.
90 *
91 *
92 * <h2> Invariants </h2>
93 *
94 * <p> The following invariant holds for the mark, position, limit, and
95 * capacity values:
96 *
97 * <blockquote>
98 * <tt>0</tt> <tt><=</tt>
99 * <i>mark</i> <tt><=</tt>
100 * <i>position</i> <tt><=</tt>
101 * <i>limit</i> <tt><=</tt>
102 * <i>capacity</i>
103 * </blockquote>
104 *
105 * <p> A newly-created buffer always has a position of zero and a mark that is
106 * undefined. The initial limit may be zero, or it may be some other value
107 * that depends upon the type of the buffer and the manner in which it is
108 * constructed. Each element of a newly-allocated buffer is initialized
109 * to zero.
110 *
111 *
112 * <h2> Clearing, flipping, and rewinding </h2>
113 *
114 * <p> In addition to methods for accessing the position, limit, and capacity
115 * values and for marking and resetting, this class also defines the following
116 * operations upon buffers:
117 *
118 * <ul>
119 *
120 * <li><p> {@link #clear} makes a buffer ready for a new sequence of
121 * channel-read or relative <i>put</i> operations: It sets the limit to the
122 * capacity and the position to zero. </p></li>
123 *
124 * <li><p> {@link #flip} makes a buffer ready for a new sequence of
125 * channel-write or relative <i>get</i> operations: It sets the limit to the
126 * current position and then sets the position to zero. </p></li>
127 *
128 * <li><p> {@link #rewind} makes a buffer ready for re-reading the data that
129 * it already contains: It leaves the limit unchanged and sets the position
130 * to zero. </p></li>
131 *
132 * </ul>
133 *
134 *
135 * <h2> Read-only buffers </h2>
136 *
137 * <p> Every buffer is readable, but not every buffer is writable. The
138 * mutation methods of each buffer class are specified as <i>optional
139 * operations</i> that will throw a {@link ReadOnlyBufferException} when
140 * invoked upon a read-only buffer. A read-only buffer does not allow its
141 * content to be changed, but its mark, position, and limit values are mutable.
142 * Whether or not a buffer is read-only may be determined by invoking its
143 * {@link #isReadOnly isReadOnly} method.
144 *
145 *
146 * <h2> Thread safety </h2>
147 *
148 * <p> Buffers are not safe for use by multiple concurrent threads. If a
149 * buffer is to be used by more than one thread then access to the buffer
150 * should be controlled by appropriate synchronization.
151 *
152 *
153 * <h2> Invocation chaining </h2>
154 *
155 * <p> Methods in this class that do not otherwise have a value to return are
156 * specified to return the buffer upon which they are invoked. This allows
157 * method invocations to be chained; for example, the sequence of statements
158 *
159 * <blockquote><pre>
160 * b.flip();
161 * b.position(23);
162 * b.limit(42);</pre></blockquote>
163 *
164 * can be replaced by the single, more compact statement
165 *
166 * <blockquote><pre>
167 * b.flip().position(23).limit(42);</pre></blockquote>
168 *
169 *
170 * @author Mark Reinhold
171 * @author JSR-51 Expert Group
172 * @since 1.4
173 */
174
175 public abstract class Buffer {
176
177 /**
178 * The characteristics of Spliterators that traverse and split elements
179 * maintained in Buffers.
180 */
181 static final int SPLITERATOR_CHARACTERISTICS =
182 Spliterator.SIZED | Spliterator.SUBSIZED | Spliterator.ORDERED;
183
184 // Invariants: mark <= position <= limit <= capacity
185 private int mark = -1;
186 private int position = 0;
187 private int limit;
188 private int capacity;
189
190 // Used only by direct buffers
191 // NOTE: hoisted here for speed in JNI GetDirectBufferAddress
192 long address;
193
194 // Creates a new buffer with the given mark, position, limit, and capacity,
195 // after checking invariants.
196 //
197 Buffer(int mark, int pos, int lim, int cap) { // package-private
198 if (cap < 0)
199 throw new IllegalArgumentException("Negative capacity: " + cap);
200 this.capacity = cap;
201 limit(lim);
202 position(pos);
203 if (mark >= 0) {
204 if (mark > pos)
205 throw new IllegalArgumentException("mark > position: ("
206 + mark + " > " + pos + ")");
207 this.mark = mark;
208 }
209 }
210
211 /**
212 * Returns this buffer's capacity.
213 *
214 * @return The capacity of this buffer
215 */
216 public final int capacity() {
217 return capacity;
218 }
219
220 /**
221 * Returns this buffer's position.
222 *
223 * @return The position of this buffer
224 */
225 public final int position() {
226 return position;
227 }
228
229 /**
230 * Sets this buffer's position. If the mark is defined and larger than the
231 * new position then it is discarded.
232 *
233 * @param newPosition
234 * The new position value; must be non-negative
235 * and no larger than the current limit
236 *
237 * @return This buffer
238 *
239 * @throws IllegalArgumentException
240 * If the preconditions on <tt>newPosition</tt> do not hold
241 */
242 public Buffer position(int newPosition) {
243 if ((newPosition > limit) || (newPosition < 0))
244 throw new IllegalArgumentException();
245 position = newPosition;
246 if (mark > position) mark = -1;
247 return this;
248 }
249
250 /**
251 * Returns this buffer's limit.
252 *
253 * @return The limit of this buffer
254 */
255 public final int limit() {
256 return limit;
257 }
258
259 /**
260 * Sets this buffer's limit. If the position is larger than the new limit
261 * then it is set to the new limit. If the mark is defined and larger than
262 * the new limit then it is discarded.
263 *
264 * @param newLimit
265 * The new limit value; must be non-negative
266 * and no larger than this buffer's capacity
267 *
268 * @return This buffer
269 *
270 * @throws IllegalArgumentException
271 * If the preconditions on <tt>newLimit</tt> do not hold
272 */
273 public Buffer limit(int newLimit) {
274 if ((newLimit > capacity) || (newLimit < 0))
275 throw new IllegalArgumentException();
276 limit = newLimit;
277 if (position > limit) position = limit;
278 if (mark > limit) mark = -1;
279 return this;
280 }
281
282 /**
283 * Sets this buffer's mark at its position.
284 *
285 * @return This buffer
286 */
287 public Buffer mark() {
288 mark = position;
289 return this;
290 }
291
292 /**
293 * Resets this buffer's position to the previously-marked position.
294 *
295 * <p> Invoking this method neither changes nor discards the mark's
296 * value. </p>
297 *
298 * @return This buffer
299 *
300 * @throws InvalidMarkException
301 * If the mark has not been set
302 */
303 public Buffer reset() {
304 int m = mark;
305 if (m < 0)
306 throw new InvalidMarkException();
307 position = m;
308 return this;
309 }
310
311 /**
312 * Clears this buffer. The position is set to zero, the limit is set to
313 * the capacity, and the mark is discarded.
314 *
315 * <p> Invoke this method before using a sequence of channel-read or
316 * <i>put</i> operations to fill this buffer. For example:
317 *
318 * <blockquote><pre>
319 * buf.clear(); // Prepare buffer for reading
320 * in.read(buf); // Read data</pre></blockquote>
321 *
322 * <p> This method does not actually erase the data in the buffer, but it
323 * is named as if it did because it will most often be used in situations
324 * in which that might as well be the case. </p>
325 *
326 * @return This buffer
327 */
328 public Buffer clear() {
329 position = 0;
330 limit = capacity;
331 mark = -1;
332 return this;
333 }
334
335 /**
336 * Flips this buffer. The limit is set to the current position and then
337 * the position is set to zero. If the mark is defined then it is
338 * discarded.
339 *
340 * <p> After a sequence of channel-read or <i>put</i> operations, invoke
341 * this method to prepare for a sequence of channel-write or relative
342 * <i>get</i> operations. For example:
343 *
344 * <blockquote><pre>
345 * buf.put(magic); // Prepend header
346 * in.read(buf); // Read data into rest of buffer
347 * buf.flip(); // Flip buffer
348 * out.write(buf); // Write header + data to channel</pre></blockquote>
349 *
350 * <p> This method is often used in conjunction with the {@link
351 * java.nio.ByteBuffer#compact compact} method when transferring data from
352 * one place to another. </p>
353 *
354 * @return This buffer
355 */
356 public Buffer flip() {
357 limit = position;
358 position = 0;
359 mark = -1;
360 return this;
361 }
362
363 /**
364 * Rewinds this buffer. The position is set to zero and the mark is
365 * discarded.
366 *
367 * <p> Invoke this method before a sequence of channel-write or <i>get</i>
368 * operations, assuming that the limit has already been set
369 * appropriately. For example:
370 *
371 * <blockquote><pre>
372 * out.write(buf); // Write remaining data
373 * buf.rewind(); // Rewind buffer
374 * buf.get(array); // Copy data into array</pre></blockquote>
375 *
376 * @return This buffer
377 */
378 public Buffer rewind() {
379 position = 0;
380 mark = -1;
381 return this;
382 }
383
384 /**
385 * Returns the number of elements between the current position and the
386 * limit.
387 *
388 * @return The number of elements remaining in this buffer
389 */
390 public final int remaining() {
391 return limit - position;
392 }
393
394 /**
395 * Tells whether there are any elements between the current position and
396 * the limit.
397 *
398 * @return <tt>true</tt> if, and only if, there is at least one element
399 * remaining in this buffer
400 */
401 public final boolean hasRemaining() {
402 return position < limit;
403 }
404
405 /**
406 * Tells whether or not this buffer is read-only.
407 *
408 * @return <tt>true</tt> if, and only if, this buffer is read-only
409 */
410 public abstract boolean isReadOnly();
411
412 /**
413 * Tells whether or not this buffer is backed by an accessible
414 * array.
415 *
416 * <p> If this method returns <tt>true</tt> then the {@link #array() array}
417 * and {@link #arrayOffset() arrayOffset} methods may safely be invoked.
418 * </p>
419 *
420 * @return <tt>true</tt> if, and only if, this buffer
421 * is backed by an array and is not read-only
422 *
423 * @since 1.6
424 */
425 public abstract boolean hasArray();
426
427 /**
428 * Returns the array that backs this
429 * buffer <i>(optional operation)</i>.
430 *
431 * <p> This method is intended to allow array-backed buffers to be
432 * passed to native code more efficiently. Concrete subclasses
433 * provide more strongly-typed return values for this method.
434 *
435 * <p> Modifications to this buffer's content will cause the returned
436 * array's content to be modified, and vice versa.
437 *
438 * <p> Invoke the {@link #hasArray hasArray} method before invoking this
439 * method in order to ensure that this buffer has an accessible backing
440 * array. </p>
441 *
442 * @return The array that backs this buffer
443 *
444 * @throws ReadOnlyBufferException
445 * If this buffer is backed by an array but is read-only
446 *
447 * @throws UnsupportedOperationException
448 * If this buffer is not backed by an accessible array
449 *
450 * @since 1.6
451 */
452 public abstract Object array();
453
454 /**
455 * Returns the offset within this buffer's backing array of the first
456 * element of the buffer <i>(optional operation)</i>.
457 *
458 * <p> If this buffer is backed by an array then buffer position <i>p</i>
459 * corresponds to array index <i>p</i> + <tt>arrayOffset()</tt>.
460 *
461 * <p> Invoke the {@link #hasArray hasArray} method before invoking this
462 * method in order to ensure that this buffer has an accessible backing
463 * array. </p>
464 *
465 * @return The offset within this buffer's array
466 * of the first element of the buffer
467 *
468 * @throws ReadOnlyBufferException
469 * If this buffer is backed by an array but is read-only
470 *
471 * @throws UnsupportedOperationException
472 * If this buffer is not backed by an accessible array
473 *
474 * @since 1.6
475 */
476 public abstract int arrayOffset();
477
478 /**
479 * Tells whether or not this buffer is
480 * <a href="ByteBuffer.html#direct"><i>direct</i></a>.
481 *
482 * @return <tt>true</tt> if, and only if, this buffer is direct
483 *
484 * @since 1.6
485 */
486 public abstract boolean isDirect();
487
488
489 // -- Package-private methods for bounds checking, etc. --
490
491 /**
492 * Checks the current position against the limit, throwing a {@link
493 * BufferUnderflowException} if it is not smaller than the limit, and then
494 * increments the position.
495 *
496 * @return The current position value, before it is incremented
497 */
498 final int nextGetIndex() { // package-private
499 if (position >= limit)
500 throw new BufferUnderflowException();
501 return position++;
502 }
503
504 final int nextGetIndex(int nb) { // package-private
505 if (limit - position < nb)
506 throw new BufferUnderflowException();
507 int p = position;
508 position += nb;
509 return p;
510 }
511
512 /**
513 * Checks the current position against the limit, throwing a {@link
514 * BufferOverflowException} if it is not smaller than the limit, and then
515 * increments the position.
516 *
517 * @return The current position value, before it is incremented
518 */
519 final int nextPutIndex() { // package-private
520 if (position >= limit)
521 throw new BufferOverflowException();
522 return position++;
523 }
524
525 final int nextPutIndex(int nb) { // package-private
526 if (limit - position < nb)
527 throw new BufferOverflowException();
528 int p = position;
529 position += nb;
530 return p;
531 }
532
533 /**
534 * Checks the given index against the limit, throwing an {@link
535 * IndexOutOfBoundsException} if it is not smaller than the limit
536 * or is smaller than zero.
537 */
538 final int checkIndex(int i) { // package-private
539 if ((i < 0) || (i >= limit))
540 throw new IndexOutOfBoundsException();
541 return i;
542 }
543
544 final int checkIndex(int i, int nb) { // package-private
545 if ((i < 0) || (nb > limit - i))
546 throw new IndexOutOfBoundsException();
547 return i;
548 }
549
550 final int markValue() { // package-private
551 return mark;
552 }
553
554 final void truncate() { // package-private
555 mark = -1;
556 position = 0;
557 limit = 0;
558 capacity = 0;
559 }
560
561 final void discardMark() { // package-private
562 mark = -1;
563 }
564
565 static void checkBounds(int off, int len, int size) { // package-private
566 if ((off | len | (off + len) | (size - (off + len))) < 0)
567 throw new IndexOutOfBoundsException();
568 }
569
570 }