Package com.lucimber.dbus.netty

Class RealityCheckpoint

java.lang.Object
io.netty.channel.ChannelHandlerAdapter
io.netty.channel.ChannelInboundHandlerAdapter
io.netty.channel.ChannelDuplexHandler
com.lucimber.dbus.netty.RealityCheckpoint
All Implemented Interfaces:
io.netty.channel.ChannelHandler, io.netty.channel.ChannelInboundHandler, io.netty.channel.ChannelOutboundHandler
public class RealityCheckpoint extends io.netty.channel.ChannelDuplexHandler
The critical bridge between the Netty pipeline and public API pipeline systems.

This handler serves as the reality checkpoint where messages transition between the low-level transport layer (Netty) and the high-level application layer (public API). It manages request-response correlation, timeouts, and ensures proper thread isolation by routing messages to the appropriate execution contexts. All inbound messages and connection events are switched from the Netty EventLoop to the ApplicationTaskExecutor here, enabling safe blocking operations in user handlers.

Named after the brilliant drum & bass track "Reality Checkpoint" by Logistics, because like that track, this class represents a moment of transition and clarity in the complex flow of D-Bus message processing.

  • Nested Class Summary

    Nested classes/interfaces inherited from interface io.netty.channel.ChannelHandler

    io.netty.channel.ChannelHandler.Sharable

  • Constructor Summary

    Constructors
    Constructor
    Description
    RealityCheckpoint(ExecutorService applicationTaskExecutor, Connection connection)
    Creates a new instance.
    RealityCheckpoint(ExecutorService applicationTaskExecutor, Connection connection, long methodCallTimeoutMs)
    Creates a new instance with custom timeout.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    channelInactive(io.netty.channel.ChannelHandlerContext ctx)
     
    void
    channelRead(io.netty.channel.ChannelHandlerContext ctx, Object msg)
     
    void
    exceptionCaught(io.netty.channel.ChannelHandlerContext ctx, Throwable cause)
     
    void
    handlerAdded(io.netty.channel.ChannelHandlerContext ctx)
     
    void
    userEventTriggered(io.netty.channel.ChannelHandlerContext ctx, Object evt)
     
    io.netty.util.concurrent.Future<Void>
    writeAndRouteResponse(OutboundMessage msg)
    Sends the given OutboundMessage without returning a future for the reply.
    io.netty.util.concurrent.Future<io.netty.util.concurrent.Future<InboundMessage>>
    writeMessage(OutboundMessage msg)
    Sends the given OutboundMessage and returns a nested Future that tracks both the write completion and the eventual reply.

    Methods inherited from class io.netty.channel.ChannelDuplexHandler

    bind, close, connect, deregister, disconnect, flush, read, write

    Methods inherited from class io.netty.channel.ChannelInboundHandlerAdapter

    channelActive, channelReadComplete, channelRegistered, channelUnregistered, channelWritabilityChanged

    Methods inherited from class io.netty.channel.ChannelHandlerAdapter

    ensureNotSharable, handlerRemoved, isSharable

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface io.netty.channel.ChannelHandler

    handlerRemoved

  • Constructor Details

    • RealityCheckpoint

      public RealityCheckpoint(ExecutorService applicationTaskExecutor, Connection connection)
      Creates a new instance.
      Parameters:
      applicationTaskExecutor - The executor service to run application-level callbacks (like signal handlers) on, to avoid blocking the Netty EventLoop. If null, a default will be attempted or tasks run on EventLoop (not recommended for blocking user code).
      connection - An active D-Bus connection.

    • RealityCheckpoint

      public RealityCheckpoint(ExecutorService applicationTaskExecutor, Connection connection, long methodCallTimeoutMs)
      Creates a new instance with custom timeout.
      Parameters:
      applicationTaskExecutor - The executor service to run application-level callbacks (like signal handlers) on, to avoid blocking the Netty EventLoop. If null, a default will be attempted or tasks run on EventLoop (not recommended for blocking user code).
      connection - An active D-Bus connection.
      methodCallTimeoutMs - Timeout in milliseconds for method calls before they are considered stale and removed from pending calls map.

  • Method Details

    • handlerAdded

      public void handlerAdded(io.netty.channel.ChannelHandlerContext ctx)
      Specified by:
      handlerAdded in interface io.netty.channel.ChannelHandler
      Overrides:
      handlerAdded in class io.netty.channel.ChannelHandlerAdapter

    • userEventTriggered

      public void userEventTriggered(io.netty.channel.ChannelHandlerContext ctx, Object evt)
      Specified by:
      userEventTriggered in interface io.netty.channel.ChannelInboundHandler
      Overrides:
      userEventTriggered in class io.netty.channel.ChannelInboundHandlerAdapter

    • writeMessage

      public io.netty.util.concurrent.Future<io.netty.util.concurrent.Future<InboundMessage>> writeMessage(OutboundMessage msg)
      Sends the given OutboundMessage and returns a nested Future that tracks both the write completion and the eventual reply.

      This method is intended for use by higher-level components within the library or application. It assumes that the OutboundMessage already has a valid and unique serial number assigned.

      The returned Future structure works as follows:

      • The outer Future completes when the outbound message has been successfully written to the transport.
      • The inner Future, provided as the outer result, will be completed when the corresponding InboundMessage reply is received.
      Parameters:
      msg - the outbound message to send (must have a preassigned unique serial number).
      Returns:
      a Future that completes with another Future<InboundMessage>: the outer future completes when the message is written; the inner future completes when the reply arrives.

    • writeAndRouteResponse

      public io.netty.util.concurrent.Future<Void> writeAndRouteResponse(OutboundMessage msg)
      Sends the given OutboundMessage without returning a future for the reply.

      Unlike writeMessage, this method does not provide a Future for the expected InboundMessage response. Instead, the reply will be delivered asynchronously through the connection’s Pipeline and must be handled by registered InboundHandlers.

      This method is suitable when the application relies on the pipeline for inbound message processing rather than awaiting a reply programmatically.

      Parameters:
      msg - the outbound message to send.
      Returns:
      a Future that completes when the message has been successfully written, or exceptionally if an error occurs during transmission.

    • channelRead

      public void channelRead(io.netty.channel.ChannelHandlerContext ctx, Object msg)
      Specified by:
      channelRead in interface io.netty.channel.ChannelInboundHandler
      Overrides:
      channelRead in class io.netty.channel.ChannelInboundHandlerAdapter

    • exceptionCaught

      public void exceptionCaught(io.netty.channel.ChannelHandlerContext ctx, Throwable cause)
      Specified by:
      exceptionCaught in interface io.netty.channel.ChannelHandler
      Specified by:
      exceptionCaught in interface io.netty.channel.ChannelInboundHandler
      Overrides:
      exceptionCaught in class io.netty.channel.ChannelInboundHandlerAdapter

    • channelInactive

      public void channelInactive(io.netty.channel.ChannelHandlerContext ctx) throws Exception
      Specified by:
      channelInactive in interface io.netty.channel.ChannelInboundHandler
      Overrides:
      channelInactive in class io.netty.channel.ChannelInboundHandlerAdapter
      Throws:
      Exception