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 a 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 it 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 it 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 * Transfers this buffer's data starting at the current {@code readerIndex}
1741 * to the specified channel starting at the given file position.
1742 * This method does not modify the channel's position.
1743 *
1744 * @param position the file position at which the transfer is to begin
1745 * @param length the maximum number of bytes to transfer
1746 *
1747 * @return the actual number of bytes written out to the specified channel
1748 *
1749 * @throws IndexOutOfBoundsException
1750 * if {@code length} is greater than {@code this.readableBytes}
1751 * @throws IOException
1752 * if the specified channel threw an exception during I/O
1753 */
1754 public abstract int readBytes(FileChannel out, long position, int length) throws IOException;
1755
1756 /**
1757 * Increases the current {@code readerIndex} by the specified
1758 * {@code length} in this buffer.
1759 *
1760 * @throws IndexOutOfBoundsException
1761 * if {@code length} is greater than {@code this.readableBytes}
1762 */
1763 public abstract ByteBuf skipBytes(int length);
1764
1765 /**
1766 * Sets the specified boolean at the current {@code writerIndex}
1767 * and increases the {@code writerIndex} by {@code 1} in this buffer.
1768 * If {@code this.writableBytes} is less than {@code 1}, {@link #ensureWritable(int)}
1769 * will be called in an attempt to expand capacity to accommodate.
1770 */
1771 public abstract ByteBuf writeBoolean(boolean value);
1772
1773 /**
1774 * Sets the specified byte at the current {@code writerIndex}
1775 * and increases the {@code writerIndex} by {@code 1} in this buffer.
1776 * The 24 high-order bits of the specified value are ignored.
1777 * If {@code this.writableBytes} is less than {@code 1}, {@link #ensureWritable(int)}
1778 * will be called in an attempt to expand capacity to accommodate.
1779 */
1780 public abstract ByteBuf writeByte(int value);
1781
1782 /**
1783 * Sets the specified 16-bit short integer at the current
1784 * {@code writerIndex} and increases the {@code writerIndex} by {@code 2}
1785 * in this buffer. The 16 high-order bits of the specified value are ignored.
1786 * If {@code this.writableBytes} is less than {@code 2}, {@link #ensureWritable(int)}
1787 * will be called in an attempt to expand capacity to accommodate.
1788 */
1789 public abstract ByteBuf writeShort(int value);
1790
1791 /**
1792 * Sets the specified 16-bit short integer in the Little Endian Byte
1793 * Order at the current {@code writerIndex} and increases the
1794 * {@code writerIndex} by {@code 2} in this buffer.
1795 * The 16 high-order bits of the specified value are ignored.
1796 * If {@code this.writableBytes} is less than {@code 2}, {@link #ensureWritable(int)}
1797 * will be called in an attempt to expand capacity to accommodate.
1798 */
1799 public abstract ByteBuf writeShortLE(int value);
1800
1801 /**
1802 * Sets the specified 24-bit medium integer at the current
1803 * {@code writerIndex} and increases the {@code writerIndex} by {@code 3}
1804 * in this buffer.
1805 * If {@code this.writableBytes} is less than {@code 3}, {@link #ensureWritable(int)}
1806 * will be called in an attempt to expand capacity to accommodate.
1807 */
1808 public abstract ByteBuf writeMedium(int value);
1809
1810 /**
1811 * Sets the specified 24-bit medium integer at the current
1812 * {@code writerIndex} in the Little Endian Byte Order and
1813 * increases the {@code writerIndex} by {@code 3} in this
1814 * buffer.
1815 * If {@code this.writableBytes} is less than {@code 3}, {@link #ensureWritable(int)}
1816 * will be called in an attempt to expand capacity to accommodate.
1817 */
1818 public abstract ByteBuf writeMediumLE(int value);
1819
1820 /**
1821 * Sets the specified 32-bit integer at the current {@code writerIndex}
1822 * and increases the {@code writerIndex} by {@code 4} in this buffer.
1823 * If {@code this.writableBytes} is less than {@code 4}, {@link #ensureWritable(int)}
1824 * will be called in an attempt to expand capacity to accommodate.
1825 */
1826 public abstract ByteBuf writeInt(int value);
1827
1828 /**
1829 * Sets the specified 32-bit integer at the current {@code writerIndex}
1830 * in the Little Endian Byte Order and increases the {@code writerIndex}
1831 * by {@code 4} in this buffer.
1832 * If {@code this.writableBytes} is less than {@code 4}, {@link #ensureWritable(int)}
1833 * will be called in an attempt to expand capacity to accommodate.
1834 */
1835 public abstract ByteBuf writeIntLE(int value);
1836
1837 /**
1838 * Sets the specified 64-bit long integer at the current
1839 * {@code writerIndex} and increases the {@code writerIndex} by {@code 8}
1840 * in this buffer.
1841 * If {@code this.writableBytes} is less than {@code 8}, {@link #ensureWritable(int)}
1842 * will be called in an attempt to expand capacity to accommodate.
1843 */
1844 public abstract ByteBuf writeLong(long value);
1845
1846 /**
1847 * Sets the specified 64-bit long integer at the current
1848 * {@code writerIndex} in the Little Endian Byte Order and
1849 * increases the {@code writerIndex} by {@code 8}
1850 * in this buffer.
1851 * If {@code this.writableBytes} is less than {@code 8}, {@link #ensureWritable(int)}
1852 * will be called in an attempt to expand capacity to accommodate.
1853 */
1854 public abstract ByteBuf writeLongLE(long value);
1855
1856 /**
1857 * Sets the specified 2-byte UTF-16 character at the current
1858 * {@code writerIndex} and increases the {@code writerIndex} by {@code 2}
1859 * in this buffer. The 16 high-order bits of the specified value are ignored.
1860 * If {@code this.writableBytes} is less than {@code 2}, {@link #ensureWritable(int)}
1861 * will be called in an attempt to expand capacity to accommodate.
1862 */
1863 public abstract ByteBuf writeChar(int value);
1864
1865 /**
1866 * Sets the specified 32-bit floating point number at the current
1867 * {@code writerIndex} and increases the {@code writerIndex} by {@code 4}
1868 * in this buffer.
1869 * If {@code this.writableBytes} is less than {@code 4}, {@link #ensureWritable(int)}
1870 * will be called in an attempt to expand capacity to accommodate.
1871 */
1872 public abstract ByteBuf writeFloat(float value);
1873
1874 /**
1875 * Sets the specified 32-bit floating point number at the current
1876 * {@code writerIndex} in Little Endian Byte Order and increases
1877 * the {@code writerIndex} by {@code 4} in this buffer.
1878 * If {@code this.writableBytes} is less than {@code 4}, {@link #ensureWritable(int)}
1879 * will be called in an attempt to expand capacity to accommodate.
1880 */
1881 public ByteBuf writeFloatLE(float value) {
1882 return writeIntLE(Float.floatToRawIntBits(value));
1883 }
1884
1885 /**
1886 * Sets the specified 64-bit floating point number at the current
1887 * {@code writerIndex} and increases the {@code writerIndex} by {@code 8}
1888 * in this buffer.
1889 * If {@code this.writableBytes} is less than {@code 8}, {@link #ensureWritable(int)}
1890 * will be called in an attempt to expand capacity to accommodate.
1891 */
1892 public abstract ByteBuf writeDouble(double value);
1893
1894 /**
1895 * Sets the specified 64-bit floating point number at the current
1896 * {@code writerIndex} in Little Endian Byte Order and increases
1897 * the {@code writerIndex} by {@code 8} in this buffer.
1898 * If {@code this.writableBytes} is less than {@code 8}, {@link #ensureWritable(int)}
1899 * will be called in an attempt to expand capacity to accommodate.
1900 */
1901 public ByteBuf writeDoubleLE(double value) {
1902 return writeLongLE(Double.doubleToRawLongBits(value));
1903 }
1904
1905 /**
1906 * Transfers the specified source buffer's data to this buffer starting at
1907 * the current {@code writerIndex} until the source buffer becomes
1908 * unreadable, and increases the {@code writerIndex} by the number of
1909 * the transferred bytes. This method is basically same with
1910 * {@link #writeBytes(ByteBuf, int, int)}, except that this method
1911 * increases the {@code readerIndex} of the source buffer by the number of
1912 * the transferred bytes while {@link #writeBytes(ByteBuf, int, int)}
1913 * does not.
1914 * If {@code this.writableBytes} is less than {@code src.readableBytes},
1915 * {@link #ensureWritable(int)} will be called in an attempt to expand
1916 * capacity to accommodate.
1917 */
1918 public abstract ByteBuf writeBytes(ByteBuf src);
1919
1920 /**
1921 * Transfers the specified source buffer's data to this buffer starting at
1922 * the current {@code writerIndex} and increases the {@code writerIndex}
1923 * by the number of the transferred bytes (= {@code length}). This method
1924 * is basically same with {@link #writeBytes(ByteBuf, int, int)},
1925 * except that this method increases the {@code readerIndex} of the source
1926 * buffer by the number of the transferred bytes (= {@code length}) while
1927 * {@link #writeBytes(ByteBuf, int, int)} does not.
1928 * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
1929 * will be called in an attempt to expand capacity to accommodate.
1930 *
1931 * @param length the number of bytes to transfer
1932 * @throws IndexOutOfBoundsException if {@code length} is greater then {@code src.readableBytes}
1933 */
1934 public abstract ByteBuf writeBytes(ByteBuf src, int length);
1935
1936 /**
1937 * Transfers the specified source buffer's data to this buffer starting at
1938 * the current {@code writerIndex} and increases the {@code writerIndex}
1939 * by the number of the transferred bytes (= {@code length}).
1940 * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
1941 * will be called in an attempt to expand capacity to accommodate.
1942 *
1943 * @param srcIndex the first index of the source
1944 * @param length the number of bytes to transfer
1945 *
1946 * @throws IndexOutOfBoundsException
1947 * if the specified {@code srcIndex} is less than {@code 0}, or
1948 * if {@code srcIndex + length} is greater than {@code src.capacity}
1949 */
1950 public abstract ByteBuf writeBytes(ByteBuf src, int srcIndex, int length);
1951
1952 /**
1953 * Transfers the specified source array's data to this buffer starting at
1954 * the current {@code writerIndex} and increases the {@code writerIndex}
1955 * by the number of the transferred bytes (= {@code src.length}).
1956 * If {@code this.writableBytes} is less than {@code src.length}, {@link #ensureWritable(int)}
1957 * will be called in an attempt to expand capacity to accommodate.
1958 */
1959 public abstract ByteBuf writeBytes(byte[] src);
1960
1961 /**
1962 * Transfers the specified source array's data to this buffer starting at
1963 * the current {@code writerIndex} and increases the {@code writerIndex}
1964 * by the number of the transferred bytes (= {@code length}).
1965 * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
1966 * will be called in an attempt to expand capacity to accommodate.
1967 *
1968 * @param srcIndex the first index of the source
1969 * @param length the number of bytes to transfer
1970 *
1971 * @throws IndexOutOfBoundsException
1972 * if the specified {@code srcIndex} is less than {@code 0}, or
1973 * if {@code srcIndex + length} is greater than {@code src.length}
1974 */
1975 public abstract ByteBuf writeBytes(byte[] src, int srcIndex, int length);
1976
1977 /**
1978 * Transfers the specified source buffer's data to this buffer starting at
1979 * the current {@code writerIndex} until the source buffer's position
1980 * reaches its limit, and increases the {@code writerIndex} by the
1981 * number of the transferred bytes.
1982 * If {@code this.writableBytes} is less than {@code src.remaining()},
1983 * {@link #ensureWritable(int)} will be called in an attempt to expand
1984 * capacity to accommodate.
1985 */
1986 public abstract ByteBuf writeBytes(ByteBuffer src);
1987
1988 /**
1989 * Transfers the content of the specified stream to this buffer
1990 * starting at the current {@code writerIndex} and increases the
1991 * {@code writerIndex} by the number of the transferred bytes.
1992 * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
1993 * will be called in an attempt to expand capacity to accommodate.
1994 *
1995 * @param length the number of bytes to transfer
1996 *
1997 * @return the actual number of bytes read in from the specified channel.
1998 * {@code -1} if the specified {@link InputStream} reached EOF.
1999 *
2000 * @throws IOException if the specified stream threw an exception during I/O
2001 */
2002 public abstract int writeBytes(InputStream in, int length) throws IOException;
2003
2004 /**
2005 * Transfers the content of the specified channel to this buffer
2006 * starting at the current {@code writerIndex} and increases the
2007 * {@code writerIndex} by the number of the transferred bytes.
2008 * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
2009 * will be called in an attempt to expand capacity to accommodate.
2010 *
2011 * @param length the maximum number of bytes to transfer
2012 *
2013 * @return the actual number of bytes read in from the specified channel.
2014 * {@code -1} if the specified channel is closed or it reached EOF.
2015 *
2016 * @throws IOException
2017 * if the specified channel threw an exception during I/O
2018 */
2019 public abstract int writeBytes(ScatteringByteChannel in, int length) throws IOException;
2020
2021 /**
2022 * Transfers the content of the specified channel starting at the given file position
2023 * to this buffer starting at the current {@code writerIndex} and increases the
2024 * {@code writerIndex} by the number of the transferred bytes.
2025 * This method does not modify the channel's position.
2026 * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
2027 * will be called in an attempt to expand capacity to accommodate.
2028 *
2029 * @param position the file position at which the transfer is to begin
2030 * @param length the maximum number of bytes to transfer
2031 *
2032 * @return the actual number of bytes read in from the specified channel.
2033 * {@code -1} if the specified channel is closed or it reached EOF.
2034 *
2035 * @throws IOException
2036 * if the specified channel threw an exception during I/O
2037 */
2038 public abstract int writeBytes(FileChannel in, long position, int length) throws IOException;
2039
2040 /**
2041 * Fills this buffer with <tt>NUL (0x00)</tt> starting at the current
2042 * {@code writerIndex} and increases the {@code writerIndex} by the
2043 * specified {@code length}.
2044 * If {@code this.writableBytes} is less than {@code length}, {@link #ensureWritable(int)}
2045 * will be called in an attempt to expand capacity to accommodate.
2046 *
2047 * @param length the number of <tt>NUL</tt>s to write to the buffer
2048 */
2049 public abstract ByteBuf writeZero(int length);
2050
2051 /**
2052 * Writes the specified {@link CharSequence} at the current {@code writerIndex} and increases
2053 * the {@code writerIndex} by the written bytes.
2054 * in this buffer.
2055 * If {@code this.writableBytes} is not large enough to write the whole sequence,
2056 * {@link #ensureWritable(int)} will be called in an attempt to expand capacity to accommodate.
2057 *
2058 * @param sequence to write
2059 * @param charset that should be used
2060 * @return the written number of bytes
2061 */
2062 public abstract int writeCharSequence(CharSequence sequence, Charset charset);
2063
2064 /**
2065 * Locates the first occurrence of the specified {@code value} in this
2066 * buffer. The search takes place from the specified {@code fromIndex}
2067 * (inclusive) to the specified {@code toIndex} (exclusive).
2068 * <p>
2069 * If {@code fromIndex} is greater than {@code toIndex}, the search is
2070 * performed in a reversed order from {@code fromIndex} (exclusive)
2071 * down to {@code toIndex} (inclusive).
2072 * <p>
2073 * Note that the lower index is always included and higher always excluded.
2074 * <p>
2075 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2076 * this buffer.
2077 *
2078 * @return the absolute index of the first occurrence if found.
2079 * {@code -1} otherwise.
2080 */
2081 public abstract int indexOf(int fromIndex, int toIndex, byte value);
2082
2083 /**
2084 * Locates the first occurrence of the specified {@code value} in this
2085 * buffer. The search takes place from the current {@code readerIndex}
2086 * (inclusive) to the current {@code writerIndex} (exclusive).
2087 * <p>
2088 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2089 * this buffer.
2090 *
2091 * @return the number of bytes between the current {@code readerIndex}
2092 * and the first occurrence if found. {@code -1} otherwise.
2093 */
2094 public abstract int bytesBefore(byte value);
2095
2096 /**
2097 * Locates the first occurrence of the specified {@code value} in this
2098 * buffer. The search starts from the current {@code readerIndex}
2099 * (inclusive) and lasts for the specified {@code length}.
2100 * <p>
2101 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2102 * this buffer.
2103 *
2104 * @return the number of bytes between the current {@code readerIndex}
2105 * and the first occurrence if found. {@code -1} otherwise.
2106 *
2107 * @throws IndexOutOfBoundsException
2108 * if {@code length} is greater than {@code this.readableBytes}
2109 */
2110 public abstract int bytesBefore(int length, byte value);
2111
2112 /**
2113 * Locates the first occurrence of the specified {@code value} in this
2114 * buffer. The search starts from the specified {@code index} (inclusive)
2115 * 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 specified {@code index}
2121 * and the first occurrence if found. {@code -1} otherwise.
2122 *
2123 * @throws IndexOutOfBoundsException
2124 * if {@code index + length} is greater than {@code this.capacity}
2125 */
2126 public abstract int bytesBefore(int index, int length, byte value);
2127
2128 /**
2129 * Iterates over the readable bytes of this buffer with the specified {@code processor} in ascending order.
2130 *
2131 * @return {@code -1} if the processor iterated to or beyond the end of the readable bytes.
2132 * The last-visited index If the {@link ByteProcessor#process(byte)} returned {@code false}.
2133 */
2134 public abstract int forEachByte(ByteProcessor processor);
2135
2136 /**
2137 * Iterates over the specified area of this buffer with the specified {@code processor} in ascending order.
2138 * (i.e. {@code index}, {@code (index + 1)}, .. {@code (index + length - 1)})
2139 *
2140 * @return {@code -1} if the processor iterated to or beyond the end of the specified area.
2141 * The last-visited index If the {@link ByteProcessor#process(byte)} returned {@code false}.
2142 */
2143 public abstract int forEachByte(int index, int length, ByteProcessor processor);
2144
2145 /**
2146 * Iterates over the readable bytes of this buffer with the specified {@code processor} in descending order.
2147 *
2148 * @return {@code -1} if the processor iterated to or beyond the beginning of the readable bytes.
2149 * The last-visited index If the {@link ByteProcessor#process(byte)} returned {@code false}.
2150 */
2151 public abstract int forEachByteDesc(ByteProcessor processor);
2152
2153 /**
2154 * Iterates over the specified area of this buffer with the specified {@code processor} in descending order.
2155 * (i.e. {@code (index + length - 1)}, {@code (index + length - 2)}, ... {@code index})
2156 *
2157 *
2158 * @return {@code -1} if the processor iterated to or beyond the beginning of the specified area.
2159 * The last-visited index If the {@link ByteProcessor#process(byte)} returned {@code false}.
2160 */
2161 public abstract int forEachByteDesc(int index, int length, ByteProcessor processor);
2162
2163 /**
2164 * Returns a copy of this buffer's readable bytes. Modifying the content
2165 * of the returned buffer or this buffer does not affect each other at all.
2166 * This method is identical to {@code buf.copy(buf.readerIndex(), buf.readableBytes())}.
2167 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2168 * this buffer.
2169 */
2170 public abstract ByteBuf copy();
2171
2172 /**
2173 * Returns a copy of this buffer's sub-region. Modifying the content of
2174 * the returned buffer or this buffer does not affect each other at all.
2175 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2176 * this buffer.
2177 */
2178 public abstract ByteBuf copy(int index, int length);
2179
2180 /**
2181 * Returns a slice of this buffer's readable bytes. Modifying the content
2182 * of the returned buffer or this buffer affects each other's content
2183 * while they maintain separate indexes and marks. This method is
2184 * identical to {@code buf.slice(buf.readerIndex(), buf.readableBytes())}.
2185 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2186 * this buffer.
2187 * <p>
2188 * Also be aware that this method will NOT call {@link #retain()} and so the
2189 * reference count will NOT be increased.
2190 */
2191 public abstract ByteBuf slice();
2192
2193 /**
2194 * Returns a retained slice of this buffer's readable bytes. Modifying the content
2195 * of the returned buffer or this buffer affects each other's content
2196 * while they maintain separate indexes and marks. This method is
2197 * identical to {@code buf.slice(buf.readerIndex(), buf.readableBytes())}.
2198 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2199 * this buffer.
2200 * <p>
2201 * Note that this method returns a {@linkplain #retain() retained} buffer unlike {@link #slice()}.
2202 * This method behaves similarly to {@code slice().retain()} except that this method may return
2203 * a buffer implementation that produces less garbage.
2204 */
2205 public abstract ByteBuf retainedSlice();
2206
2207 /**
2208 * Returns a slice of this buffer's sub-region. Modifying the content of
2209 * the returned buffer or this buffer affects each other's content while
2210 * they maintain separate indexes and marks.
2211 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2212 * this buffer.
2213 * <p>
2214 * Also be aware that this method will NOT call {@link #retain()} and so the
2215 * reference count will NOT be increased.
2216 */
2217 public abstract ByteBuf slice(int index, int length);
2218
2219 /**
2220 * Returns a retained slice of this buffer's sub-region. Modifying the content of
2221 * the returned buffer or this buffer affects each other's content while
2222 * they maintain separate indexes and marks.
2223 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2224 * this buffer.
2225 * <p>
2226 * Note that this method returns a {@linkplain #retain() retained} buffer unlike {@link #slice(int, int)}.
2227 * This method behaves similarly to {@code slice(...).retain()} except that this method may return
2228 * a buffer implementation that produces less garbage.
2229 */
2230 public abstract ByteBuf retainedSlice(int index, int length);
2231
2232 /**
2233 * Returns a buffer which shares the whole region of this buffer.
2234 * Modifying the content of the returned buffer or this buffer affects
2235 * each other's content while they maintain separate indexes and marks.
2236 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2237 * this buffer.
2238 * <p>
2239 * The reader and writer marks will not be duplicated. Also be aware that this method will
2240 * NOT call {@link #retain()} and so the reference count will NOT be increased.
2241 * @return A buffer whose readable content is equivalent to the buffer returned by {@link #slice()}.
2242 * However this buffer will share the capacity of the underlying buffer, and therefore allows access to all of the
2243 * underlying content if necessary.
2244 */
2245 public abstract ByteBuf duplicate();
2246
2247 /**
2248 * Returns a retained buffer which shares the whole region of this buffer.
2249 * Modifying the content of the returned buffer or this buffer affects
2250 * each other's content while they maintain separate indexes and marks.
2251 * This method is identical to {@code buf.slice(0, buf.capacity())}.
2252 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2253 * this buffer.
2254 * <p>
2255 * Note that this method returns a {@linkplain #retain() retained} buffer unlike {@link #slice(int, int)}.
2256 * This method behaves similarly to {@code duplicate().retain()} except that this method may return
2257 * a buffer implementation that produces less garbage.
2258 */
2259 public abstract ByteBuf retainedDuplicate();
2260
2261 /**
2262 * Returns the maximum number of NIO {@link ByteBuffer}s that consist this buffer. Note that {@link #nioBuffers()}
2263 * or {@link #nioBuffers(int, int)} might return a less number of {@link ByteBuffer}s.
2264 *
2265 * @return {@code -1} if this buffer has no underlying {@link ByteBuffer}.
2266 * the number of the underlying {@link ByteBuffer}s if this buffer has at least one underlying
2267 * {@link ByteBuffer}. Note that this method does not return {@code 0} to avoid confusion.
2268 *
2269 * @see #nioBuffer()
2270 * @see #nioBuffer(int, int)
2271 * @see #nioBuffers()
2272 * @see #nioBuffers(int, int)
2273 */
2274 public abstract int nioBufferCount();
2275
2276 /**
2277 * Exposes this buffer's readable bytes as an NIO {@link ByteBuffer}. The returned buffer
2278 * either share or contains the copied content of this buffer, while changing the position
2279 * and limit of the returned NIO buffer does not affect the indexes and marks of this buffer.
2280 * This method is identical to {@code buf.nioBuffer(buf.readerIndex(), buf.readableBytes())}.
2281 * This method does not modify {@code readerIndex} or {@code writerIndex} of this buffer.
2282 * Please note that the returned NIO buffer will not see the changes of this buffer if this buffer
2283 * is a dynamic buffer and it adjusted its capacity.
2284 *
2285 * @throws UnsupportedOperationException
2286 * if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
2287 *
2288 * @see #nioBufferCount()
2289 * @see #nioBuffers()
2290 * @see #nioBuffers(int, int)
2291 */
2292 public abstract ByteBuffer nioBuffer();
2293
2294 /**
2295 * Exposes this buffer's sub-region as an NIO {@link ByteBuffer}. The returned buffer
2296 * either share or contains the copied content of this buffer, while changing the position
2297 * and limit of the returned NIO buffer does not affect the indexes and marks of this buffer.
2298 * This method does not modify {@code readerIndex} or {@code writerIndex} of this buffer.
2299 * Please note that the returned NIO buffer will not see the changes of this buffer if this buffer
2300 * is a dynamic buffer and it adjusted its capacity.
2301 *
2302 * @throws UnsupportedOperationException
2303 * if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
2304 *
2305 * @see #nioBufferCount()
2306 * @see #nioBuffers()
2307 * @see #nioBuffers(int, int)
2308 */
2309 public abstract ByteBuffer nioBuffer(int index, int length);
2310
2311 /**
2312 * Internal use only: Exposes the internal NIO buffer.
2313 */
2314 public abstract ByteBuffer internalNioBuffer(int index, int length);
2315
2316 /**
2317 * Exposes this buffer's readable bytes as an NIO {@link ByteBuffer}'s. The returned buffer
2318 * either share or contains the copied content of this buffer, while changing the position
2319 * and limit of the returned NIO buffer does not affect the indexes and marks of this buffer.
2320 * This method does not modify {@code readerIndex} or {@code writerIndex} of this buffer.
2321 * Please note that the returned NIO buffer will not see the changes of this buffer if this buffer
2322 * is a dynamic buffer and it adjusted its capacity.
2323 *
2324 *
2325 * @throws UnsupportedOperationException
2326 * if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
2327 *
2328 * @see #nioBufferCount()
2329 * @see #nioBuffer()
2330 * @see #nioBuffer(int, int)
2331 */
2332 public abstract ByteBuffer[] nioBuffers();
2333
2334 /**
2335 * Exposes this buffer's bytes as an NIO {@link ByteBuffer}'s for the specified index and length
2336 * The returned buffer either share or contains the copied content of this buffer, while changing
2337 * the position and limit of the returned NIO buffer does not affect the indexes and marks of this buffer.
2338 * This method does not modify {@code readerIndex} or {@code writerIndex} of this buffer. Please note that the
2339 * returned NIO buffer will not see the changes of this buffer if this buffer is a dynamic
2340 * buffer and it adjusted its capacity.
2341 *
2342 * @throws UnsupportedOperationException
2343 * if this buffer cannot create a {@link ByteBuffer} that shares the content with itself
2344 *
2345 * @see #nioBufferCount()
2346 * @see #nioBuffer()
2347 * @see #nioBuffer(int, int)
2348 */
2349 public abstract ByteBuffer[] nioBuffers(int index, int length);
2350
2351 /**
2352 * Returns {@code true} if and only if this buffer has a backing byte array.
2353 * If this method returns true, you can safely call {@link #array()} and
2354 * {@link #arrayOffset()}.
2355 */
2356 public abstract boolean hasArray();
2357
2358 /**
2359 * Returns the backing byte array of this buffer.
2360 *
2361 * @throws UnsupportedOperationException
2362 * if there no accessible backing byte array
2363 */
2364 public abstract byte[] array();
2365
2366 /**
2367 * Returns the offset of the first byte within the backing byte array of
2368 * this buffer.
2369 *
2370 * @throws UnsupportedOperationException
2371 * if there no accessible backing byte array
2372 */
2373 public abstract int arrayOffset();
2374
2375 /**
2376 * Returns {@code true} if and only if this buffer has a reference to the low-level memory address that points
2377 * to the backing data.
2378 */
2379 public abstract boolean hasMemoryAddress();
2380
2381 /**
2382 * Returns the low-level memory address that point to the first byte of ths backing data.
2383 *
2384 * @throws UnsupportedOperationException
2385 * if this buffer does not support accessing the low-level memory address
2386 */
2387 public abstract long memoryAddress();
2388
2389 /**
2390 * Returns {@code true} if this {@link ByteBuf} implementation is backed by a single memory region.
2391 * Composite buffer implementations must return false even if they currently hold ≤ 1 components.
2392 * For buffers that return {@code true}, it's guaranteed that a successful call to {@link #discardReadBytes()}
2393 * will increase the value of {@link #maxFastWritableBytes()} by the current {@code readerIndex}.
2394 * <p>
2395 * This method will return {@code false} by default, and a {@code false} return value does not necessarily
2396 * mean that the implementation is composite or that it is <i>not</i> backed by a single memory region.
2397 */
2398 public boolean isContiguous() {
2399 return false;
2400 }
2401
2402 /**
2403 * A {@code ByteBuf} can turn into itself.
2404 * @return This {@code ByteBuf} instance.
2405 */
2406 @Override
2407 public ByteBuf asByteBuf() {
2408 return this;
2409 }
2410
2411 /**
2412 * Decodes this buffer's readable bytes into a string with the specified
2413 * character set name. This method is identical to
2414 * {@code buf.toString(buf.readerIndex(), buf.readableBytes(), charsetName)}.
2415 * This method does not modify {@code readerIndex} or {@code writerIndex} of
2416 * this buffer.
2417 *
2418 * @throws UnsupportedCharsetException
2419 * if the specified character set name is not supported by the
2420 * current VM
2421 */
2422 public abstract String toString(Charset charset);
2423
2424 /**
2425 * Decodes this buffer's sub-region into a string with the specified
2426 * character set. This method does not modify {@code readerIndex} or
2427 * {@code writerIndex} of this buffer.
2428 */
2429 public abstract String toString(int index, int length, Charset charset);
2430
2431 /**
2432 * Returns a hash code which was calculated from the content of this
2433 * buffer. If there's a byte array which is
2434 * {@linkplain #equals(Object) equal to} this array, both arrays should
2435 * return the same value.
2436 */
2437 @Override
2438 public abstract int hashCode();
2439
2440 /**
2441 * Determines if the content of the specified buffer is identical to the
2442 * content of this array. 'Identical' here means:
2443 * <ul>
2444 * <li>the size of the contents of the two buffers are same and</li>
2445 * <li>every single byte of the content of the two buffers are same.</li>
2446 * </ul>
2447 * Please note that it does not compare {@link #readerIndex()} nor
2448 * {@link #writerIndex()}. This method also returns {@code false} for
2449 * {@code null} and an object which is not an instance of
2450 * {@link ByteBuf} type.
2451 */
2452 @Override
2453 public abstract boolean equals(Object obj);
2454
2455 /**
2456 * Compares the content of the specified buffer to the content of this
2457 * buffer. Comparison is performed in the same manner with the string
2458 * comparison functions of various languages such as {@code strcmp},
2459 * {@code memcmp} and {@link String#compareTo(String)}.
2460 */
2461 @Override
2462 public abstract int compareTo(ByteBuf buffer);
2463
2464 /**
2465 * Returns the string representation of this buffer. This method does not
2466 * necessarily return the whole content of the buffer but returns
2467 * the values of the key properties such as {@link #readerIndex()},
2468 * {@link #writerIndex()} and {@link #capacity()}.
2469 */
2470 @Override
2471 public abstract String toString();
2472
2473 @Override
2474 public abstract ByteBuf retain(int increment);
2475
2476 @Override
2477 public abstract ByteBuf retain();
2478
2479 @Override
2480 public abstract ByteBuf touch();
2481
2482 @Override
2483 public abstract ByteBuf touch(Object hint);
2484
2485 /**
2486 * Used internally by {@link AbstractByteBuf#ensureAccessible()} to try to guard
2487 * against using the buffer after it was released (best-effort).
2488 */
2489 boolean isAccessible() {
2490 return refCnt() != 0;
2491 }
2492 }