This class defines {#if[byte]?six:four} categories of operations upon $fulltype$ buffers:
Absolute and relative {@link #get() get} and{@link #put($type$) put} methods that read and writesingle $fulltype$s;
Relative {@link #get($type$[]) bulk get}methods that transfer contiguous sequences of $fulltype$s from this buffer into an array; {#if[!byte]?and}
Relative {@link #put($type$[]) bulk put}methods that transfer contiguous sequences of $fulltype$s from $a$ $fulltype$ array{#if[char]?, a string,} or some other $fulltype$ buffer into this buffer;{#if[!byte]? and}
Absolute and relative {@link #getChar() get}and {@link #putChar(char) put} methods that read andwrite values of other primitive types, translating them to and from sequences of bytes in a particular byte order;
Methods for creating view buffers, which allow a byte buffer to be viewed as a buffer containing values of some other primitive type; and
Methods for {@link #compact compacting}, {@link #duplicate duplicating}, and {@link #slice slicing} $a$ $fulltype$ buffer.
$Fulltype$ buffers can be created either by {@link #allocate allocation A byte buffer is either direct or non-direct. Given a direct byte buffer, the Java virtual machine will make a best effort to perform native I/O operations directly upon it. That is, it will attempt to avoid copying the buffer's content to (or from) an intermediate buffer before (or after) each invocation of one of the underlying operating system's native I/O operations. A direct byte buffer may be created by invoking the {@link #allocateDirect(int) allocateDirect} factory method of this class. Thebuffers returned by this method typically have somewhat higher allocation and deallocation costs than non-direct buffers. The contents of direct buffers may reside outside of the normal garbage-collected heap, and so their impact upon the memory footprint of an application might not be obvious. It is therefore recommended that direct buffers be allocated primarily for large, long-lived buffers that are subject to the underlying system's native I/O operations. In general it is best to allocate direct buffers only when they yield a measureable gain in program performance. A direct byte buffer may also be created by {@link java.nio.channels.FileChannel#map Whether a byte buffer is direct or non-direct may be determined by invoking its {@link #isDirect isDirect} method. This method is provided sothat explicit buffer management can be done in performance-critical code. This class defines methods for reading and writing values of all other primitive types, except boolean. Primitive values are translated to (or from) sequences of bytes according to the buffer's current byte order, which may be retrieved and modified via the {@link #order order}methods. Specific byte orders are represented by instances of the {@link ByteOrder} class. The initial order of a byte buffer is always {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}. For access to heterogeneous binary data, that is, sequences of values of different types, this class defines a family of absolute and relative get and put methods for each type. For 32-bit floating-point values, for example, this class defines: Corresponding methods are defined for the types char, short, int, long, and double. The index parameters of the absolute get and put methods are in terms of bytes rather than of the type being read or written. For access to homogeneous binary data, that is, sequences of values of the same type, this class defines methods that can create views of a given byte buffer. A view buffer is simply another buffer whose content is backed by the byte buffer. Changes to the byte buffer's content will be visible in the view buffer, and vice versa; the two buffers' position, limit, and mark values are independent. The {@link #asFloatBuffer() asFloatBuffer} method, for example, creates an instance ofthe {@link FloatBuffer} class that is backed by the byte buffer upon whichthe method is invoked. Corresponding view-creation methods are defined for the types char, short, int, long, and double. View buffers have three important advantages over the families of type-specific get and put methods described above: A view buffer is indexed not in terms of bytes but rather in terms of the type-specific size of its values; A view buffer provides relative bulk get and put methods that can transfer contiguous sequences of values between a buffer and an array or some other buffer of the same type; and A view buffer is potentially much more efficient because it will be direct if, and only if, its backing byte buffer is direct. The byte order of a view buffer is fixed to be that of its byte buffer at the time that the view is created. Like a byte buffer, $a$ $fulltype$ buffer is either direct or non-direct. A $fulltype$ buffer created via the wrap methods of this class will be non-direct. $A$ $fulltype$ buffer created as a view of a byte buffer will be direct if, and only if, the byte buffer itself is direct. Whether or not $a$ $fulltype$ buffer is direct may be determined by invoking the {@link #isDirect isDirect} method. This class implements the {@link CharSequence} interface so thatcharacter buffers may be used wherever character sequences are accepted, for example in the regular-expression package {@link java.util.regex}. Methods in this class that do not otherwise have a value to return are specified to return the buffer upon which they are invoked. This allows method invocations to be chained. #if[byte] The sequence of statements }, which allocates space for the buffer's #if[byte] content, or by {@link #wrap($type$[]) wrapping} anexisting $fulltype$ array {#if[char]?or string} into a buffer. #else[byte] content, by {@link #wrap($type$[]) wrapping} an existing$fulltype$ array {#if[char]?or string} into a buffer, or by creating a view of an existing byte buffer. #end[byte] #if[byte] mapping Direct vs. non-direct buffers
} a region of a filedirectly into memory. An implementation of the Java platform may optionally support the creation of direct byte buffers from native code via JNI. If an instance of one of these kinds of buffers refers to an inaccessible region of memory then an attempt to access that region will not change the buffer's content and will cause an unspecified exception to be thrown either at the time of the access or at some later time. Access to binary data
float {@link #getFloat()}float {@link #getFloat(int) getFloat(int index)}void {@link #putFloat(float) putFloat(float f)}void {@link #putFloat(int,float) putFloat(int index, float f)}
Invocation chaining
#end[byte]
can, for example, be replaced by the single statement bb.putInt(0xCAFEBABE); bb.putShort(3); bb.putShort(45);
#end[byte] #if[char] The sequence of statements bb.putInt(0xCAFEBABE).putShort(3).putShort(45);
can, for example, be replaced by the single statement cb.put("text/"); cb.put(subtype); cb.put("; charset="); cb.put(enc);
#end[char]
@author Mark Reinhold
@author JSR-51 Expert Group
@since 1.4
cb.put("text/").put(subtype).put("; charset=").put(enc);
| |
| |