Module storm.foundation
Package st.orm.spi

Interface QueryObserver

public interface QueryObserver
Observes query executions performed by an ORM template.

Query observers are designed to back metrics and tracing bindings, such as Micrometer Observations. They are configured per ORM template via the template builder; they are deliberately not discovered through the ServiceLoader mechanism.

Observer failures are contained by the framework and never affect query execution: an exception thrown by an observer is logged and discarded, and the query result or failure is delivered to the caller unchanged.

Since:
1.13
See Also:

  • Field Details

    • NOOP

      static final QueryObserver NOOP
      Observer that ignores all executions. Exposed as a constant so hot paths can skip context creation with an identity check.

  • Method Details

    • onExecute

      QueryObserver.Observation onExecute(QueryContext context)
      Called when a statement execution starts.

      The returned observation is closed exactly once: for updates and batches when execution completes; for result streams when the stream is closed.

      Parameters:
      context - describes the statement execution; never null.
      Returns:
      the observation tracking this execution; never null.

    • onTransaction

      default QueryObserver.TransactionObservation onTransaction(TransactionOptions options)
      Called when a physical transaction opens: an outermost transaction block, or a REQUIRES_NEW block. Joined blocks and savepoint scopes are not physical transactions and are not observed.

      The default implementation ignores transactions.

      Parameters:
      options - the options the transaction was opened with; never null.
      Returns:
      the observation tracking this transaction; never null.
      Since:
      1.13

    • noop

      static QueryObserver noop()