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.OutputStreamjava.io.InputStreamjava.nio.channels.SeekableByteChanneljava.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);
}
}
}
Releases & Development Snapshots
Releases
You can subscribe to the atom feed to be notified of project releases.
The most recently released version of the package is 3.0.0.
3.0.0 Release (2025-05-04Z)
- Update com.io7m.junit.version:5.10.2 → 5.10.3.
- The API now raises structured error exceptions. (Backwards incompatible)
- Update org.slf4j:slf4j-api:2.0.13 → 2.0.14.
- Update org.slf4j:slf4j-api:2.0.14 → 2.0.15.
- Update org.slf4j:slf4j-api:2.0.15 → 2.0.16.
- Update org.junit:junit-bom:5.10.3 → 5.11.0.
- Update ch.qos.logback:logback-classic:1.5.6 → 1.5.7.
- Update ch.qos.logback:logback-classic:1.5.7 → 1.5.8.
- Update commons-io:commons-io:2.16.1 → 2.17.0.
- Update org.junit:junit-bom:5.11.0 → 5.11.1.
- Update org.junit:junit-bom:5.11.1 → 5.11.2.
- Update ch.qos.logback:logback-classic:1.5.8 → 1.5.9.
- Update ch.qos.logback:logback-classic:1.5.9 → 1.5.10.
- Update ch.qos.logback:logback-classic:1.5.10 → 1.5.11.
- Update org.junit:junit-bom:5.11.2 → 5.11.3.
- Update ch.qos.logback:logback-classic:1.5.11 → 1.5.12.
- Update commons-io:commons-io:2.17.0 → 2.18.0.
- Update org.junit:junit-bom:5.11.3 → 5.11.4.
- Update ch.qos.logback:logback-classic:1.5.12 → 1.5.13.
- Update ch.qos.logback:logback-classic:1.5.13 → 1.5.14.
- Update ch.qos.logback:logback-classic:1.5.14 → 1.5.15.
- Update ch.qos.logback:logback-classic:1.5.15 → 1.5.16.
- Update org.slf4j:slf4j-api:2.0.16 → 2.0.17.
- Update ch.qos.logback:logback-classic:1.5.16 → 1.5.18.
- Update org.junit:junit-bom:5.11.4 → 5.12.1.
- Update org.junit:junit-bom:5.12.1 → 5.12.2.
- Update commons-io:commons-io:2.18.0 → 2.19.0.
- Publish a com.io7m.jbssio.bom module.
The compiled artifacts for the release (and all previous releases) are available on Maven Central.
Maven Modules
<dependency> <group>com.io7m.jbssio</group> <artifactId>com.io7m.jbssio.api</artifactId> <version>3.0.0</version> </dependency><dependency> <group>com.io7m.jbssio</group> <artifactId>com.io7m.jbssio.bom</artifactId> <version>3.0.0</version> </dependency><dependency> <group>com.io7m.jbssio</group> <artifactId>com.io7m.jbssio.ext.bounded</artifactId> <version>3.0.0</version> </dependency><dependency> <group>com.io7m.jbssio</group> <artifactId>com.io7m.jbssio.tests</artifactId> <version>3.0.0</version> </dependency><dependency> <group>com.io7m.jbssio</group> <artifactId>com.io7m.jbssio.vanilla</artifactId> <version>3.0.0</version> </dependency>
Previous Releases
The changelogs for the most recent previous releases are as follows:
2.1.0 Release (2024-05-10Z)
- Update org.slf4j:slf4j-api:2.0.10 → 2.0.13.
- Update ch.qos.logback:logback-classic:1.4.14 → 1.5.6.
- Update commons-io:commons-io:2.15.1 → 2.16.1.
- Update com.io7m.junit.version:5.10.1 → 5.10.2.
- Update com.io7m.ieee754b16:com.io7m.ieee754b16.core:3.0.0 → 3.0.1.
2.0.0 Release (2023-04-02Z)
- Updated dependencies.
- Added bounded extensions. (Tickets: 5)
- Added fallible interface for creating exceptions. (Tickets: 4)
1.1.1 Release (2022-04-09Z)
- Update ieee754b16
- Update OSGi bundle annotations
- Update Logback
- Update commons-io
1.1.0 Release (2020-12-24Z)
- Add reader/writer implementations that throw UnsupportedOperationException
Development Snapshots
At the time of writing, the current unstable development version of the package is 3.1.0-SNAPSHOT.
Development snapshots may be available in the Central Portal Snapshots repository. Snapshots are published to this repository every time the project is built by the project's continuous integration system, but snapshots do expire after around ninety days and so may or may not be available depending on when a build of the package was last triggered.
Manual
This project does not have any user manuals or other documentation beyond what might be present on the page above.
Sources
This project uses Git to manage source code.
Repository: https://www.github.com/io7m-com/jbssio
$ git clone --recursive https://www.github.com/io7m-com/jbssio
Issues
This project uses GitHub Issues to track issues.
License
Copyright © 2023 Mark Raynsford <code@io7m.com> https://www.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.