This example demonstrates the usage of the Java NioHeapByteBuffer. The Java NioHeapByteBuffer is an odd class, one you will never reference directly and for good reason, it’s package private. Although it’s use is almost guaranteed when working withByteBuffers unless you opt for aDirectByteBuffer (off heap). By virtue of extendingByteBuffer, it also happens to extend Buffer and implement Comparable.
1. Introduction
A Java NioHeapByteBuffer is created via calling the following methods on theByteBuffer class:
allocate(int)wrap(byte[], int, int)wrap(byte[])
All of theget(...)andput(...)methods defined on the super abstract classByteBuffer return the current implementation owing to the fluent API design. If the actual implementation have been aHeapByteBuffer then this will surely be returned.
HeapByteBuffer further specializes intoHeapByteBufferR which is a read only implementation for aHeapByteBuffer disallowing mutations and ensuring that “views” of this type ofByteBuffer only return an instance ofHeapByteBufferR and not the superclass, thus protecting the invariant. AHeapByteBufferR instance is created by callingasReadOnlyBuffer()on an instance ofHeapByteBuffer.
2. Technologies used
The example code in this article was built and run using:
- Java 1.8.101 (1.8.x will do fine)
- Maven 3.3.9 (3.3.x will do fine)
- Spring source tool suite 4.6.3 (Any Java IDE would work)
- Ubuntu 16.04 (Windows, Mac or Linux will do fine)
3. Overview
This article builds upon a previousarticle onByteBuffers in general and I would recommend to read that article first before continuing with this one.HeapByteBuffers are simply the default implementation provided when creating aByteBuffer via the 3 methods listed in the introduction.
One way to ensure you are working with a aHeapByteBuffer implementation is to call theisDirect()method which will returnfalse forHeapByteBuffer andHeapByteBufferR implementations.
HeapByteBuffer instances are, barring escape analysis, always allocated on the Java heap and thus are wonderfully managed by the GC.DirectByteBuffers are not and thus are not easily quantifiable in terms of space.
The reasons for the differentiation stem from the fact that the Operating system can optimize IO operations onDirectByteBuffers because the bytes are guaranteed to be physically contiguous, whereas heap memory is at the whim of the GC and thus means thatHeapByteBuffer bytes may not necessarily be contiguous.
4. Test cases
Testing a HeapByteBuffer identity
public class HeapByteBufferIdentityTest { @Test public void isHeapBuffer() { final ByteBuffer heapBuffer = ByteBuffer.allocate(5 * 10000); final ByteBuffer directBuffer = ByteBuffer.allocateDirect(5 * 10000); assertTrue("Must be direct", directBuffer.isDirect()); assertTrue("Must not be direct", !heapBuffer.isDirect()); } @Test public void persistenIdentityChecker() { final ByteBuffer buffer = ByteBuffer.allocate(5 * 10000); check(buffer, (a) -> !a.duplicate().isDirect()); check(buffer, (a) -> !a.slice().isDirect()); check(buffer, (a) -> !a.put("I am going to trick this buffer".getBytes()).isDirect()); check(buffer, (a) -> !a.asIntBuffer().isDirect()); check(buffer, (a) -> !a.asCharBuffer().isDirect()); check(buffer, (a) -> !a.asFloatBuffer().isDirect()); } private void check(final ByteBuffer buffer, final Predicate<? super ByteBuffer> action) { assertTrue(action.test(buffer)); }}- line 24-26: we accept a predicate which asserts the fact that the
HeapByteBufferstays aHeapByteBufferregardless of the operation we performed on it.
Testing a HeapByteBuffer memory vs DirectByteBuffer
public class HeapByteBufferMemoryTest { private static final Runtime RUNTIME = Runtime.getRuntime(); private ByteBuffer heapBuffer; private ByteBuffer directBuffer; private long startFreeMemory; @Before public void setUp() { this.startFreeMemory = RUNTIME.freeMemory(); } @Test public void memoryUsage() { this.heapBuffer = ByteBuffer.allocate(5 * 100000); long afterHeapAllocation = RUNTIME.freeMemory(); assertTrue("Heap memory did not increase", afterHeapAllocation > this.startFreeMemory); this.directBuffer = ByteBuffer.allocateDirect(5 * 100000); assertTrue("Heap memory must not increase", RUNTIME.freeMemory() >= afterHeapAllocation); }}- In this test case we attempt to prove that allocating a
HeapByteBufferwill have an impact on heap memory usage whereas the allocation of aDirectByteBufferwill not.
Testing the read only properties of a HeapByteBuffer
public class HeapByteBufferReadOnlyTest { private ByteBuffer buffer; @Before public void setUp() { this.buffer = ByteBuffer.allocate(5 * 10000); } @Test(expected = ReadOnlyBufferException.class) public void readOnly() { this.buffer = this.buffer.asReadOnlyBuffer(); assertTrue("Must be readOnly", this.buffer.isReadOnly()); this.buffer.putChar('b'); } @Test(expected = ReadOnlyBufferException.class) public void readOnlyWithManners() { this.buffer = this.buffer.asReadOnlyBuffer(); assertTrue("Must be readOnly", this.buffer.isReadOnly()); this.buffer.put("Please put this in the buffer".getBytes()); } @Test public void persistenReadOnlyChecker() { this.buffer = buffer.asReadOnlyBuffer(); check(this.buffer, (a) -> a.duplicate().put("I am going to trick this buffer".getBytes())); check(this.buffer, (a) -> a.slice().put("I am going to trick this buffer".getBytes())); check(this.buffer, (a) -> a.put("I am going to trick this buffer".getBytes())); check(this.buffer, (a) -> a.asIntBuffer().put(1)); check(this.buffer, (a) -> a.asCharBuffer().put('c')); check(this.buffer, (a) -> a.asFloatBuffer().put(1f)); } private void check(final ByteBuffer buffer, final Consumer>? super ByteBuffer< action) { try { action.accept(buffer); fail("Must throw exception"); } catch (ReadOnlyBufferException e) { } }}- lines 35-41: we invoke a function that should throw a
ReadOnlyBufferExceptionproving the property of read only despite creating a different view of theHeapByteBufferthrough it’s api. Various methods are called ranging fromput(...)toduplicate(),sice()etc. to try and break this property
Cloning a HeapByteBuffer into a DirectByteBuffer
Thank you!
We will contact you soon.
public class HeapByteBufferIdentityCrisisTest { @Test public void shapeShift() { final ByteBuffer buffer = ByteBuffer.wrap("Hello world!".getBytes()); assertTrue("Not a heap buffer", !buffer.isDirect()); final ByteBuffer shapeShifter = ByteBuffer.allocateDirect(buffer.capacity()).put(getBytes(buffer)); assertTrue("Not a direct buffer", shapeShifter.isDirect()); shapeShifter.flip(); byte [] contents = new byte[shapeShifter.capacity()]; shapeShifter.get(contents); assertEquals("Invalid text", "Hello world!", new String(contents).trim()); } private byte [] getBytes(final ByteBuffer buffer) { byte [] dest = new byte[buffer.remaining()]; buffer.get(dest); return dest; }}- lines 18-22 we copy the bytes (remaining) between
positionandlimitinto a destinationbyte []. This is to ensure that the content of the originalHeapByteBufferare exumed and made ready for insertion into a comingDirectByteBuffer - I did not concern myself with encoding and decoding explicitness in this test. I refer you to a previousarticle in this series which does those test cases explicit in theCharset usage during encoding and decoding.
5. Summary
This example demonstrated the creation and usage of aHeapByteBuffer implementation of aByteBuffer. It proved properties of the API and attempted to demonstrate the core difference in implementation between this and aDirectByteBuffer in terms of memory allocation.
6. Download the source code
This was a Java Nio HeapByteBuffer example.
You can download the full source code of this example here:Java Nio HeapByteBuffer example
Thank you!
We will contact you soon.
