# Package org.jboss.netty.buffer

Abstraction of a byte buffer - the fundamental data structure to represent a low-level binary and text message.

See: Description

Interface Summary
Interface | Description
--- | ---
ChannelBuffer | A random and sequential accessible sequence of zero or more bytes (octets).
ChannelBufferFactory | A factory that creates or pools `ChannelBuffer`s.
ChannelBufferIndexFinder | Locates an index of data in a `ChannelBuffer`.
WrappedChannelBuffer | The common interface for buffer wrappers and derived buffers.

Class Summary
Class | Description
--- | ---
AbstractChannelBuffer | A skeletal implementation of a buffer.
AbstractChannelBufferFactory | A skeletal implementation of `ChannelBufferFactory`.
BigEndianHeapChannelBuffer | A big-endian Java heap buffer.
ByteBufferBackedChannelBuffer | A NIO `ByteBuffer` based buffer.
ChannelBufferInputStream | An `InputStream` which reads data from a `ChannelBuffer`.
ChannelBufferOutputStream | An `OutputStream` which writes data to a `ChannelBuffer`.
ChannelBuffers | Creates a new `ChannelBuffer` by allocating new space or by wrapping or copying existing byte arrays, byte buffers and a string.
CompositeChannelBuffer | A virtual buffer which shows multiple buffers as a single merged buffer.
DirectChannelBufferFactory | A `ChannelBufferFactory` which pre-allocates a large chunk of direct buffer and returns its slice on demand.
DuplicatedChannelBuffer | A derived buffer which simply forwards all data access requests to its parent.
DynamicChannelBuffer | A dynamic capacity buffer which increases its capacity as needed.
HeapChannelBuffer | A skeletal implementation for Java heap buffers.
HeapChannelBufferFactory | A `ChannelBufferFactory` which merely allocates a heap buffer with the specified capacity.
LittleEndianHeapChannelBuffer | A little-endian Java heap buffer.
ReadOnlyChannelBuffer | A derived buffer which forbids any write requests to its parent.
SlicedChannelBuffer | A derived buffer which exposes its parent's sub-region only.
TruncatedChannelBuffer | A derived buffer which hides its parent's tail data beyond a certain index.

## Package org.jboss.netty.buffer Description

Abstraction of a byte buffer - the fundamental data structure to represent a low-level binary and text message. Netty uses its own buffer API instead of NIO `ByteBuffer` to represent a sequence of bytes. This approach has significant advantage over using `ByteBuffer`. Netty's new buffer type, `ChannelBuffer`, has been designed from ground up to address the problems of `ByteBuffer` and to meet the daily needs of network application developers. To list a few cool features:

- You can define your buffer type if necessary.
- Transparent zero copy is achieved by built-in composite buffer type.
- A dynamic buffer type is provided out-of-the-box, whose capacity is expanded on demand, just like `StringBuffer`.
- There's no need to call the `flip()` method anymore.
- It is often faster than `ByteBuffer`.

### Extensibility

`ChannelBuffer` has rich set of operations optimized for rapid protocol implementation. For example, `ChannelBuffer` provides various operations for accessing unsigned values and strings and searching for certain byte sequence in a buffer. You can also extend or wrap existing buffer type to add convenient accessors. The custom buffer type still implements `ChannelBuffer` interface rather than introducing an incompatible type.

### Transparent Zero Copy

To lift up the performance of a network application to the extreme, you need to reduce the number of memory copy operation. You might have a set of buffers that could be sliced and combined to compose a whole message. Netty provides a composite buffer which allows you to create a new buffer from the arbitrary number of existing buffers with no memory copy. For example, a message could be composed of two parts; header and body. In a modularized application, the two parts could be produced by different modules and assembled later when the message is sent out.

     +--------+----------+
     | header |   body   |
     +--------+----------+

If `ByteBuffer` were used, you would have to create a new big buffer and copy the two parts into the new buffer. Alternatively, you can perform a gathering write operation in NIO, but it restricts you to represent the composite of buffers as an array of `ByteBuffer`s rather than a single buffer, breaking the abstraction and introducing complicated state management. Moreover, it's of no use if you are not going to read or write from an NIO channel.

     // The composite type is incompatible with the component type.
     ByteBuffer[] message = new ByteBuffer[] { header, body };

By contrast, `ChannelBuffer` does not have such caveats because it is fully extensible and has a built-in composite buffer type.

     // The composite type is compatible with the component type.
     ChannelBuffer message = ChannelBuffers.wrappedBuffer(header, body);

     // Therefore, you can even create a composite by mixing a composite and an
     // ordinary buffer.
     ChannelBuffer messageWithFooter = ChannelBuffers.wrappedBuffer(message, footer);

     // Because the composite is still a ChannelBuffer, you can access its content
     // easily, and the accessor method will behave just like it's a single buffer
     // even if the region you want to access spans over multiple components.  The
     // unsigned integer being read here is located across body and footer.
     messageWithFooter.getUnsignedInt(
         messageWithFooter.readableBytes() - footer.readableBytes() - 1);

### Automatic Capacity Extension

Many protocols define variable length messages, which means there's no way to determine the length of a message until you construct the message or it is difficult and inconvenient to calculate the length precisely. It is just like when you build a `String`. You often estimate the length of the resulting string and let `StringBuffer` expand itself on demand. Netty allows you to do the same via a dynamic buffer which is created by the `ChannelBuffers.dynamicBuffer()` method.

     // A new dynamic buffer is created.  Internally, the actual buffer is created
     // lazily to avoid potentially wasted memory space.
     ChannelBuffer b = ChannelBuffers.dynamicBuffer(4);

     // When the first write attempt is made, the internal buffer is created with
     // the specified initial capacity (4).
     b.writeByte('1');

     b.writeByte('2');
     b.writeByte('3');
     b.writeByte('4');

     // When the number of written bytes exceeds the initial capacity (4), the
     // internal buffer is reallocated automatically with a larger capacity.
     b.writeByte('5');

### Better Performance

Most frequently used buffer implementation of `ChannelBuffer` is a very thin wrapper of a byte array (i.e. `byte[]`). Unlike `ByteBuffer`, it has no complicated boundary check and index compensation, and therefore it is easier for a JVM to optimize the buffer access. More complicated buffer implementation is used only for sliced or composite buffers, and it performs as well as `ByteBuffer`.