D-Bus Client Java - Developer Guide

Welcome to the D-Bus Client Java library! This guide provides a structured learning path for developers using the library for the first time, organized by practical importance and usefulness.

🚀 Quick Start (5 minutes)

Get up and running immediately with basic D-Bus operations.

Essential Concepts

What it does: High-performance, asynchronous D-Bus client for Java applications
Key benefit: Thread-safe blocking operations with sophisticated dual-pipeline architecture
Use cases: System integration, IPC, desktop applications, IoT device communication

First Steps

import com.lucimber.dbus.connection.Connection;
import com.lucimber.dbus.netty.NettyConnection;

// Connect to system bus
Connection connection = NettyConnection.newSystemBusConnection();
connection.connect().toCompletableFuture().get();

// Your D-Bus operations here...

connection.close();

📖 Detailed Documentation: Quick Start Guide

🏗️ Basic Message Operations (15 minutes)

Learn to send method calls, handle responses, and work with D-Bus messages.

Core Operations

Method Calls: Send synchronous and asynchronous method calls
Signal Handling: Subscribe to and process D-Bus signals
Message Types: Work with method calls, returns, signals, and errors
Request-Response: Handle method call timeouts and correlation

Example

import com.lucimber.dbus.message.OutboundMethodCall;
import com.lucimber.dbus.type.*;

OutboundMethodCall call = OutboundMethodCall.Builder
    .create()
    .withSerial(DBusUInt32.valueOf(1))
    .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);

📖 Detailed Documentation: Message Operations

🔧 Configuration & Connection Management (10 minutes)

Configure connections for different environments and use cases.

Connection Types

System Bus: For system-level services (requires permissions)
Session Bus: For user-level applications
Custom Address: TCP, Unix sockets, custom transports

Configuration Options

import com.lucimber.dbus.connection.ConnectionConfig;

ConnectionConfig config = ConnectionConfig.builder()
    .withAutoReconnectEnabled(true)
    .withHealthCheckEnabled(true)
    .withConnectTimeout(Duration.ofSeconds(10))
    .withMethodCallTimeout(Duration.ofSeconds(30))
    .build();

Connection connection = NettyConnection.newSystemBusConnection(config);

📖 Detailed Documentation:

🎯 Handler Development (20 minutes)

Create custom handlers for processing D-Bus messages in your application logic.

Handler Types

Inbound Handlers: Process incoming messages (signals, method calls)
Outbound Handlers: Modify outgoing messages
Duplex Handlers: Handle both directions

Safe Blocking Operations

✅ Important: Your handlers run on dedicated thread pools - blocking operations are completely safe!

import com.lucimber.dbus.connection.AbstractInboundHandler;
import com.lucimber.dbus.connection.Context;

public class MyBusinessLogicHandler 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 operation - totally fine!
        
        ctx.propagateInboundMessage(enrichMessage(msg, result));
    }
}

// Add to pipeline
connection.getPipeline().addLast("business-logic", new MyBusinessLogicHandler());

📖 Detailed Documentation:

Essential: Blocking Operations Guide
Handler Architecture

🌱 Spring Boot Integration (15 minutes)

Integrate with Spring Boot applications using dependency injection and configuration.

Auto-Configuration

@Configuration
public class DBusConfiguration {
    
    @Bean
    public Connection dbusConnection() {
        return NettyConnection.newSystemBusConnection();
    }
}

@Service
public class MyDBusService {
    private final Connection dbusConnection;
    
    public MyDBusService(Connection dbusConnection) {
        this.dbusConnection = dbusConnection;
        setupHandlers();
    }
}

Spring Boot Features

Health checks with Actuator
Metrics with Micrometer
Configuration properties
Lifecycle management

📖 Detailed Documentation:

🎯 High-Level Abstractions (20 minutes)

Simplify D-Bus programming with powerful abstractions.

Service Proxy Pattern (Client-side)

// Define interface with annotations
@DBusInterface("org.freedesktop.DBus")
public interface DBusService {
    @DBusMethod("GetId")
    String getId();
    
    @DBusMethod("ListNames")
    CompletableFuture<String[]> listNames();
}

// Create proxy - no manual message building!
DBusService service = ServiceProxy.create(
    connection, 
    "/org/freedesktop/DBus", 
    DBusService.class
);

// Use like a regular Java interface
String id = service.getId();

Note: ServiceProxy is for simple client request/response scenarios only. For implementing D-Bus services (server-side), use StandardInterfaceHandler instead.

Promise-Style Async Operations

DBusPromise.from(connection.sendRequest(call))
    .timeout(Duration.ofSeconds(5))
    .mapReturn()
    .firstAs(DBusString.class)
    .map(DBusString::getDelegate)
    .thenAccept(result -> System.out.println("Result: " + result))
    .exceptionally(error -> {
        System.err.println("Failed: " + error.getMessage());
        return null;
    });

