Class ChangeNotificationQueue

java.lang.Object
io.micronaut.data.jdbc.notification.ChangeNotificationQueue

@Internal public class ChangeNotificationQueue extends Object
Queues one listener's callbacks for sequential delivery on a dedicated daemon thread.

The worker starts with the first queued callback. Accepted callbacks run in queue order, outside this object's monitor. Queue admission, replacement and removal share that monitor. Callers supply data processing and reconciliation callbacks and filter out notifications that should no longer be delivered.

When the queue reaches its limit, waiting data and the new submission are replaced with one reconciliation callback. Further data submissions are ignored while that callback is queued. Once the worker starts it, new data submissions can be queued normally.

enqueueFinal(Runnable) replaces waiting work with one callback and closes admission; the worker exits after delivering it. stop() closes admission and discards all waiting work, including a queued final callback. Neither operation interrupts a running callback. Subsequent submissions are ignored. Runtime exceptions are logged and processing continues; an error or an interruption while waiting closes the queue and discards remaining work.

  • Constructor Details

    • ChangeNotificationQueue

      public ChangeNotificationQueue(String threadName, int capacity)
      Creates an empty queue without starting its worker.
      Parameters:
      threadName - descriptive name for this listener's daemon worker
      capacity - limit for waiting notifications, excluding the running callback
      Throws:
      IllegalArgumentException - if capacity is less than one
  • Method Details

    • enqueue

      public void enqueue(Runnable command, Runnable reconcile)
      Queues data processing, or replaces waiting data with a reconciliation callback when the limit is reached. If a reconciliation callback is already queued, both supplied callbacks are ignored and the queued callback is retained. New data can be queued once it starts running. Submissions are ignored once admission is closed.
      Parameters:
      command - data notification processing
      reconcile - reconciliation covering all discarded notifications
    • enqueueInvalidation

      public void enqueueInvalidation(Runnable reconcile)
      Replaces all waiting work, including a queued reconciliation callback, with the supplied callback. A running callback finishes first. Ignored once admission is closed.
      Parameters:
      reconcile - reconciliation covering discarded notifications
    • enqueueFinal

      public void enqueueFinal(Runnable command)
      Replaces waiting work with one final callback and closes admission. A running callback finishes first, then the worker delivers this callback and exits. Calling stop() before delivery discards it. Ignored if admission is already closed.
      Parameters:
      command - final listener notification
    • discardPending

      public void discardPending()
      Discards all waiting callbacks and clears pending reconciliation without interrupting the running callback. Leaves the current admission state unchanged.
    • stop

      public CompletionStage<Void> stop()
      Stops admission, discards waiting work, and wakes an idle worker. Running work is not interrupted. Repeated calls are safe. If the worker has never started, completion is immediate.
      Returns:
      a read-only stage completed normally after processing and worker cleanup finish
    • completion

      public CompletionStage<Void> completion()
      Observes completion without closing admission or discarding waiting work.

      Used by tests to await final delivery or worker failure without calling stop(), which could discard the callback being tested. Completion confirms that processing and cleanup have ended; it does not indicate that callbacks succeeded. For an unused queue, the stage remains incomplete until stop() is called.

      Returns:
      a read-only stage completed normally when processing ends, including after a worker failure
    • isStopped

      public boolean isStopped()
      Reports whether admission is closed. A callback may still be running or awaiting final delivery; use completion() to observe the end of processing.
      Returns:
      whether further submissions are ignored