Interface Statement

All Superinterfaces:

Query

public interface Statement
extends Query

Interface used to control the execution of executable statements. In the Jakarta Persistence query language only UPDATE and DELETE statements are executable statements. On the other hand, a native SQL statement is considered executable if it returns a row count instead of a result set.

Since:

4.0

See Also:

• EntityHandler.createStatement(String)
• EntityHandler.createStatement(jakarta.persistence.criteria.CriteriaStatement)
• EntityHandler.createStatement(StatementReference)
• EntityHandler.createNativeStatement(String)
• EntityHandler.createNamedStatement(String)
• StatementOrTypedQuery.asStatement()

API note:

Just like any other data access API, including JDBC itself, native SQL statement strings and Jakarta Persistence query language strings executed via this API must never be composed by concatenating user input or other untrusted data. User input should be properly validated and passed as a parameter to a parameterized statement string. In particular, native SQL statement strings executed via this API are typically executed verbatim with no additional validation or sanitization beyond that performed by the JDBC driver.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	Statement.Option	An option influencing execution of a statement.

Method Summary

Modifier and Type	Method	Description
Statement	addOption(Statement.Option option)	Specify an option influencing execution of this statement, overwriting any existing option of the same type.
int	execute()	Execute an UPDATE or DELETE statement or a native SQL statement that returns a row count.
Set<Statement.Option>	getOptions()	Get the options influencing execution of this statement.
<P> Statement	setConvertedParameter(int position, P value, Class<? extends AttributeConverter<P,?>> converter)	Bind an argument value to a named parameter, explicitly specifying an attribute converter to use.
<P> Statement	setConvertedParameter(String name, P value, Class<? extends AttributeConverter<P,?>> converter)	Bind an argument value to a named parameter, explicitly specifying an attribute converter to use.
Statement	setFlushMode(FlushModeType flushMode)	Deprecated. Use setQueryFlushMode(QueryFlushMode).
Statement	setHint(String hintName, Object value)	Set a query property or hint.
Statement	setParameter(int position, Object value)	Bind an argument value to a positional parameter.
Statement	setParameter(int position, Calendar value, TemporalType temporalType)	Deprecated. Newly written code should use the date/time types defined in java.time.
Statement	setParameter(int position, Date value, TemporalType temporalType)	Deprecated. Newly written code should use the date/time types defined in java.time.
<P> Statement	setParameter(int position, P value, Type<P> type)	Bind an argument value to a positional parameter, explicitly specifying the parameter type.
<P> Statement	setParameter(int position, P value, Class<P> type)	Bind an argument value to a positional parameter, explicitly specifying the parameter type.
Statement	setParameter(Parameter<Calendar> param, Calendar value, TemporalType temporalType)	Deprecated. Newly written code should use the date/time types defined in java.time.
Statement	setParameter(Parameter<Date> param, Date value, TemporalType temporalType)	Deprecated. Newly written code should use the date/time types defined in java.time.
<T> Statement	setParameter(Parameter<T> parameter, T value)	Bind an argument to a parameter of this query respresented as a Parameter object.
Statement	setParameter(String name, Object value)	Bind an argument value to a named parameter.
Statement	setParameter(String name, Calendar value, TemporalType temporalType)	Deprecated. Newly written code should use the date/time types defined in java.time.
Statement	setParameter(String name, Date value, TemporalType temporalType)	Deprecated. Newly written code should use the date/time types defined in java.time.
<P> Statement	setParameter(String name, P value, Type<P> type)	Bind an argument value to a named parameter, explicitly specifying the parameter type.
<P> Statement	setParameter(String name, P value, Class<P> type)	Bind an argument value to a named parameter, explicitly specifying the parameter type.
Statement	setQueryFlushMode(QueryFlushMode flushMode)	Set the query flush mode to be used when the query is executed.
Statement	setTimeout(Timeout timeout)	Set the query timeout.
Statement	setTimeout(Integer timeout)	Set the query timeout, in milliseconds.

Methods inherited from interface Query

executeUpdate, getCacheRetrieveMode, getCacheStoreMode, getFirstResult, getFlushMode, getHints, getLockMode, getMaxResults, getParameter, getParameter, getParameter, getParameter, getParameters, getParameterValue, getParameterValue, getParameterValue, getQueryFlushMode, getResultList, getResultStream, getSingleResult, getSingleResultOrNull, getTimeout, isBound, setCacheRetrieveMode, setCacheStoreMode, setFirstResult, setLockMode, setMaxResults, unwrap

Method Details

execute

int execute()

Execute an UPDATE or DELETE statement or a native SQL statement that returns a row count.

