Project icon

com.io7m.jbssio

Build status Maven Central Codacy Codecov

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

Contents

Features

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

Releases

The current release is 0.0.1-SNAPSHOT.

Source code and binaries are available from the repository.

Documentation

Documentation for the 0.0.1-SNAPSHOT release is available for reading online.

Documentation for current and older releases is archived in the repository.

User documentation

Overview

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. For example:

The above message 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:

 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:

 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 read [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 read [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);
    }
  }
}
]]>

Maven

The following is a complete list of the project's modules expressed as Maven dependencies:

<dependency>
  <groupId>com.io7m.jbssio</groupId>
  <artifactId>com.io7m.jbssio</artifactId>
  <version>0.0.1-SNAPSHOT</version>
</dependency>

<dependency>
  <groupId>com.io7m.jbssio</groupId>
  <artifactId>com.io7m.jbssio.api</artifactId>
  <version>0.0.1-SNAPSHOT</version>
</dependency>

<dependency>
  <groupId>com.io7m.jbssio</groupId>
  <artifactId>com.io7m.jbssio.tests</artifactId>
  <version>0.0.1-SNAPSHOT</version>
</dependency>

<dependency>
  <groupId>com.io7m.jbssio</groupId>
  <artifactId>com.io7m.jbssio.vanilla</artifactId>
  <version>0.0.1-SNAPSHOT</version>
</dependency>

Each release of the project is made available on Maven Central within ten minutes of the release announcement.

Changes

Subscribe to the releases atom feed.

No formal releases have been made.

Sources

This project uses Git to manage source code.

Repository: https://github.com/io7m/jbssio

$ git clone https://github.com/io7m/jbssio

License

Copyright ⓒ 2018 Mark Raynsford <code@io7m.com> http://io7m.com

Permission to use, copy, modify, and/or distribute this software for
any purpose with or without fee is hereby granted, provided that the
above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR
BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES
OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
SOFTWARE.

Bug Tracker

The project uses GitHub Issues to track issues.