Package com.lucimber.dbus.connection

package com.lucimber.dbus.connection
Connection management, lifecycle, and handler pipeline for D-Bus communication.

This package provides the core abstractions for establishing and managing D-Bus connections. It implements a pipeline-based architecture that allows for extensible message processing through custom handlers.

Getting Started

For first-time users: Start with Connection interface documentation, then see NettyConnection for the concrete implementation. The ConnectionConfig class shows all available configuration options.

Core Concepts

Connection

The Connection interface is the main entry point for D-Bus communication. It provides methods for:

  • Establishing connections to D-Bus daemons
  • Sending method calls and receiving responses
  • Managing connection lifecycle and health
  • Accessing the handler pipeline

Pipeline Architecture

The handler pipeline processes messages in a configurable chain: 


 // Add custom handlers to the pipeline
 Pipeline pipeline = connection.getPipeline();
 pipeline.addLast("logger", new LoggingHandler());
 pipeline.addLast("auth", new AuthenticationHandler());
 pipeline.addLast("app", new ApplicationHandler());

Handler Types

InboundHandler
Processes messages received from the D-Bus daemon
OutboundHandler
Processes messages being sent to the D-Bus daemon
Duplex Handlers (extend AbstractDuplexHandler)
Handle both inbound and outbound messages

Configuration

Connection behavior can be customized through ConnectionConfig: 


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

Connection Lifecycle

Connections follow a well-defined lifecycle:

  1. Creation: Connection instance is created with configuration
  2. Connection: Connection.connect() establishes the D-Bus connection
  3. Authentication: SASL authentication is performed automatically
  4. Ready: Connection is ready for message exchange
  5. Health Monitoring: Optional health checks ensure connection validity
  6. Reconnection: Automatic reconnection on connection loss (if enabled)
  7. Shutdown: AutoCloseable.close() cleanly closes the connection

Event Handling

Connection events can be monitored through ConnectionEventListener: 


 connection.addConnectionEventListener((conn, event) -> {
     switch (event.getType()) {
         case CONNECTED:
             System.out.println("Connected to D-Bus");
             break;
         case DISCONNECTED:
             System.out.println("Disconnected from D-Bus");
             break;
         case RECONNECTION_ATTEMPT:
             System.out.println("Attempting reconnection...");
             break;
     }
 });

Handler Examples

Simple Inbound Handler


 public class LoggingHandler extends AbstractInboundHandler {
     @Override
     public void handleInboundMessage(Context ctx, InboundMessage msg) {
         System.out.println("Received: " + msg.getType());
         ctx.propagateInboundMessage(msg); // Always propagate
     }
 }

Signal Filter Handler


 public class SignalFilterHandler extends AbstractInboundHandler {
     private final Set<String> interestedInterfaces;

     @Override
     public void handleInboundMessage(Context ctx, InboundMessage msg) {
         if (msg instanceof InboundSignal) {
             InboundSignal signal = (InboundSignal) msg;
             String interfaceName = signal.getInterfaceName()
                 .map(DBusString::toString)
                 .orElse("");

             if (interestedInterfaces.contains(interfaceName)) {
                 ctx.propagateInboundMessage(msg);
             }
             // Filtered signals are not propagated
         } else {
             ctx.propagateInboundMessage(msg);
         }
     }
 }

SASL Authentication

The com.lucimber.dbus.connection.sasl sub-package provides SASL authentication mechanisms for secure D-Bus communication.

Since:
1.0
See Also: