Using Java MappedByteBuffer

1. Overview

In this quick article, we’ll be looking at the MappedByteBuffer in the java.nio package. This utility can be quite useful for efficient file reads.

2. How MappedByteBuffer Works

When we’re loading a region of the file, we can load it to the particular memory region that can be accessed later.

When we know that we’ll need to read the content of a file multiple times, it’s a good idea to optimize the costly process e.g. by saving that content in the memory. Thanks to that, subsequent lookups of that part of the file will go only to the main memory without the need to load the data from the disc, reducing latency substantially.

One thing that we need to be careful with when using the MappedByteBuffer is when we’re working with very large files from disc – we need to make sure the file will fit in memory.

Otherwise, we can fill up the entire memory and, as a consequence, run into the common OutOfMemoryException. We can overcome that by loading only part of the file – based for example on usage patterns.

3. Reading the File Using MappedByteBuffer

Let’s say that we have a file called fileToRead.txt with the following content:

This is a content of the file

The file is located in the /resource directory so we can load it using the following function:

Path getFileURIFromResources(String fileName) throws Exception {
    ClassLoader classLoader = getClass().getClassLoader();
    return Paths.get(classLoader.getResource(fileName).getPath());
}

To create the MappedByteBuffer from a file, firstly we need to create a FileChannel from it. Once we have our channel created, we can invoke the map() method on it passing in the MapMode, a position from which we want to read, and the size parameter that specifies how many bytes we want:

CharBuffer charBuffer = null;
Path pathToRead = getFileURIFromResources("fileToRead.txt");

try (FileChannel fileChannel (FileChannel) Files.newByteChannel(
  pathToRead, EnumSet.of(StandardOpenOption.READ))) {
 
    MappedByteBuffer mappedByteBuffer = fileChannel
      .map(FileChannel.MapMode.READ_ONLY, 0, fileChannel.size());

    if (mappedByteBuffer != null) {
        charBuffer = Charset.forName("UTF-8").decode(mappedByteBuffer);
    }
}

Once we mapped our file into the memory mapped buffer, we can read the data from it into the CharBuffer. Important to note is that although we are reading the content of the file when we call the decode() method passing MappedByteBuffer, we read from memory, not from the disc. Therefore that read will be very fast.

We can assert that content that we read from our file is the actual content of the fileToRead.txt file:

assertNotNull(charBuffer);
assertEquals(
  charBuffer.toString(), "This is a content of the file");

Every subsequent read from the mappedByteBuffer will be very fast because the content of the file is mapped in memory and reading is done without a need to lookup data from the disc.

4. Writing to the File using MappedByteBuffer

Let’s say that we want to write some content into the file fileToWriteTo.txt using the MappedByteBuffer API. To achieve that we need to open the FileChannel and call the map() method on it, passing in the FileChannel.MapMode.READ_WRITE. 

Next, we can save the content of the CharBuffer into the file using the put() method from the MappedByteBuffer:

CharBuffer charBuffer = CharBuffer
  .wrap("This will be written to the file");
Path pathToWrite = getFileURIFromResources("fileToWriteTo.txt");

try (FileChannel fileChannel = (FileChannel) Files
  .newByteChannel(pathToWrite, EnumSet.of(
    StandardOpenOption.READ, 
    StandardOpenOption.WRITE, 
    StandardOpenOption.TRUNCATE_EXISTING))) {
    
    MappedByteBuffer mappedByteBuffer = fileChannel
      .map(FileChannel.MapMode.READ_WRITE, 0, charBuffer.length());
    
    if (mappedByteBuffer != null) {
        mappedByteBuffer.put(
          Charset.forName("utf-8").encode(charBuffer));
    }
}

We can assert that the actual content of the charBuffer was written to the file by reading the content of it:

List<String> fileContent = Files.readAllLines(pathToWrite);
assertEquals(fileContent.get(0), "This will be written to the file");

5. Conclusion

In this quick tutorial, we were looking at the MappedByteBuffer construct from the java.nio package.

This is a very efficient way to read a content of the file multiple times, as the file is mapped into memory and subsequent reads do not need to go to disc every time.

All these examples and code snippets can be found over on GitHub – this is a Maven project, so it should be easy to import and run as it is.