After execution of a bulk update or delete operation, the persistence provider is not required to resynchronize state held in memory with the effects of the operation on data held in the database. However, when this method is called within a transaction, the persistence context is joined to the transaction, and FlushModeType.AUTO is in effect, the persistence provider must ensure that every modification to the state of every entity associated with the persistence context which could possibly alter the effects of the bulk update or delete operation is visible to the processing of the operation.

Returns:

the number of entities updated or deleted, or the row count of the native SQL statement

Throws:

IllegalStateException - if called for a Jakarta Persistence query language SELECT statement or for a criteria query

TransactionRequiredException - if there is no transaction or the persistence context has not been joined to the transaction

QueryTimeoutException - if the statement execution exceeds the query timeout value set and only the statement is rolled back

PersistenceException - if the query execution exceeds the query timeout value set and the transaction is rolled back

PersistenceException - if the flush fails

OptimisticLockException - if an optimistic locking conflict is detected during the flush

setHint

@Nonnull
Statement setHint(@Nonnull
 String hintName,
 @Nullable
 Object value)

Set a query property or hint. Properties defined by this specification must be observed by the persistence provider. Vendor-specific hints that are not recognized by a provider must be silently ignored. Portable applications should not rely on the standard timeout hint; depending on the database in use and the locking mechanisms used by the provider, this hint may or may not be observed.

Specified by:

setHint in interface Query

Parameters:

hintName - The name of the property or hint

value - The value for the property or hint

Returns:

the same statement instance

Throws:

IllegalArgumentException - if the given property or hint name is recognized by the provider, but the second argument is not a legal value for the given property or hint

API note:

The use of named hints lacks type safety compared to the use of options.

setTimeout

@Nonnull
Statement setTimeout(@Nullable
 Integer timeout)

Set the query timeout, in milliseconds. This is a hint, and is an alternative to setting the hint jakarta.persistence.query.timeout.

Specified by:

setTimeout in interface Query

Parameters:

timeout - The timeout, in milliseconds, or null to indicate no timeout

Returns:

the same statement instance

Since:

3.2

setTimeout

@Nonnull
Statement setTimeout(@Nullable
 Timeout timeout)

Set the query timeout. This is a hint.

Specified by:

setTimeout in interface Query

Parameters:

timeout - the timeout, or null to indicate no timeout

Returns:

the same statement instance

Since:

4.0

setQueryFlushMode

@Nonnull
Statement setQueryFlushMode(@Nonnull
 QueryFlushMode flushMode)

Set the query flush mode to be used when the query is executed. This flush mode overrides the flush mode type of the entity manager.

Specified by:

setQueryFlushMode in interface Query

Parameters:

flushMode - The new flush mode

Returns:

the same statement instance

Since:

4.0

setFlushMode

@Deprecated
@Nonnull
Statement setFlushMode(@Nonnull
 FlushModeType flushMode)

Deprecated.

Use setQueryFlushMode(QueryFlushMode).

Set the flush mode type to be used when the query is executed. This flush mode overrides the flush mode type of the entity manager.

Specified by:

setFlushMode in interface Query

Parameters:

flushMode - The new flush mode

Returns:

the same statement instance

setParameter

@Nonnull
<T> Statement setParameter(@Nonnull
 Parameter<T> parameter,
 @Nullable
 T value)

Bind an argument to a parameter of this query respresented as a Parameter object.

Specified by:

setParameter in interface Query

Type Parameters:

T - the parameter type

Parameters:

parameter - The parameter object

value - The argument to the parameter

Returns:

the same statement instance

Throws:

IllegalArgumentException - if the parameter does not correspond to a parameter of the query

Since:

2.0

setParameter

@Deprecated(since="3.2")
@Nonnull
Statement setParameter(@Nonnull
 Parameter<Calendar> param,
 @Nullable
 Calendar value,
 @Nonnull
 TemporalType temporalType)

Deprecated.

Newly written code should use the date/time types defined in java.time.

Bind an instance of Calendar to a Parameter object.

Specified by:

setParameter in interface Query

Parameters:

param - The parameter object

value - The argument to the parameter

temporalType - A temporal type

Returns:

the same statement instance

Throws:

IllegalArgumentException - if the parameter does not correspond to a parameter of the query

Since:

2.0

setParameter

@Deprecated(since="3.2")
@Nonnull
Statement setParameter(@Nonnull
 Parameter<Date> param,
 @Nullable
 Date value,
 @Nonnull
 TemporalType temporalType)

Deprecated.

Newly written code should use the date/time types defined in java.time.

