D-Bus Client Java

A high-performance, asynchronous D-Bus client library for Java applications. Built on Netty with a sophisticated dual-pipeline architecture that supports safe blocking operations in handlers.

Key Features

• Asynchronous & Thread-Safe: Non-blocking I/O with safe blocking operations in handlers
• Multiple Transports: Unix domain sockets and TCP/IP connections
• SASL Authentication: EXTERNAL and DBUS_COOKIE_SHA1 mechanisms
• Complete Type System: All D-Bus types with proper marshalling/unmarshalling
• Cross-Platform: Containerized integration tests for consistent behavior
• Production Ready: Comprehensive testing, monitoring, and error handling

Documentation

Complete API documentation is available on GitHub Pages with version support:

• Full Documentation - Comprehensive guides and API reference
• Latest API - Current development documentation
• Version History - Documentation for all releases

Quick Start

Installation

Available on Maven Central:

<!-- Maven -->
<dependency>
    <groupId>com.lucimber</groupId>
    <artifactId>lucimber-dbus-client</artifactId>
    <version>2.0.0</version>
</dependency>

// Gradle
implementation 'com.lucimber:lucimber-dbus-client:2.0.0'

Basic Usage

// Connect to D-Bus
Connection connection = NettyConnection.newSystemBusConnection();
connection.connect().toCompletableFuture().get();

// Send a method call
OutboundMethodCall call = OutboundMethodCall.Builder
    .create()
    .withSerial(connection.getNextSerial())
    .withPath(DBusObjectPath.valueOf("/org/freedesktop/DBus"))
    .withMember(DBusString.valueOf("ListNames"))
    .withDestination(DBusString.valueOf("org.freedesktop.DBus"))
    .withInterface(DBusString.valueOf("org.freedesktop.DBus"))
    .withReplyExpected(true)
    .build();

CompletableFuture<InboundMessage> response = connection.sendRequest(call);

// Close connection
connection.close();

Safe Blocking Operations

✅ Handlers run on dedicated thread pools - blocking operations are completely safe!

public class MyHandler extends AbstractInboundHandler {
    @Override
    public void handleInboundMessage(Context ctx, InboundMessage msg) {
        // ✅ SAFE - Database calls, REST APIs, file I/O all OK here!
        String result = databaseCall(msg);  // Blocking - totally fine!
        ctx.propagateInboundMessage(processedMessage(msg, result));
    }
}

Testing

Linux

# Build and test directly
./gradlew build

# Run integration tests (containerized)
./gradlew integrationTest

macOS / Windows

# Start D-Bus in Docker
docker-compose -f docker/docker-compose.yml up -d

# Run tests against Docker D-Bus
./gradlew test

# Or run tests inside container
docker-compose -f docker/docker-compose.yml run --rm test-runner

See Platform Setup Guide for detailed cross-platform instructions.

Documentation

• Developer Guide - Comprehensive usage guide
• Platform Setup - Cross-platform development setup
• Client-Server Patterns - Using ServiceProxy and StandardInterfaceHandler
• Standard Interfaces - Using D-Bus standard interfaces
• D-Bus Compatibility - Specification version support
• Contributing Guidelines - How to contribute
• Security Policy - Vulnerability reporting

Architecture

This library implements a dual-pipeline architecture with strict thread isolation:

• Transport Layer: Netty-based async I/O for D-Bus protocol handling
• Application Layer: Dedicated thread pools for user code
• RealityCheckpoint: The bridge ensuring safe threading and message routing

This design enables handlers to safely perform blocking operations without affecting the underlying transport performance.

D-Bus Compatibility

• Protocol Version: 1 (fully compatible)
• Specification Support: 0.41+ with selective newer features
• Tested Against: Standard D-Bus daemon and systemd's sd-bus

See D-Bus Compatibility for detailed version support.

Status

Current: v2.0.0 - Production-ready release with stable API

• ✅ Stable Core: D-Bus client operations, SASL authentication, message handling
• ✅ Production Architecture: Thread-safe with comprehensive error handling
• ✅ Comprehensive Testing: Unit, integration, and performance tests
• ✅ CI/CD Ready: Automated testing, coverage, and security scanning

Contributing

We welcome contributions! Please see our Contributing Guidelines and Code of Conduct.

For security issues, see our Security Policy.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Copyright 2021-2025 Lucimber UG