jbssio

JVM	Platform	Status
OpenJDK (Temurin) Current	Linux
OpenJDK (Temurin) LTS	Linux
OpenJDK (Temurin) Current	Windows
OpenJDK (Temurin) LTS	Windows

jbssio

The jbssio package implements a set of types and functions for efficient, structural binary I/O.

Features

• Efficient binary I/O over streams, channels, and byte buffers.
• Nested, bounded stream abstraction to increase readability of code and improve diagnostic information.
• High coverage test suite.
• OSGi-ready
• JPMS-ready
• ISC license.

Usage

The jbssio package provides imperative reader and writer abstractions. Readers and writers may be sequential, meaning that they encapsulate a stream in which only forward seeking is allowed, or random access, meaning that they encapsulate a resource that allows for arbitrary forwards and backwards seeking. The API attempts, as much as is possible, to present a common API for both sequential and random access so that code using readers and writers can potentially be agnostic of the seekability of the underlying resources. Current implementations can encapsulate:

• java.io.OutputStream
• java.io.InputStream
• java.nio.channels.SeekableByteChannel
• java.nio.ByteBuffer

Readers and writers are explicitly nested: All offsets/positions of readers and writers are given relative to their parent. A reader or writer with no parent effectively works with absolute positions within an encapsulated resource. Readers and writers may be given explicit bounds to limit the region of the resource from which they may read or write. Bounds, combined with nesting, allow for very easy-to-understand code when parsing complex binary structures. Individual readers and writers are assigned names as they are created, and these names are appended together during nesting to construct detailed diagnostic messages when errors occur. All exceptions raised by the API are structured errors:

com.io7m.seltzer.io.SIOException: Out of bounds.
  Reader URI: file://tmp/example.data
  Reader path: header/info:size
  Reader bounds: absolute [0x0, 0x10)
  Target offset: absolute 0x16
  Offset: absolute 0x0

The above error clearly indicates that the code that was attempting to read the size field, of the info member of the header structure, ended up trying to read more data than the reader was configured to allow: The reader was specified to be allowed to read within the bounds [0x0, 0x10) but the code tried to read beyond these bounds. Note that readers and writers do not know anything about the actual binary structures being parsed; the programmer specifies names that correspond to the structures that the programmer is trying to parse, and the reader and writer implementations use these names in an attempt to construct useful diagnostics.

Readers and writers operate on their underlying resources using simple, explicit read/write methods. For example, the readU32BE method defined for readers reads a single, unsigned, big-endian, 32-bit integer from the current position. Methods exist for all of the common machine types. Additionally, readers and writers contain convenient methods for aligning data, and for reading arbitrary byte sequences. Calls to reader or writer methods advance the current position of the reader or writer.

Reading Data

Retrieve a BSSReaderType and use it to read data:

ServiceLoader.load(BSSReaderProviderType.class)
  .findFirst()
  .orElseThrow(() -> new IllegalStateException("No reader service available"));

try (var channel = Files.newByteChannel(path, READ)) {
  // Create an unbounded reader that will read from the start of the channel
  try (var reader = readers.createReaderFromChannel(pathURI, channel, "root")) {

    // Create a reader that is permitted to read [0, 8) relative to "reader"
    try (var sr = reader.createSubReaderAtBounded("head", 0L, 8L)) {
      var x = sr.readS32BE();
      var y = sr.readS32BE();
    }

    // Create a reader that is permitted to read [8, 16) relative to "reader"
    try (var sr = reader.createSubReaderAtBounded("body", 8L, 16L)) {
      var a = sr.readS32BE();
      var b = sr.readS32BE();
      var c = sr.readS32BE();
      var d = sr.readS32BE();
    }
  }
}

Using ServiceLoader is not required: The various providers in the jbssio package can be used via ServiceLoader, via OSGi declarative services, or simply instantiated manually. See the JavaDoc.

Writing Data

Retrieve a BSSWriterType and use it to write data:

final var readers =
  ServiceLoader.load(BSSWriterProviderType.class)
    .findFirst()
    .orElseThrow(() -> new IllegalStateException("No writer service available"));

try (var channel = Files.newByteChannel(path, WRITE, CREATE)) {
  // Create an unbounded writer that will write from the start of the channel
  try (var writer = writers.createWriterFromChannel(pathURI, channel, "root")) {

    // Create a writer that is permitted to write [0, 8) relative to "writer"
    try (var sw = writer.createSubWriterAtBounded("head", 0L, 8L)) {
      sw.writeS32BE(0x10203040L);
      sw.writeS32BE(0x50607080L);
    }

    // Create a writer that is permitted to write [8, 16) relative to "writer"
    try (var sw = writer.createSubWriterAtBounded("body", 8L, 16L)) {
      sw.writeS32BE(0x90909090L);
      sw.writeS32BE(0x80808080L);
      sw.writeS32BE(0xa0a0a0a0L);
      sw.writeS32BE(0xb0b0b0b0L);
    }
  }
}