Package org.hibernate.jdbc
Interface Expectation
-
- All Known Implementing Classes:
Expectation.None
,Expectation.OutParameter
,Expectation.RowCount
,Expectations.BasicExpectation
,Expectations.BasicParamExpectation
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, andExpectation.OutParameter
for checking the return code assigned to an output parameter of aCallableStatement
. 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 { ... }
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
Expectation.None
No return code checking.static class
Expectation.OutParameter
Essentially identical toExpectation.RowCount
except that the row count is obtained via an output parameter of astored procedure
.static class
Expectation.RowCount
Row count checking.
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default boolean
canBeBatched()
Is it acceptable to combine this expectation with JDBC statement batching? If this method returnsfalse
, 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 ofPreparedStatement
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 givenPreparedStatement
.
-
-
-
Method Detail
-
canBeBatched
default boolean canBeBatched()
Is it acceptable to combine this expectation with JDBC statement batching? If this method returnsfalse
, the use of batch updates is disabled.- Returns:
- True if batching can be combined with this expectation; false otherwise.
- See Also:
Statement.executeBatch()
-
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 givenPreparedStatement
. When a SQL statement is executed viaPreparedStatement.executeUpdate()
,verifyOutcome()
is called exactly once. WhenStatement.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 viaexecuteUpdate()
. However, in the case whereexecuteBatch()
is used to execute a batch update, it might beStatement.EXECUTE_FAILED
orStatement.SUCCESS_NO_INFO
. - The argument to
batchPosition
is negative unlessexecuteBatch()
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 operationbatchPosition
- The position in the batch (if batching), or-1
if not part of a batchsql
- 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:
PreparedStatement.executeUpdate()
,Statement.executeBatch()
- The argument to
-
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 driverHibernateException
- Problem performing preparation.- See Also:
CallableStatement.registerOutParameter(int, int)
-
validate
default void validate(boolean callable) throws MappingException
Check that this implementation is compatible with the kind ofPreparedStatement
it will be called with. Implementors should throw aMappingException
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 thisExpectation
will be called with aCallableStatement
.- Throws:
MappingException
- Since:
- 6.5
-
-