Package com.lucimber.dbus.connection

Interface Connection

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
DummyConnection, NettyConnection
public interface Connection extends AutoCloseable
Represents a virtual channel for communication over D-Bus.

A D-Bus connection enables inter-process communication by allowing messages to be sent and received. There are two primary types of buses in D-Bus:

  • System Bus: A bus shared between system and user processes.
  • Session Bus: A user-specific bus available within a single login session.
Applications can also establish their own session buses for isolated communication within a session.

  • Method Details

    • connect

      CompletionStage<Void> connect()
      Initiates a connection to a D-Bus instance.
      Returns:
      a CompletionStage that completes when the connection is established, or exceptionally if the attempt fails.

    • isConnected

      boolean isConnected()
      Indicates whether the connection has been successfully established and is active.
      Returns:
      true if the connection is active, false otherwise.

    • getPipeline

      Pipeline getPipeline()
      Retrieves the associated Pipeline for this connection.
      Returns:
      the Pipeline instance used by this connection.

    • getNextSerial

      DBusUInt32 getNextSerial()
      Generates and returns the next unique serial number for outbound messages.

      Serial numbers are used to correlate requests and replies and are unique per connection.

      Returns:
      a unique DBusUInt32 serial number for an OutboundMessage.

    • sendRequest

      CompletionStage<InboundMessage> sendRequest(OutboundMessage msg)
      Sends the given OutboundMessage over this connection, bypassing the pipeline.

      This method is intended for simple request-response interactions where no additional pipeline-based processing is needed. The returned CompletionStage is completed directly with the corresponding InboundMessage response or exceptionally if an error occurs.

      Note: Use this method only for straightforward communication scenarios that do not require handler involvement or advanced message routing.

      Parameters:
      msg - the outbound message to send.
      Returns:
      a CompletionStage that completes with the corresponding inbound response message, or fails exceptionally on error.

    • sendAndRouteResponse

      void sendAndRouteResponse(OutboundMessage msg, CompletionStage<Void> future)
      Sends the given OutboundMessage over the connection and completes the provided future when the message has been written to the D-Bus transport.

      The outbound message is transmitted directly over the connection and does not pass through the outbound pipeline. However, the corresponding InboundMessage response will be delivered through the pipeline, allowing it to be processed by registered InboundHandlers.

      This method is intended for scenarios where custom or advanced processing of responses is needed, while keeping message transmission efficient.

      Parameters:
      msg - the outbound message to send.
      future - the CompletionStage to complete once the message is written or if an error occurs.

    • getConfig

      ConnectionConfig getConfig()
      Retrieves the configuration for this connection.
      Returns:
      the ConnectionConfig instance used by this connection.

    • getState

      ConnectionState getState()
      Gets the current connection state.
      Returns:
      the current ConnectionState

    • addConnectionEventListener

      void addConnectionEventListener(ConnectionEventListener listener)
      Adds a connection event listener to receive notifications about connection events.
      Parameters:
      listener - the listener to add

    • removeConnectionEventListener

      void removeConnectionEventListener(ConnectionEventListener listener)
      Removes a connection event listener.
      Parameters:
      listener - the listener to remove

    • triggerHealthCheck

      CompletionStage<Void> triggerHealthCheck()
      Manually triggers a health check if health monitoring is enabled.
      Returns:
      a CompletionStage that completes when the health check is triggered

    • getReconnectAttemptCount

      int getReconnectAttemptCount()
      Gets the current number of reconnection attempts.
      Returns:
      the current reconnection attempt count

    • cancelReconnection

      void cancelReconnection()
      Cancels any pending reconnection attempts.

    • resetReconnectionState

      void resetReconnectionState()
      Resets the reconnection state, clearing attempt count and timers.