📖 Detailed Documentation: High-Level Abstractions Example

🔧 Advanced Features (30 minutes)

Explore sophisticated features for production applications.

Error Handling & Resilience

Exception propagation and handling
Circuit breakers and retry patterns
Health monitoring and reconnection
Graceful degradation

Performance & Monitoring

Connection pooling strategies
Metrics collection
Performance tuning
Memory management

Reactive Programming

Project Reactor integration
RxJava support
Async/await patterns
Backpressure handling

📖 Detailed Documentation:

🏛️ Architecture Deep Dive (45 minutes)

Understand the sophisticated dual-pipeline architecture for advanced use cases.

Core Architecture

Dual-Pipeline System: Public API + Netty transport layers
RealityCheckpoint: The bridge between pipeline layers (named after the Logistics drum & bass track!)
Thread Isolation: ApplicationTaskExecutor vs Netty EventLoop
Event Propagation: How messages flow through the system

When You Need This

Custom transport implementations
Advanced handler development
Performance optimization
Understanding thread safety guarantees

📖 Detailed Documentation:

Comprehensive: Pipeline & Event Architecture
Architecture Overview
Transport Strategies

🧪 Testing & Debugging (20 minutes)

Test your D-Bus integration effectively.

Testing Strategies

Unit testing with mocks
Integration testing with containerized D-Bus daemon (single entry point)
Performance testing
Memory testing

Single Entry Point

The library provides a single, reliable entry point for integration testing:

./gradlew integrationTest

This command automatically:

Sets up a Linux container with D-Bus daemon
Copies your source code into the container
Compiles and runs tests with proper SASL authentication
Copies test results back to your local project structure
Works consistently on all platforms (Windows, macOS, Linux)

Debugging Tools

Connection health checks
Pipeline introspection
Thread analysis
Performance monitoring

📖 Detailed Documentation:

📚 Reference Documentation

Quick Reference

D-Bus Specification Overview - Understanding the D-Bus protocol
Examples Collection - Working code samples
Timeout Configuration - Managing timeouts

Advanced Topics

Message Flow Architecture - Traditional view of message processing
Transport Strategies - Custom transport implementations

🎯 Recommended Learning Path

For New Developers (1-2 hours)

Quick Start (5 min) → Message Operations (15 min) → Configuration (10 min)
Handler Development (20 min) + Blocking Operations (essential reading!)
Spring Boot Integration (15 min) if using Spring

For Production Applications (3-4 hours)

Complete the New Developer path
Advanced Features (30 min) → Architecture Deep Dive (45 min)
Testing & Debugging (20 min)
Error Handling and Performance Monitoring

For Library Contributors (5+ hours)

Complete all previous paths
Study all Architecture Documentation in detail
Review Transport Strategies and Pipeline Architecture
Understand the RealityCheckpoint bridge pattern

💡 Key Tips for Success

Start Simple: Begin with basic message operations before diving into advanced features
Embrace Blocking: Unlike other async libraries, blocking operations are safe and encouraged in handlers
Use Spring Boot: The integration patterns make enterprise development much easier
Read Blocking Operations Guide: This is the most important document for handler development
Understand the Bridge: The RealityCheckpoint class is the key to understanding thread safety

🆘 Getting Help

Common Issues: Check the Error Handling Guide
Performance: See Integration Patterns for optimization
Architecture Questions: Start with Pipeline Architecture
Examples: Browse working examples for your use case

Happy coding with D-Bus! 🚀

FilesExpand file tree

developer-guide.md

Latest commit

History

developer-guide.md

File metadata and controls

D-Bus Client Java - Developer Guide

🚀 Quick Start (5 minutes)

Essential Concepts

First Steps

🏗️ Basic Message Operations (15 minutes)

Core Operations

Example

🔧 Configuration & Connection Management (10 minutes)

Connection Types

Configuration Options

🎯 Handler Development (20 minutes)

Handler Types

Safe Blocking Operations

🌱 Spring Boot Integration (15 minutes)

Auto-Configuration

Spring Boot Features

🎯 High-Level Abstractions (20 minutes)

Service Proxy Pattern (Client-side)

Promise-Style Async Operations

🔧 Advanced Features (30 minutes)

Error Handling & Resilience

Performance & Monitoring

Reactive Programming

🏛️ Architecture Deep Dive (45 minutes)

Core Architecture

When You Need This

🧪 Testing & Debugging (20 minutes)

Testing Strategies

Single Entry Point

Debugging Tools

📚 Reference Documentation

Quick Reference

Advanced Topics

🎯 Recommended Learning Path

For New Developers (1-2 hours)

For Production Applications (3-4 hours)

For Library Contributors (5+ hours)

💡 Key Tips for Success

🆘 Getting Help