1 /*
2 * Copyright 2012 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty.buffer;
17
18 import io.netty.util.ByteProcessor;
19 import io.netty.util.ReferenceCounted;
20
21 import java.io.IOException;
22 import java.io.InputStream;
23 import java.io.OutputStream;
24 import java.nio.ByteBuffer;
25 import java.nio.ByteOrder;
26 import java.nio.channels.FileChannel;
27 import java.nio.channels.GatheringByteChannel;
28 import java.nio.channels.ScatteringByteChannel;
29 import java.nio.charset.Charset;
30 import java.nio.charset.UnsupportedCharsetException;
31
32 /**
33 * A random and sequential accessible sequence of zero or more bytes (octets).
34 * This interface provides an abstract view for one or more primitive byte
35 * arrays ({@code byte[]}) and {@linkplain ByteBuffer NIO buffers}.
36 *
37 * <h3>Creation of a buffer</h3>
38 *
39 * It is recommended to create a new buffer using the helper methods in
40 * {@link Unpooled} rather than calling an individual implementation's
41 * constructor.
42 *
43 * <h3>Random Access Indexing</h3>
44 *
45 * Just like an ordinary primitive byte array, {@link ByteBuf} uses
46 * <a href="https://en.wikipedia.org/wiki/Zero-based_numbering">zero-based indexing</a>.
47 * It means the index of the first byte is always {@code 0} and the index of the last byte is
48 * always {@link #capacity() capacity - 1}. For example, to iterate all bytes of a buffer, you
49 * can do the following, regardless of its internal implementation:
50 *
51 * <pre>
52 * {@link ByteBuf} buffer = ...;
53 * for (int i = 0; i < buffer.capacity(); i ++) {
54 * byte b = buffer.getByte(i);
55 * System.out.println((char) b);
56 * }
57 * </pre>
58 *
59 * <h3>Sequential Access Indexing</h3>
60 *
61 * {@link ByteBuf} provides two pointer variables to support sequential
62 * read and write operations - {@link #readerIndex() readerIndex} for a read
63 * operation and {@link #writerIndex() writerIndex} for a write operation
64 * respectively. The following diagram shows how a buffer is segmented into
65 * three areas by the two pointers:
66 *
67 * <pre>
68 * +-------------------+------------------+------------------+
69 * | discardable bytes | readable bytes | writable bytes |
70 * | | (CONTENT) | |
71 * +-------------------+------------------+------------------+
72 * | | | |
73 * 0 <= readerIndex <= writerIndex <= capacity
74 * </pre>
75 *
76 * <h4>Readable bytes (the actual content)</h4>
77 *
78 * This segment is where the actual data is stored. Any operation whose name
79 * starts with {@code read} or {@code skip} will get or skip the data at the
80 * current {@link #readerIndex() readerIndex} and increase it by the number of
81 * read bytes. If the argument of the read operation is also a
82 * {@link ByteBuf} and no destination index is specified, the specified
83 * buffer's {@link #writerIndex() writerIndex} is increased together.
84 * <p>
85 * If there's not enough content left, {@link IndexOutOfBoundsException} is
86 * raised. The default value of newly allocated, wrapped or copied buffer's
87 * {@link #readerIndex() readerIndex} is {@code 0}.
88 *
89 * <pre>
90 * // Iterates the readable bytes of a buffer.
91 * {@link ByteBuf} buffer = ...;
92 * while (buffer.isReadable()) {
93 * System.out.println(buffer.readByte());
94 * }
95 * </pre>
96 *
97 * <h4>Writable bytes</h4>
98 *
99 * This segment is an undefined space which needs to be filled. Any operation
100 * whose name starts with {@code write} will write the data at the current
101 * {@link #writerIndex() writerIndex} and increase it by the number of written
102 * bytes. If the argument of the write operation is also a {@link ByteBuf},
103 * and no source index is specified, the specified buffer's
104 * {@link #readerIndex() readerIndex} is increased together.
105 * <p>
106 * If there's not enough writable bytes left, {@link IndexOutOfBoundsException}
107 * is raised. The default value of newly allocated buffer's
108 * {@link #writerIndex() writerIndex} is {@code 0}. The default value of
109 * wrapped or copied buffer's {@link #writerIndex() writerIndex} is the
110 * {@link #capacity() capacity} of the buffer.
111 *
112 * <pre>
113 * // Fills the writable bytes of a buffer with random integers.
114 * {@link ByteBuf} buffer = ...;
115 * while (buffer.maxWritableBytes() >= 4) {
116 * buffer.writeInt(random.nextInt());
117 * }
118 * </pre>
119 *
120 * <h4>Discardable bytes</h4>
121 *
122 * This segment contains the bytes which were read already by a read operation.
123 * Initially, the size of this segment is {@code 0}, but its size increases up
124 * to the {@link #writerIndex() writerIndex} as read operations are executed.
125 * The read bytes can be discarded by calling {@link #discardReadBytes()} to
126 * reclaim unused area as depicted by the following diagram:
127 *
128 * <pre>
129 * BEFORE discardReadBytes()
130 *
131 * +-------------------+------------------+------------------+
132 * | discardable bytes | readable bytes | writable bytes |
133 * +-------------------+------------------+------------------+
134 * | | | |
135 * 0 <= readerIndex <= writerIndex <= capacity
136 *
137 *
138 * AFTER discardReadBytes()
139 *
140 * +------------------+--------------------------------------+
141 * | readable bytes | writable bytes (got more space) |
142 * +------------------+--------------------------------------+
143 * | | |
144 * readerIndex (0) <= writerIndex (decreased) <= capacity
145 * </pre>
146 *
147 * Please note that there is no guarantee about the content of writable bytes
148 * after calling {@link #discardReadBytes()}. The writable bytes will not be
149 * moved in most cases and could even be filled with completely different data
150 * depending on the underlying buffer implementation.
151 *
152 * <h4>Clearing the buffer indexes</h4>
153 *
154 * You can set both {@link #readerIndex() readerIndex} and
155 * {@link #writerIndex() writerIndex} to {@code 0} by calling {@link #clear()}.
156 * It does not clear the buffer content (e.g. filling with {@code 0}) but just
157 * clears the two pointers. Please also note that the semantic of this
158 * operation is different from {@link ByteBuffer#clear()}.
159 *
160 * <pre>
161 * BEFORE clear()
162 *
163 * +-------------------+------------------+------------------+
164 * | discardable bytes | readable bytes | writable bytes |
165 * +-------------------+------------------+------------------+
166 * | | | |
167 * 0 <= readerIndex <= writerIndex <= capacity
168 *
169 *
170 * AFTER clear()
171 *
172 * +---------------------------------------------------------+
173 * | writable bytes (got more space) |
174 * +---------------------------------------------------------+
175 * | |
176 * 0 = readerIndex = writerIndex <= capacity
177 * </pre>
178 *
179 * <h3>Search operations</h3>
180 *
181 * For simple single-byte searches, use {@link #indexOf(int, int, byte)} and {@link #bytesBefore(int, int, byte)}.
182 * {@link #bytesBefore(byte)} is especially useful when you deal with a {@code NUL}-terminated string.
183 * For complicated searches, use {@link #forEachByte(int, int, ByteProcessor)} with a {@link ByteProcessor}
184 * implementation.
185 *
186 * <h3>Mark and reset</h3>
187 *
188 * There are two marker indexes in every buffer. One is for storing
189 * {@link #readerIndex() readerIndex} and the other is for storing
190 * {@link #writerIndex() writerIndex}. You can always reposition one of the
191 * two indexes by calling a reset method. It works in a similar fashion to
192 * the mark and reset methods in {@link InputStream} except that there's no
193 * {@code readlimit}.
194 *
195 * <h3>Derived buffers</h3>
196 *
197 * You can create a view of an existing buffer by calling one of the following methods:
198 * <ul>
199 * <li>{@link #duplicate()}</li>
200 * <li>{@link #slice()}</li>
201 * <li>{@link #slice(int, int)}</li>
202 * <li>{@link #readSlice(int)}</li>
203 * <li>{@link #retainedDuplicate()}</li>
204 * <li>{@link #retainedSlice()}</li>
205 * <li>{@link #retainedSlice(int, int)}</li>
206 * <li>{@link #readRetainedSlice(int)}</li>
207 * </ul>
208 * A derived buffer will have an independent {@link #readerIndex() readerIndex},
209 * {@link #writerIndex() writerIndex} and marker indexes, while it shares
210 * other internal data representation, just like a NIO buffer does.
211 * <p>
212 * In case a completely fresh copy of an existing buffer is required, please
213 * call {@link #copy()} method instead.
214 *
215 * <h4>Non-retained and retained derived buffers</h4>
216 *
217 * Note that the {@link #duplicate()}, {@link #slice()}, {@link #slice(int, int)} and {@link #readSlice(int)} does NOT
218 * call {@link #retain()} on the returned derived buffer, and thus its reference count will NOT be increased. If you
219 * need to create a derived buffer with increased reference count, consider using {@link #retainedDuplicate()},
220 * {@link #retainedSlice()}, {@link #retainedSlice(int, int)} and {@link #readRetainedSlice(int)} which may return
221 * a buffer implementation that produces less garbage.
222 *
223 * <h3>Conversion to existing JDK types</h3>
224 *
225 * <h4>Byte array</h4>
226 *
227 * If a {@link ByteBuf} is backed by a byte array (i.e. {@code byte[]}),
228 * you can access it directly via the {@link #array()} method. To determine
229 * if a buffer is backed by a byte array, {@link #hasArray()} should be used.
230 *
231 * <h4>NIO Buffers</h4>
232 *
233 * If a {@link ByteBuf} can be converted into an NIO {@link ByteBuffer} which shares its
234 * content (i.e. view buffer), you can get it via the {@link #nioBuffer()} method. To determine
235 * if a buffer can be converted into an NIO buffer, use {@link #nioBufferCount()}.
236 *
237 * <h4>Strings</h4>
238 *
239 * Various {@link #toString(Charset)} methods convert a {@link ByteBuf}
240 * into a {@link String}. Please note that {@link #toString()} is not a
241 * conversion method.
242 *
243 * <h4>I/O Streams</h4>
244 *
245 * Please refer to {@link ByteBufInputStream} and
246 * {@link ByteBufOutputStream}.
247 */
248 public abstract class ByteBuf implements ReferenceCounted, Comparable<ByteBuf>, ByteBufConvertible {
249
250 /**
251 * Returns the number of bytes (octets) this buffer can contain.
252 */
253 public abstract int capacity();
254
255 /**
256 * Adjusts the capacity of this buffer. If the {@code newCapacity} is less than the current
257 * capacity, the content of this buffer is truncated. If the {@code newCapacity} is greater
258 * than the current capacity, the buffer is appended with unspecified data whose length is
259 * {@code (newCapacity - currentCapacity)}.
260 *
261 * @throws IllegalArgumentException if the {@code newCapacity} is greater than {@link #maxCapacity()}
262 */
263 public abstract ByteBuf capacity(int newCapacity);
264
265 /**
266 * Returns the maximum allowed capacity of this buffer. This value provides an upper
267 * bound on {@link #capacity()}.
268 */
269 public abstract int maxCapacity();
270
271 /**
272 * Returns the {@link ByteBufAllocator} which created this buffer.
273 */
274 public abstract ByteBufAllocator alloc();
275
276 /**
277 * Returns the <a href="https://en.wikipedia.org/wiki/Endianness">endianness</a>
278 * of this buffer.
279 *
280 * @deprecated use the Little Endian accessors, e.g. {@code getShortLE}, {@code getIntLE}
281 * instead of creating a buffer with swapped {@code endianness}.
282 */
283 @Deprecated
284 public abstract ByteOrder order();
285
286 /**
287 * Returns a buffer with the specified {@code endianness} which shares the whole region,
288 * indexes, and marks of this buffer. Modifying the content, the indexes, or the marks of the
289 * returned buffer or this buffer affects each other's content, indexes, and marks. If the
290 * specified {@code endianness} is identical to this buffer's byte order, this method can
291 * return {@code this}. This method does not modify {@code readerIndex} or {@code writerIndex}
292 * of this buffer.
293 *
294 * @deprecated use the Little Endian accessors, e.g. {@code getShortLE}, {@code getIntLE}
295 * instead of creating a buffer with swapped {@code endianness}.
296 */
297 @Deprecated
298 public abstract ByteBuf order(ByteOrder endianness);
299
300 /**
301 * Return the underlying buffer instance if this buffer is a wrapper of another buffer.
302 *
303 * @return {@code null} if this buffer is not a wrapper
304 */
305 public abstract ByteBuf unwrap();
306
307 /**
308 * Returns {@code true} if and only if this buffer is backed by an
309 * NIO direct buffer.
310 */
311 public abstract boolean isDirect();
312
313 /**
314 * Returns {@code true} if and only if this buffer is read-only.
315 */
316 public abstract boolean isReadOnly();
317
318 /**
319 * Returns a read-only version of this buffer.
320 */
321 public abstract ByteBuf asReadOnly();
322
323 /**
324 * Returns the {@code readerIndex} of this buffer.
325 */
326 public abstract int readerIndex();
327
328 /**
329 * Sets the {@code readerIndex} of this buffer.
330 *
331 * @throws IndexOutOfBoundsException
332 * if the specified {@code readerIndex} is
333 * less than {@code 0} or
334 * greater than {@code this.writerIndex}
335 */
336 public abstract ByteBuf readerIndex(int readerIndex);
337
338 /**
339 * Returns the {@code writerIndex} of this buffer.
340 */
341 public abstract int writerIndex();
342
343 /**
344 * Sets the {@code writerIndex} of this buffer.
345 *
346 * @throws IndexOutOfBoundsException
347 * if the specified {@code writerIndex} is
348 * less than {@code this.readerIndex} or
349 * greater than {@code this.capacity}
350 */
351 public abstract ByteBuf writerIndex(int writerIndex);
352
353 /**
354 * Sets the {@code readerIndex} and {@code writerIndex} of this buffer
355 * in one shot. This method is useful when you have to worry about the
356 * invocation order of {@link #readerIndex(int)} and {@link #writerIndex(int)}
357 * methods. For example, the following code will fail:
358 *
359 * <pre>
360 * // Create a buffer whose readerIndex, writerIndex and capacity are
361 * // 0, 0 and 8 respectively.
362 * {@link ByteBuf} buf = {@link Unpooled}.buffer(8);
363 *
364 * // IndexOutOfBoundsException is thrown because the specified
365 * // readerIndex (2) cannot be greater than the current writerIndex (0).
366 * buf.readerIndex(2);
367 * buf.writerIndex(4);
368 * </pre>
369 *
370 * The following code will also fail:
371 *
372 * <pre>
373 * // Create a buffer whose readerIndex, writerIndex and capacity are
374 * // 0, 8 and 8 respectively.
375 * {@link ByteBuf} buf = {@link Unpooled}.wrappedBuffer(new byte[8]);
376 *
377 * // readerIndex becomes 8.
378 * buf.readLong();
379 *
380 * // IndexOutOfBoundsException is thrown because the specified
381 * // writerIndex (4) cannot be less than the current readerIndex (8).
382 * buf.writerIndex(4);
383 * buf.readerIndex(2);
384 * </pre>
385 *
386 * By contrast, this method guarantees that it never
387 * throws an {@link IndexOutOfBoundsException} as long as the specified
388 * indexes meet basic constraints, regardless what the current index
389 * values of the buffer are:
390 *
391 * <pre>
392 * // No matter what the current state of the buffer is, the following
393 * // call always succeeds as long as the capacity of the buffer is not
394 * // less than 4.
395 * buf.setIndex(2, 4);
396 * </pre>
397 *
398 * @throws IndexOutOfBoundsException
399 * if the specified {@code readerIndex} is less than 0,
400 * if the specified {@code writerIndex} is less than the specified
401 * {@code readerIndex} or if the specified {@code writerIndex} is
402 * greater than {@code this.capacity}
403 */
404 public abstract ByteBuf setIndex(int readerIndex, int writerIndex);
405
406 /**
407 * Returns the number of readable bytes which is equal to
408 * {@code (this.writerIndex - this.readerIndex)}.
409 */
410 public abstract int readableBytes();
411
412 /**
413 * Returns the number of writable bytes which is equal to
414 * {@code (this.capacity - this.writerIndex)}.
415 */
416 public abstract int writableBytes();
417
418 /**
419 * Returns the maximum possible number of writable bytes, which is equal to
420 * {@code (this.maxCapacity - this.writerIndex)}.
421 */
422 public abstract int maxWritableBytes();
423
424 /**
425 * Returns the maximum number of bytes which can be written for certain without involving
426 * an internal reallocation or data-copy. The returned value will be ≥ {@link #writableBytes()}
427 * and ≤ {@link #maxWritableBytes()}.
428 */
429 public int maxFastWritableBytes() {
430 return writableBytes();
431 }
432
433 /**
434 * Returns {@code true}
435 * if and only if {@code (this.writerIndex - this.readerIndex)} is greater
436 * than {@code 0}.
437 */
438 public abstract boolean isReadable();
439
440 /**
441 * Returns {@code true} if and only if this buffer contains equal to or more than the specified number of elements.
442 */
443 public abstract boolean isReadable(int size);
444
445 /**
446 * Returns {@code true}
447 * if and only if {@code (this.capacity - this.writerIndex)} is greater
448 * than {@code 0}.
449 */
450 public abstract boolean isWritable();
451
452 /**
453 * Returns {@code true} if and only if this buffer has enough room to allow writing the specified number of
454 * elements.
455 */
456 public abstract boolean isWritable(int size);
457
458 /**
459 * Sets the {@code readerIndex} and {@code writerIndex} of this buffer to
460 * {@code 0}.
461 * This method is identical to {@link #setIndex(int, int) setIndex(0, 0)}.
462 * <p>
463 * Please note that the behavior of this method is different
464 * from that of NIO buffer, which sets the {@code limit} to
465 * the {@code capacity} of the buffer.
466 */
467 public abstract ByteBuf clear();
468
469 /**
470 * Marks the current {@code readerIndex} in this buffer. You can
471 * reposition the current {@code readerIndex} to the marked
472 * {@code readerIndex} by calling {@link #resetReaderIndex()}.
473 * The initial value of the marked {@code readerIndex} is {@code 0}.
474 */
475 public abstract ByteBuf markReaderIndex();
476
477 /**
478 * Repositions the current {@code readerIndex} to the marked
479 * {@code readerIndex} in this buffer.
480 *
481 * @throws IndexOutOfBoundsException
482 * if the current {@code writerIndex} is less than the marked
483 * {@code readerIndex}
484 */
485 public abstract ByteBuf resetReaderIndex();
486
487 /**
488 * Marks the current {@code writerIndex} in this buffer. You can
489 * reposition the current {@code writerIndex} to the marked
490 * {@code writerIndex} by calling {@link #resetWriterIndex()}.
491 * The initial value of the marked {@code writerIndex} is {@code 0}.
492 */
493 public abstract ByteBuf markWriterIndex();
494
495 /**
496 * Repositions the current {@code writerIndex} to the marked
497 * {@code writerIndex} in this buffer.
498 *
499 * @throws IndexOutOfBoundsException
500 * if the current {@code readerIndex} is greater than the marked
501 * {@code writerIndex}
502 */
503 public abstract ByteBuf resetWriterIndex();
504
505 /**
506 * Discards the bytes between the 0th index and {@code readerIndex}.
507 * It moves the bytes between {@code readerIndex} and {@code writerIndex}
508 * to the 0th index, and sets {@code readerIndex} and {@code writerIndex}
509 * to {@code 0} and {@code oldWriterIndex - oldReaderIndex} respectively.
510 * <p>
511 * Please refer to the class documentation for more detailed explanation.
512 */
513 public abstract ByteBuf discardReadBytes();
514
515 /**
516 * Similar to {@link ByteBuf#discardReadBytes()} except that this method might discard
517 * some, all, or none of read bytes depending on its internal implementation to reduce
518 * overall memory bandwidth consumption at the cost of potentially additional memory
519 * consumption.
520 */
521 public abstract ByteBuf discardSomeReadBytes();
522
523 /**
524 * Expands the buffer {@link #capacity()} to make sure the number of
525 * {@linkplain #writableBytes() writable bytes} is equal to or greater than the
526 * specified value. If there are enough writable bytes in this buffer, this method
527 * returns with no side effect.
528 *
529 * @param minWritableBytes
530 * the expected minimum number of writable bytes
531 * @throws IndexOutOfBoundsException
532 * if {@link #writerIndex()} + {@code minWritableBytes} > {@link #maxCapacity()}.
533 * @see #capacity(int)
534 */
535 public abstract ByteBuf ensureWritable(int minWritableBytes);
536
537 /**
538 * Expands the buffer {@link #capacity()} to make sure the number of
539 * {@linkplain #writableBytes() writable bytes} is equal to or greater than the
540 * specified value. Unlike {@link #ensureWritable(int)}, this method returns a status code.
541 *
542 * @param minWritableBytes
543 * the expected minimum number of writable bytes
544 * @param force
545 * When {@link #writerIndex()} + {@code minWritableBytes} > {@link #maxCapacity()}:
546 * <ul>
547 * <li>{@code true} - the capacity of the buffer is expanded to {@link #maxCapacity()}</li>
548 * <li>{@code false} - the capacity of the buffer is unchanged</li>
549 * </ul>
550 * @return {@code 0} if the buffer has enough writable bytes, and its capacity is unchanged.
551 * {@code 1} if the buffer does not have enough bytes, and its capacity is unchanged.
552 * {@code 2} if the buffer has enough writable bytes, and its capacity has been increased.
553 * {@code 3} if the buffer does not have enough bytes, but its capacity has been
554 * increased to its maximum.
555 */
556 public abstract int ensureWritable(int minWritableBytes, boolean force);
557
558 /**
559 * Gets a boolean at the specified absolute (@code index) in this buffer.
560 * This method does not modify the {@code readerIndex} or {@code writerIndex}
561 * of this buffer.
562 *
563 * @throws IndexOutOfBoundsException
564 * if the specified {@code index} is less than {@code 0} or
565 * {@code index + 1} is greater than {@code this.capacity}
566 */
567 public abstract boolean getBoolean(int index);
568
569 /**
570 * Gets a byte at the specified absolute {@code index} in this buffer.
571 * This method does not modify {@code readerIndex} or {@code writerIndex} of
572 * this buffer.
573 *
574 * @throws IndexOutOfBoundsException
575 * if the specified {@code index} is less than {@code 0} or
576 * {@code index + 1} is greater than {@code this.capacity}
577 */
578 public abstract byte getByte(int index);
579
580 /**
581 * Gets an unsigned byte at the specified absolute {@code index} in this
582 * buffer. This method does not modify {@code readerIndex} or
583 * {@code writerIndex} of this buffer.
584 *
585 * @throws IndexOutOfBoundsException
586 * if the specified {@code index} is less than {@code 0} or
587 * {@code index + 1} is greater than {@code this.capacity}
588 */
589 public abstract short getUnsignedByte(int index);
590
591 /**
592 * Gets a 16-bit short integer at the specified absolute {@code index} in
593 * this buffer. This method does not modify {@code readerIndex} or
594 * {@code writerIndex} of this buffer.
595 *
596 * @throws IndexOutOfBoundsException
597 * if the specified {@code index} is less than {@code 0} or
598 * {@code index + 2} is greater than {@code this.capacity}
599 */
600 public abstract short getShort(int index);
601
602 /**
603 * Gets a 16-bit short integer at the specified absolute {@code index} in
604 * this buffer in Little Endian Byte Order. This method does not modify
605 * {@code readerIndex} or {@code writerIndex} of this buffer.
606 *
607 * @throws IndexOutOfBoundsException
608 * if the specified {@code index} is less than {@code 0} or
609 * {@code index + 2} is greater than {@code this.capacity}
610 */
611 public abstract short getShortLE(int index);
612
613 /**
614 * Gets an unsigned 16-bit short integer at the specified absolute
615 * {@code index} in this buffer. This method does not modify
616 * {@code readerIndex} or {@code writerIndex} of this buffer.
617 *
618 * @throws IndexOutOfBoundsException
619 * if the specified {@code index} is less than {@code 0} or
620 * {@code index + 2} is greater than {@code this.capacity}
621 */
622 public abstract int getUnsignedShort(int index);
623
624 /**
625 * Gets an unsigned 16-bit short integer at the specified absolute
626 * {@code index} in this buffer in Little Endian Byte Order.
627 * This method does not modify {@code readerIndex} or
628 * {@code writerIndex} of this buffer.
629 *
630 * @throws IndexOutOfBoundsException
631 * if the specified {@code index} is less than {@code 0} or
632 * {@code index + 2} is greater than {@code this.capacity}
633 */
634 public abstract int getUnsignedShortLE(int index);
635
636 /**
637 * Gets a 24-bit medium integer at the specified absolute {@code index} in
638 * this buffer. This method does not modify {@code readerIndex} or
639 * {@code writerIndex} of this buffer.
640 *
641 * @throws IndexOutOfBoundsException
642 * if the specified {@code index} is less than {@code 0} or
643 * {@code index + 3} is greater than {@code this.capacity}
644 */
645 public abstract int getMedium(int index);
646
647 /**
648 * Gets a 24-bit medium integer at the specified absolute {@code index} in
649 * this buffer in the Little Endian Byte Order. This method does not
650 * modify {@code readerIndex} or {@code writerIndex} of this buffer.
651 *
652 * @throws IndexOutOfBoundsException
653 * if the specified {@code index} is less than {@code 0} or
654 * {@code index + 3} is greater than {@code this.capacity}
655 */
656 public abstract int getMediumLE(int index);
657
658 /**
659 * Gets an unsigned 24-bit medium integer at the specified absolute
660 * {@code index} in this buffer. This method does not modify
661 * {@code readerIndex} or {@code writerIndex} of this buffer.
662 *
663 * @throws IndexOutOfBoundsException
664 * if the specified {@code index} is less than {@code 0} or
665 * {@code index + 3} is greater than {@code this.capacity}
666 */
667 public abstract int getUnsignedMedium(int index);
668
669 /**
670 * Gets an unsigned 24-bit medium integer at the specified absolute
671 * {@code index} in this buffer in Little Endian Byte Order.
672 * This method does not modify {@code readerIndex} or
673 * {@code writerIndex} of this buffer.
674 *
675 * @throws IndexOutOfBoundsException
676 * if the specified {@code index} is less than {@code 0} or
677 * {@code index + 3} is greater than {@code this.capacity}
678 */
679 public abstract int getUnsignedMediumLE(int index);
680
681 /**
682 * Gets a 32-bit integer at the specified absolute {@code index} in
683 * this buffer. This method does not modify {@code readerIndex} or
684 * {@code writerIndex} of this buffer.
685 *
686 * @throws IndexOutOfBoundsException
687 * if the specified {@code index} is less than {@code 0} or
688 * {@code index + 4} is greater than {@code this.capacity}
689 */
690 public abstract int getInt(int index);
691
692 /**
693 * Gets a 32-bit integer at the specified absolute {@code index} in
694 * this buffer with Little Endian Byte Order. This method does not
695 * modify {@code readerIndex} or {@code writerIndex} of this buffer.
696 *
697 * @throws IndexOutOfBoundsException
698 * if the specified {@code index} is less than {@code 0} or
699 * {@code index + 4} is greater than {@code this.capacity}
700 */
701 public abstract int getIntLE(int index);
702
703 /**
704 * Gets an unsigned 32-bit integer at the specified absolute {@code index}
705 * in this buffer. This method does not modify {@code readerIndex} or
706 * {@code writerIndex} of this buffer.
707 *
708 * @throws IndexOutOfBoundsException
709 * if the specified {@code index} is less than {@code 0} or
710 * {@code index + 4} is greater than {@code this.capacity}
711 */
712 public abstract long getUnsignedInt(int index);
713
714 /**
715 * Gets an unsigned 32-bit integer at the specified absolute {@code index}
716 * in this buffer in Little Endian Byte Order. This method does not
717 * modify {@code readerIndex} or {@code writerIndex} of this buffer.
718 *
719 * @throws IndexOutOfBoundsException
720 * if the specified {@code index} is less than {@code 0} or
721 * {@code index + 4} is greater than {@code this.capacity}
722 */
723 public abstract long getUnsignedIntLE(int index);
724
725 /**
726 * Gets a 64-bit long integer at the specified absolute {@code index} in
727 * this buffer. This method does not modify {@code readerIndex} or
728 * {@code writerIndex} of this buffer.
729 *
730 * @throws IndexOutOfBoundsException
731 * if the specified {@code index} is less than {@code 0} or
732 * {@code index + 8} is greater than {@code this.capacity}
733 */
734 public abstract long getLong(int index);
735
736 /**
737 * Gets a 64-bit long integer at the specified absolute {@code index} in
738 * this buffer in Little Endian Byte Order. This method does not
739 * modify {@code readerIndex} or {@code writerIndex} of this buffer.
740 *
741 * @throws IndexOutOfBoundsException
742 * if the specified {@code index} is less than {@code 0} or
743 * {@code index + 8} is greater than {@code this.capacity}
744 */
745 public abstract long getLongLE(int index);
746
747 /**
748 * Gets a 2-byte UTF-16 character at the specified absolute
749 * {@code index} in this buffer. This method does not modify
750 * {@code readerIndex} or {@code writerIndex} of this buffer.
751 *
752 * @throws IndexOutOfBoundsException
753 * if the specified {@code index} is less than {@code 0} or
754 * {@code index + 2} is greater than {@code this.capacity}
755 */
756 public abstract char getChar(int index);
757
758 /**
759 * Gets a 32-bit floating point number at the specified absolute
760 * {@code index} in this buffer. This method does not modify
761 * {@code readerIndex} or {@code writerIndex} of this buffer.
762 *
763 * @throws IndexOutOfBoundsException
764 * if the specified {@code index} is less than {@code 0} or
765 * {@code index + 4} is greater than {@code this.capacity}
766 */
767 public abstract float getFloat(int index);
768
769 /**
770 * Gets a 32-bit floating point number at the specified absolute
771 * {@code index} in this buffer in Little Endian Byte Order.
772 * This method does not modify {@code readerIndex} or
773 * {@code writerIndex} of this buffer.
774 *
775 * @throws IndexOutOfBoundsException
776 * if the specified {@code index} is less than {@code 0} or
777 * {@code index + 4} is greater than {@code this.capacity}
778 */
779 public float getFloatLE(int index) {
780 return Float.intBitsToFloat(getIntLE(index));
781 }
782
783 /**
784 * Gets a 64-bit floating point number at the specified absolute
785 * {@code index} in this buffer. This method does not modify
786 * {@code readerIndex} or {@code writerIndex} of this buffer.
787 *
788 * @throws IndexOutOfBoundsException
789 * if the specified {@code index} is less than {@code 0} or
790 * {@code index + 8} is greater than {@code this.capacity}
791 */
792 public abstract double getDouble(int index);
793
794 /**
795 * Gets a 64-bit floating point number at the specified absolute
796 * {@code index} in this buffer in Little Endian Byte Order.
797 * This method does not modify {@code readerIndex} or
798 * {@code writerIndex} of this buffer.
799 *
800 * @throws IndexOutOfBoundsException
801 * if the specified {@code index} is less than {@code 0} or
802 * {@code index + 8} is greater than {@code this.capacity}
803 */
804 public double getDoubleLE(int index) {
805 return Double.longBitsToDouble(getLongLE(index));
806 }
807
808 /**
809 * Transfers this buffer's data to the specified destination starting at
810 * the specified absolute {@code index} until the destination becomes
811 * non-writable. This method is basically same with
812 * {@link #getBytes(int, ByteBuf, int, int)}, except that this
813 * method increases the {@code writerIndex} of the destination by the
814 * number of the transferred bytes while
815 * {@link #getBytes(int, ByteBuf, int, int)} does not.
816 * This method does not modify {@code readerIndex} or {@code writerIndex} of
817 * the source buffer (i.e. {@code this}).
818 *
819 * @throws IndexOutOfBoundsException
820 * if the specified {@code index} is less than {@code 0} or
821 * if {@code index + dst.writableBytes} is greater than
822 * {@code this.capacity}
823 */
824 public abstract ByteBuf getBytes(int index, ByteBuf dst);
825
826 /**
827 * Transfers this buffer's data to the specified destination starting at
828 * the specified absolute {@code index}. This method is basically same
829 * with {@link #getBytes(int, ByteBuf, int, int)}, except that this
830 * method increases the {@code writerIndex} of the destination by the
831 * number of the transferred bytes while
832 * {@link #getBytes(int, ByteBuf, int, int)} does not.
833 * This method does not modify {@code readerIndex} or {@code writerIndex} of
834 * the source buffer (i.e. {@code this}).
835 *
836 * @param length the number of bytes to transfer
837 *
838 * @throws IndexOutOfBoundsException
839 * if the specified {@code index} is less than {@code 0},
840 * if {@code index + length} is greater than
841 * {@code this.capacity}, or
842 * if {@code length} is greater than {@code dst.writableBytes}
843 */
844 public abstract ByteBuf getBytes(int index, ByteBuf dst, int length);
845
846 /**
847 * Transfers this buffer's data to the specified destination starting at
848 * the specified absolute {@code index}.
849 * This method does not modify {@code readerIndex} or {@code writerIndex}
850 * of both the source (i.e. {@code this}) and the destination.
851 *
852 * @param dstIndex the first index of the destination
853 * @param length the number of bytes to transfer
854 *
855 * @throws IndexOutOfBoundsException
856 * if the specified {@code index} is less than {@code 0},
857 * if the specified {@code dstIndex} is less than {@code 0},
858 * if {@code index + length} is greater than
859 * {@code this.capacity}, or
860 * if {@code dstIndex + length} is greater than
861 * {@code dst.capacity}
862 */
863 public abstract ByteBuf getBytes(int index, ByteBuf dst, int dstIndex, int length);
864
865 /**
866 * Transfers this buffer's data to the specified destination starting at
867 * the specified absolute {@code index}.
868 * This method does not modify {@code readerIndex} or {@code writerIndex} of
869 * this buffer
870 *
871 * @throws IndexOutOfBoundsException
872 * if the specified {@code index} is less than {@code 0} or
873 * if {@code index + dst.length} is greater than
874 * {@code this.capacity}
875 */
876 public abstract ByteBuf getBytes(int index, byte[] dst);
877
878 /**
879 * Transfers this buffer's data to the specified destination starting at
880 * the specified absolute {@code index}.
881 * This method does not modify {@code readerIndex} or {@code writerIndex}
882 * of this buffer.
883 *
884 * @param dstIndex the first index of the destination
885 * @param length the number of bytes to transfer
886 *
887 * @throws IndexOutOfBoundsException
888 * if the specified {@code index} is less than {@code 0},
889 * if the specified {@code dstIndex} is less than {@code 0},
890 * if {@code index + length} is greater than
891 * {@code this.capacity}, or
892 * if {@code dstIndex + length} is greater than
893 * {@code dst.length}
894 */
895 public abstract ByteBuf getBytes(int index, byte[] dst, int dstIndex, int length);
896
897 /**
898 * Transfers this buffer's data to the specified destination starting at
899 * the specified absolute {@code index} until the destination's position
900 * reaches its limit.
901 * This method does not modify {@code readerIndex} or {@code writerIndex} of
902 * this buffer while the destination's {@code position} will be increased.
903 *
904 * @throws IndexOutOfBoundsException
905 * if the specified {@code index} is less than {@code 0} or
906 * if {@code index + dst.remaining()} is greater than
907 * {@code this.capacity}
908 */
909 public abstract ByteBuf getBytes(int index, ByteBuffer dst);
910
911 /**
912 * Transfers this buffer's data to the specified stream starting at the
913 * specified absolute {@code index}.
914 * This method does not modify {@code readerIndex} or {@code writerIndex} of
915 * this buffer.
916 *
917 * @param length the number of bytes to transfer
918 *
919 * @throws IndexOutOfBoundsException
920 * if the specified {@code index} is less than {@code 0} or
921 * if {@code index + length} is greater than
922 * {@code this.capacity}
923 * @throws IOException
924 * if the specified stream threw an exception during I/O
925 */
926 public abstract ByteBuf getBytes(int index, OutputStream out, int length) throws IOException;
927
928 /**
929 * Transfers this buffer's data to the specified channel starting at the
930 * specified absolute {@code index}.
931 * This method does not modify {@code readerIndex} or {@code writerIndex} of
932 * this buffer.
933 *
934 * @param length the maximum number of bytes to transfer
935 *
936 * @return the actual number of bytes written out to the specified channel
937 *
938 * @throws IndexOutOfBoundsException
939 * if the specified {@code index} is less than {@code 0} or
940 * if {@code index + length} is greater than
941 * {@code this.capacity}
942 * @throws IOException
943 * if the specified channel threw an exception during I/O
944 */
945 public abstract int getBytes(int index, GatheringByteChannel out, int length) throws IOException;
946
947 /**
948 * Transfers this buffer's data starting at the specified absolute {@code index}
949 * to the specified channel starting at the given file position.
950 * This method does not modify {@code readerIndex} or {@code writerIndex} of
951 * this buffer. This method does not modify the channel's position.
952 *
953 * @param position the file position at which the transfer is to begin
954 * @param length the maximum number of bytes to transfer
955 *
956 * @return the actual number of bytes written out to the specified channel
957 *
958 * @throws IndexOutOfBoundsException
959 * if the specified {@code index} is less than {@code 0} or
960 * if {@code index + length} is greater than
961 * {@code this.capacity}
962 * @throws IOException
963 * if the specified channel threw an exception during I/O
964 */
965 public abstract int getBytes(int index, FileChannel out, long position, int length) throws IOException;
966
967 /**
968 * Gets a {@link CharSequence} with the given length at the given index.
969 *
970 * @param length the length to read
971 * @param charset that should be used
972 * @return the sequence
973 * @throws IndexOutOfBoundsException
974 * if {@code length} is greater than {@code this.readableBytes}
975 */
976 public abstract CharSequence getCharSequence(int index, int length, Charset charset);
977
978 /**
979 * Sets the specified boolean at the specified absolute {@code index} in this
980 * buffer.
981 * This method does not modify {@code readerIndex} or {@code writerIndex} of
982 * this buffer.
983 *
984 * @throws IndexOutOfBoundsException
985 * if the specified {@code index} is less than {@code 0} or
986 * {@code index + 1} is greater than {@code this.capacity}
987 */
988 public abstract ByteBuf setBoolean(int index, boolean value);
989
990 /**
991 * Sets the specified byte at the specified absolute {@code index} in this
992 * buffer. The 24 high-order bits of the specified value are ignored.
993 * This method does not modify {@code readerIndex} or {@code writerIndex} of
994 * this buffer.
995 *
996 * @throws IndexOutOfBoundsException
997 * if the specified {@code index} is less than {@code 0} or
998 * {@code index + 1} is greater than {@code this.capacity}
999 */
1000 public abstract ByteBuf setByte(int index, int value);
1001
1002 /**
1003 * Sets the specified 16-bit short integer at the specified absolute
1004 * {@code index} in this buffer. The 16 high-order bits of the specified
1005 * value are ignored.
1006 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1007 * this buffer.
1008 *
1009 * @throws IndexOutOfBoundsException
1010 * if the specified {@code index} is less than {@code 0} or
1011 * {@code index + 2} is greater than {@code this.capacity}
1012 */
1013 public abstract ByteBuf setShort(int index, int value);
1014
1015 /**
1016 * Sets the specified 16-bit short integer at the specified absolute
1017 * {@code index} in this buffer with the Little Endian Byte Order.
1018 * The 16 high-order bits of the specified value are ignored.
1019 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1020 * this buffer.
1021 *
1022 * @throws IndexOutOfBoundsException
1023 * if the specified {@code index} is less than {@code 0} or
1024 * {@code index + 2} is greater than {@code this.capacity}
1025 */
1026 public abstract ByteBuf setShortLE(int index, int value);
1027
1028 /**
1029 * Sets the specified 24-bit medium integer at the specified absolute
1030 * {@code index} in this buffer. Please note that the most significant
1031 * byte is ignored in the specified value.
1032 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1033 * this buffer.
1034 *
1035 * @throws IndexOutOfBoundsException
1036 * if the specified {@code index} is less than {@code 0} or
1037 * {@code index + 3} is greater than {@code this.capacity}
1038 */
1039 public abstract ByteBuf setMedium(int index, int value);
1040
1041 /**
1042 * Sets the specified 24-bit medium integer at the specified absolute
1043 * {@code index} in this buffer in the Little Endian Byte Order.
1044 * Please note that the most significant byte is ignored in the
1045 * specified value.
1046 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1047 * this buffer.
1048 *
1049 * @throws IndexOutOfBoundsException
1050 * if the specified {@code index} is less than {@code 0} or
1051 * {@code index + 3} is greater than {@code this.capacity}
1052 */
1053 public abstract ByteBuf setMediumLE(int index, int value);
1054
1055 /**
1056 * Sets the specified 32-bit integer at the specified absolute
1057 * {@code index} in this buffer.
1058 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1059 * this buffer.
1060 *
1061 * @throws IndexOutOfBoundsException
1062 * if the specified {@code index} is less than {@code 0} or
1063 * {@code index + 4} is greater than {@code this.capacity}
1064 */
1065 public abstract ByteBuf setInt(int index, int value);
1066
1067 /**
1068 * Sets the specified 32-bit integer at the specified absolute
1069 * {@code index} in this buffer with Little Endian byte order
1070 * .
1071 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1072 * this buffer.
1073 *
1074 * @throws IndexOutOfBoundsException
1075 * if the specified {@code index} is less than {@code 0} or
1076 * {@code index + 4} is greater than {@code this.capacity}
1077 */
1078 public abstract ByteBuf setIntLE(int index, int value);
1079
1080 /**
1081 * Sets the specified 64-bit long integer at the specified absolute
1082 * {@code index} in this buffer.
1083 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1084 * this buffer.
1085 *
1086 * @throws IndexOutOfBoundsException
1087 * if the specified {@code index} is less than {@code 0} or
1088 * {@code index + 8} is greater than {@code this.capacity}
1089 */
1090 public abstract ByteBuf setLong(int index, long value);
1091
1092 /**
1093 * Sets the specified 64-bit long integer at the specified absolute
1094 * {@code index} in this buffer in Little Endian Byte Order.
1095 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1096 * this buffer.
1097 *
1098 * @throws IndexOutOfBoundsException
1099 * if the specified {@code index} is less than {@code 0} or
1100 * {@code index + 8} is greater than {@code this.capacity}
1101 */
1102 public abstract ByteBuf setLongLE(int index, long value);
1103
1104 /**
1105 * Sets the specified 2-byte UTF-16 character at the specified absolute
1106 * {@code index} in this buffer.
1107 * The 16 high-order bits of the specified value are ignored.
1108 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1109 * this buffer.
1110 *
1111 * @throws IndexOutOfBoundsException
1112 * if the specified {@code index} is less than {@code 0} or
1113 * {@code index + 2} is greater than {@code this.capacity}
1114 */
1115 public abstract ByteBuf setChar(int index, int value);
1116
1117 /**
1118 * Sets the specified 32-bit floating-point number at the specified
1119 * absolute {@code index} in this buffer.
1120 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1121 * this buffer.
1122 *
1123 * @throws IndexOutOfBoundsException
1124 * if the specified {@code index} is less than {@code 0} or
1125 * {@code index + 4} is greater than {@code this.capacity}
1126 */
1127 public abstract ByteBuf setFloat(int index, float value);
1128
1129 /**
1130 * Sets the specified 32-bit floating-point number at the specified
1131 * absolute {@code index} in this buffer in Little Endian Byte Order.
1132 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1133 * this buffer.
1134 *
1135 * @throws IndexOutOfBoundsException
1136 * if the specified {@code index} is less than {@code 0} or
1137 * {@code index + 4} is greater than {@code this.capacity}
1138 */
1139 public ByteBuf setFloatLE(int index, float value) {
1140 return setIntLE(index, Float.floatToRawIntBits(value));
1141 }
1142
1143 /**
1144 * Sets the specified 64-bit floating-point number at the specified
1145 * absolute {@code index} in this buffer.
1146 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1147 * this buffer.
1148 *
1149 * @throws IndexOutOfBoundsException
1150 * if the specified {@code index} is less than {@code 0} or
1151 * {@code index + 8} is greater than {@code this.capacity}
1152 */
1153 public abstract ByteBuf setDouble(int index, double value);
1154
1155 /**
1156 * Sets the specified 64-bit floating-point number at the specified
1157 * absolute {@code index} in this buffer in Little Endian Byte Order.
1158 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1159 * this buffer.
1160 *
1161 * @throws IndexOutOfBoundsException
1162 * if the specified {@code index} is less than {@code 0} or
1163 * {@code index + 8} is greater than {@code this.capacity}
1164 */
1165 public ByteBuf setDoubleLE(int index, double value) {
1166 return setLongLE(index, Double.doubleToRawLongBits(value));
1167 }
1168
1169 /**
1170 * Transfers the specified source buffer's data to this buffer starting at
1171 * the specified absolute {@code index} until the source buffer becomes
1172 * unreadable. This method is basically same with
1173 * {@link #setBytes(int, ByteBuf, int, int)}, except that this
1174 * method increases the {@code readerIndex} of the source buffer by
1175 * the number of the transferred bytes while
1176 * {@link #setBytes(int, ByteBuf, int, int)} does not.
1177 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1178 * this buffer (i.e. {@code this}).
1179 *
1180 * @throws IndexOutOfBoundsException
1181 * if the specified {@code index} is less than {@code 0} or
1182 * if {@code index + src.readableBytes} is greater than
1183 * {@code this.capacity}
1184 */
1185 public abstract ByteBuf setBytes(int index, ByteBuf src);
1186
1187 /**
1188 * Transfers the specified source buffer's data to this buffer starting at
1189 * the specified absolute {@code index}. This method is basically same
1190 * with {@link #setBytes(int, ByteBuf, int, int)}, except that this
1191 * method increases the {@code readerIndex} of the source buffer by
1192 * the number of the transferred bytes while
1193 * {@link #setBytes(int, ByteBuf, int, int)} does not.
1194 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1195 * this buffer (i.e. {@code this}).
1196 *
1197 * @param length the number of bytes to transfer
1198 *
1199 * @throws IndexOutOfBoundsException
1200 * if the specified {@code index} is less than {@code 0},
1201 * if {@code index + length} is greater than
1202 * {@code this.capacity}, or
1203 * if {@code length} is greater than {@code src.readableBytes}
1204 */
1205 public abstract ByteBuf setBytes(int index, ByteBuf src, int length);
1206
1207 /**
1208 * Transfers the specified source buffer's data to this buffer starting at
1209 * the specified absolute {@code index}.
1210 * This method does not modify {@code readerIndex} or {@code writerIndex}
1211 * of both the source (i.e. {@code this}) and the destination.
1212 *
1213 * @param srcIndex the first index of the source
1214 * @param length the number of bytes to transfer
1215 *
1216 * @throws IndexOutOfBoundsException
1217 * if the specified {@code index} is less than {@code 0},
1218 * if the specified {@code srcIndex} is less than {@code 0},
1219 * if {@code index + length} is greater than
1220 * {@code this.capacity}, or
1221 * if {@code srcIndex + length} is greater than
1222 * {@code src.capacity}
1223 */
1224 public abstract ByteBuf setBytes(int index, ByteBuf src, int srcIndex, int length);
1225
1226 /**
1227 * Transfers the specified source array's data to this buffer starting at
1228 * the specified absolute {@code index}.
1229 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1230 * this buffer.
1231 *
1232 * @throws IndexOutOfBoundsException
1233 * if the specified {@code index} is less than {@code 0} or
1234 * if {@code index + src.length} is greater than
1235 * {@code this.capacity}
1236 */
1237 public abstract ByteBuf setBytes(int index, byte[] src);
1238
1239 /**
1240 * Transfers the specified source array's data to this buffer starting at
1241 * the specified absolute {@code index}.
1242 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1243 * this buffer.
1244 *
1245 * @throws IndexOutOfBoundsException
1246 * if the specified {@code index} is less than {@code 0},
1247 * if the specified {@code srcIndex} is less than {@code 0},
1248 * if {@code index + length} is greater than
1249 * {@code this.capacity}, or
1250 * if {@code srcIndex + length} is greater than {@code src.length}
1251 */
1252 public abstract ByteBuf setBytes(int index, byte[] src, int srcIndex, int length);
1253
1254 /**
1255 * Transfers the specified source buffer's data to this buffer starting at
1256 * the specified absolute {@code index} until the source buffer's position
1257 * reaches its limit.
1258 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1259 * this buffer.
1260 *
1261 * @throws IndexOutOfBoundsException
1262 * if the specified {@code index} is less than {@code 0} or
1263 * if {@code index + src.remaining()} is greater than
1264 * {@code this.capacity}
1265 */
1266 public abstract ByteBuf setBytes(int index, ByteBuffer src);
1267
1268 /**
1269 * Transfers the content of the specified source stream to this buffer
1270 * starting at the specified absolute {@code index}.
1271 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1272 * this buffer.
1273 *
1274 * @param length the number of bytes to transfer
1275 *
1276 * @return the actual number of bytes read in from the specified channel.
1277 * {@code -1} if the specified {@link InputStream} reached EOF.
1278 *
1279 * @throws IndexOutOfBoundsException
1280 * if the specified {@code index} is less than {@code 0} or
1281 * if {@code index + length} is greater than {@code this.capacity}
1282 * @throws IOException
1283 * if the specified stream threw an exception during I/O
1284 */
1285 public abstract int setBytes(int index, InputStream in, int length) throws IOException;
1286
1287 /**
1288 * Transfers the content of the specified source channel to this buffer
1289 * starting at the specified absolute {@code index}.
1290 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1291 * this buffer.
1292 *
1293 * @param length the maximum number of bytes to transfer
1294 *
1295 * @return the actual number of bytes read in from the specified channel.
1296 * {@code -1} if the specified channel is closed or reached EOF.
1297 *
1298 * @throws IndexOutOfBoundsException
1299 * if the specified {@code index} is less than {@code 0} or
1300 * if {@code index + length} is greater than {@code this.capacity}
1301 * @throws IOException
1302 * if the specified channel threw an exception during I/O
1303 */
1304 public abstract int setBytes(int index, ScatteringByteChannel in, int length) throws IOException;
1305
1306 /**
1307 * Transfers the content of the specified source channel starting at the given file position
1308 * to this buffer starting at the specified absolute {@code index}.
1309 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1310 * this buffer. This method does not modify the channel's position.
1311 *
1312 * @param position the file position at which the transfer is to begin
1313 * @param length the maximum number of bytes to transfer
1314 *
1315 * @return the actual number of bytes read in from the specified channel.
1316 * {@code -1} if the specified channel is closed or reached EOF.
1317 *
1318 * @throws IndexOutOfBoundsException
1319 * if the specified {@code index} is less than {@code 0} or
1320 * if {@code index + length} is greater than {@code this.capacity}
1321 * @throws IOException
1322 * if the specified channel threw an exception during I/O
1323 */
1324 public abstract int setBytes(int index, FileChannel in, long position, int length) throws IOException;
1325
1326 /**
1327 * Fills this buffer with <tt>NUL (0x00)</tt> starting at the specified
1328 * absolute {@code index}.
1329 * This method does not modify {@code readerIndex} or {@code writerIndex} of
1330 * this buffer.
1331 *
1332 * @param length the number of <tt>NUL</tt>s to write to the buffer
1333 *
1334 * @throws IndexOutOfBoundsException
1335 * if the specified {@code index} is less than {@code 0} or
1336 * if {@code index + length} is greater than {@code this.capacity}
1337 */
1338 public abstract ByteBuf setZero(int index, int length);
1339
1340 /**
1341 * Writes the specified {@link CharSequence} at the given {@code index}.
1342 * The {@code writerIndex} is not modified by this method.
1343 *
1344 * @param index on which the sequence should be written
1345 * @param sequence to write
1346 * @param charset that should be used.
1347 * @return the written number of bytes.
1348 * @throws IndexOutOfBoundsException
1349 * if the sequence at the given index would be out of bounds of the buffer capacity
1350 */
1351 public abstract int setCharSequence(int index, CharSequence sequence, Charset charset);
1352
1353 /**
1354 * Gets a boolean at the current {@code readerIndex} and increases
1355 * the {@code readerIndex} by {@code 1} in this buffer.
1356 *
1357 * @throws IndexOutOfBoundsException
1358 * if {@code this.readableBytes} is less than {@code 1}
1359 */
1360 public abstract boolean readBoolean();
1361
1362 /**
1363 * Gets a byte at the current {@code readerIndex} and increases
1364 * the {@code readerIndex} by {@code 1} in this buffer.
1365 *
1366 * @throws IndexOutOfBoundsException
1367 * if {@code this.readableBytes} is less than {@code 1}
1368 */
1369 public abstract byte readByte();
1370
1371 /**
1372 * Gets an unsigned byte at the current {@code readerIndex} and increases
1373 * the {@code readerIndex} by {@code 1} in this buffer.
1374 *
1375 * @throws IndexOutOfBoundsException
1376 * if {@code this.readableBytes} is less than {@code 1}
1377 */
1378 public abstract short readUnsignedByte();
1379
1380 /**
1381 * Gets a 16-bit short integer at the current {@code readerIndex}
1382 * and increases the {@code readerIndex} by {@code 2} in this buffer.
1383 *
1384 * @throws IndexOutOfBoundsException
1385 * if {@code this.readableBytes} is less than {@code 2}
1386 */
1387 public abstract short readShort();
1388
1389 /**
1390 * Gets a 16-bit short integer at the current {@code readerIndex}
1391 * in the Little Endian Byte Order and increases the {@code readerIndex}
1392 * by {@code 2} in this buffer.
1393 *
1394 * @throws IndexOutOfBoundsException
1395 * if {@code this.readableBytes} is less than {@code 2}
1396 */
1397 public abstract short readShortLE();
1398
1399 /**
1400 * Gets an unsigned 16-bit short integer at the current {@code readerIndex}
1401 * and increases the {@code readerIndex} by {@code 2} in this buffer.
1402 *
1403 * @throws IndexOutOfBoundsException
1404 * if {@code this.readableBytes} is less than {@code 2}
1405 */
1406 public abstract int readUnsignedShort();
1407
1408 /**
1409 * Gets an unsigned 16-bit short integer at the current {@code readerIndex}
1410 * in the Little Endian Byte Order and increases the {@code readerIndex}
1411 * by {@code 2} in this buffer.
1412 *
1413 * @throws IndexOutOfBoundsException
1414 * if {@code this.readableBytes} is less than {@code 2}
1415 */
1416 public abstract int readUnsignedShortLE();
1417
1418 /**
1419 * Gets a 24-bit medium integer at the current {@code readerIndex}
1420 * and increases the {@code readerIndex} by {@code 3} in this buffer.
1421 *
1422 * @throws IndexOutOfBoundsException
1423 * if {@code this.readableBytes} is less than {@code 3}
1424 */
1425 public abstract int readMedium();
1426
1427 /**
1428 * Gets a 24-bit medium integer at the current {@code readerIndex}
1429 * in the Little Endian Byte Order and increases the
1430 * {@code readerIndex} by {@code 3} in this buffer.
1431 *
1432 * @throws IndexOutOfBoundsException
1433 * if {@code this.readableBytes} is less than {@code 3}
1434 */
1435 public abstract int readMediumLE();
1436
1437 /**
1438 * Gets an unsigned 24-bit medium integer at the current {@code readerIndex}
1439 * and increases the {@code readerIndex} by {@code 3} in this buffer.
1440 *
1441 * @throws IndexOutOfBoundsException
1442 * if {@code this.readableBytes} is less than {@code 3}
1443 */
1444 public abstract int readUnsignedMedium();
1445
1446 /**
1447 * Gets an unsigned 24-bit medium integer at the current {@code readerIndex}
1448 * in the Little Endian Byte Order and increases the {@code readerIndex}
1449 * by {@code 3} in this buffer.
1450 *
1451 * @throws IndexOutOfBoundsException
1452 * if {@code this.readableBytes} is less than {@code 3}
1453 */
1454 public abstract int readUnsignedMediumLE();
1455
1456 /**
1457 * Gets a 32-bit integer at the current {@code readerIndex}
1458 * and increases the {@code readerIndex} by {@code 4} in this buffer.
1459 *
1460 * @throws IndexOutOfBoundsException
1461 * if {@code this.readableBytes} is less than {@code 4}
1462 */
1463 public abstract int readInt();
1464
1465 /**
1466 * Gets a 32-bit integer at the current {@code readerIndex}
1467 * in the Little Endian Byte Order and increases the {@code readerIndex}
1468 * by {@code 4} in this buffer.
1469 *
1470 * @throws IndexOutOfBoundsException
1471 * if {@code this.readableBytes} is less than {@code 4}
1472 */
1473 public abstract int readIntLE();
1474
1475 /**
1476 * Gets an unsigned 32-bit integer at the current {@code readerIndex}
1477 * and increases the {@code readerIndex} by {@code 4} in this buffer.
1478 *
1479 * @throws IndexOutOfBoundsException
1480 * if {@code this.readableBytes} is less than {@code 4}
1481 */
1482 public abstract long readUnsignedInt();
1483
1484 /**
1485 * Gets an unsigned 32-bit integer at the current {@code readerIndex}
1486 * in the Little Endian Byte Order and increases the {@code readerIndex}
1487 * by {@code 4} in this buffer.
1488 *
1489 * @throws IndexOutOfBoundsException
1490 * if {@code this.readableBytes} is less than {@code 4}
1491 */
1492 public abstract long readUnsignedIntLE();
1493
1494 /**
1495 * Gets a 64-bit integer at the current {@code readerIndex}
1496 * and increases the {@code readerIndex} by {@code 8} in this buffer.
1497 *
1498 * @throws IndexOutOfBoundsException
1499 * if {@code this.readableBytes} is less than {@code 8}
1500 */
1501 public abstract long readLong();
1502
1503 /**
1504 * Gets a 64-bit integer at the current {@code readerIndex}
1505 * in the Little Endian Byte Order and increases the {@code readerIndex}
1506 * by {@code 8} in this buffer.
1507 *
1508 * @throws IndexOutOfBoundsException
1509 * if {@code this.readableBytes} is less than {@code 8}
1510 */
1511 public abstract long readLongLE();
1512
1513 /**
1514 * Gets a 2-byte UTF-16 character at the current {@code readerIndex}
1515 * and increases the {@code readerIndex} by {@code 2} in this buffer.
1516 *
1517 * @throws IndexOutOfBoundsException
1518 * if {@code this.readableBytes} is less than {@code 2}
1519 */
1520 public abstract char readChar();
1521
1522 /**
1523 * Gets a 32-bit floating point number at the current {@code readerIndex}
1524 * and increases the {@code readerIndex} by {@code 4} in this buffer.
1525 *
1526 * @throws IndexOutOfBoundsException
1527 * if {@code this.readableBytes} is less than {@code 4}
1528 */
1529 public abstract float readFloat();
1530
1531 /**
1532 * Gets a 32-bit floating point number at the current {@code readerIndex}
1533 * in Little Endian Byte Order and increases the {@code readerIndex}
1534 * by {@code 4} in this buffer.
1535 *
1536 * @throws IndexOutOfBoundsException
1537 * if {@code this.readableBytes} is less than {@code 4}
1538 */
1539 public float readFloatLE() {
1540 return Float.intBitsToFloat(readIntLE());
1541 }
1542
1543 /**
1544 * Gets a 64-bit floating point number at the current {@code readerIndex}
1545 * and increases the {@code readerIndex} by {@code 8} in this buffer.
1546 *
1547 * @throws IndexOutOfBoundsException
1548 * if {@code this.readableBytes} is less than {@code 8}
1549 */
1550 public abstract double readDouble();
1551
1552 /**
1553 * Gets a 64-bit floating point number at the current {@code readerIndex}
1554 * in Little Endian Byte Order and increases the {@code readerIndex}
1555 * by {@code 8} in this buffer.
1556 *
1557 * @throws IndexOutOfBoundsException
1558 * if {@code this.readableBytes} is less than {@code 8}
1559 */
1560 public double readDoubleLE() {
1561 return Double.longBitsToDouble(readLongLE());
1562 }
1563
1564 /**
1565 * Transfers this buffer's data to a newly created buffer starting at
1566 * the current {@code readerIndex} and increases the {@code readerIndex}
1567 * by the number of the transferred bytes (= {@code length}).
1568 * The returned buffer's {@code readerIndex} and {@code writerIndex} are
1569 * {@code 0} and {@code length} respectively.
1570 *
1571 * @param length the number of bytes to transfer
1572 *
1573 * @return the newly created buffer which contains the transferred bytes
1574 *
1575 * @throws IndexOutOfBoundsException
1576 * if {@code length} is greater than {@code this.readableBytes}
1577 */
1578 public abstract ByteBuf readBytes(int length);
1579
1580 /**
1581 * Returns a new slice of this buffer's sub-region starting at the current
1582 * {@code readerIndex} and increases the {@code readerIndex} by the size
1583 * of the new slice (= {@code length}).
1584 * <p>
1585 * Also be aware that this method will NOT call {@link #retain()} and so the
1586 * reference count will NOT be increased.
1587 *
1588 * @param length the size of the new slice
1589 *
1590 * @return the newly created slice
1591 *
1592 * @throws IndexOutOfBoundsException
1593 * if {@code length} is greater than {@code this.readableBytes}
1594 */
1595 public abstract ByteBuf readSlice(int length);
1596
1597 /**
1598 * Returns a new retained slice of this buffer's sub-region starting at the current
1599 * {@code readerIndex} and increases the {@code readerIndex} by the size
1600 * of the new slice (= {@code length}).
1601 * <p>
1602 * Note that this method returns a {@linkplain #retain() retained} buffer unlike {@link #readSlice(int)}.
1603 * This method behaves similarly to {@code readSlice(...).retain()} except that this method may return
1604 * a buffer implementation that produces less garbage.
1605 *
1606 * @param length the size of the new slice
1607 *
1608 * @return the newly created slice
1609 *
1610 * @throws IndexOutOfBoundsException
1611 * if {@code length} is greater than {@code this.readableBytes}
1612 */
1613 public abstract ByteBuf readRetainedSlice(int length);
1614
1615 /**
1616 * Transfers this buffer's data to the specified destination starting at
1617 * the current {@code readerIndex} until the destination becomes
1618 * non-writable, and increases the {@code readerIndex} by the number of the
1619 * transferred bytes. This method is basically same with
1620 * {@link #readBytes(ByteBuf, int, int)}, except that this method
1621 * increases the {@code writerIndex} of the destination by the number of
1622 * the transferred bytes while {@link #readBytes(ByteBuf, int, int)}
1623 * does not.
1624 *
1625 * @throws IndexOutOfBoundsException
1626 * if {@code dst.writableBytes} is greater than
1627 * {@code this.readableBytes}
1628 */
1629 public abstract ByteBuf readBytes(ByteBuf dst);
1630
1631 /**
1632 * Transfers this buffer's data to the specified destination starting at
1633 * the current {@code readerIndex} and increases the {@code readerIndex}
1634 * by the number of the transferred bytes (= {@code length}). This method
1635 * is basically same with {@link #readBytes(ByteBuf, int, int)},
1636 * except that this method increases the {@code writerIndex} of the
1637 * destination by the number of the transferred bytes (= {@code length})
1638 * while {@link #readBytes(ByteBuf, int, int)} does not.
1639 *
1640 * @throws IndexOutOfBoundsException
1641 * if {@code length} is greater than {@code this.readableBytes} or
1642 * if {@code length} is greater than {@code dst.writableBytes}
1643 */
1644 public abstract ByteBuf readBytes(ByteBuf dst, int length);
1645
1646 /**
1647 * Transfers this buffer's data to the specified destination starting at
1648 * the current {@code readerIndex} and increases the {@code readerIndex}
1649 * by the number of the transferred bytes (= {@code length}).
1650 *
1651 * @param dstIndex the first index of the destination
1652 * @param length the number of bytes to transfer
1653 *
1654 * @throws IndexOutOfBoundsException
1655 * if the specified {@code dstIndex} is less than {@code 0},
1656 * if {@code length} is greater than {@code this.readableBytes}, or
1657 * if {@code dstIndex + length} is greater than
1658 * {@code dst.capacity}
1659 */
1660 public abstract ByteBuf readBytes(ByteBuf dst, int dstIndex, int length);
1661
1662 /**
1663 * Transfers this buffer's data to the specified destination starting at
1664 * the current {@code readerIndex} and increases the {@code readerIndex}
1665 * by the number of the transferred bytes (= {@code dst.length}).
1666 *
1667 * @throws IndexOutOfBoundsException
1668 * if {@code dst.length} is greater than {@code this.readableBytes}
1669 */
1670 public abstract ByteBuf readBytes(byte[] dst);
1671
1672 /**
1673 * Transfers this buffer's data to the specified destination starting at
1674 * the current {@code readerIndex} and increases the {@code readerIndex}
1675 * by the number of the transferred bytes (= {@code length}).
1676 *
1677 * @param dstIndex the first index of the destination
1678 * @param length the number of bytes to transfer
1679 *
1680 * @throws IndexOutOfBoundsException
1681 * if the specified {@code dstIndex} is less than {@code 0},
1682 * if {@code length} is greater than {@code this.readableBytes}, or
1683 * if {@code dstIndex + length} is greater than {@code dst.length}
1684 */
1685 public abstract ByteBuf readBytes(byte[] dst, int dstIndex, int length);
1686
1687 /**
1688 * Transfers this buffer's data to the specified destination starting at
1689 * the current {@code readerIndex} until the destination's position
1690 * reaches its limit, and increases the {@code readerIndex} by the
1691 * number of the transferred bytes.
1692 *
1693 * @throws IndexOutOfBoundsException
1694 * if {@code dst.remaining()} is greater than
1695 * {@code this.readableBytes}
1696 */
1697 public abstract ByteBuf readBytes(ByteBuffer dst);
1698
1699 /**
1700 * Transfers this buffer's data to the specified stream starting at the
1701 * current {@code readerIndex}.
1702 *
1703 * @param length the number of bytes to transfer
1704 *
1705 * @throws IndexOutOfBoundsException
1706 * if {@code length} is greater than {@code this.readableBytes}
1707 * @throws IOException
1708 * if the specified stream threw an exception during I/O
1709 */
1710 public abstract ByteBuf readBytes(OutputStream out, int length) throws IOException;
1711
1712 /**
1713 * Transfers this buffer's data to the specified stream starting at the
1714 * current {@code readerIndex}.
1715 *
1716 * @param length the maximum number of bytes to transfer
1717 *
1718 * @return the actual number of bytes written out to the specified channel
1719 *
1720 * @throws IndexOutOfBoundsException
1721 * if {@code length} is greater than {@code this.readableBytes}
1722 * @throws IOException
1723 * if the specified channel threw an exception during I/O
1724 */
1725 public abstract int readBytes(GatheringByteChannel out, int length) throws IOException;
1726
1727 /**
1728 * Gets a {@link CharSequence} with the given length at the current {@code readerIndex}
1729 * and increases the {@code readerIndex} by the given length.
1730 *
1731 * @param length the length to read
1732 * @param charset that should be used
1733 * @return the sequence
1734 * @throws IndexOutOfBoundsException
1735 * if {@code length} is greater than {@code this.readableBytes}
1736 */
1737 public abstract CharSequence readCharSequence(int length, Charset charset);
1738
1739 /**
1740 * Gets a {@link String} with the given length at the current {@code readerIndex}
1741 * and increases the {@code readerIndex} by the given length.
1742 *
1743 * @param length the length to read
1744 * @param charset that should be used
1745 * @return the string
1746 * @throws IndexOutOfBoundsException
1747 * if {@code length} is greater than {@code this.readableBytes}
1748 */
1749 public String readString(int length, Charset charset) {
1750 int readerIndex = readerIndex();
1751 String string = toString(readerIndex, length, charset);
1752 readerIndex(readerIndex + length);
1753 return string;
1754 }
1755
1756 /**
1757 * Transfers this buffer's data starting at the current {@code readerIndex}
1758 * to the specified channel starting at the given file position.
1759 * This method does not modify the channel's position.
1760 *
1761 * @param position the file position at which the transfer is to begin
1762 * @param length the maximum number of bytes to transfer
1763 *
1764 * @return the actual number of bytes written out to the specified channel
1765 *
1766 * @throws IndexOutOfBoundsException
1767 * if {@code length} is greater than {@code this.readableBytes}
1768 * @throws IOException
1769 * if the specified channel threw an exception during I/O
1770 */
1771 public abstract int readBytes(FileChannel out, long position, int length) throws IOException;
1772
1773 /**
1774 * Increases the current {@code readerIndex} by the specified
1775 * {@code length} in this buffer.
1776 *
1777 * @throws IndexOutOfBoundsException
1778 * if {@code length} is greater than {@code this.readableBytes}
1779 */
1780 public abstract ByteBuf skipBytes(int length);
1781
1782 /**
1783 * Sets the specified boolean at the current {@code writerIndex}
1784 * and increases the {@code writerIndex} by {@code 1} in this buffer.
1785 * If {@code this.writableBytes} is less than {@code 1}, {@link #ensureWritable(int)}
1786 * will be called in an attempt to expand capacity to accommodate.
1787 */
1788 public abstract ByteBuf writeBoolean(boolean value);
1789
1790 /**
1791 * Sets the specified byte at the current {@code writerIndex}
1792 * and increases the {@code writerIndex} by {@code 1} in this buffer.
1793 * The 24 high-order bits of the specified value are ignored.
1794 * If {@code this.writableBytes} is less than {@code 1}, {@link #ensureWritable(int)}
1795 * will be called in an attempt to expand capacity to accommodate.
1796 */
1797 public abstract ByteBuf writeByte(int value);
1798
1799 /**
1800 * Sets the specified 16-bit short integer at the current
1801 * {@code writerIndex} and increases the {@code writerIndex} by {@code 2}
1802 * in this buffer. The 16 high-order bits of the specified value are ignored.
1803 * If {@code this.writableBytes} is less than {@code 2}, {@link #ensureWritable(int)}
1804 * will be called in an attempt to expand capacity to accommodate.
1805 */
1806 public abstract ByteBuf writeShort(int value);
1807
1808 /**
1809 * Sets the specified 16-bit short integer in the Little Endian Byte
1810 * Order at the current {@code writerIndex} and increases the
1811 * {@code writerIndex} by {@code 2} in this buffer.
1812 * The 16 high-order bits of the specified value are ignored.
1813 * If {@code this.writableBytes} is less than {@code 2}, {@link #ensureWritable(int)}
1814 * will be called in an attempt to expand capacity to accommodate.
1815 */
1816 public abstract ByteBuf writeShortLE(int value);
1817
1818 /**
1819 * Sets the specified 24-bit medium integer at the current
1820 * {@code writerIndex} and increases the {@code writerIndex} by {@code 3}
1821 * in this buffer.
1822 * If {@code this.writableBytes} is less than {@code 3}, {@link #ensureWritable(int)}
1823 * will be called in an attempt to expand capacity to accommodate.
1824 */
1825 public abstract ByteBuf writeMedium(int value);
1826
1827 /**
1828 * Sets the specified 24-bit medium integer at the current
1829 * {@code writerIndex} in the Little Endian Byte Order and
1830 * increases the {@code writerIndex} by {@code 3} in this
1831 * buffer.
1832 * If {@code this.writableBytes} is less than {@code 3}, {@link #ensureWritable(int)}
1833 * will be called in an attempt to expand capacity to accommodate.
1834 */
1835 public abstract ByteBuf writeMediumLE(int value);
1836
1837 /**
1838 * Sets the specified 32-bit integer at the current {@code writerIndex}
1839 * and increases the {@code writerIndex} by {@code 4} in this buffer.
1840 * If {@code this.writableBytes} is less than {@code 4}, {@link #ensureWritable(int)}
1841 * will be called in an attempt to expand capacity to accommodate.
1842 */
1843 public abstract ByteBuf writeInt(int value);
1844
1845 /**
1846 * Sets the specified 32-bit integer at the current {@code writerIndex}
1847 * in the Little Endian Byte Order and increases the {@code writerIndex}
1848 * by {@code 4} in this buffer.
1849 * If {@code this.writableBytes} is less than {@code 4}, {@link #ensureWritable(int)}
1850 * will be called in an attempt to expand capacity to accommodate.
1851 */
1852 public abstract ByteBuf writeIntLE(int value);
1853
1854 /**
1855 * Sets the specified 64-bit long integer at the current
1856 * {@code writerIndex} and increases the {@code writerIndex} by {@code 8}
1857 * in this buffer.
1858 * If {@code this.writableBytes} is less than {@code 8}, {@link #ensureWritable(int)}
1859 * will be called in an attempt to expand capacity to accommodate.
1860 */
1861 public abstract ByteBuf writeLong(long value);
1862
1863 /**
1864 * Sets the specified 64-bit long integer at the current
1865 * {@code writerIndex} in the Little Endian Byte Order and
1866 * increases the {@code writerIndex} by {@code 8}
1867 * in this buffer.
1868 * If {@code this.writableBytes} is less than {@code 8}, {@link #ensureWritable(int)}
1869 * will be called in an attempt to expand capacity to accommodate.
1870 */
1871 public abstract ByteBuf writeLongLE(long value);
1872
1873 /**
1874 * Sets the specified 2-byte UTF-16 character at the current
1875 * {@code writerIndex} and increases the {@code writerIndex} by {@code 2}
1876 * in this buffer. The 16 high-order bits of the specified value are ignored.
1877 * If {@code this.writableBytes} is less than {@code 2}, {@link #ensureWritable(int)}
1878 * will be called in an attempt to expand capacity to accommodate.
1879 */
1880 public abstract ByteBuf writeChar(int value);
1881
1882 /**
1883 * Sets the specified 32-bit floating point number at the current
1884 * {@code writerIndex} and increases the {@code writerIndex} by {@code 4}
1885 * in this buffer.
1886 * If {@code this.writableBytes} is less than {@code 4}, {@link #ensureWritable(int)}
1887 * will be called in an attempt to expand capacity to accommodate.
1888 */
1889 public abstract ByteBuf writeFloat(float value);
1890
1891 /**
1892 * Sets the specified 32-bit floating point number at the current
1893 * {@code writerIndex} in Little Endian Byte Order and increases
1894 * the {@code writerIndex} by {@code 4} in this buffer.
1895 * If {@code this.writableBytes} is less than {@code 4}, {@link #ensureWritable(int)}
1896 * will be called in an attempt to expand capacity to accommodate.
1897 */
1898 public ByteBuf writeFloatLE(float value) {
1899 return writeIntLE(Float.floatToRawIntBits(value));
1900 }
1901
1902 /**
1903 * Sets the specified 64-bit floating point number at the current
1904 * {@code writerIndex} and increases the {@code writerIndex} by {@code 8}
1905 * in this buffer.
1906 * If {@code this.writableBytes} is less than {@code 8}, {@link #ensureWritable(int)}
1907 * will be called in an attempt to expand capacity to accommodate.
1908 */
1909 public abstract ByteBuf writeDouble(double value);
1910
1911 /**
1912 * Sets the specified 64-bit floating point number at the current
1913 * {@code writerIndex} in Little Endian Byte Order and increases
1914 * the {@code writerIndex} by {@code 8} in this buffer.
1915 * If {@code this.writableBytes} is less than {@code 8}, {@link #ensureWritable(int)}
1916 * will be called in an attempt to expand capacity to accommodate.
1917 */
1918 public ByteBuf writeDoubleLE(double value) {
1919 return writeLongLE(Double.doubleToRawLongBits(value));
1920 }
1921
1922 /**
1923 * Transfers the specified source buffer's data to this buffer starting at
1924 * the current {@code writerIndex} until the source buffer becomes
1925 * unreadable, and increases the {@code writerIndex} by the number of
1926 * the transferred bytes. This method is basically same with
1927 * {@link #writeBytes(ByteBuf, int, int)}, except that this method
1928 * increases the {@code readerIndex} of the source buffer by the number of
1929 * the transferred bytes while {@link #writeBytes(ByteBuf, int, int)}
1930 * does not.
1931 * If {@code this.writableBytes} is less than {@code src.readableBytes},
1932 * {@link #ensureWritable(int)} will be called in an attempt to expand
1933 * capacity to accommodate.
1934 */
1935 public abstract ByteBuf writeBytes(ByteBuf src);
1936
1937 /**
1938 * Transfers the specified source buffer's data to this buffer starting at
1939 * the current {@code writerIndex} and increases the {@code writerIndex}
1940 * by the number of the transferred bytes (= {@code length}). This method
1941 * is basically same with {@link #writeBytes(ByteBuf, int, int)},
1942 * except that this method increases the {@code readerIndex} of the source
1943 * buffer by the number of the transferred bytes (= {@code length}) while
1944 * {@link #writeBytes(ByteBuf, int, int)} does not.
1945 * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
1946 * will be called in an attempt to expand capacity to accommodate.
1947 *
1948 * @param length the number of bytes to transfer
1949 * @throws IndexOutOfBoundsException if {@code length} is greater then {@code src.readableBytes}
1950 */
1951 public abstract ByteBuf writeBytes(ByteBuf src, int length);
1952
1953 /**
1954 * Transfers the specified source buffer's data to this buffer starting at
1955 * the current {@code writerIndex} and increases the {@code writerIndex}
1956 * by the number of the transferred bytes (= {@code length}).
1957 * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
1958 * will be called in an attempt to expand capacity to accommodate.
1959 *
1960 * @param srcIndex the first index of the source
1961 * @param length the number of bytes to transfer
1962 *
1963 * @throws IndexOutOfBoundsException
1964 * if the specified {@code srcIndex} is less than {@code 0}, or
1965 * if {@code srcIndex + length} is greater than {@code src.capacity}
1966 */
1967 public abstract ByteBuf writeBytes(ByteBuf src, int srcIndex, int length);
1968
1969 /**
1970 * Transfers the specified source array's data to this buffer starting at
1971 * the current {@code writerIndex} and increases the {@code writerIndex}
1972 * by the number of the transferred bytes (= {@code src.length}).
1973 * If {@code this.writableBytes} is less than {@code src.length}, {@link #ensureWritable(int)}
1974 * will be called in an attempt to expand capacity to accommodate.
1975 */
1976 public abstract ByteBuf writeBytes(byte[] src);
1977
1978 /**
1979 * Transfers the specified source array's data to this buffer starting at
1980 * the current {@code writerIndex} and increases the {@code writerIndex}
1981 * by the number of the transferred bytes (= {@code length}).
1982 * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
1983 * will be called in an attempt to expand capacity to accommodate.
1984 *
1985 * @param srcIndex the first index of the source
1986 * @param length the number of bytes to transfer
1987 *
1988 * @throws IndexOutOfBoundsException
1989 * if the specified {@code srcIndex} is less than {@code 0}, or
1990 * if {@code srcIndex + length} is greater than {@code src.length}
1991 */
1992 public abstract ByteBuf writeBytes(byte[] src, int srcIndex, int length);
1993
1994 /**
1995 * Transfers the specified source buffer's data to this buffer starting at
1996 * the current {@code writerIndex} until the source buffer's position
1997 * reaches its limit, and increases the {@code writerIndex} by the
1998 * number of the transferred bytes.
1999 * If {@code this.writableBytes} is less than {@code src.remaining()},
2000 * {@link #ensureWritable(int)} will be called in an attempt to expand
2001 * capacity to accommodate.
2002 */
2003 public abstract ByteBuf writeBytes(ByteBuffer src);
2004
2005 /**
2006 * Transfers the content of the specified stream to this buffer
2007 * starting at the current {@code writerIndex} and increases the
2008 * {@code writerIndex} by the number of the transferred bytes.
2009 * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
2010 * will be called in an attempt to expand capacity to accommodate.
2011 *
2012 * @param length the number of bytes to transfer
2013 *
2014 * @return the actual number of bytes read in from the specified channel.
2015 * {@code -1} if the specified {@link InputStream} reached EOF.
2016 *
2017 * @throws IOException if the specified stream threw an exception during I/O
2018 */
2019 public abstract int writeBytes(InputStream in, int length) throws IOException;
2020
2021 /**
2022 * Transfers the content of the specified channel to this buffer
2023 * starting at the current {@code writerIndex} and increases the
2024 * {@code writerIndex} by the number of the transferred bytes.
2025 * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
2026 * will be called in an attempt to expand capacity to accommodate.
2027 *
2028 * @param length the maximum number of bytes to transfer
2029 *
2030 * @return the actual number of bytes read in from the specified channel.
2031 * {@code -1} if the specified channel is closed or reached EOF.
2032 *
2033 * @throws IOException
2034 * if the specified channel threw an exception during I/O
2035 */
2036 public abstract int writeBytes(ScatteringByteChannel in, int length) throws IOException;
2037
2038 /**
2039 * Transfers the content of the specified channel starting at the given file position
2040 * to this buffer starting at the current {@code writerIndex} and increases the
2041 * {@code writerIndex} by the number of the transferred bytes.
2042 * This method does not modify the channel's position.
2043 * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
2044 * will be called in an attempt to expand capacity to accommodate.
2045 *
2046 * @param position the file position at which the transfer is to begin
2047 * @param length the maximum number of bytes to transfer
2048 *
2049 * @return the actual number of bytes read in from the specified channel.
2050 * {@code -1} if the specified channel is closed or reached EOF.
2051 *
2052 * @throws IOException
2053 * if the specified channel threw an exception during I/O
2054 */
2055 public abstract int writeBytes(FileChannel in, long position, int length) throws IOException;
2056
2057 /**
2058 * Fills this buffer with <tt>NUL (0x00)</tt> starting at the current
2059 * {@code writerIndex} and increases the {@code writerIndex} by the
2060 * specified {@code length}.
2061 * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
2062 * will be called in an attempt to expand capacity to accommodate.
2063 *
2064 * @param length the number of <tt>NUL</tt>s to write to the buffer
2065 */
2066 public abstract ByteBuf writeZero(int length);
2067
2068 /**
2069 * Writes the specified {@link CharSequence} at the current {@code writerIndex} and increases
2070 * the {@code writerIndex} by the written bytes.
2071 * If {@code this.writableBytes} is not large enough to write the whole sequence,
2072 * {@link #ensureWritable(int)} will be called in an attempt to expand capacity to accommodate.
2073 *
2074 * @param sequence to write
2075 * @param charset that should be used
2076 * @return the written number of bytes
2077 */
2078 public abstract int writeCharSequence(CharSequence sequence, Charset charset);
2079
2080 /**
2081 * Locates the first occurrence of the specified {@code value} in this
2082 * buffer. The search takes place from the specified {@code fromIndex}
2083 * (inclusive) to the specified {@code toIndex} (exclusive).
2084 * <p>
2085 * If {@code fromIndex} is greater than {@code toIndex}, the search is
2086 * performed in a reversed order from {@code fromIndex} (exclusive)
2087 * down to {@code toIndex} (inclusive).
2088 * <p>
2089 * Note that the lower index is always included and higher always excluded.
2090 * <p>
2091 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2092 * this buffer.
2093 *
2094 * @return the absolute index of the first occurrence if found.
2095 * {@code -1} otherwise.
2096 */
2097 public abstract int indexOf(int fromIndex, int toIndex, byte value);
2098
2099 /**
2100 * Locates the first occurrence of the specified {@code value} in this
2101 * buffer. The search takes place from the current {@code readerIndex}
2102 * (inclusive) to the current {@code writerIndex} (exclusive).
2103 * <p>
2104 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2105 * this buffer.
2106 *
2107 * @return the number of bytes between the current {@code readerIndex}
2108 * and the first occurrence if found. {@code -1} otherwise.
2109 */
2110 public abstract int bytesBefore(byte value);
2111
2112 /**
2113 * Locates the first occurrence of the specified {@code value} in this
2114 * buffer. The search starts from the current {@code readerIndex}
2115 * (inclusive) and lasts for the specified {@code length}.
2116 * <p>
2117 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2118 * this buffer.
2119 *
2120 * @return the number of bytes between the current {@code readerIndex}
2121 * and the first occurrence if found. {@code -1} otherwise.
2122 *
2123 * @throws IndexOutOfBoundsException
2124 * if {@code length} is greater than {@code this.readableBytes}
2125 */
2126 public abstract int bytesBefore(int length, byte value);
2127
2128 /**
2129 * Locates the first occurrence of the specified {@code value} in this
2130 * buffer. The search starts from the specified {@code index} (inclusive)
2131 * and lasts for the specified {@code length}.
2132 * <p>
2133 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2134 * this buffer.
2135 *
2136 * @return the number of bytes between the specified {@code index}
2137 * and the first occurrence if found. {@code -1} otherwise.
2138 *
2139 * @throws IndexOutOfBoundsException
2140 * if {@code index + length} is greater than {@code this.capacity}
2141 */
2142 public abstract int bytesBefore(int index, int length, byte value);
2143
2144 /**
2145 * Iterates over the readable bytes of this buffer with the specified {@code processor} in ascending order.
2146 *
2147 * @return {@code -1} if the processor iterated to or beyond the end of the readable bytes.
2148 * The last-visited index If the {@link ByteProcessor#process(byte)} returned {@code false}.
2149 */
2150 public abstract int forEachByte(ByteProcessor processor);
2151
2152 /**
2153 * Iterates over the specified area of this buffer with the specified {@code processor} in ascending order.
2154 * (i.e. {@code index}, {@code (index + 1)}, .. {@code (index + length - 1)})
2155 *
2156 * @return {@code -1} if the processor iterated to or beyond the end of the specified area.
2157 * The last-visited index If the {@link ByteProcessor#process(byte)} returned {@code false}.
2158 */
2159 public abstract int forEachByte(int index, int length, ByteProcessor processor);
2160
2161 /**
2162 * Iterates over the readable bytes of this buffer with the specified {@code processor} in descending order.
2163 *
2164 * @return {@code -1} if the processor iterated to or beyond the beginning of the readable bytes.
2165 * The last-visited index If the {@link ByteProcessor#process(byte)} returned {@code false}.
2166 */
2167 public abstract int forEachByteDesc(ByteProcessor processor);
2168
2169 /**
2170 * Iterates over the specified area of this buffer with the specified {@code processor} in descending order.
2171 * (i.e. {@code (index + length - 1)}, {@code (index + length - 2)}, ... {@code index})
2172 *
2173 *
2174 * @return {@code -1} if the processor iterated to or beyond the beginning of the specified area.
2175 * The last-visited index If the {@link ByteProcessor#process(byte)} returned {@code false}.
2176 */
2177 public abstract int forEachByteDesc(int index, int length, ByteProcessor processor);
2178
2179 /**
2180 * Returns a copy of this buffer's readable bytes. Modifying the content
2181 * of the returned buffer or this buffer does not affect each other at all.
2182 * This method is identical to {@code buf.copy(buf.readerIndex(), buf.readableBytes())}.
2183 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2184 * this buffer.
2185 */
2186 public abstract ByteBuf copy();
2187
2188 /**
2189 * Returns a copy of this buffer's sub-region. Modifying the content of
2190 * the returned buffer or this buffer does not affect each other at all.
2191 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2192 * this buffer.
2193 */
2194 public abstract ByteBuf copy(int index, int length);
2195
2196 /**
2197 * Returns a slice of this buffer's readable bytes. Modifying the content
2198 * of the returned buffer or this buffer affects each other's content
2199 * while they maintain separate indexes and marks. This method is
2200 * identical to {@code buf.slice(buf.readerIndex(), buf.readableBytes())}.
2201 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2202 * this buffer.
2203 * <p>
2204 * Also be aware that this method will NOT call {@link #retain()} and so the
2205 * reference count will NOT be increased.
2206 */
2207 public abstract ByteBuf slice();
2208
2209 /**
2210 * Returns a retained slice of this buffer's readable bytes. Modifying the content
2211 * of the returned buffer or this buffer affects each other's content
2212 * while they maintain separate indexes and marks. This method is
2213 * identical to {@code buf.slice(buf.readerIndex(), buf.readableBytes())}.
2214 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2215 * this buffer.
2216 * <p>
2217 * Note that this method returns a {@linkplain #retain() retained} buffer unlike {@link #slice()}.
2218 * This method behaves similarly to {@code slice().retain()} except that this method may return
2219 * a buffer implementation that produces less garbage.
2220 */
2221 public abstract ByteBuf retainedSlice();
2222
2223 /**
2224 * Returns a slice of this buffer's sub-region. Modifying the content of
2225 * the returned buffer or this buffer affects each other's content while
2226 * they maintain separate indexes and marks.
2227 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2228 * this buffer.
2229 * <p>
2230 * Also be aware that this method will NOT call {@link #retain()} and so the
2231 * reference count will NOT be increased.
2232 */
2233 public abstract ByteBuf slice(int index, int length);
2234
2235 /**
2236 * Returns a retained slice of this buffer's sub-region. Modifying the content of
2237 * the returned buffer or this buffer affects each other's content while
2238 * they maintain separate indexes and marks.
2239 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2240 * this buffer.
2241 * <p>
2242 * Note that this method returns a {@linkplain #retain() retained} buffer unlike {@link #slice(int, int)}.
2243 * This method behaves similarly to {@code slice(...).retain()} except that this method may return
2244 * a buffer implementation that produces less garbage.
2245 */
2246 public abstract ByteBuf retainedSlice(int index, int length);
2247
2248 /**
2249 * Returns a buffer which shares the whole region of this buffer.
2250 * Modifying the content of the returned buffer or this buffer affects
2251 * each other's content while they maintain separate indexes and marks.
2252 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2253 * this buffer.
2254 * <p>
2255 * The reader and writer marks will not be duplicated. Also be aware that this method will
2256 * NOT call {@link #retain()} and so the reference count will NOT be increased.
2257 * @return A buffer whose readable content is equivalent to the buffer returned by {@link #slice()}.
2258 * However this buffer will share the capacity of the underlying buffer, and therefore allows access to all of the
2259 * underlying content if necessary.
2260 */
2261 public abstract ByteBuf duplicate();
2262
2263 /**
2264 * Returns a retained buffer which shares the whole region of this buffer.
2265 * Modifying the content of the returned buffer or this buffer affects
2266 * each other's content while they maintain separate indexes and marks.
2267 * This method is identical to {@code buf.slice(0, buf.capacity())}.
2268 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2269 * this buffer.
2270 * <p>
2271 * Note that this method returns a {@linkplain #retain() retained} buffer unlike {@link #slice(int, int)}.
2272 * This method behaves similarly to {@code duplicate().retain()} except that this method may return
2273 * a buffer implementation that produces less garbage.
2274 */
2275 public abstract ByteBuf retainedDuplicate();
2276
2277 /**
2278 * Returns the maximum number of NIO {@link ByteBuffer}s that consist this buffer. Note that {@link #nioBuffers()}
2279 * or {@link #nioBuffers(int, int)} might return a less number of {@link ByteBuffer}s.
2280 *
2281 * @return {@code -1} if this buffer has no underlying {@link ByteBuffer}.
2282 * the number of the underlying {@link ByteBuffer}s if this buffer has at least one underlying
2283 * {@link ByteBuffer}. Note that this method does not return {@code 0} to avoid confusion.
2284 *
2285 * @see #nioBuffer()
2286 * @see #nioBuffer(int, int)
2287 * @see #nioBuffers()
2288 * @see #nioBuffers(int, int)
2289 */
2290 public abstract int nioBufferCount();
2291
2292 /**
2293 * Exposes this buffer's readable bytes as an NIO {@link ByteBuffer}. The returned buffer
2294 * either share or contains the copied content of this buffer, while changing the position
2295 * and limit of the returned NIO buffer does not affect the indexes and marks of this buffer.
2296 * This method is identical to {@code buf.nioBuffer(buf.readerIndex(), buf.readableBytes())}.
2297 * This method does not modify {@code readerIndex} or {@code writerIndex} of this buffer.
2298 * Please note that the returned NIO buffer will not see the changes of this buffer if this buffer
2299 * is a dynamic buffer and it adjusted its capacity.
2300 *
2301 * @throws UnsupportedOperationException
2302 * if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
2303 *
2304 * @see #nioBufferCount()
2305 * @see #nioBuffers()
2306 * @see #nioBuffers(int, int)
2307 */
2308 public abstract ByteBuffer nioBuffer();
2309
2310 /**
2311 * Exposes this buffer's sub-region as an NIO {@link ByteBuffer}. The returned buffer
2312 * either share or contains the copied content of this buffer, while changing the position
2313 * and limit of the returned NIO buffer does not affect the indexes and marks of this buffer.
2314 * This method does not modify {@code readerIndex} or {@code writerIndex} of this buffer.
2315 * Please note that the returned NIO buffer will not see the changes of this buffer if this buffer
2316 * is a dynamic buffer and it adjusted its capacity.
2317 *
2318 * @throws UnsupportedOperationException
2319 * if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
2320 *
2321 * @see #nioBufferCount()
2322 * @see #nioBuffers()
2323 * @see #nioBuffers(int, int)
2324 */
2325 public abstract ByteBuffer nioBuffer(int index, int length);
2326
2327 /**
2328 * Internal use only: Exposes the internal NIO buffer.
2329 */
2330 public abstract ByteBuffer internalNioBuffer(int index, int length);
2331
2332 /**
2333 * Exposes this buffer's readable bytes as an NIO {@link ByteBuffer}'s. The returned buffer
2334 * either share or contains the copied content of this buffer, while changing the position
2335 * and limit of the returned NIO buffer does not affect the indexes and marks of this buffer.
2336 * This method does not modify {@code readerIndex} or {@code writerIndex} of this buffer.
2337 * Please note that the returned NIO buffer will not see the changes of this buffer if this buffer
2338 * is a dynamic buffer and it adjusted its capacity.
2339 *
2340 *
2341 * @throws UnsupportedOperationException
2342 * if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
2343 *
2344 * @see #nioBufferCount()
2345 * @see #nioBuffer()
2346 * @see #nioBuffer(int, int)
2347 */
2348 public abstract ByteBuffer[] nioBuffers();
2349
2350 /**
2351 * Exposes this buffer's bytes as an NIO {@link ByteBuffer}'s for the specified index and length
2352 * The returned buffer either share or contains the copied content of this buffer, while changing
2353 * the position and limit of the returned NIO buffer does not affect the indexes and marks of this buffer.
2354 * This method does not modify {@code readerIndex} or {@code writerIndex} of this buffer. Please note that the
2355 * returned NIO buffer will not see the changes of this buffer if this buffer is a dynamic
2356 * buffer and it adjusted its capacity.
2357 *
2358 * @throws UnsupportedOperationException
2359 * if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
2360 *
2361 * @see #nioBufferCount()
2362 * @see #nioBuffer()
2363 * @see #nioBuffer(int, int)
2364 */
2365 public abstract ByteBuffer[] nioBuffers(int index, int length);
2366
2367 /**
2368 * Returns {@code true} if and only if this buffer has a backing byte array.
2369 * If this method returns true, you can safely call {@link #array()} and
2370 * {@link #arrayOffset()}.
2371 */
2372 public abstract boolean hasArray();
2373
2374 /**
2375 * Returns the backing byte array of this buffer.
2376 *
2377 * @throws UnsupportedOperationException
2378 * if there no accessible backing byte array
2379 */
2380 public abstract byte[] array();
2381
2382 /**
2383 * Returns the offset of the first byte within the backing byte array of
2384 * this buffer.
2385 *
2386 * @throws UnsupportedOperationException
2387 * if there no accessible backing byte array
2388 */
2389 public abstract int arrayOffset();
2390
2391 /**
2392 * Returns {@code true} if and only if this buffer has a reference to the low-level memory address that points
2393 * to the backing data.
2394 */
2395 public abstract boolean hasMemoryAddress();
2396
2397 /**
2398 * Returns the low-level memory address that point to the first byte of ths backing data.
2399 *
2400 * @throws UnsupportedOperationException
2401 * if this buffer does not support accessing the low-level memory address
2402 */
2403 public abstract long memoryAddress();
2404
2405 /**
2406 * Returns {@code true} if this {@link ByteBuf} implementation is backed by a single memory region.
2407 * Composite buffer implementations must return false even if they currently hold ≤ 1 components.
2408 * For buffers that return {@code true}, it's guaranteed that a successful call to {@link #discardReadBytes()}
2409 * will increase the value of {@link #maxFastWritableBytes()} by the current {@code readerIndex}.
2410 * <p>
2411 * This method will return {@code false} by default, and a {@code false} return value does not necessarily
2412 * mean that the implementation is composite or that it is <i>not</i> backed by a single memory region.
2413 */
2414 public boolean isContiguous() {
2415 return false;
2416 }
2417
2418 /**
2419 * A {@code ByteBuf} can turn into itself.
2420 * @return This {@code ByteBuf} instance.
2421 */
2422 @Override
2423 public ByteBuf asByteBuf() {
2424 return this;
2425 }
2426
2427 /**
2428 * Decodes this buffer's readable bytes into a string with the specified
2429 * character set name. This method is identical to
2430 * {@code buf.toString(buf.readerIndex(), buf.readableBytes(), charsetName)}.
2431 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2432 * this buffer.
2433 *
2434 * @throws UnsupportedCharsetException
2435 * if the specified character set name is not supported by the
2436 * current VM
2437 */
2438 public abstract String toString(Charset charset);
2439
2440 /**
2441 * Decodes this buffer's sub-region into a string with the specified
2442 * character set. This method does not modify {@code readerIndex} or
2443 * {@code writerIndex} of this buffer.
2444 */
2445 public abstract String toString(int index, int length, Charset charset);
2446
2447 /**
2448 * Returns a hash code which was calculated from the content of this
2449 * buffer. If there's a byte array which is
2450 * {@linkplain #equals(Object) equal to} this array, both arrays should
2451 * return the same value.
2452 */
2453 @Override
2454 public abstract int hashCode();
2455
2456 /**
2457 * Determines if the content of the specified buffer is identical to the
2458 * content of this array. 'Identical' here means:
2459 * <ul>
2460 * <li>the size of the contents of the two buffers are same and</li>
2461 * <li>every single byte of the content of the two buffers are same.</li>
2462 * </ul>
2463 * Please note that it does not compare {@link #readerIndex()} nor
2464 * {@link #writerIndex()}. This method also returns {@code false} for
2465 * {@code null} and an object which is not an instance of
2466 * {@link ByteBuf} type.
2467 */
2468 @Override
2469 public abstract boolean equals(Object obj);
2470
2471 /**
2472 * Compares the content of the specified buffer to the content of this
2473 * buffer. Comparison is performed in the same manner with the string
2474 * comparison functions of various languages such as {@code strcmp},
2475 * {@code memcmp} and {@link String#compareTo(String)}.
2476 */
2477 @Override
2478 public abstract int compareTo(ByteBuf buffer);
2479
2480 /**
2481 * Returns the string representation of this buffer. This method does not
2482 * necessarily return the whole content of the buffer but returns
2483 * the values of the key properties such as {@link #readerIndex()},
2484 * {@link #writerIndex()} and {@link #capacity()}.
2485 */
2486 @Override
2487 public abstract String toString();
2488
2489 @Override
2490 public abstract ByteBuf retain(int increment);
2491
2492 @Override
2493 public abstract ByteBuf retain();
2494
2495 @Override
2496 public abstract ByteBuf touch();
2497
2498 @Override
2499 public abstract ByteBuf touch(Object hint);
2500
2501 /**
2502 * Used internally by {@link AbstractByteBuf#ensureAccessible()} to try to guard
2503 * against using the buffer after it was released (best-effort).
2504 */
2505 boolean isAccessible() {
2506 return refCnt() != 0;
2507 }
2508 }