Java The ByteBuffer Class in Java

The ByteBuffer Class in Java






… in Java by Richard G Baldwin

Java Programming Notes # 1782


Preface


New features in SDK Version 1.4.0

The recently released JavaTM 2 SDK, Standard Edition Version
1.4.0 contains a number of new features.  This article explains how
to use some of those new features.

Among the new features is a new I/O API.  Here is how Sun describes
that API and the new features that it provides:

“The new I/O (NIO) APIs introduced in v 1.4 provide new
features and improved performance in the areas of buffer management, scalable
network and file I/O, character-set support, and regular-expression matching.
The NIO APIs supplement the I/O facilities in the java.io package.”

Basic classes

The abstract Buffer class, and its subclasses, are basic
to many of the new features in the NIO.  The Sun documentation lists
the following known subclasses of Buffer:

  • ByteBuffer
  • CharBuffer
  • DoubleBuffer
  • FloatBuffer
  • IntBuffer
  • LongBuffer
  • ShortBuffer

I explained the use of the Buffer class in a previous article entitled
Understanding
the Buffer class in Java
. As shown above, one of the subclasses of
Buffer
is named ByteBuffer.  The ByteBuffer class is very important
because it forms a basis for the use of channels in Java. (The concept
of I/O channels is another new feature of version 1.4, which I plan to
cover in a future lesson.)

The purpose of this lesson is to help you understand how to use the
features of the ByteBuffer class.  I will describe many of
those features, and will illustrate the use of those features by explaining
the code in a sample program.

Caution: Dangerous Curves Ahead

A caution is in order regarding the capabilities discussed in this lesson. 
Once you enter the domain of the ByteBuffer class, you have left
the type-safe world normally associated with Java behind.  You have
entered a domain more akin to that normally enjoyed by adventuresome C
and C++ programmers.

For example, there is nothing to prevent you from creating a buffer
for byte data, populating it with double data, and then erroneously
viewing and interpreting it as type int.  Also, there is nothing
to prevent you from interpreting LITTLE_ENDIAN data as BIG_ENDIAN, and
vice versa.  There are many other ways that you can go astray as well,
and neither the compiler nor the virtual machine are of much help in preventing
such programming errors.

I won’t spend a lot of time discussing these matters, but I have provided
a short sample program that illustrates the above sequence of events in
Listing 38 near the end of the lesson.

Viewing tip

You may find it useful to open another copy of this lesson in a separate
browser window.  That will make it easier for you to scroll back and
forth among the different listings and figures while you are reading about
them.

Supplementary material

I recommend that you also study the other lessons in my extensive collection
of online Java tutorials.  You will find those lessons published at
Gamelan.com
However, as of the date of this writing, Gamelan doesn’t maintain a consolidated
index of my Java tutorial lessons, and sometimes they are difficult to
locate there.  You will find a consolidated index at
www.DickBaldwin.com.

Discussion
and Sample Code


The inheritance model

As mentioned above, the class named ByteBuffer extends the abstract
class named Buffer.  The Sun documentation lists the following
known subclasses of Buffer:

  • ByteBuffer
  • CharBuffer
  • DoubleBuffer
  • FloatBuffer
  • IntBuffer
  • LongBuffer
  • ShortBuffer

Four common capabilities

As you can see from the names of the subclasses, there is one subclass
of the Buffer class for each non-boolean primitive type.  If
you compare the documentation for the seven subclasses of Buffer,
you will find that they are very similar.  In fact, each of the subclasses
provides the following four capabilities for data of the type whose name
appears in the subclass name.

  • Absolute and relative get and put methods that
    read and write single elements.
  • Relative get methods that transfer contiguous sequences of
    elements from the buffer into an array.
  • Relative put methods that transfer contiguous sequences of
    elements from an array (of the same type) or some other buffer
    (of
    the same type)
    into a buffer.
  • Methods for compacting, duplicating, and slicing a buffer.

(In addition, some of the subclasses provide capabilities that are specific
to the type involved.  For example, the CharBuffer class provides
capabilities that are specific to the use of characters and strings, such
as a method that wraps a String into a CharBuffer object.)

Additional capabilities of ByteBuffer class

The ByteBuffer class also provides the following two additional
capabilities.  This makes the ByteBuffer class more general
than the other five subclasses of Buffer.

  • Absolute and relative get and put methods that read
    and write values of primitive types other than byte.
  • Methods for creating view buffers, which allow a byte buffer to
    be viewed as a buffer containing values of some other primitive type.

In addition, as I mentioned earlier, the ByteBuffer class is very
important in understanding I/O channels in Java, which I intend
to discuss in a future lesson.

Will concentrate on the ByteBuffer class

Therefore, I have singled out the
ByteBuffer class for a detailed
discussion in this lesson.  Once you understand how to use objects
of the ByteBuffer class, you should also understand how to use objects
instantiated from the other subclasses of Buffer.

A container for primitive data

None of the container classes in the Java Collections Framework
are designed to contain primitive data.  Those containers are all
designed to contain references to objects.  Objects instantiated from
subclasses of Buffer are containers for primitive data.

Three important properties

Every object instantiated from Buffer has the following three
important properties:

  • capacity:  The number of elements the buffer contains.
  • limit:  The index of the first element that should not be read
    or written.
  • position:  The next element to be read or written.

Various methods are provided by the Buffer
class to deal with these properties, and these methods are inherited into
the ByteBuffer class.  I will use some of those methods in
the sample program in this lesson.  However, an earlier lesson (see
the link above)
that explained the use of the Buffer class also
explained how to use all of the property-manipulating methods of the Buffer
class.  If you aren’t familiar with those methods, you might want
to refer back to that lesson.

Writing and reading data

Subclasses of Buffer use put and get operations
to store data into a buffer and to read data from the buffer (to transfer
data into and out of the buffer).
  Each subclass defines two categories
of put and get operations:
relative and absolute.

Relative put and get operations

Relative data transfer operations store or read one or more elements
starting at the current position.  The position is automatically
incremented based on the number of items transferred and the type of data
transferred.

Absolute put and get operations

Absolute data transfer operations take an element index as a
parameter and use that index to store or retrieve data.  These operations
do not affect the value of the position property.

Method chaining

Some of the methods of the ByteBuffer class return a reference
to the buffer.  This makes it possible to use method invocation
chaining
syntax such as that shown in Figure 1.

 

buf5.putDouble(1.0/3.0).
     putFloat((float)(1.0/6.0)).
     putLong(Long.MAX_VALUE);

Figure 1

Read-only buffers

It is possible to create read-only buffers, and I will do so in the
sample program in this lesson.  Methods that normally change the contents
of a buffer will throw a ReadOnlyBufferException when invoked on
a read-only buffer.

While a read-only buffer does not allow its content to be changed, its
mark,
position,
and limit values may be changed. You can determine
if a buffer is read-only by invoking its isReadOnly method.

The sample program named ByteBuffer01

The features of the ByteBuffer class are illustrated in the program
named ByteBuffer01, which I will discuss in fragments.  A complete
listing of the program is provided in Listing 37 near the end of the lesson.

Displaying buffer properties

Listing 1 shows a convenience method that I wrote, whose purpose is
to display the properties of a buffer.  The reference to the buffer
of interest and a String to identify the buffer are passed as parameters
to the method.

 

  static void showBufferProperties(
               Buffer buf,String name){
    System.out.println(
       "Buffer Properties for " + name
                    +"n  capacity=" 
                    + buf.capacity()
                    + " limit=" 
                    + buf.limit()
                    + " position=" 
                    + buf.position());
  }//end showBufferProperties

Listing 1

The method uses the three getter methods of the Buffer
class to get and display the values of the following properties:

  • capacity
  • limit
  • position

(Note that the property getter methods of the Buffer class do
not conform to the JavaBeans design patterns for property getter methods.)

The format of the output produced by Listing 1 is illustrated in Figure
2.

 

Buffer Properties for buf5
  capacity=25 limit=25 position=0

Figure 2

Display byte data in the buffer

Listing 2 shows a convenience method designed to display the byte data
stored in the buffer, from the current value of the position property
to the value of the limit property.  The byte data is displayed
12 bytes per row of output.

 

  static void showBufferData(
          ByteBuffer buf, String name){
    System.out.println(
            "Buffer data for " + name);
    int cnt = 0;
    while(buf.hasRemaining()){
      System.out.print(
                      buf.get() + " ");
      cnt++;
      if(cnt%12 == 0)
            System.out.println();//line
    }//end while loop
    System.out.println();//blank line
  }//end showBufferData

Listing 2

The code in Listing 2 invokes two important methods that are new to
version 1.4.0 of the SDK:

  • The hasRemaining method of the Buffer class
  • The relative get method of the ByteBuffer class

The hasRemaining method

The hasRemaining method is much like one of the methods of the
Iterator
and Enumeration interfaces, which are used to iterate on objects
instantiated from the concrete classes of the Java Collections Framework.

The hasRemaining method tells whether there are any elements
remaining between the current
position and the limit
The method returns a boolean, which is true only if there
is at least one element remaining in the buffer.  Thus, this method
works very nicely in the conditional clause of a while loop for
the purpose of iterating on a buffer.

The relative get method

The relative
get method of the ByteBuffer class reads
and returns the byte at the buffer’s current position, and then
increments the position.  Thus, it also works quite well in an iterator
loop for a buffer (provided you have exercised proper control over the
values of the position and limit properties beforehand).

