blackducksoftware/bdio

Purpose and build

Black Duck I/O (BDIO) is a Java 8+ multi-module library and CLI for producing, consuming, validating, transforming, and storing JSON-LD BOM and scan graphs. The root Gradle build assembles its modules; the normative format is documented under docs/spec/02.Model.txt and docs/spec/04.DocumentFormat.txt.

Core JSON-LD model and streaming API

The bdio2 module defines the primary public data model, document framing/context, and streaming read/write contracts. Applications construct model nodes, associate them with metadata/context, then serialize or consume document entries through reader/writer/emitter abstractions.

• bdio2/src/main/java/com/blackducksoftware/bdio2/BdioDocument.java

• bdio2/src/main/java/com/blackducksoftware/bdio2/BdioReader.java

• bdio2/src/main/java/com/blackducksoftware/bdio2/BdioWriter.java

• bdio2/src/main/java/com/blackducksoftware/bdio2/model/

Context, compatibility, and parsing boundary

BdioContext and bundled JSON-LD contexts define vocabulary/version interpretation. Emitters provide the ingestion boundary for native BDIO streams and legacy BDIO 1.x or scan-container inputs, isolating compatibility conversion from the current model.

• bdio2/src/main/java/com/blackducksoftware/bdio2/BdioContext.java

• bdio2/src/main/java/com/blackducksoftware/bdio2/EmitterFactory.java

• bdio2/src/main/java/com/blackducksoftware/bdio2/LegacyBdio1xEmitter.java

• bdio2/src/main/resources/com/blackducksoftware/bdio2/bdio-context-2.1.jsonld

Reactive document implementations

Two adapter modules expose the core document/JSON-LD processing flow under alternative reactive runtimes. Consumers choose Reactor or RxJava rather than the base streaming interfaces; these are library integrations, not standalone services.

• bdio-reactor/src/main/java/com/blackducksoftware/bdio2/reactor/ReactorBdioDocument.java

• bdio-reactor/src/main/java/com/blackducksoftware/bdio2/reactor/ReactorJsonLdProcessing.java

• bdio-rxjava/src/main/java/com/blackducksoftware/bdio2/rxjava/RxJavaBdioDocument.java

• bdio-rxjava/src/main/java/com/blackducksoftware/bdio2/rxjava/RxJavaJsonLdProcessing.java

TinkerPop graph persistence and normalization

The graph layer maps BDIO JSON-LD documents to Apache TinkerPop graphs, with reader/writer and normalization stages behind a common BlackDuckIo API. Default implementations target in-memory TinkerGraph; SQLG implementations support PostgreSQL-backed graph storage, query optimization, and schema migration.

• bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/BlackDuckIo.java

• bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/spi/DefaultBlackDuckIoReader.java

• bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/sqlg/SqlgBlackDuckIo.java

• bdio-tinkerpop/src/main/java/com/blackducksoftware/bdio2/tinkerpop/sqlg/flyway/SqlgFlywayExecutor.java

Protobuf scan interchange

bdio-protobuf is a separate binary scan-data interchange path. Version-specific readers, writers, validators, and converters operate on typed header/node/chunk APIs, generated from protobuf schemas. Its boundary is distinct from the JSON-LD BDIO 2 graph model.

• bdio-protobuf/src/main/java/com/blackducksoftware/bdio/proto/ProtobufBdioReader.java

• bdio-protobuf/src/main/java/com/blackducksoftware/bdio/proto/impl/ProtobufBdioConverter.java

• bdio-protobuf/src/main/java/com/blackducksoftware/bdio/proto/impl/ProtobufBdioV2Writer.java

• bdio-protobuf/src/main/proto/bdba_scan_nodes_v2.proto

CLI entry point and operational flow

bdio-tool provides the executable entry point, BdioMain, dispatching file and graph operations such as concatenation, filtering, dependency/tree views, JSON-LD conversion, linting, SPDX output, and visualization. It consumes/produces BDIO through the core and graph boundaries rather than hosting a web application.

• bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/BdioMain.java

• bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/AbstractFileTool.java

• bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/AbstractGraphTool.java

• bdio-tool/src/main/java/com/blackducksoftware/bdio2/tool/LintTool.java

Infrastructure and external dependencies

The material runtime is the JVM with Gradle builds. JSON-LD is the interchange representation; Reactor/RxJava are optional processing runtimes; Apache TinkerPop is the graph abstraction. SQLG, Flyway, JDBC, and PostgreSQL comprise the persistent graph path; bdio-tinkerpop-db/Dockerfile supplies the database image used by the documented build/test setup.