Class NotificationSession

java.lang.Object
com.pyranid.NotificationSession
@NotThreadSafe public final class NotificationSession extends Object
A callback-scoped session for receiving transient database notifications.

Instances are supplied only to NotificationSessionOperation by Database.withNotificationSession(String, NotificationSessionOperation) or Database.withNotificationSession(java.util.Set, NotificationSessionOperation). A session is confined to the callback thread, expires when that callback exits, and never reconnects. It exposes no lifecycle snapshot: an apparently quiet session is not proof that its physical connection remains healthy.

Notification delivery is lossy and non-durable. Treat each returned batch as a hint to reconcile authoritative state rather than as an event count or work queue.

Since:
4.6.0
Author:
Mark Allen

  • Method Details

    • awaitNotifications

      public @NonNull List<@NonNull Notification> awaitNotifications(@NonNull Duration maxWait) throws InterruptedException
      Waits for a nonempty batch of notifications, until the best-effort elapsed-time budget expires.

      Pyranid divides positive waits into driver calls of at most 250 milliseconds so interruption can normally be observed between calls. The budget is not a hard completion deadline: a JDBC driver call already in progress may overrun it. A zero duration has exactly the polling semantics of drainNotifications().

      A nonempty batch wins over an interrupt that races after the driver returns; the batch is returned and the interrupt flag remains set for application code or the next receive to observe.

      Parameters:
      maxWait - maximum best-effort elapsed time to wait, which must not be negative
      Returns:
      an immutable notification batch, empty only when the budget expires without an observed notification
      Throws:
      NullPointerException - if maxWait is null
      IllegalArgumentException - if maxWait is negative
      IllegalStateException - if the session is expired, failed, used from another thread, used reentrantly, or used while any Pyranid transaction is active on this thread
      InterruptedException - if interruption is observed before protocol work or after an empty receive
      DatabaseException - if notification transport fails
      Since:
      4.6.0

    • drainNotifications

      public @NonNull List<@NonNull Notification> drainNotifications() throws InterruptedException
      Polls the existing listener connection once using the adapter's driver-specific non-waiting mode.

      The method performs no acquisition, registration, sleep, reconnect, or reconciliation. A nonempty batch wins over an interrupt that races after the driver returns.

      Returns:
      an immutable notification batch, possibly empty
      Throws:
      IllegalStateException - if the session is expired, failed, used from another thread, used reentrantly, or used while any Pyranid transaction is active on this thread
      InterruptedException - if interruption is observed before protocol work or after an empty receive
      DatabaseException - if notification transport fails
      Since:
      4.6.0