The format of the output produced by the code in Listing 2 is illustrated
in Figure 3.  Each numeric value in figure three is the value of a
single byte, and the values for twelve bytes are displayed on each row
of output.

 

Buffer data for buf5
0 0 0 1 0 0 0 2 0 0 0 4
0 0 0 8 0 0 0 16 0 0 0 32
0

Figure 3

Display array data

Listing 3 is a convenience method designed simply to display the data
in an array object of type byte.

 

  static void showArrayData(
                         byte[] array){
    System.out.println(
                    "Show array data");
    for(int cnt = 0; 
            cnt < array.length; cnt++){
      System.out.print(
                     array[cnt] + " ");
      if((cnt+1)%12 == 0)
            System.out.println();//line
    }//end for loop
    System.out.println();//blank line
  }//end showArrayData

Listing 3

I am assuming that you are already familiar with the use of array objects
in Java, and therefore, I won’t discuss this code in detail.  If that
is not the case, you can learn about array objects at www.DickBaldwin.com.

Create an array object

There are several ways to create a buffer object in Java.  One
of those ways is to wrap an existing array object in a buffer object. 
To do that, we need an array object, which I will create using the code
in Listing 4.  (I will discuss two other ways to create a buffer
object later in this lesson.)

Listing 4 shows the beginning of the main method.  The code
in Listing 4 creates, populates, and displays an eight-element array object
containing data of type byte.

 

  public static void main(
                        String[] args){
    
    //Wrap a byte array into a buffer
    System.out.println(
          "Create and populate array");
    byte[] a1 = {0,1,2,3,4,5,6,7};
    showArrayData(a1);

Listing 4

Again, I am assuming that you are already familiar with the use of array
objects in Java, and therefore, I won’t discuss this code in detail. 
The code in Listing 4 produces the output shown in Figure 4.

 

Create and populate array
Show array data
0 1 2 3 4 5 6 7

Figure 4

I show this here because we will want to compare it with the data stored
in our buffer object later.

Create a ByteBuffer object

As mentioned above, there are several ways to create a buffer, and one
of them is shown in Listing 5.

 

    System.out.println(
          "Wrap byte array in buffer");
    ByteBuffer buf1 = 
                ByteBuffer.wrap(a1);
    System.out.println(
                  "Buffer is direct: " 
                   + buf1.isDirect());
    showBufferData(buf1, "buf1");

Listing 5

Listing 5 invokes the static wrap method of the ByteBuffer
class to create a buffer that wraps the existing array object referred
to by the reference variable named a1.

Wrapping an array object

There are two overloaded versions of the wrap method, one that
requires incoming offset and length parameters, and one that
doesn’t.  (Both versions require an incoming reference to an array
object.)
  I used the simpler of the two versions, which does not
require
offset and length.

A backing array

For both versions, the new buffer is backed up by, or connected to,
the byte array, which it wraps.  Modifications to the buffer cause
the array contents to be modified, and modifications to the array cause
the buffer contents to be modified.  (It appears as though they
are really the same set of data.  Note that this is a common theme
that will arise more than once in this lesson.)

Buffer property values

For the version of the wrap method that I used, the capacity
and limit properties of the new buffer are the same as array.length. 
The initial value of the position property of the new buffer is
zero, and its mark is undefined.

For the more complex version, the initial values of the buffer properties
are determined by the values of the offset and length parameters
passed to the wrap method.

Direct vs. non-direct buffers

The code in Listing 5 also introduces you to the fact that a byte buffer
is either direct or non-direct. I will have more to say about
this later.  For now, suffice it to say that a buffer created by wrapping
an array object is non-direct, as indicated by the program output
shown in Figure 5.

 

Wrap byte array in buffer
Buffer is direct: false
Buffer data for buf1
0 1 2 3 4 5 6 7

Figure 5

Figure 5 also shows the byte contents of the buffer.  If you compare
this with the array contents shown in Figure 4, you will see that the buffer
and its backing array contain the same values.

Modifications are reflected …

Modifications to the buffer cause the array contents to be modified,
and modifications to the array cause the buffer contents to be modified. 
This is partially illustrated in Listing 6.

 

    System.out.println(
         "Modify first array element");

    a1[0] = 10;
    showArrayData(a1);
    buf1.position(0);
    showBufferData(buf1, "buf1");

Listing 6

The code in Listing 6 changes the value in the first array element from
0 to 10, and then displays the modified contents of the array object and
the buffer.  You will see that this causes the value of the first
element in the buffer to change accordingly.

Set the position to zero

Recall that the showBufferData method described earlier (and
invoked in Listing 6)
displays the contents of the buffer from the
element specified by the value of the position property, to the
element specified by the value of the limit property.

At this point, (and at numerous other points in this program), it
is necessary to set the value of the position property to zero before
invoking showBufferData.  Otherwise, the contents of the entire
buffer would not be displayed.  This is accomplished by invoking the
position
method inherited from the Buffer class and passing zero as a parameter.

Figure 6 shows the output produced by the code in Listing 6.

 

Modify first array element
Show array data
10 1 2 3 4 5 6 7
Buffer data for buf1
10 1 2 3 4 5 6 7

Figure 6

The important thing to note in Figure 6 is that the value in the first
element of the buffer was changed when the value in the first element of
the backing array was changed.

Absolute and relative put methods

As I explained earlier, the ByteBuffer class provides both absolute
and relative versions of the put and get methods. 
Listing 7 illustrates both categories of put methods.  In addition,
Listing 7 also illustrates the fact that modifications to the buffer cause
the array contents to be modified accordingly.

 

    System.out.println(
                  "Modify the buffer");
    buf1.put(3,(byte)20);
    buf1.position(4);
    buf1.put((byte)21);
    buf1.put((byte)22);
    buf1.position(0);
    showBufferData(buf1, "buf1");
    showArrayData(a1);

Listing 7

Invoke absolute put method

The code in Listing 7 begins by using the absolute version of
the put method to write the byte value 20 into the buffer at position
3.  This overwrites the value previously stored at that position.
(Note
that the invocation of the absolute version of the put method has
no effect on the value of the position property.)

Invoke relative put method

Then the code in Listing 7 sets the value of the position property
to 4, and invokes the relative version of the put method
twice in succession.  This causes the values 21 and 22 to overwrite
the values previously stored in positions 4 and 5.

Display the data

Then Listing 7 sets the position to 0 and displays the contents
of the buffer, followed by the contents of the array.  The output
produced by Listing 7 is shown in Figure 7.

 

Modify the buffer
Buffer data for buf1
10 1 2 20 21 22 6 7
Show array data
10 1 2 20 21 22 6 7

Figure 7

Perhaps the most important things to observe in this output are:

  • The values of the elements at positions 3, 4, and 5 in the buffer are changed
    to 20, 21, and 22 respectively.
  • The values of the corresponding elements in the array are also changed
    accordingly.

Absolute get method

The relative get method is illustrated in the showBufferData
method discussed earlier.  The absolute get method is
illustrated in Listing 8.

 

    System.out.println("Get absolute");
    System.out.println("Element 3 = " 
                        + buf1.get(3));
    System.out.println("Element 5 = " 
                        + buf1.get(5));
    System.out.println("Element 7 = " 
                        + buf1.get(7));

Listing 8

The code in Listing 8 gets and displays the values stored in positions
3, 5, and 7.  The output produced is shown in Figure 8.

 

Get absolute
Element 3 = 20
Element 5 = 22
Element 7 = 7

Figure 8

You can verify these results by comparing them back against the buffer
contents shown in Figure 7.

Contiguous get and put operations

In addition to reading and writing single elements from the buffer,
the subclasses of the Buffer class (including ByteBuffer)
allow for transferring contiguous blocks of elements into and out of the
buffer.

The ByteBuffer class provides for the transfer of a block of
bytes from the buffer into an array object of type byte (contiguous
get).
 
The class also provides for the transfer of a block of bytes from an array
object (of type byte), or from another
ByteBuffer
object, into contiguous elements of a ByteBuffer object (contiguous
put).

A contiguous get to an array

Listing 9 illustrates the use of the contiguous get method to
transfer a block of contiguous bytes from the buffer to a new empty array
object of type byte.

 

    
    System.out.println(
                     "Contiguous get");
    buf1.position(0);
    showBufferData(buf1, "buf1");

    byte[] a2 = new byte[10];
    showArrayData(a2);

    buf1.position(1);
    buf1.get(a2, 3, 5);

    showArrayData(a2);

Listing 9

Create a new byte array

The code in Listing 9 begins by displaying the contents of the buffer
for later comparison with the array contents.  Then it creates a new
array object of type byte whose length is 10.  This is larger
than the capacity of the buffer.  (Recall that the initial value
of each of the elements in a new byte array is zero unless purposely initialized
using the syntax shown in Listing 4.)

Invoke the contiguous get method

Then the code in Listing 9 sets the position of the buffer to
1, and invokes the get method, passing the following parameters:

  • The array referred to by a2 as the destination array into which
    bytes are to be written
  • A value of 3 for the offset within the array of the first byte to be written
  • A value of 5 for the maximum number of bytes to be written to the given
    array

This version of the get method copies the specified number of bytes
from the buffer into the array, starting at the current position
of the buffer and at the given offset in the array. The position
of the buffer is then incremented by the specified number of bytes.

Throwing exceptions

As you have probably figured out already, various conditions involving
the specified number of bytes, the remaining number of bytes in the buffer,
and the length of the array can conflict, causing exceptions to be thrown. 
I won’t attempt to explain those conditions here, but will simply refer
you to the Sun documentation for those details.

Display the data

Finally, the code in Listing 9 displays the contents of the array into
which the bytes were transferred.

The output produced by this section of the program is shown in Figure
9.

 

Contiguous get
Buffer data for buf1
10 1 2 20 21 22 6 7
Show array data
0 0 0 0 0 0 0 0 0 0
Show array data
0 0 0 1 2 20 21 22 0 0

Figure 9

As you can see in Figure 9, after the transfer takes place, there are
five non-zero values in the array, beginning at index 3.  This matches
the array offset value of 3 and the specified length of 5 passed as parameters
to the contiguous get method.

Also, as you can see in Figure 9, the five values transferred from the
buffer to the array began at position 1 in the buffer, corresponding
to the fact that the position was set to 1 immediately prior to
the invocation of the get method.

Contiguous put from array as source of data

Listing 10 illustrates the transfer of a block of bytes from an array
into contiguous elements in a buffer.

 

    System.out.println(
          "Contiguous put from array");
    showArrayData(a2);

    buf1.position(0);
    buf1.put(a2, 1, 8);

    buf1.position(0);
    showBufferData(buf1, "buf1");

Listing 10

The code in Listing 10 begins by displaying the contents of the array
for later comparison with the contents of the buffer.

Invoke contiguous put method

Then the code in Listing 10 sets the position of the buffer to
0, and invokes the put method, passing the following parameters:

  • The array referred to by a2 as the source array from which the bytes
    are to be read
  • A value of 1 for the offset within the array of the first byte to be read
  • A value of 8 for the maximum number of bytes to be read from the array

The output

The output produced by the code in Listing 10 is shown in Figure 10.

 

Contiguous put from array
Show array data
0 0 0 1 2 20 21 22 0 0
Buffer data for buf1
0 0 1 2 20 21 22 0

Figure 10

Figure 10 shows that 8 bytes were transferred from the array to the
buffer, beginning with the value at array index 1.  These eight bytes
were written into the buffer beginning at position 0, overwriting the eight
values that previously existed in the buffer.

Another non-direct buffer

Here are some of the details from Sun regarding direct and non-direct
buffers:

“A byte buffer is either direct or non-direct. … A direct
byte buffer may be created by invoking the allocateDirect factory
method of this class. … Whether a byte buffer is direct or non-direct
may be determined by invoking its isDirect method. This method is
provided so that explicit buffer management can be done in performance-critical
code.”

I will have more to say about direct buffers later on.

Listing 11 illustrates the creation of a non-direct buffer through
allocation.

 

    ByteBuffer buf2 = 
               ByteBuffer.allocate(10);

    System.out.println(
                   "Buffer is direct: "
                    + buf2.isDirect());

Listing 11

Allocate the buffer

Note that the code in Listing 11 invokes the allocate factory
method of the ByteBuffer class (and not the allocateDirect
factory method, which would create a direct buffer).

Then, for purpose of illustration, the code in Listing 11 invokes the
isDirect
method on the new buffer to determine if it is direct or non-direct.

The output

Figure 11 shows the output produced by the code in Listing 11.

 

Buffer is direct: false

Figure 11

As you can see from the output, this buffer is non-direct.

Not a wrap

This approach to creating a new buffer is different from the wrapping
approach illustrated earlier in the program.  This buffer is initially
empty, and its capacity is 10 elements (the value passed as a
parameter to the factory method). 
As an empty buffer of type
byte,
the initial value of each of its elements is zero.

The new buffer’s initial position is 0, its limit is the
same as its capacity, and its mark is undefined.

Although this buffer was not created by wrapping an existing array,
the buffer does have a backing array, and the offset of the backing array
is zero (I will have more to say about the backing array later).

Contiguous put from buffer as source of data

This new empty buffer is referred to by the reference variable named
buf2
Listing 12 illustrates the transfer of a contiguous block of bytes from
the buffer referred to by buf1 to this new buffer.

 

    showBufferData(buf2, "buf2");

    buf2.position(1);
    buf1.position(0);
    buf2.put(buf1);

    buf1.position(0);
    showBufferData(buf1, "buf1");
    buf2.position(0);
    showBufferData(buf2, "buf2");

Listing 12

The code in Listing 12 begins by displaying the contents of the new
buffer.  We will see shortly that each of the elements in the new
buffer is initialized to a value of zero.

Set positions and invoke contiguous put method

Then the code in Listing 12 sets position values for each of
the buffers and invokes the contiguous put method on buf2,
passing buf1 as a parameter.  The parameter specifies the buffer
that acts as a source for the data to be transferred.  The position
values of each of the buffers control the data that is actually transferred.

What data is actually transferred?

In particular, this version of the put method transfers the bytes
remaining in the source buffer (between position and limit) into
the destination buffer on which the method is invoked.  The data is
transferred into the destination buffer beginning at the current position
for the destination buffer.  Then the position properties of
both buffers are incremented by the number of bytes transferred.

Exceptions can be thrown

Several conditions can cause exceptions to be thrown, but I will simply
refer you to the Sun documentation for the details in that regard.

The output

After the data has been transferred, the contents of both buffers are
displayed.  The output produced by the code in Listing 12 is shown
in Figure 12.

 

Buffer data for buf2
0 0 0 0 0 0 0 0 0 0
Buffer data for buf1
0 0 1 2 20 21 22 0
Buffer data for buf2
0 0 0 1 2 20 21 22 0 0

Figure 12

As you can see, the initial values of each of the ten elements in the
new empty buffer are zero.

All eight bytes of data are transferred from buf1 (beginning
at position 0 in buf1)
to buf2 (beginning at position
1 in buf2).

(Note that the boldface values don’t mean anything special here. 
I will refer back to them later.)

A backing array

As I mentioned earlier, creation of a non-direct buffer using
the allocate factory method also creates a backing array for the
buffer.  This is confirmed by the code in Listing 13.

 

    if(buf2.hasArray())
      showArrayData(buf2.array());

Listing 13

Listing 13 invokes the hasArray method of the ByteBuffer
class to confirm the existence of a backing array, and then invokes the
array
method of that same class to get and display the contents of the array. 
The output produced by this code is shown in Figure 13.

 

Show array data
0 0 0 1 2 20 21 22 0 0

Figure 13

As you should expect by now, the contents of the backing array shown
in Figure 13 exactly match the contents of the buffer referred to by buf2
shown in Figure 12.  From this point forward, changes to the buffer
will change the contents of the backing array, and changes to the backing
array will change the contents of the buffer.

Compacting a buffer

The code in Listing 14 invokes the compact method on the buffer,
after setting its position to 3.  Then the code displays the contents
of the buffer twice, first without setting the position to zero,
and then again after setting the position to zero.

 

    System.out.println("Compacting");
    buf2.position(3);
    buf2.compact();
    showBufferData(buf2, "buf2");
    buf2.position(0);
    showBufferData(buf2, "buf2");

Listing 14

The compact method

Basically, the invocation of the compact method on a buffer discards
the bytes between the beginning and the position, and slides the
remaining bytes forward to the beginning.

Note that the bytes vacated at the upper end continue to contain the
values that were there before the compact method was invoked (as
opposed to filling in vacated elements with the value zero, for example).

Here is a partial description of the behavior as provided by Sun:

“The bytes between the buffer’s current position and its
limit, if any, are copied to the beginning of the buffer. … The buffer’s
position is then set to n and its limit is set to its capacity.”

Sun goes on to explain:

“The buffer’s position is set to the number of bytes copied,
rather than to zero, so that an invocation of this method can be followed
immediately by an invocation of another relative put method.”

The output

The output produced by the code in Listing 14 is shown in Figure 14.

 

Compacting
Buffer data for buf2
22 0 0
Buffer data for buf2
1 2 20 21 22 0 0 22 0 0

Figure 14

The row of data containing only three values is the result of invoking
showBufferData
without first setting the value of the position property to zero. 
In this case, these are the elements that were vacated when the remaining
data in the buffer was copied to the beginning of the buffer.  In
other words, these are the last three elements in the buffer.  Note
that they still contain the values that were there before the compact
method was invoked.

The row of data containing ten values is the result of invoking showBufferData
after setting the value of the position property to zero. 
The boldface values in this row correspond to the boldface values in Figure
12.  As you can see, those values were slid to the left, leaving the
original values in the three vacated bytes on the right.

Duplicating a buffer

The code in Listing 15 creates a new buffer that is a duplicate of the
buffer referred to by buf2.  Then it displays the contents
of the original buffer and the new buffer.

 

    System.out.println("Duplicating");
    ByteBuffer buf3 = buf2.duplicate();
    buf2.position(0);
    showBufferData(buf2, "buf2");
    buf3.position(0);
    showBufferData(buf3, "buf3");

Listing 15

The duplicate method

Invoking the duplicate method on a buffer creates a new buffer
that shares the original buffer’s content.  In the same sense that
we have seen backing arrays linked to buffers, this process causes two
buffers to be similarly linked.  Changes to the original buffer’s
content will be reflected in the new buffer, and vice versa.  However,
position,
limit,
and mark values for the two buffers are independent of one another.

The new buffer’s initial capacity, limit, position,
and mark values are identical to those of the original buffer. The
new buffer will be direct if the original buffer is
direct,
and it will be read-only if the original buffer is read-only.

The output

Figure 15 shows the output produced by the code in Listing 15.

 

Duplicating
Buffer data for buf2
1 2 20 21 22 0 0 22 0 0
Buffer data for buf3
1 2 20 21 22 0 0 22 0 0

Figure 15

As you would expect from the name duplicate, the values in the
two buffers are identical.

Demonstrate that the buffers are linked

The code in Listing 16 demonstrates that the two buffers are linked
as described above.  This code changes the value at position
7 in one of the buffers, from 22 to 99, and then displays the contents
of both buffers.

 

    buf3.put(7,(byte)99);
    buf2.position(0);
    showBufferData(buf2, "buf2");
    buf3.position(0);
    showBufferData(buf3, "buf3");

Listing 16

The output

The output produced by Listing 16 is shown in Figure 16.

 

Buffer data for buf2
1 2 20 21 22 0 0 99 0 0
Buffer data for buf3
1 2 20 21 22 0 0 99 0 0

Figure 16

As you can see, both buffers now contain the value 99 in position
7.

Slicing a buffer

Listing 17 creates a new buffer, which contains a slice of the
data contained in the buffer referred to by buf2.

 

    System.out.println("Slice");
    buf2.position(3);
    ByteBuffer buf4 = buf2.slice();
    buf2.position(0);
    showBufferData(buf2, "buf2");
    buf4.position(0);
    showBufferData(buf4, "buf4");

Listing 17

The slice method

Invoking the slice method on a buffer creates a new buffer whose
content is a shared subsequence of the original buffer’s content.

The content of the new buffer starts at the original buffer’s position
at the time the slice method was invoked.

As was the case with the duplicate method, the content of the
new buffer is linked to the content of the original buffer.  Changes
to the original buffer’s content will be reflected in the new buffer, and
vice versa.  However, position, limit, and mark values
for the two buffers are independent of one another.

The new buffer’s initial position is zero.  Its capacity
and its limit is the number of bytes remaining in the original buffer. 
Its mark is undefined.

The new buffer will be direct if the original buffer is direct,
and it will be read-only if the original buffer is read-only.

Note that the position of the original buffer was set to 3 in
Listing 12.  Therefore the new buffer should contain all of the elements
from element 3 to the limit.

The output

Figure 17 shows the output produced by the code in Listing 17.

 

Slice
Buffer data for buf2
1 2 20 21 22 0 0 99 0 0
Buffer data for buf4
21 22 0 0 99 0 0

Figure 17

As you can see, the seven elements in the new buffer (buf4) consist
of the seven boldface elements in the original buffer (buf2).

Linked buffers

Listing 18 demonstrates that the contents of the new buffer are linked
to the contents of the buffer of which it is a slice.

 

    buf4.put(5,(byte)66);
    buf2.position(0);
    showBufferData(buf2, "buf2");
    buf4.position(0);
    showBufferData(buf4, "buf4");

Listing 18

Listing 18 changes the value of the element at position 5 in
the new buffer from zero to 66, and then displays the contents of both
buffers.  The output is shown in Figure 18.

 

Buffer data for buf2
1 2 20 21 22 0 0 99 66 0
Buffer data for buf4
21 22 0 0 99 66 0

Figure 18

As you can see, this change to the new buffer is reflected in the value
of the corresponding element in the original buffer from which the new
buffer is a slice.  Note, however, that the element that is changed
in the original buffer is the element from which the changed element in
the new buffer was extracted.  In this case, a change to the element
at position 5 in the new buffer was reflected by a change in the
element at position 8 in the original buffer.

Direct buffers

All of the buffers used thus far have been non-direct buffers. 
As mentioned earlier, a buffer is either direct or non-direct. 
The difference between the two is rather complex, so I will only scratch
the surface in describing the differences.  For additional information,
you are encouraged to review the topic in the Sun documentation for the
ByteBuffer
class.

This information intended solely to expose the salient points regarding
direct
buffers.

Avoid copying buffers

The Java virtual machine will make a best effort to perform native I/O
operations directly upon a direct buffer. According to Sun, the
JVM “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.”

Possible garbage collector problems

Also, according to Sun, “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
measurable gain in program performance.”

Mapping a file to memory

A direct byte buffer may also be created by mapping a region of a file
directly into memory. I plan to discuss this possibility in a future lesson
when I discuss the FileChannel class.

Create a direct buffer

The code in Listing 19 creates a 25-element direct buffer by
invoking the allocateDirect factory method of the ByteBuffer
class.

 

    ByteBuffer buf5 = 
         ByteBuffer.allocateDirect(25);
    System.out.println(
                   "Buffer is direct: "
                    + buf5.isDirect());
    System.out.println("Order = " 
                       + buf5.order());
    showBufferData(buf5, "buf5");
    if(buf5.hasArray())
      showArrayData(buf5.array());
    else System.out.println(
                   "No backing array");

Listing 19

Invocation of the allocateDirect method allocates a new direct
byte buffer.  The new buffer’s position is zero, its limit
is its capacity, and its mark is undefined.

Does the buffer have a backing array?

According to Sun, “Whether or not it has a backing array is unspecified.” 
The code in Listing 19 checks to see if this buffer has a backing array
by invoking hasArray method on the new buffer object.  When
we view the output, we will see that the answer is no when this program
is executed on my machine.

The byte order

The next set of operations that we will investigate involves storing
data of other primitive types in a buffer of type ByteBuffer
If we were populating the buffers from a source outside of Java, such as
a disk file, we might be interested in the order of the bytes. 
The code in Listing 19 gets and displays the byte order the new buffer.

According to Sun, the ByteBuffer 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 order methods. Specific byte orders are represented by instances
of the ByteOrder class.”

BIG_ENDIAN or LITTLE_ENDIAN

The ByteOrder class supports the following byte orders:

  • BIG_ENDIAN, in which the bytes of a multibyte value are ordered from most
    significant to least significant.
  • LITTLE_ENDIAN, in which the bytes of a multibyte value are ordered from
    least significant to most significant.

The ByteOrder class also provides a static method named nativeOrder,
which retrieves the native byte order of the underlying platform. (For
example, the machine that I am using to compose this lesson reports that
its native byte order is LITTLE_ENDIAN).

According to Sun, “This method is defined so that performance-sensitive
Java code can allocate direct buffers with the same byte order as the hardware.
Native code libraries are often more efficient when such buffers are used.”

Also according to Sun, ” The initial order of a byte buffer is always
BIG_ENDIAN.”

Beyond the scope of this lesson …

Beyond this brief discussion, the topic of byte order for multi-byte
values is beyond the scope of this lesson.  If you would like to see
about 8,000 online references to byte order, go to http://www.google.com/
and search for BIG_ENDIAN.

The output

The code in Listing 19 invokes the order method on the new buffer
to get and display the order of the buffer.  The code also invokes
the isDirect method to confirm that the new buffer is a direct
buffer.

Figure 19 shows the output produced by the fragment of code in Listing
19.

 

Buffer is direct: true
Order = BIG_ENDIAN
Buffer data for buf5
0 0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0 0
0
No backing array

Figure 19

The output confirms that the buffer:

  • Is a direct buffer
  • Is in BIG_ENDIAN order
  • Has 25 elements, each with an initial value of zero
  • Has no backing array

Operations specific to ByteBuffer

Most of the operations that I have discussed so far can be performed
on objects instantiated from any of the classes in the following list (subclasses
of Buffer):

  • ByteBuffer
  • CharBuffer
  • DoubleBuffer
  • FloatBuffer
  • IntBuffer
  • LongBuffer
  • ShortBuffer

In each case, the behavior of the operation is appropriate for the type
of data encapsulated in the object.

As I mentioned earlier in this lesson, the ByteBuffer class also
provides several operations that are not available for the other classes
in the above list.  I will begin explaining those operations at this
point.

Encapsulating other primitive types

In addition to encapsulating data of type byte, an object of
the ByteBuffer class can also encapsulate a mixture of all of the
other primitive types except for boolean.

For access to sequences of values of different types, the ByteBuffer
class defines a family of absolute and relative get
and put methods for each type.

Index is by bytes and not by type

It is important to note however, that the index parameters of the absolute
get
and put methods are in terms of bytes rather than in terms
of the type being read or written.

(For example, one value of type int requires four
bytes in a byte buffer, so an int value that begins at index zero
ends at index 3.  The next value of some type would need to begin
at index 4.)

Invoke relative putDouble method

Listing 20 illustrates storing a primitive double value in a
buffer of type ByteBuffer.

 

    buf5.position(0);
    //...print statement deleted
    System.out.println(
              "Put a double relative");
    buf5.putDouble(1.0/3.0);
    System.out.println("position = " 
                    + buf5.position());

Listing 20

The code in Listing 20 starts by setting the position to zero. 
This specifies where the putDouble method will begin storing the
sequence of bytes that represent the double value (a double
requires eight bytes).

The relative putDouble method

The relative putDouble method is invoked to store a double
value in the buffer beginning at position.  Invocation of the
method writes eight bytes containing the given double value, in
the current byte order, into the buffer at the current position,
and then increments the position by eight.

The output

Then the code in Listing 20 gets and displays the new value of position.

Figure 20 shows the output produced by the code fragment in Listing
20.

 

Put a double relative
position = 8

Figure 20

As you can see, the new value for position is 8.

Store a float and a long

The code in Listing 21 stores two more primitive values, a float,
and a long, by invoking the appropriate relative put method
for the type of data being stored.

 

    System.out.println(
               "Put a float relative");
    buf5.putFloat((float)(1.0/6.0));
    System.out.println("position = " 
                    + buf5.position());
    System.out.println(
                "Put a long relative");
    buf5.putLong(Long.MAX_VALUE);
    System.out.println("position = " 
                    + buf5.position());

Listing 21

In each case, the code in Listing 21 gets and displays the new value
of position after storing the value.

The output

Figure 21 shows the output produced by the code in Listing 21.

 

Put a float relative
position = 12
Put a long relative
position = 20

Figure 21

There should be no surprises in Figure 21.  In each case, the value
of position was incremented by the number of bytes required to store
the value.

Get and display primitive values

The code in Listing 22 sets position to zero, and then invokes
the appropriate relative get method to get and display each of the
primitive values stored earlier in Listings 20 and 21.

 

    buf5.position(0);
    System.out.println(
                "Get double relative");
    System.out.println(
                     buf5.getDouble());
    System.out.println("position = " 
                    + buf5.position());
    System.out.println(
                 "Get float relative");
    System.out.println(
                      buf5.getFloat());
    System.out.println("position = " 
                    + buf5.position());
    System.out.println(
                  "Get long relative");
    System.out.println(buf5.getLong());
    System.out.println("position = " 
                    + buf5.position());

Listing 22

Note that for data of mixed types, the program must know where to begin,
and must know the type order in which to extract the values.

The relative getDouble method

The relative getDouble method, which is representative
of similar methods of all the non-boolean types, reads the next eight bytes
at the buffer’s current position, composing them into a double
value, according to the current byte order.  Then it increments
the
position by eight.

The output

Figure 22 shows the output produced by the code in Listing 22.

 

Get double relative
0.3333333333333333
position = 8
Get float relative
0.16666667
position = 12
Get long relative
9223372036854775807
position = 20

Figure 22

Again, there should be no surprises in Figure 22.  In each case,
the value stored earlier is retrieved and the position is incremented
by the number of bytes appropriate for the type involved.

Perhaps the biggest problem to be faced with using this capability of
mixed types is keeping track of what type is stored in which set of bytes
so that they can be successfully retrieved later.

If you would like to see the effect of having a mix-up in
byte order, insert the following statement after the put code in
Listing 21 and before the get code in Listing 22.  This will
cause the multibyte values to be stored as BIG_ENDIAN and retrieved as
LITTLE_ENDIAN.  Then examine the values that are displayed to see
if they make sense.

buf5.order(ByteOrder.LITTLE_ENDIAN);

Absolute get and put methods for other types

In addition to the relative get and put methods
discussed above, the ByteBuffer class also provides absolute
get
and put methods for all primitive types other than
boolean.

Listing 23 uses the absolute version of the getFloat method
to get and display the float value stored earlier in Listing 21.

 

    System.out.println(
                 "Get float absolute");
    System.out.println(
                     buf5.getFloat(8));
    System.out.println("position = " 
                    + buf5.position());

Listing 23

Don’t use and don’t modify the position
property

Note that the absolute versions of this family of methods don’t
use the value of position to read, and don’t modify the value of
position. 
Rather, the position from which the bytes should be read is provided by
an incoming index parameter.

Listing 23 gets and displays the value of position after getting
and displaying the float value beginning at element index 8.

The output

Figure 23 shown the output produced by the code in Listing 23.

 

Get float absolute
0.16666667
position = 20

Figure 23

Note that the value of the position property is still 20, which
is the value established earlier by the code in Listing 22.

Put and get absolute for type int

Listing 24 illustrates the use of the absolute putInt
method to put a primitive int value into the buffer beginning
at element index 20.

 

    System.out.println(
                   "Put int absolute");
    buf5.putInt(20,Integer.MAX_VALUE);
    System.out.println(
                   "Get int absolute");
    System.out.println(
                      buf5.getInt(20));
    System.out.println("position = " 
                    + buf5.position());

Listing 24

Then the code uses the absolute getInt method to get and
display the int value stored at that location.

Figure 24 shows the output produced by the code in Listing 24.

 

Put int absolute
Get int absolute
2147483647
position = 20

Figure 24

By now, you should be able to understand this code, and the output that
it produces with no further discussion on my part.

Time for a break

If you haven’t taken a break since you first started reading this lesson,
this would be a good time to do so.  We are getting ready to switch
gears and move in a somewhat different direction.

Working with views

Another major capability is provided by the ByteBuffer class
for the case where the buffer contains types other than byte or
boolean,
and where all of the data stored in the buffer is of the same type.

Methods to create view buffers

The ByteBuffer class defines methods to create views of a given
buffer, when all of the data in the buffer is of the same type.

(Actually, all the data in the buffer doesn’t have to be
of the same type, but all of the data between the current position and
the limit must be of the same type in order for the results to be meaningful.)

A view buffer is another buffer (of a type other than ByteBuffer)
whose
content is backed by the buffer of type ByteBuffer.  The data
contained in the view buffer is the data contained in the byte buffer,
between position and limit, when the view buffer is created.

A backing buffer

Changes made to the byte buffer’s content will be reflected in the view
buffer (assuming that the change is made to an element that is common
between the two),
and changes made to the view buffer will be reflected
in the byte buffer.  However, the values of the two buffers’ position,
limit,
and mark properties are independent of one another.

Advantages of a view buffer

A view buffer is indexed in terms of the type-specific size of its values
instead of being indexed in terms of the number of bytes.

A view buffer provides relative get and put methods for
transferring contiguous sequences of values (for types other than byte
and boolean)
between a buffer and an array or some other buffer
of the same type.

According to Sun, “A view buffer is potentially much more efficient
because it will be direct if, and only if, its backing byte buffer is direct.”

Prepare some data in a buffer

To begin working with views, we first need to put some data, all of
the same type, in a byte buffer.  The code in Listing 25 begins by
clearing one of our existing byte buffers.

 

    buf5.clear();
    showBufferProperties(buf5, "buf5");
    buf5.putInt((int)1);
    buf5.putInt((int)2);
    buf5.putInt((int)4);
    buf5.putInt((int)8);
    buf5.putInt((int)16);
    buf5.putInt((int)32);
    buf5.position(0);
    System.out.println(
                      "Raw byte data");
    showBufferData(buf5, "buf5");

Listing 25

The clear method

As the name of the method implies, when the clear method is invoked
on a buffer, the position is set to zero, the limit is set
to the capacity, and the mark is discarded.

However, according to Sun, “This method does not actually erase the
data in the buffer, but it is named as if it did because it will most often
be used in situations in which that might as well be the case.”

After the buffer is cleared, the code in Listing 25 invokes the showBufferProperties
method to confirm that the values of the properties are as explained above.

Invoke the relative putInt method

Then the code in Listing 25 invokes the putInt method six times
in succession to store six different int values in the buffer.

Recall that an int value in Java is stored in 32 bits (four
bytes)
in two’s complement notation.  The int values stored
in the buffer in Listing 25 were chosen so that each of the six values
was small enough to reside in the least significant byte of its four-byte
group.  You will see why I did this in Figure 25, which shows the
output produced by the code in Listing 25.

The output

After storing the six int values in the buffer, (which requires
24 bytes),
the code in Listing 25 displays the buffer in raw byte format. 
The output is shown in Figure 25.

 

Buffer Properties for buf5
  capacity=25 limit=25 position=0
Raw byte data
Buffer data for buf5
0 0 0 1 0 0 0 2 0 0 0 4
0 0 0 8 0 0 0 16 0 0 0 32
0

Figure 25

For purposes of this presentation, I colored each of the four-byte groups
that constitute the six int values in alternating colors of red
and blue.  You should be able to correlate the values in those bytes
with the int values stored in the buffer by the code in Listing
25.

The final byte in the buffer was not used in the storage of the six
int
values.  Therefore, I left it black.

ByteBuffer is indexed on bytes

Even though it is possible to store primitive values other than byte
in a buffer of type ByteBuffer, it isn’t always easy to work with
them later because the buffer is always indexed on the number of bytes.

For example, we would like to be able to iterate on the buffer to gain
access to each primitive int value in succession.  We saw earlier
(in
the method named showBufferData)
that it is very to use the
hasRemaining
method and the relative get method to iterate on a byte buffer containing
data of type byte.

This approach doesn’t always work

However, an attempt to use that same approach when the type of data
is something other than byte only works if the capacity of
the buffer is an even multiple of the byte size of the data type stored
in the buffer.  For example, the code shown in Listing 26 is similar
to the showBufferData method (with get replaced by getInt)
but it won’t work properly in this case.

 

    buf5.position(0);
    showBufferProperties(buf5, "buf5");
/******
    while(buf5.hasRemaining()){
      System.out.print(
                  buf5.getInt() + " ");
    }//end while loop
******/

Listing 26

The code in Listing 26 throws an exception after retrieving each of
the six int values.  (Therefore it was necessary for me
to put it in comments to cause the program to run successfully without
throwing an exception.)

The problem is that the six int values only consume 24 of the
25 bytes in the buffer.  After all six of the int values have
been read, the 25th byte is left dangling.  This causes the hasRemaining
method to return true when in fact, there are no more int
values remaining in the buffer.  This causes the getInt method
to be invoked one more time, and an attempt to invoke getInt at
this point causes an exception to be thrown.

A more complex approach

Of course, it is possible to iterate over the int values stored
in the buffer using more complex code, as shown in Listing 27.

 

    int cnt = 0;
    while(cnt < buf5.limit()-4){
      System.out.print(
               buf5.getInt(cnt) + " ");
      cnt += 4;
    }//end while loop

Listing 27

However, it would be nice if a simpler approach were available (and
a view provides the simpler approach).

The output

Figure 27 shows the output produced by the code in Listing 27.

 

1 2 4 8 16 32

Figure 27

As you might expect, the code in Listing 27 displays the six int
values stored in the buffer by the code in Listing 25.

Get a view buffer

The code in Listing 28 invokes the asIntBuffer method on the
byte buffer to create a view buffer of type IntBuffer.

 

    buf5.position(0);
    IntBuffer buf6 = 
                    buf5.asIntBuffer();
    showBufferProperties(buf6, "buf6");
    System.out.println("Read-only = " 
                  + buf6.isReadOnly()); 

Listing 28

The asIntBuffer method

Invocation of asIntBuffer on a byte buffer creates a view object
of the byte buffer as type IntBuffer (another subclass of Buffer). 
This causes the methods of the IntBuffer class to become available
for performing operations on the new view buffer.

(Note that the invocation of asIntBuffer on a byte
buffer only makes sense when the byte buffer contains a sequence of int
values between the current value of the position property and the
value of the limit property.  However, I don’t believe there
are any safety nets to keep you from invoking the asIntBuffer method
on a byte buffer even when it isn’t appropriate.  You won’t get a
compiler error, and you probably won’t get a runtime error either, unless
there is a buffer overflow or buffer underflow.  Viewing the data
through the view buffer simply won’t make any sense.  From the viewpoint
of safety, these new programming capabilities are more like programming
in C or C++ than programming in Java.)

The view buffer

The content of the view buffer starts at the byte buffer’s current position.

Once the view buffer has been created, changes to the byte buffer’s
content will be reflected in the view buffer, and vice versa.  However,
the values of the two buffers’ position, limit, and mark
properties will be independent.

The view buffer’s initial position is zero.  Its capacity
and its
limit are the number of bytes remaining in the byte buffer
divided by four (for type int).  Its mark is
undefined.

The view buffer will be direct if the byte buffer is direct,
and it will be read-only if the byte buffer is read-only.

The output

After creating the view buffer, the code in Listing 28 displays its
properties and checks to see if it is a read-only buffer.  Figure
28 shows the output produced by the code in Listing 28.

 

Buffer Properties for buf6
  capacity=6 limit=6 position=0
Read-only = false

Figure 28

The capacity and the limit for the view buffer are equal
to the number of int values reflected in the buffer, and the position
is set to zero.

Iterate on the view buffer

The code in Listing 29 uses the relative get method of the IntBuffer
class, along with the hasRemaining method of the Buffer class
to get and to display each of the int values reflected in the view
buffer.

 

    while(buf6.hasRemaining()){
      System.out.print(
                     buf6.get() + " ");
    }//end while loop

Listing 29

Note the simplicity of the code in Listing 29, as compared to the code
in Listing 27.

The output

The output produced by the code in Listing 29 (shown in Figure 29)
is exactly the same as the output produced by the more complex code in
Listing 27.

 

1 2 4 8 16 32

Figure 29

In both cases, the code gets and displays the six int values
stored in the buffer of type ByteBuffer.  However, the code
in Listing 29 operates on a view buffer of type IntBuffer, whereas
the code in Listing 27 operates on the original buffer of type ByteBuffer.

Get an int value with the absolute get
method

Listing 30 illustrates another major advantage of using a view buffer.

 

    System.out.println("Element 4 = " 
                        + buf6.get(4));

Listing 30

The code in Listing 30 gets and displays the int value at position
4 in the view buffer.  Note that when invoking the absolute get
method on the view buffer, it isn’t necessary to take into account the
number of bytes required to form each int value.  In other
words, the view buffer of type IntBuffer is indexed by byte groups
(where
each group consists of the number of bytes required to store a value of
type int)
and not by raw byte numbers.

To access the same int value from the byte buffer, it would be
necessary to invoke the getInt method on the buffer and to specify
the proper index, taking into account that each int value requires
four bytes.

Figure 30 shows the output produced by the code in Listing 30.

 

Element 4 = 16

Figure 30

You can confirm that this is correct by comparing the value with that
shown in Figure 29.

Using absolute put method on the view
object

New int values can be stored in the underlying buffer of type
ByteBuffer
by invoking the absolute put method on the view object.  This
is illustrated in Listing 31, which invokes the absoluteput
method on the view object to store the int value 99 at
position
4.

 

    buf6.put(4,99);

    buf6.position(0);
    //...print statement deleted
    while(buf6.hasRemaining()){
      System.out.print(
                     buf6.get() + " ");
    }//end while loop

Listing 31

After storing the new value, the code in Listing 31 iterates on the
view object to display the contents of the shared byte buffer, as reflected
in the view object.  Figure 31 shows the output produced by the code
in Listing 31.

 

1 2 4 8 99 32

Figure 31

Note that the int value of 16 previously stored in position
4 has now been replaced by an int value of 99.

Show the backing buffer

Keep in mind that changes made to the view are also reflected in the
backing buffer, which is the original buffer of type ByteBuffer.

The code in Listing 32 displays the contents of the original buffer
of type ByteBuffer in raw byte form, twelve bytes per line.

 

    buf5.position(0);
    showBufferData(buf5, "buf5");

Listing 32

Figure 32 shows the output from the code in Listing 32.

 

Buffer data for buf5
0 0 0 1 0 0 0 2 0 0 0 4
0 0 0 8 0 0 0 99 0 0 0 32
0

Figure 32

Once again, I have colored the four-byte groups that constitute the
six int values in alternating colors of red and blue.  Note
in particular the boldface red group that now contains the value 99 in
the least significant byte.  If you refer back to Figure 25, you will
see that the least significant byte of this group contained 16 before the
change was made to the view object.

A read-only view of type byte

Each of the seven subclasses of the Buffer class provide a method
named asReadOnlyBuffer, which can be used to create a read-only
view buffer for that buffer type.  This is illustrated in Listing
33.

 

    buf5.position(0);
    ByteBuffer buf7 = 
               buf5.asReadOnlyBuffer();
    System.out.println("Read-only = " 
                  + buf7.isReadOnly());

Listing 33

The asReadOnlyBuffer method

Invocation of the asReadOnlyBuffer method on a buffer creates
a new, read-only buffer that shares the original buffer’s content.

The content of the new buffer is the same as the content of the original
buffer (regardless of the value of position when the asReadOnlyBuffer
method is invoked).

Changes to the original buffer’s content are reflected in the new buffer. 
However, the new buffer is read-only and its content cannot be modified. 
Therefore, the shared content cannot be modified by making changes to the
read-only buffer.  The values of the two buffers’ position, limit,
and
mark
properties are independent of one another

The new buffer’s initial capacity, limit, position, and mark
values are identical to those of the original buffer.

The output

Figure 33 shows the output produced by the code in Listing 33.

 

Read-only = true

Figure 33

As you can see from Figure 33, invocation of the isReadOnly method
on the new buffer confirms that it is a read-only buffer.

Compare the two buffers

The code in Listing 34 displays the contents of the original buffer
and the read-only view buffer to confirm that they have the same contents.

 

    System.out.println(
                "Show backing buffer");
    showBufferData(buf5, "buf5");
    System.out.println(
                     "Show view data");
    showBufferData(buf7, "buf7");

Listing 34

The output shown in Figure 34 confirms that the two buffers do have
the same contents.

 

Show backing buffer
Buffer data for buf5
0 0 0 1 0 0 0 2 0 0 0 4
0 0 0 8 0 0 0 99 0 0 0 32
0
Show view data
Buffer data for buf7
0 0 0 1 0 0 0 2 0 0 0 4
0 0 0 8 0 0 0 99 0 0 0 32
0

Figure 34

Modify the backing buffer

The code in Listing 35 modifies the value in the first byte of the original
backing buffer, and then displays the contents of both buffers to confirm
that changes to the original buffer are reflected in the read-only view
buffer.

 

    buf5.put(0,(byte)66);
    System.out.println(
                "Show backing buffer");
    buf5.position(0);
    showBufferData(buf5, "buf5");
    System.out.println(
                     "Show view data");
    buf7.position(0);
    showBufferData(buf7, "buf7");

Listing 35

Figure 35 shows the output produced by the code in Listing 35, and does
confirm that changes made to the backing buffer are reflected in the view
buffer.

 

Show backing buffer
Buffer data for buf5
66 0 0 1 0 0 0 2 0 0 0 4
0 0 0 8 0 0 0 99 0 0 0 32
0
Show view data
Buffer data for buf7
66 0 0 1 0 0 0 2 0 0 0 4
0 0 0 8 0 0 0 99 0 0 0 32
0

Figure 35

In particular, when the value in the first byte in the original buffer
was changed to 66, this new value was reflected in the first byte of the
view buffer.

Modify the view buffer – oops, not possible

An attempt to execute the statement shown as a comment in Listing 36
causes the program to throw an exception

 

    //buf7.put(0,(byte)66);

Listing 36

This confirms that this view buffer really is a read-only buffer.

That’s it for now

By now you should understand a quite a lot about the ByteBuffer
class in the new java.nio package.

Future articles will discuss channels and other new I/O features introduced
in Java version 1.4.0.  Those discussions will depend heavily on an
understanding of the Buffer class and its subclasses, including
ByteBuffer.

Run the Program


If you haven’t already done so, I encourage you to copy the code from Listing
37 into your text editor, compile it, and execute it.  Experiment
with it, making changes, and observing the results of your changes.

Remember, however, that you must be running Java version 1.4.0 or later
to compile and execute this program.

Complete Program Listing


Complete listings of the programs discussed in this lesson are shown in
Listing 37 and 38 below.

 

/* File ByteBuffer01.java
Copyright 2002, R.G.Baldwin

Illustrates most of the features of
the ByteBuffer class.

Tested using JDK 1.4.0 under Win 2000.

The output is:

Create and populate array
Show array data
0 1 2 3 4 5 6 7

Wrap byte array in buffer
Buffer is direct: false
Buffer data for buf1
0 1 2 3 4 5 6 7

Modify first array element
Show array data
10 1 2 3 4 5 6 7
Buffer data for buf1
10 1 2 3 4 5 6 7

Modify the buffer
Buffer data for buf1
10 1 2 20 21 22 6 7
Show array data
10 1 2 20 21 22 6 7

Get absolute
Element 3 = 20
Element 5 = 22
Element 7 = 7

Contiguous get
Buffer data for buf1
10 1 2 20 21 22 6 7
Show array data
0 0 0 0 0 0 0 0 0 0
Show array data
0 0 0 1 2 20 21 22 0 0

Contiguous put from array
Show array data
0 0 0 1 2 20 21 22 0 0
Buffer data for buf1
0 0 1 2 20 21 22 0

Contiguous put from buffer
Buffer is direct: false
Buffer data for buf2
0 0 0 0 0 0 0 0 0 0
Buffer data for buf1
0 0 1 2 20 21 22 0
Buffer data for buf2
0 0 0 1 2 20 21 22 0 0
Show array data
0 0 0 1 2 20 21 22 0 0

Compacting
Buffer data for buf2
22 0 0
Buffer data for buf2
1 2 20 21 22 0 0 22 0 0

Duplicating
Buffer data for buf2
1 2 20 21 22 0 0 22 0 0
Buffer data for buf3
1 2 20 21 22 0 0 22 0 0
Buffer data for buf2
1 2 20 21 22 0 0 99 0 0
Buffer data for buf3
1 2 20 21 22 0 0 99 0 0

Slice
Buffer data for buf2
1 2 20 21 22 0 0 99 0 0
Buffer data for buf4
21 22 0 0 99 0 0
Buffer data for buf2
1 2 20 21 22 0 0 99 66 0
Buffer data for buf4
21 22 0 0 99 66 0

Other primitive types
Buffer is direct: true
Order = BIG_ENDIAN
Buffer data for buf5
0 0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0 0
0
No backing array
Put and get primitive types
Put a double relative
position = 8
Put a float relative
position = 12
Put a long relative
position = 20

Get double relative
0.3333333333333333
position = 8
Get float relative
0.16666667
position = 12
Get long relative
9223372036854775807
position = 20

Get float absolute
0.16666667
position = 20

Put int absolute
Get int absolute
2147483647
position = 20

Work with views
Clear buf5
Buffer Properties for buf5
  capacity=25 limit=25 position=0
Raw byte data
Buffer data for buf5
0 0 0 1 0 0 0 2 0 0 0 4
0 0 0 8 0 0 0 16 0 0 0 32
0

This won't always work

More complex approach
1 2 4 8 16 32

Get a view
Buffer Properties for buf6
  capacity=6 limit=6 position=0
Read-only = false

Get relative from view
1 2 4 8 16 32
Get absolute from view
Element 4 = 16

Put absolute in view
Show modified view
1 2 4 8 99 32
Show backing buffer
Buffer data for buf5
0 0 0 1 0 0 0 2 0 0 0 4
0 0 0 8 0 0 0 99 0 0 0 32
0

Create read-only view
Read-only = true
Show backing buffer
Buffer data for buf5
0 0 0 1 0 0 0 2 0 0 0 4
0 0 0 8 0 0 0 99 0 0 0 32
0
Show view data
Buffer data for buf7
0 0 0 1 0 0 0 2 0 0 0 4
0 0 0 8 0 0 0 99 0 0 0 32
0

Modify backing buffer
Show backing buffer
Buffer data for buf5
66 0 0 1 0 0 0 2 0 0 0 4
0 0 0 8 0 0 0 99 0 0 0 32
0
Show view data
Buffer data for buf7
66 0 0 1 0 0 0 2 0 0 0 4
0 0 0 8 0 0 0 99 0 0 0 32
0

Modify view oops!

**************************************/

import java.nio.*;

class ByteBuffer01{
  static void showBufferProperties(
               Buffer buf,String name){
    System.out.println(
       "Buffer Properties for " + name
                    +"n  capacity=" 
                    + buf.capacity()
                    + " limit=" 
                    + buf.limit()
                    + " position=" 
                    + buf.position());
  }//end showBufferProperties
  //---------------------------------//
  
  static void showBufferData(
          ByteBuffer buf, String name){
    //Displays buffer contents from 
    // current position to limit using
    // relative get method, twelve 
    // elements per row.
    System.out.println(
            "Buffer data for " + name);
    int cnt = 0;
    while(buf.hasRemaining()){
      System.out.print(
                      buf.get() + " ");
      cnt++;
      if(cnt%12 == 0)
            System.out.println();//line
    }//end while loop
    System.out.println();//blank line
  }//end showBufferData
  //---------------------------------//

  static void showArrayData(
                         byte[] array){
    System.out.println(
                    "Show array data");
    for(int cnt = 0; 
            cnt < array.length; cnt++){
      System.out.print(
                     array[cnt] + " ");
      if((cnt+1)%12 == 0)
            System.out.println();//line
    }//end for loop
    System.out.println();//blank line
  }//end showArrayData
  //---------------------------------//
    
  public static void main(
                        String[] args){
    
    //Wrap a byte array into a buffer
    System.out.println(
          "Create and populate array");
    byte[] a1 = {0,1,2,3,4,5,6,7};
    showArrayData(a1);
    System.out.println();//blank line
    
    System.out.println(
          "Wrap byte array in buffer");
    ByteBuffer buf1 = 
                ByteBuffer.wrap(a1);
    System.out.println(
                  "Buffer is direct: " 
                   + buf1.isDirect());
    showBufferData(buf1, "buf1");
    System.out.println();//blank line
        
    //Mods to the buffer will cause the
    // array to be modified and vice 
    // versa.
    System.out.println(
         "Modify first array element");
    a1[0] = 10;
    showArrayData(a1);
    buf1.position(0);
    showBufferData(buf1, "buf1");
    System.out.println();//blank line
    
    System.out.println(
                  "Modify the buffer");
    buf1.put(3,(byte)20);
    buf1.position(4);
    buf1.put((byte)21);
    buf1.put((byte)22);
    buf1.position(0);
    showBufferData(buf1, "buf1");
    showArrayData(a1);
    System.out.println();//blank line
    
    System.out.println("Get absolute");
    System.out.println("Element 3 = " 
                        + buf1.get(3));
    System.out.println("Element 5 = " 
                        + buf1.get(5));
    System.out.println("Element 7 = " 
                        + buf1.get(7));
    System.out.println();//blank line
    
    System.out.println(
                     "Contiguous get");
    buf1.position(0);
    showBufferData(buf1, "buf1");
    byte[] a2 = new byte[10];
    showArrayData(a2);
    buf1.position(1);
    buf1.get(a2, 3, 5);
    showArrayData(a2);
    System.out.println();//blank line
    
    System.out.println(
          "Contiguous put from array");
    showArrayData(a2);
    buf1.position(0);
    buf1.put(a2, 1, 8);
    buf1.position(0);
    showBufferData(buf1, "buf1");
    System.out.println();//blank line
    
    System.out.println(
         "Contiguous put from buffer");
    ByteBuffer buf2 = 
               ByteBuffer.allocate(10);
    System.out.println(
                   "Buffer is direct: "
                    + buf2.isDirect());
    showBufferData(buf2, "buf2");
    buf2.position(1);

    buf1.position(0);
    buf2.put(buf1);
    buf1.position(0);
    showBufferData(buf1, "buf1");
    buf2.position(0);
    showBufferData(buf2, "buf2");
    if(buf2.hasArray())
      showArrayData(buf2.array());
    System.out.println();//blank line
      
    System.out.println("Compacting");
    buf2.position(3);
    buf2.compact();
    showBufferData(buf2, "buf2");
    buf2.position(0);
    showBufferData(buf2, "buf2");
    System.out.println();//blank line
    
    System.out.println("Duplicating");
    ByteBuffer buf3 = buf2.duplicate();
    buf2.position(0);
    showBufferData(buf2, "buf2");
    buf3.position(0);
    showBufferData(buf3, "buf3");
    buf3.put(7,(byte)99);
    buf2.position(0);
    showBufferData(buf2, "buf2");
    buf3.position(0);
    showBufferData(buf3, "buf3");
    System.out.println();//blank line
    
    System.out.println("Slice");
    buf2.position(3);
    ByteBuffer buf4 = buf2.slice();
    buf2.position(0);
    showBufferData(buf2, "buf2");
    buf4.position(0);
    showBufferData(buf4, "buf4");
    buf4.put(5,(byte)66);
    buf2.position(0);
    showBufferData(buf2, "buf2");
    buf4.position(0);
    showBufferData(buf4, "buf4");
    System.out.println();//blank line
    
    //The above operations are common
    // to most of the subclasses of
    // Buffer.  The following 
    // operations are specific to
    // ByteBuffer.
    
    System.out.println(
              "Other primitive types");
    ByteBuffer buf5 = 
         ByteBuffer.allocateDirect(25);
    System.out.println(
                   "Buffer is direct: "
                    + buf5.isDirect());
    System.out.println("Order = " 
                       + buf5.order());
    showBufferData(buf5, "buf5");
    if(buf5.hasArray())
      showArrayData(buf5.array());
    else System.out.println(
                   "No backing array");
    
    buf5.position(0);
    System.out.println(
        "Put and get primitive types");
    System.out.println(
              "Put a double relative");
    buf5.putDouble(1.0/3.0);
    System.out.println("position = " 
                    + buf5.position());
    System.out.println(
               "Put a float relative");
    buf5.putFloat((float)(1.0/6.0));
    System.out.println("position = " 
                    + buf5.position());
    System.out.println(
                "Put a long relative");
    buf5.putLong(Long.MAX_VALUE);
    System.out.println("position = " 
                    + buf5.position());
    System.out.println();//blank line
    
    buf5.position(0);
    System.out.println(
                "Get double relative");
    System.out.println(
                     buf5.getDouble());
    System.out.println("position = " 
                    + buf5.position());
    System.out.println(
                 "Get float relative");
    System.out.println(
                      buf5.getFloat());
    System.out.println("position = " 
                    + buf5.position());
    System.out.println(
                  "Get long relative");
    System.out.println(buf5.getLong());
    System.out.println("position = " 
                    + buf5.position());
    System.out.println();//blank line
    
    System.out.println(
                 "Get float absolute");
    System.out.println(
                     buf5.getFloat(8));
    System.out.println("position = " 
                    + buf5.position());
    System.out.println();//blank line
    
    System.out.println(
                   "Put int absolute");
    buf5.putInt(20,Integer.MAX_VALUE);
    System.out.println(
                   "Get int absolute");
    System.out.println(
                      buf5.getInt(20));
    System.out.println("position = " 
                    + buf5.position());
    System.out.println();//blank line
    
    System.out.println(
                    "Work with views");
    System.out.println("Clear buf5");
    buf5.clear();
    showBufferProperties(buf5, "buf5");
    buf5.putInt((int)1);
    buf5.putInt((int)2);
    buf5.putInt((int)4);
    buf5.putInt((int)8);
    buf5.putInt((int)16);
    buf5.putInt((int)32);
    buf5.position(0);
    System.out.println(
                      "Raw byte data");
    showBufferData(buf5, "buf5");
    System.out.println();//blank line
    
    System.out.println(
             "This won't always work");
    //The following works only if the
    // size of the buffer is a 
    // multiple of the number of bytes
    // for the type.
    buf5.position(0);
/*
    showBufferProperties(buf5, "buf5");
    while(buf5.hasRemaining()){
      System.out.print(
                  buf5.getInt() + " ");
    }//end while loop
*/
    System.out.println();//blank line
    
    System.out.println(
              "More complex approach");
    int cnt = 0;
    while(cnt < buf5.limit()-4){
      System.out.print(
               buf5.getInt(cnt) + " ");
      cnt += 4;
    }//end while loop
    System.out.println();//blank line
    System.out.println();//blank line

    System.out.println("Get a view");
    buf5.position(0);
    IntBuffer buf6 = 
                    buf5.asIntBuffer();
    showBufferProperties(buf6, "buf6");
    System.out.println("Read-only = " 
                  + buf6.isReadOnly());
    System.out.println();//blank line 
    
    System.out.println(
             "Get relative from view");
    while(buf6.hasRemaining()){
      System.out.print(
                     buf6.get() + " ");
    }//end while loop
    System.out.println();//blank line

    System.out.println(
             "Get absolute from view");
    System.out.println("Element 4 = " 
                        + buf6.get(4));
    System.out.println();//blank line
    
    System.out.println(
               "Put absolute in view");
    buf6.put(4,99);
    buf6.position(0);
    System.out.println(
                 "Show modified view");
    while(buf6.hasRemaining()){
      System.out.print(
                     buf6.get() + " ");
    }//end while loop
    System.out.println();//blank line

    System.out.println(
                "Show backing buffer");
    buf5.position(0);
    showBufferData(buf5, "buf5");

    System.out.println();//blank line
    
    System.out.println(
              "Create read-only view");
    buf5.position(0);
    ByteBuffer buf7 = 
               buf5.asReadOnlyBuffer();
    System.out.println("Read-only = " 
                  + buf7.isReadOnly());
    
    System.out.println(
                "Show backing buffer");
    showBufferData(buf5, "buf5");
    System.out.println(
                     "Show view data");
    showBufferData(buf7, "buf7");
    System.out.println();//blank line
    
    System.out.println(
              "Modify backing buffer");
    buf5.put(0,(byte)66);
    System.out.println(
                "Show backing buffer");
    buf5.position(0);
    showBufferData(buf5, "buf5");
    System.out.println(
                     "Show view data");
    buf7.position(0);
    showBufferData(buf7, "buf7");
    System.out.println();//blank line

    System.out.println(
                  "Modify view oops!");
    //Following statement throws 
    // exception
    //buf7.put(0,(byte)66);
  
  }// end main

}//end class ByteBuffer01 definition

Listing 37

 

 

/* File ByteBuffer02.java
Copyright 2002, R.G.Baldwin

Illustrates lack of type safety when
using views of a ByteBuffer object.

Creates a ByteBuffer object having 17
elements.

Populates the buffer with two double
values.

Displays the individual bytes in the
buffer.

Views the buffer as type double.

Views the buffer as type int.

Tested using JDK 1.4.0 under Win 2000.

The output is:
  
Show empty byte buffer
Buffer data for buf1
0 0 0 0 0 0 0 0 
0 0 0 0 0 0 0 0 
0 
Populate with double values
Show populated buffer as bytes
Buffer data for buf1
63 -16 0 0 0 0 0 0 
64 0 0 0 0 0 0 0 
0 
View buffer as type double
1.0 2.0 
View buffer as type int
1072693248 0 1073741824 0
**************************************/

import java.nio.*;

class ByteBuffer02{
  
  static void showBufferData(
          ByteBuffer buf, String name){
    //Displays byte buffer contents
    // eight bytes per row.
    
    //Save position
    int pos = buf.position();
    //Set position to zero
    buf.position(0);
    System.out.println(
            "Buffer data for " + name);
    int cnt = 0;
    while(buf.hasRemaining()){
      System.out.print(
                      buf.get() + " ");
      cnt++;
      if(cnt%8 == 0)//start new row
            System.out.println();
    }//end while loop
    System.out.println();//new line
    //Restore position and return
    buf.position(pos);
  }//end showBufferData
  //---------------------------------//
    
  public static void main(
                        String[] args){
    
    ByteBuffer buf1 = 
               ByteBuffer.allocate(17);
    System.out.println(
             "Show empty byte buffer");
    showBufferData(buf1,"buf1");
    System.out.println(
        "Populate with double values");
    buf1.putDouble(1.0);
    buf1.putDouble(2.0);
    System.out.println(
     "Show populated buffer as bytes");
    showBufferData(buf1,"buf1");
    
    System.out.println(
         "View buffer as type double");
    buf1.position(0);
    DoubleBuffer buf2 = //view object
                 buf1.asDoubleBuffer();
    while(buf2.hasRemaining()){
      System.out.print(
                     buf2.get() + " ");
    }//end while loop
    System.out.println();//blank line
    
    System.out.println(
            "View buffer as type int");
    IntBuffer buf3 = //view object
                    buf1.asIntBuffer();
    while(buf3.hasRemaining()){
      System.out.print(
                     buf3.get() + " ");
    }//end while loop
    System.out.println();//blank line
  }// end main

}//end class ByteBuffer02 definition

Listing 38

Copyright 2002, Richard G. Baldwin.  Reproduction in whole or in
part in any form or medium without express written permission from Richard
Baldwin is prohibited.

About the author

Richard Baldwin
is a college professor (at Austin Community College in Austin, TX) and
private consultant whose primary focus is a combination of Java, C#, and
XML. In addition to the many platform and/or language independent benefits
of Java and C# applications, he believes that a combination of Java, C#,
and XML will become the primary driving force in the delivery of structured
information on the Web.

Richard has participated in numerous consulting projects, and he
frequently provides onsite training at the high-tech companies located
in and around Austin, Texas.  He is the author of Baldwin’s Programming
Tutorials,
which has gained a worldwide following among experienced and aspiring programmers.
He has also published articles in JavaPro magazine.

Richard holds an MSEE degree from Southern Methodist University and
has many years of experience in the application of computer technology
to real-world problems.

[email protected]

-end-

 

Latest Posts

Related Stories