Interface ConnectionOperations<C>

Type Parameters:
C - The connection type.
All Known Subinterfaces:
DataSourceConnectionOperations, MongoConnectionOperations
All Known Implementing Classes:
AbstractConnectionOperations, DefaultDataSourceConnectionOperations, HibernateConnectionConnectionOperations, HibernateConnectionOperations, SpringHibernateConnectionOperations, SpringJdbcConnectionOperations, SynchronousConnectionOperationsFromReactiveConnectionOperations
public interface ConnectionOperations<C>
The synchronous connection operations interface.
Since:
4.0.0
Author:
Denis Stepanov

  • Method Details

    • getConnectionStatus

      default @NonNull ConnectionStatus<C> getConnectionStatus()
      Obtains the current required connection.
      Returns:
      The connection or exception if the connection doesn't exist

    • findConnectionStatus

      Optional<ConnectionStatus<C>> findConnectionStatus()
      Obtains the current connection.
      Returns:
      The optional connection

    • execute

      <R> R execute(@NonNull ConnectionDefinition definition, @NonNull Function<ConnectionStatus<C>, R> callback)
      Execute a connection within the context of the function.
      Type Parameters:
      R - The result
      Parameters:
      definition - The connection definition
      callback - The call back
      Returns:
      The result

    • executeWithConnection

      default <R> R executeWithConnection(@NonNull C connection, @NonNull ConnectionDefinition definition, @NonNull Function<ConnectionStatus<C>, R> callback)
      Executes the callback with a connection supplied by the caller as the current connection, with transactions started inside the callback controlled by Micronaut Data. Equivalent to executeWithConnection(Object, ConnectionDefinition, boolean, Function) with ownerControlsTransaction set to false.
      Type Parameters:
      R - The result
      Parameters:
      connection - The connection
      definition - The connection definition describing it
      callback - The call back
      Returns:
      The result
      Since:
      5.3.0

    • executeWithConnection

      default <R> R executeWithConnection(@NonNull C connection, @NonNull ConnectionDefinition definition, boolean ownerControlsTransaction, @NonNull Function<ConnectionStatus<C>, R> callback)
      Executes the callback with a connection supplied by the caller as the current connection.

      Repositories, connection-scoped operations and transactions started inside the callback use the supplied connection, as they would use a connection opened by these operations, even when the caller is inside a transaction on another connection: a transaction started inside the callback never joins that transaction. Use it when another library owns a connection that Micronaut Data should take part in, such as the database connection of an Oracle AQ JMS session or of an XA resource.

      When ownerControlsTransaction is true, the connection must not be in auto-commit mode: with auto-commit on there is no owner transaction to join, so every statement commits as it runs and the owner cannot roll it back. The owner of the connection controls its transaction, as with an AQ session, an OKafka producer or an XA resource, and transactions started inside the callback join it. They don't change the auto-commit mode or the isolation level, and they don't commit or roll back the connection. A NESTED transaction uses a savepoint, and REQUIRES_NEW opens a separate connection. When joined work rolls back, the exception propagates, or this method throws a ConnectionException if the exception was handled inside the callback, so that the owner rolls back its transaction; transactions joined after such a rollback fail with an UnexpectedRollbackException. Micronaut Data does not see the owner's commit, so transaction synchronizations, such as @TransactionalEventListener methods and afterCommit callbacks, cannot be registered on a joined transaction and fail with a TransactionUsageException. Hibernate transactions cannot join the owner's transaction either, because Hibernate writes need a Hibernate transaction of their own, so they also fail with a TransactionUsageException: use JDBC repositories on such a connection.

      When ownerControlsTransaction is false, transactions started inside the callback begin, commit and roll back on the supplied connection, and restore its auto-commit mode afterwards.

      Connection operations that cannot adopt a connection, such as the Spring ones, throw UnsupportedOperationException. The JDBC and Hibernate connection operations support it; for Hibernate, the work runs on a session opened on the supplied connection.

      The connection is not set up (for example, read-only mode is left as it is), no request boundaries are marked on it and it is never closed: the caller remains responsible for it, including Oracle request boundaries and DRCP release.

      Type Parameters:
      R - The result
      Parameters:
      connection - The connection
      definition - The connection definition describing it
      ownerControlsTransaction - Whether the owner of the connection controls its transaction, so that transactions inside the callback join it
      callback - The call back
      Returns:
      The result
      Since:
      5.3.0

    • executeRead

      default <R> R executeRead(@NonNull Function<ConnectionStatus<C>, R> callback)
      Execute a read-only connection within the context of the function. NOTE: The connection manager might not support the read only connection!
      Type Parameters:
      R - The result
      Parameters:
      callback - The call back
      Returns:
      The result

    • executeWrite

      default <R> R executeWrite(@NonNull Function<ConnectionStatus<C>, R> callback)
      Execute a write supported connection within the context of the function.
      Type Parameters:
      R - The result
      Parameters:
      callback - The call back
      Returns:
      The result

    • managesConnection

      boolean managesConnection(@NonNull ConnectionStatus<C> connectionStatus)
      Determine whether the given connection status refers to a connection managed by this ConnectionOperations instance.
      Parameters:
      connectionStatus - The connection status to verify
      Returns:
      true if the connection is managed (i.e. created/supplied) by this operations instance
      Since:
      5.0