io.netty.buffer.package-info Maven / Gradle / Ivy
Go to download
This artifact provides a single jar that contains all classes required to use remote EJB and JMS, including
all dependencies. It is intended for use by those not using maven, maven users should just import the EJB and
JMS BOM's instead (shaded JAR's cause lots of problems with maven, as it is very easy to inadvertently end up
with different versions on classes on the class path).
The newest version!
/*
* Copyright 2012 The Netty Project
*
* The Netty Project licenses this file to you under the Apache License,
* version 2.0 (the "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at:
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*/
/**
* 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 {@link java.nio.ByteBuffer} to
* represent a sequence of bytes. This approach has significant advantage over
* using {@link java.nio.ByteBuffer}. Netty's new buffer type,
* {@link io.netty.buffer.ByteBuf}, has been designed from ground
* up to address the problems of {@link java.nio.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 {@link java.lang.StringBuffer}.
* - There's no need to call the {@code flip()} method anymore.
* - It is often faster than {@link java.nio.ByteBuffer}.
*
*
* Extensibility
*
* {@link io.netty.buffer.ByteBuf} has rich set of operations
* optimized for rapid protocol implementation. For example,
* {@link io.netty.buffer.ByteBuf} 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
* {@link io.netty.buffer.ByteBuf} 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 {@link java.nio.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 {@link java.nio.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, {@link io.netty.buffer.ByteBuf} 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.
* {@link io.netty.buffer.ByteBuf} message = {@link io.netty.buffer.Unpooled}.wrappedBuffer(header, body);
*
* // Therefore, you can even create a composite by mixing a composite and an
* // ordinary buffer.
* {@link io.netty.buffer.ByteBuf} messageWithFooter = {@link io.netty.buffer.Unpooled}.wrappedBuffer(message, footer);
*
* // Because the composite is still a {@link io.netty.buffer.ByteBuf}, 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 {@link java.lang.String}. You often estimate the length
* of the resulting string and let {@link java.lang.StringBuffer} expand itself
* on demand.
*
* // A new dynamic buffer is created. Internally, the actual buffer is created
* // lazily to avoid potentially wasted memory space.
* {@link io.netty.buffer.ByteBuf} b = {@link io.netty.buffer.Unpooled}.buffer(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
* {@link io.netty.buffer.ByteBuf} is a very thin wrapper of a
* byte array (i.e. {@code byte[]}). Unlike {@link java.nio.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 {@link java.nio.ByteBuffer}.
*/
package io.netty.buffer;