Update javadocs to highlight that derived buffers will not increment the reference count.

Motivation:

We not explain the derived buffers will not retain the parent buffer.

Modifications:

Add docs.

Result:

Correctly document behaviour
This commit is contained in:
Norman Maurer 2015-06-03 11:31:47 +02:00
parent 49643fb5b1
commit 6f9eb2cd34

View File

@ -201,6 +201,9 @@ import java.nio.charset.UnsupportedCharsetException;
* <p>
* In case a completely fresh copy of an existing buffer is required, please
* call {@link #copy()} method instead.
* <p>
* Also be aware that obtaining derived buffers will NOT call {@link #retain()} and so the
* reference count will NOT be increased.
*
* <h3>Conversion to existing JDK types</h3>
*
@ -1191,6 +1194,9 @@ public abstract class ByteBuf implements ReferenceCounted, Comparable<ByteBuf> {
* Returns a new slice of this buffer's sub-region starting at the current
* {@code readerIndex} and increases the {@code readerIndex} by the size
* of the new slice (= {@code length}).
* <p>
* Also be aware that this method will NOT call {@link #retain()} and so the
* reference count will NOT be increased.
*
* @param length the size of the new slice
*
@ -1661,6 +1667,9 @@ public abstract class ByteBuf implements ReferenceCounted, Comparable<ByteBuf> {
* identical to {@code buf.slice(buf.readerIndex(), buf.readableBytes())}.
* This method does not modify {@code readerIndex} or {@code writerIndex} of
* this buffer.
* <p>
* Also be aware that this method will NOT call {@link #retain()} and so the
* reference count will NOT be increased.
*/
public abstract ByteBuf slice();
@ -1670,6 +1679,9 @@ public abstract class ByteBuf implements ReferenceCounted, Comparable<ByteBuf> {
* they maintain separate indexes and marks.
* This method does not modify {@code readerIndex} or {@code writerIndex} of
* this buffer.
* <p>
* Also be aware that this method will NOT call {@link #retain()} and so the
* reference count will NOT be increased.
*/
public abstract ByteBuf slice(int index, int length);
@ -1680,7 +1692,9 @@ public abstract class ByteBuf implements ReferenceCounted, Comparable<ByteBuf> {
* This method is identical to {@code buf.slice(0, buf.capacity())}.
* This method does not modify {@code readerIndex} or {@code writerIndex} of
* this buffer.
* The reader and writer marks will not be duplicated.
* <p>
* The reader and writer marks will not be duplicated. Also be aware that this method will
* NOT call {@link #retain()} and so the reference count will NOT be increased.
*/
public abstract ByteBuf duplicate();