Annotation Interface OracleChangeNotification


@Documented @Retention(RUNTIME) @Target(METHOD) public @interface OracleChangeNotification
Configures Continuous Query Notification for a method annotated with ChangeListener.

For an Oracle datasource, every change-listener method must use this annotation, including listeners that rely on its defaults. The annotation enables compile-time generation of a ROWID reload query. For listener methods inherited from separately compiled base classes without generated query metadata, the query is built from the entity mapping at startup. Registrations always request row identifiers so inserts and updates can be reloaded. Oracle Database may report a full-table invalidation when row-level details are not available, or report a table identified as a dependent table for Query Result Change Notification. Either condition is delivered as ChangeOperation.INVALIDATE.

Notification tables are matched against the entity's mapped table name and, when explicitly configured, its schema. Without an explicit schema, a notification for a same-named table in another schema can be processed as an entity row change instead of an invalidation. Micronaut Data does not resolve the entity table's schema from the database. Set MappedEntity.schema() to distinguish same-named tables across schemas.

Entities with Where clauses are rejected at compilation time because those clauses filter entity reloads without filtering the notification registration query. For Query Result Change Notification, use where() to filter the registered result.

Query fragments, registration property names and values, and mapped table and schema names must be literal values. Configuration placeholders are rejected at compilation time.

Registrations do not expire by default. A positive NTF_TIMEOUT property makes Oracle Database expire the registration after the specified number of seconds; Micronaut Data does not renew it. When Oracle Database reports a deregistration, that listener receives ChangeOperation.TERMINATED and notifications stop. Exhausting recovery retries or failing to schedule another recovery attempt also reports termination. If the JDBC driver reports a notification-connection failure or Oracle Database reports a shutdown, Micronaut Data attempts to create a replacement registration and dispatches an invalidation event after recovery succeeds. Registrations are also unregistered during application shutdown.

Oracle change notifications require Oracle JDBC 23.26.3.0.0 or later. The driver version is checked during application startup before notification registration. Client-initiated notification connections are enabled by default and require Oracle Database 19c or later. Set the DCN_CLIENT_INIT_CONNECTION registration property to false to use server-initiated notification connections instead.

Since:
5.3.0
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static @interface 
    An Oracle JDBC Continuous Query Notification registration property.
  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    Oracle JDBC Continuous Query Notification registration properties for this listener.
    The select list to register for Query Result Change Notification.
    The predicate to register for Query Result Change Notification.
  • Element Details

    • select

      String select
      The select list to register for Query Result Change Notification. The value must be * or a comma-separated list of mapped column identifiers. Quoted identifiers must match the Oracle-rendered column name exactly. The selection controls the result registered with Oracle Database; it does not define a projection for the entity supplied to the listener. A non-default selection is valid only when OracleConnection.DCN_QUERY_CHANGE_NOTIFICATION is enabled in properties().
      Returns:
      The mapped column list, or * to select all columns.
      Default:
      "*"
    • where

      String where
      The predicate to register for Query Result Change Notification. A non-empty predicate is valid only when OracleConnection.DCN_QUERY_CHANGE_NOTIFICATION is enabled in properties().
      Returns:
      The predicate, or an empty string to omit the WHERE clause.
      Default:
      ""
    • properties

      Oracle JDBC Continuous Query Notification registration properties for this listener.

      The DCN_CLIENT_INIT_CONNECTION property defaults to true unless explicitly configured here. The NTF_TIMEOUT property defaults to 0, which leaves the registration without a configured expiry. Connection-level oracle.jdbc.dcnOptions may override these values; conflicting overrides of framework-controlled settings fail registration. Reattaching to an existing registration with DCN_CLIENT_INIT_REGID is not supported.

      Returns:
      The configured registration properties.
      Default:
      {}