Bind an instance of Date to a Parameter object.

Specified by:

setParameter in interface Query

Parameters:

param - The parameter object

value - The argument to the parameter

temporalType - A temporal type

Returns:

the same statement instance

Throws:

IllegalArgumentException - if the parameter does not correspond to a parameter of the query

Since:

2.0

setParameter

@Nonnull
Statement setParameter(@Nonnull
 String name,
 @Nullable
 Object value)

Bind an argument value to a named parameter.

Specified by:

setParameter in interface Query

Parameters:

name - The name of the parameter

value - The argument to the parameter

Returns:

the same statement instance

Throws:

IllegalArgumentException - if the parameter name does not correspond to a parameter of the query, or if the argument is of incompatible type

setParameter

@Nonnull
<P> Statement setParameter(@Nonnull
 String name,
 @Nullable
 P value,
 @Nonnull
 Class<P> type)

Bind an argument value to a named parameter, explicitly specifying the parameter type. This is most useful when the argument might be null, especially in the case of a native query.

em.createNativeStatement("update books set pub_date = :date where isbn = :ISBN")
    .setParameter("date", optionalPublicationDate, LocalDate.class)
    .setParameter("ISBN", isbn)
    .execute();

Specified by:

setParameter in interface Query

Type Parameters:

P - the parameter type

Parameters:

name - The name of the parameter

value - The argument to the parameter

type - A class object representing the parameter type

Returns:

the same statement instance

Throws:

IllegalArgumentException - if the parameter name does not correspond to a parameter of the query, or if the argument is of incompatible type

Since:

4.0

setParameter

@Nonnull
<P> Statement setParameter(@Nonnull
 String name,
 @Nullable
 P value,
 @Nonnull
 Type<P> type)

Bind an argument value to a named parameter, explicitly specifying the parameter type. This is most useful when the binding is affected by an attribute converter.

em.createNativeStatement("update books set pub_date = :date where isbn = :ISBN")
    .setParameter("date", optionalPublicationDate, Book_.publicationDate.getType())
    .setParameter("ISBN", isbn, Book_.isbn.getType())
    .execute();

Specified by:

setParameter in interface Query

Type Parameters:

P - the parameter type

Parameters:

name - The name of the parameter

value - The argument to the parameter

type - The Type of the parameter

Returns:

the same statement instance

Throws:

IllegalArgumentException - if the parameter name does not correspond to a parameter of the query, or if the argument is of incompatible type

Since:

4.0

setConvertedParameter

@Nonnull
<P> Statement setConvertedParameter(@Nonnull
 String name,
 @Nullable
 P value,
 @Nonnull
 Class<? extends AttributeConverter<P,?>> converter)

Bind an argument value to a named parameter, explicitly specifying an attribute converter to use.

em.createNativeStatement("update books set pub_date = :date where isbn = :ISBN")
    .setParameter("date", publicationDate)
    .setParameter("ISBN", isbn, IsbnConverter.class)
    .execute();

Specified by:

setConvertedParameter in interface Query

Type Parameters:

P - the parameter type

Parameters:

name - The name of the parameter

value - The argument to the parameter

converter - The class of the attribute converter

Returns:

the same statement instance

Throws:

IllegalArgumentException - if the parameter name does not correspond to a parameter of the query, or if the argument is of incompatible type

Since:

4.0

setParameter

@Deprecated(since="3.2")
@Nonnull
Statement setParameter(@Nonnull
 String name,
 @Nullable
 Calendar value,
 @Nonnull
 TemporalType temporalType)

Deprecated.

Newly written code should use the date/time types defined in java.time.

Bind an instance of Calendar to a named parameter.

Specified by:

setParameter in interface Query

Parameters:

name - The name of the parameter

value - The argument to the parameter

temporalType - A temporal type

Returns:

the same statement instance

Throws:

IllegalArgumentException - if the parameter name does not correspond to a parameter of the query, or if the value argument is of incompatible type

setParameter

@Deprecated(since="3.2")
@Nonnull
Statement setParameter(@Nonnull
 String name,
 @Nullable
 Date value,
 @Nonnull
 TemporalType temporalType)

Deprecated.

Newly written code should use the date/time types defined in java.time.

Bind an instance of Date to a named parameter.

Specified by:

setParameter in interface Query

Parameters:

name - The name of the parameter

value - The argument to the parameter

temporalType - A temporal type

Returns:

the same statement instance

Throws:

IllegalArgumentException - if the parameter name does not correspond to a parameter of the query, or if the value argument is of incompatible type

setParameter

