Package org.hibernate.jdbc

Interface Expectation

All Known Implementing Classes:
Expectation.None, Expectation.OutParameter, Expectation.RowCount
public interface Expectation
Defines an expected DML operation outcome. Used to verify that a JDBC operation completed successfully.

The two standard implementations are Expectation.RowCount for row count checking, and Expectation.OutParameter for checking the return code assigned to an output parameter of a CallableStatement. Custom implementations are permitted.

An Expectation is usually selected via an annotation, for example: 

 @Entity
 @SQLUpdate(sql = "update Record set uid = gen_random_uuid(), whatever = ? where id = ?",
            verify = Expectation.RowCount.class)
 class Record { ... }
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    Expectation.None
    No return code checking.
    static class 
    Expectation.OutParameter
    Essentially identical to Expectation.RowCount except that the row count is obtained via an output parameter of a stored procedure.
    static class 
    Expectation.RowCount
    Row count checking.

  • Method Summary

    Modifier and Type
    Method
    Description
    default boolean
    canBeBatched()
    Is it acceptable to combine this expectation with JDBC statement batching? If this method returns false, the use of batch updates is disabled.
    default int
    getNumberOfParametersUsed()
    The number of JDBC parameters this expectation uses.
    default int
    prepare(PreparedStatement statement)
    Perform any special statement preparation, for example, registration of OUT parameters.
    default void
    validate(boolean callable)
    Check that this implementation is compatible with the kind of PreparedStatement it will be called with.
    void
    verifyOutcome(int rowCount, PreparedStatement statement, int batchPosition, String sql)
    Perform verification of the outcome of the JDBC operation based on the type of expectation defined, after execution of the given PreparedStatement.

  • Method Details

    • canBeBatched

      default boolean canBeBatched()
      Is it acceptable to combine this expectation with JDBC statement batching? If this method returns false, the use of batch updates is disabled.
      Returns:
      True if batching can be combined with this expectation; false otherwise.
      See Also:

    • getNumberOfParametersUsed

      default int getNumberOfParametersUsed()
      The number of JDBC parameters this expectation uses. For example, Expectation.OutParameter requires a single OUT parameter for reading back the number of affected rows.

    • verifyOutcome

      void verifyOutcome(int rowCount, PreparedStatement statement, int batchPosition, String sql) throws SQLException, HibernateException
      Perform verification of the outcome of the JDBC operation based on the type of expectation defined, after execution of the given PreparedStatement. When a SQL statement is executed via PreparedStatement.executeUpdate(), verifyOutcome() is called exactly once. When Statement.executeBatch() is used to execute a batch update, this method is called once for each element of the batch.
      • The argument to rowCount is usually the number of table rows affected by execution of the SQL statement via executeUpdate(). However, in the case where executeBatch() is used to execute a batch update, it might be Statement.EXECUTE_FAILED or Statement.SUCCESS_NO_INFO.
      • The argument to batchPosition is negative unless executeBatch() is used to execute a batch update, in which case it is the position within the batch of the row count being verified.
      Parameters:
      rowCount - The RDBMS reported "number of rows affected"
      statement - The statement representing the operation
      batchPosition - The position in the batch (if batching), or -1 if not part of a batch
      sql - The SQL backing the prepared statement, for error reporting and logging purposes
      Throws:
      SQLException - Exception from the JDBC driver.
      HibernateException - Problem processing the outcome.
      See Also:

    • prepare

      default int prepare(PreparedStatement statement) throws SQLException, HibernateException
      Perform any special statement preparation, for example, registration of OUT parameters.
      Parameters:
      statement - The statement to be prepared
      Returns:
      The number of bind positions consumed (if any)
      Throws:
      SQLException - Exception from the JDBC driver
      HibernateException - Problem performing preparation.
      See Also:

    • validate

      default void validate(boolean callable) throws MappingException
      Check that this implementation is compatible with the kind of PreparedStatement it will be called with. Implementors should throw a MappingException if the configuration is not supported. This operation is called when Hibernate starts up, so that incompatibilities are detected and reported as early as possible.
      Parameters:
      callable - true if this Expectation will be called with a CallableStatement.
      Throws:
      MappingException
      Since:
      6.5