@Nonnull
Statement setParameter(int position,
 @Nullable
 Object value)

Bind an argument value to a positional parameter.

Specified by:

setParameter in interface Query

Parameters:

position - The parameter position

value - The argument to the parameter

Returns:

the same statement instance

Throws:

IllegalArgumentException - if the given position does not correspond to a positional parameter of the query, or if the argument is of incompatible type

setParameter

@Nonnull
<P> Statement setParameter(int position,
 @Nullable
 P value,
 @Nonnull
 Class<P> type)

Bind an argument value to a positional parameter, explicitly specifying the parameter type. This is most useful when the argument might be null, especially in the case of a native SQL query.

em.createNativeStatement("update books set pub_date = ?1 where isbn = ?2")
    .setParameter(1, optionalPublicationDate, LocalDate.class)
    .setParameter(2, isbn)
    .execute();

Specified by:

setParameter in interface Query

Type Parameters:

P - the parameter type

Parameters:

position - The parameter position

value - The argument to the parameter

type - A class object representing the parameter type

Returns:

the same statement instance

Throws:

IllegalArgumentException - if the given position does not correspond to a parameter of the query, or if the argument is of incompatible type

Since:

4.0

setParameter

@Nonnull
<P> Statement setParameter(int position,
 @Nullable
 P value,
 @Nonnull
 Type<P> type)

Bind an argument value to a positional parameter, explicitly specifying the parameter type. This is most useful when the binding is affected by an attribute converter.

em.createNativeStatement("update books set pub_date = ?1 where isbn = ?2")
    .setParameter(1, optionalPublicationDate, Book_.publicationDate.getType())
    .setParameter(2, isbn, Book_.isbn.getType())
    .execute();

Specified by:

setParameter in interface Query

Type Parameters:

P - the parameter type

Parameters:

position - The parameter position

value - The argument to the parameter

type - The Type of the parameter

Returns:

the same statement instance

Throws:

IllegalArgumentException - if the given position does not correspond to a positional parameter of the query, or if the argument is of incompatible type

Since:

4.0

setConvertedParameter

@Nonnull
<P> Statement setConvertedParameter(int position,
 @Nullable
 P value,
 @Nonnull
 Class<? extends AttributeConverter<P,?>> converter)

Bind an argument value to a named parameter, explicitly specifying an attribute converter to use.

em.createNativeStatement("update books set pub_date = ?1 where isbn = ?2")
    .setParameter(1, publicationDate)
    .setParameter(2, isbn, IsbnConverter.class)
    .execute();

Specified by:

setConvertedParameter in interface Query

Type Parameters:

P - the parameter type

Parameters:

position - The parameter position

value - The argument to the parameter

converter - The class of the attribute converter

Returns:

the same statement instance

Throws:

IllegalArgumentException - if the given position does not correspond to a parameter of the query, or if the argument is of incompatible type

Since:

4.0

setParameter

@Deprecated(since="3.2")
@Nonnull
Statement setParameter(int position,
 @Nullable
 Calendar value,
 @Nonnull
 TemporalType temporalType)

Deprecated.

Newly written code should use the date/time types defined in java.time.

Bind an instance of Calendar to a positional parameter.

Specified by:

setParameter in interface Query

Parameters:

position - The parameter position

value - The argument to the parameter

temporalType - A temporal type

Returns:

the same statement instance

Throws:

IllegalArgumentException - if the given position does not correspond to a positional parameter of the query, or if the argument is of incompatible type

setParameter

@Deprecated(since="3.2")
@Nonnull
Statement setParameter(int position,
 @Nullable
 Date value,
 @Nonnull
 TemporalType temporalType)

Deprecated.

Newly written code should use the date/time types defined in java.time.

Bind an instance of Date to a positional parameter.

Specified by:

setParameter in interface Query

Parameters:

position - The parameter position

value - The argument to the parameter

temporalType - A temporal type

Returns:

the same statement instance

Throws:

IllegalArgumentException - if the given position does not correspond to a positional parameter of the query, or if the argument is of incompatible type

addOption

@Nonnull
Statement addOption(@Nonnull
 Statement.Option option)

Specify an option influencing execution of this statement, overwriting any existing option of the same type.

Parameters:

option - the option

Returns:

the same statement instance

Since:

4.0

getOptions

@Nonnull
Set<Statement.Option> getOptions()

Get the options influencing execution of this statement. The returned set includes options set via addOption(Statement.Option), along with options specified via setTimeout(Integer) or setQueryFlushMode(QueryFlushMode). Mutation of the returned set does not affect the options of the statement.

Returns:

the options for this statement

Since:

4.0