Interface Query

All Known Subinterfaces:
Statement, StoredProcedureQuery, TypedQuery<X>
public interface Query
Declares common operations for controlling the execution of statements and queries written in the Jakarta Persistence query language or in native SQL.
  • For a Jakarta Persistence UPDATE or DELETE statement, or for a native SQL statement that returns a row count, an instance Statement should be used to execute the statement.
  • For a Jakarta Persistence SELECT query or for any native SQL query that returns a result set, an instance of TypedQuery should be used.
  • For a stored procedure call, a StoredProcedureQuery should be used.

If an instance of this interface represents an UPDATE or DELETE statement, then a Statement representing the same statement may be obtained by calling asStatement(). 

int updated =
        em.createQuery("delete from Temporary where timestamp > ?1")
                .asStatement()
                .setParameter(1, cutoffDateTime)
                .execute();

If an instance of this interface represents a SELECT query, then a TypedQuery representing the same query may be obtained by calling ofType(Class), passing the result type of the query. 

List<Book> books =
        em.createQuery("from Book where extract(year from publicationDate) > :year")
                .ofType(Book.class)
                .setParameter("year", Year.of(2000))
                .setMaxResults(10)
                .setCacheRetrieveMode(CacheRetrieveMode.BYPASS)
                .getResultList();

These operations may be viewed as a sort of type cast to a given subtype of this interface.

Since:
1.0
See Also:
API note:
Every operation only relevant to SELECT queries, for example, getResultList() and setMaxResults(int), is now declared deprecated by this interface. Such operations should be invoked via the TypedQuery interface. Similarly, the operation executeUpdate(), which was only used to execute statements, is declared as deprecated; the new operation Statement.execute() should be used instead.

  • Method Details

    • asStatement

      Statement asStatement()
      Obtain a Statement representing this query, which must be some kind of executable statement, that is, a Jakarta Persistence UPDATE or DELETE statement, or any native SQL statement that returns a row count. The executable statement may be executed by calling Statement.execute().
      Throws:
      IllegalStateException - if this query is a Jakarta Persistence SELECT query
      Since:
      4.0

    • ofType

      <R> TypedQuery<R> ofType(Class<R> resultType)
      Obtain a TypedQuery with the given query result type, which must be a supertype of the result type of this query. This query must be a Jakarta Persistence SELECT query or a native SQL query which returns a result set.
      Type Parameters:
      R - The query result type
      Parameters:
      resultType - The Java class of the query result type
      Throws:
      IllegalArgumentException - if the given result type is not a supertype of the result type of this query
      IllegalStateException - if this query is a Jakarta Persistence UPDATE or DELETE statement
      Since:
      4.0

    • withEntityGraph

      <R> TypedQuery<R> withEntityGraph(EntityGraph<R> graph)
      Obtain a TypedQuery with the given entity graph, which must be rooted at a supertype of the result type of this query. This query must be a Jakarta Persistence SELECT query which returns a single entity type.
      Type Parameters:
      R - The query result type
      Parameters:
      graph - The entity graph, interpreted as a load graph
      Throws:
      IllegalArgumentException - if the given graph type is not rooted at a supertype of the result type of this query
      IllegalStateException - if this query is a Jakarta Persistence UPDATE or DELETE statement
      Since:
      4.0

    • getResultList

      @Deprecated(since="4.0", forRemoval=true) List getResultList()
      Deprecated, for removal: This API element is subject to removal in a future version.
      This method returns a raw type. Use TypedQuery.getResultList() to execute queries.
      Execute a SELECT query or a native query that returns a result set and return the query results as an untyped List. If necessary, first synchronize changes with the database by flushing the persistence context.
      Returns:
      a list of the results, or an empty list if there are no results
      Throws:
      IllegalStateException - if called for a Jakarta Persistence query language UPDATE or DELETE statement
      QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back
      TransactionRequiredException - if a lock mode other than NONE has been set and there is no transaction or the persistence context has not been joined to the transaction
      PessimisticLockException - if pessimistic locking fails and the transaction is rolled back
      LockTimeoutException - if pessimistic locking fails 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

    • getResultStream

      @Deprecated(since="4.0", forRemoval=true) default Stream getResultStream()
      Deprecated, for removal: This API element is subject to removal in a future version.
      This method returns a raw type. Use TypedQuery.getResultStream() to execute queries
      Execute a SELECT query or a native query that returns a result set and return the query results as an untyped Stream. If necessary, first synchronize changes with the database by flushing the persistence context.

      By default, this method delegates to getResultList().stream(), The persistence provider may choose to override this method to provide additional capabilities.

      Returns:
      a stream of the results, or an empty stream if there are no results
      Throws:
      IllegalStateException - if called for a Jakarta Persistence query language UPDATE or DELETE statement
      QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back
      TransactionRequiredException - if a lock mode other than NONE has been set and there is no transaction or the persistence context has not been joined to the transaction
      PessimisticLockException - if pessimistic locking fails and the transaction is rolled back
      LockTimeoutException - if pessimistic locking fails 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
      Since:
      2.2
      See Also:

    • getSingleResult

      @Deprecated(since="4.0", forRemoval=true) Object getSingleResult()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use TypedQuery.getSingleResult() to execute queries
      Execute a SELECT query or a native query that returns a result set, returning a single untyped result. If necessary, first synchronize changes with the database by flushing the persistence context.
      Returns:
      the result
      Throws:
      NoResultException - if there is no result
      NonUniqueResultException - if more than one result
      IllegalStateException - if called for a Jakarta Persistence query language UPDATE or DELETE statement
      QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back
      TransactionRequiredException - if a lock mode other than NONE has been set and there is no transaction or the persistence context has not been joined to the transaction
      PessimisticLockException - if pessimistic locking fails and the transaction is rolled back
      LockTimeoutException - if pessimistic locking fails 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

    • getSingleResultOrNull

      @Deprecated(since="4.0", forRemoval=true) Object getSingleResultOrNull()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use TypedQuery.getSingleResult() to execute queries
      Execute a SELECT query or a native query that returns a result set, returning a single untyped result, or null if the query has no results. If necessary, first synchronize changes with the database by flushing the persistence context.
      Returns:
      the result, or null if there is no result
      Throws:
      NonUniqueResultException - if more than one result
      IllegalStateException - if called for a Jakarta Persistence query language UPDATE or DELETE statement
      QueryTimeoutException - if the query execution exceeds the query timeout value set and only the statement is rolled back
      TransactionRequiredException - if a lock mode other than NONE has been set and there is no transaction or the persistence context has not been joined to the transaction
      PessimisticLockException - if pessimistic locking fails and the transaction is rolled back
      LockTimeoutException - if pessimistic locking fails 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
      Since:
      3.2

    • executeUpdate

      @Deprecated(since="4.0", forRemoval=true) int executeUpdate()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use Statement.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

    • setMaxResults

      @Deprecated(since="4.0", forRemoval=true) Query setMaxResults(int maxResult)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use TypedQuery.setMaxResults(int)
      Set the maximum number of results returned to the client. If the query has more results than the given maximum, results are excluded from the list returned by getResultList(), so that only the given number of results is returned. If the query returns results with a well-defined order, the excluded results must be those which would otherwise occur later in the list.
      Parameters:
      maxResult - The maximum number of results
      Returns:
      the same query instance
      Throws:
      IllegalArgumentException - if the argument is negative

    • getMaxResults

      @Deprecated(since="4.0", forRemoval=true) int getMaxResults()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use TypedQuery.getMaxResults()
      The maximum number of results returned to the client, as specified by setMaxResults(int), or 2147483647 if setMaxResults(int) was not called.
      Returns:
      the maximum number of results
      Since:
      2.0

    • setFirstResult

      @Deprecated(since="4.0", forRemoval=true) Query setFirstResult(int startPosition)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use TypedQuery.setFirstResult(int)
      Set the position of the first query result returned to the client. The given number of results is excluded from the list returned by getResultList(). If the query returns results with a well-defined order, the excluded results must be those which would otherwise occur earlier in the list.
      Parameters:
      startPosition - The position of the first result, numbered from 0
      Returns:
      the same query instance
      Throws:
      IllegalArgumentException - if the argument is negative

    • getFirstResult

      @Deprecated(since="4.0", forRemoval=true) int getFirstResult()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use TypedQuery.getFirstResult()
      The position of the first result returned to the client, as specified by setFirstResult(int), or 0 if setFirstResult(int) was not called.
      Returns:
      the position of the first result
      Since:
      2.0

    • setHint

      Query setHint(String hintName, Object value)
      Set a query property or hint. The hints elements may be used to specify query properties and hints. Properties defined by this specification must be observed by the 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.
      Parameters:
      hintName - The name of the property or hint
      value - The value for the property or hint
      Returns:
      the same query instance
      Throws:
      IllegalArgumentException - if the second argument is not valid for the implementation

    • getHints

      Map<String,Object> getHints()
      Get the properties and hints and associated values that are in effect for the query instance.
      Returns:
      query properties and hints
      Since:
      2.0

    • setParameter

      <T> Query setParameter(Parameter<T> parameter, T value)
      Bind an argument to a parameter of this query respresented as a Parameter object.
      Parameters:
      parameter - The parameter object
      value - The argument to the parameter
      Returns:
      the same query instance
      Throws:
      IllegalArgumentException - if the parameter does not correspond to a parameter of the query
      Since:
      2.0

    • setParameter

      @Deprecated(since="3.2") Query setParameter(Parameter<Calendar> param, Calendar value, 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.
      Parameters:
      param - The parameter object
      value - The argument to the parameter
      temporalType - A temporal type
      Returns:
      the same query instance
      Throws:
      IllegalArgumentException - if the parameter does not correspond to a parameter of the query
      Since:
      2.0

    • setParameter

      @Deprecated(since="3.2") Query setParameter(Parameter<Date> param, Date value, 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.
      Parameters:
      param - The parameter object
      value - The argument to the parameter
      temporalType - A temporal type
      Returns:
      the same query instance
      Throws:
      IllegalArgumentException - if the parameter does not correspond to a parameter of the query
      Since:
      2.0

    • setParameter

      Query setParameter(String name, Object value)
      Bind an argument value to a named parameter.
      Parameters:
      name - The name of the parameter
      value - The argument to the parameter
      Returns:
      the same query 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

      <P> Query setParameter(String name, P value, 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.createNativeQuery("update books set pub_date = :date where isbn = :ISBN")
    .setParameter("date", optionalPublicationDate, LocalDate.class)
    .setParameter("ISBN", isbn)
    .executeUpdate();

      var books =
    session.createNativeQuery("select * from books where :limit is null or pub_date > :limit",
                              Book.class)
        .setParameter("limit", optionalDateLimit, LocalDate.class)
        .getResultList();
      Parameters:
      name - The name of the parameter
      value - The argument to the parameter
      type - A class object representing the parameter type
      Returns:
      the same query 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

      <P> Query setParameter(String name, P value, 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. 
      var amount = MonetaryAmount.of(priceLimit, currency);
var affordableBooks =
    em.createQuery("from Book where price < :amount")
        .setParameter("amount", amount, Book_.price.getType())
        .getResultList();
      Parameters:
      name - The name of the parameter
      value - The argument to the parameter
      type - The Type of the parameter
      Returns:
      the same query 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

      <P> Query 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. 
      var amount = MonetaryAmount.of(priceLimit, currency);
var affordableBooks =
    em.createQuery("from Book where price < :amount")
        .setConvertedParameter("amount", amount,
                MonetaryAmountConverter.class)
        .getResultList();
      Parameters:
      name - The name of the parameter
      value - The argument to the parameter
      converter - The class of the attribute converter
      Returns:
      the same query 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") Query setParameter(String name, Calendar value, 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.
      Parameters:
      name - The name of the parameter
      value - The argument to the parameter
      temporalType - A temporal type
      Returns:
      the same query 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") Query setParameter(String name, Date value, 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.
      Parameters:
      name - The name of the parameter
      value - The argument to the parameter
      temporalType - A temporal type
      Returns:
      the same query 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

      Query setParameter(int position, Object value)
      Bind an argument value to a positional parameter.
      Parameters:
      position - The parameter position
      value - The argument to the parameter
      Returns:
      the same query instance
      Throws:
      IllegalArgumentException - if the given position does not correspond to a parameter of the query, or if the argument is of incompatible type

    • setParameter

      <P> Query setParameter(int position, P value, 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.createNativeQuery("update books set pub_date = ?1 where isbn = ?2")
    .setParameter(1, optionalPublicationDate, LocalDate.class)
    .setParameter(2, isbn)
    .executeUpdate();

      var books =
    session.createNativeQuery("select * from books where ?1 is null or pub_date > ?1",
                              Book.class)
        .setParameter(1, optionalDateLimit, LocalDate.class)
        .getResultList();
      Parameters:
      position - The parameter position
      value - The argument to the parameter
      type - A class object representing the parameter type
      Returns:
      the same query 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

      <P> Query setParameter(int position, P value, 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. 
      var amount = MonetaryAmount.of(priceLimit, currency);
var affordableBooks =
    em.createQuery("from Book where price < ?1")
        .setParameter(1, amount, Book_.price.getType())
        .getResultList();
      Parameters:
      position - The parameter position
      value - The argument to the parameter
      type - The Type of the parameter
      Returns:
      the same query 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

      <P> Query 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. 
      var amount = MonetaryAmount.of(priceLimit, currency);
var affordableBooks =
    em.createQuery("from Book where price < ?1")
        .setConvertedParameter(1, amount,
                MonetaryAmountConverter.class)
        .getResultList();
      Parameters:
      position - The parameter position
      value - The argument to the parameter
      converter - The class of the attribute converter
      Returns:
      the same query 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") Query setParameter(int position, Calendar value, 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.
      Parameters:
      position - The parameter position
      value - The argument to the parameter
      temporalType - A temporal type
      Returns:
      the same query 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") Query setParameter(int position, Date value, 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.
      Parameters:
      position - The parameter position
      value - The argument to the parameter
      temporalType - A temporal type
      Returns:
      the same query 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

    • getParameters

      Set<Parameter<?>> getParameters()
      Get the Parameter objects representing the declared parameters of the query or an empty set if the query has no parameters. This method is not required to be supported for native queries.
      Returns:
      a set containing the parameter objects
      Throws:
      IllegalStateException - if invoked on a native query when the implementation does not support this use
      Since:
      2.0

    • getParameter

      Parameter<?> getParameter(String name)
      Get the Parameter object representing the declared named parameter with the given name. This method is not required to be supported for native queries.
      Parameters:
      name - The name of the parameter
      Returns:
      The parameter object representing the named parameter
      Throws:
      IllegalArgumentException - if the parameter of the specified name does not exist
      IllegalStateException - if invoked on a native query when the implementation does not support this use
      Since:
      2.0

    • getParameter

      <T> Parameter<T> getParameter(String name, Class<T> type)
      Get the Parameter object representing the declared named parameter with the given name and type. This method is required to be supported for criteria queries only.
      Parameters:
      name - The name of the parameter
      type - A class object representing the parameter type
      Returns:
      The parameter object representing the named parameter
      Throws:
      IllegalArgumentException - if the parameter of the specified name does not exist or is not assignable to the type
      IllegalStateException - if invoked on a native query or Jakarta Persistence query language query when the implementation does not support this use
      Since:
      2.0

    • getParameter

      Parameter<?> getParameter(int position)
      Get the Parameter object representing the declared positional parameter with the given position. This method is not required to be supported for native queries.
      Parameters:
      position - The parameter position
      Returns:
      The parameter object representing the positional parameter
      Throws:
      IllegalArgumentException - if the parameter with the specified position does not exist
      IllegalStateException - if invoked on a native query when the implementation does not support this use
      Since:
      2.0

    • getParameter

      <T> Parameter<T> getParameter(int position, Class<T> type)
      Get the Parameter object corresponding to the declared positional parameter with the given position and type. This method is not required to be supported by the provider.
      Parameters:
      position - The parameter position
      type - A class object representing the parameter type
      Returns:
      The parameter object representing the positional parameter
      Throws:
      IllegalArgumentException - if the parameter with the specified position does not exist or is not assignable to the type
      IllegalStateException - if invoked on a native query or Jakarta Persistence query language query when the implementation does not support this use
      Since:
      2.0

    • isBound

      boolean isBound(Parameter<?> parameter)
      Return a boolean value indicating whether an argument has been bound to the parameter represented by the given parameter object.
      Parameters:
      parameter - The parameter object
      Returns:
      true an argument has been bound, or false otherwise
      Since:
      2.0

    • getParameterValue

      <T> T getParameterValue(Parameter<T> parameter)
      Return the input value bound to the parameter. (Note that OUT parameters are unbound.)
      Parameters:
      parameter - The parameter object
      Returns:
      parameter value
      Throws:
      IllegalArgumentException - if the parameter is not a parameter of the query
      IllegalStateException - if the parameter has not been bound
      Since:
      2.0

    • getParameterValue

      Object getParameterValue(String name)
      Return the input value bound to the named parameter. (Note that OUT parameters are unbound.)
      Parameters:
      name - The name of the parameter
      Returns:
      parameter value
      Throws:
      IllegalStateException - if the parameter has not been bound
      IllegalArgumentException - if the parameter of the specified name does not exist
      Since:
      2.0

    • getParameterValue

      Object getParameterValue(int position)
      Return the input value bound to the positional parameter. (Note that OUT parameters are unbound.)
      Parameters:
      position - The parameter position
      Returns:
      parameter value
      Throws:
      IllegalStateException - if the parameter has not been bound
      IllegalArgumentException - if the parameter with the specified position does not exist
      Since:
      2.0

    • setFlushMode

      Query setFlushMode(FlushModeType flushMode)
      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.
      Parameters:
      flushMode - The new flush mode
      Returns:
      the same query instance

    • getFlushMode

      FlushModeType getFlushMode()
      Get the flush mode which will be in effect when the query is executed. If a flush mode has not been set for this query object, return the current flush mode type of the entity manager.
      Returns:
      flush mode
      Since:
      2.0

    • setLockMode

      @Deprecated(since="4.0", forRemoval=true) Query setLockMode(LockModeType lockMode)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use TypedQuery.setLockMode(LockModeType)
      Set the lock mode type to use when the query is executed.
      Parameters:
      lockMode - The new lock mode
      Returns:
      the same query instance
      Throws:
      IllegalStateException - if the query is not a Jakarta Persistence query language SELECT query or a CriteriaQuery
      Since:
      2.0
      See Also:

    • getLockMode

      @Deprecated(since="4.0", forRemoval=true) LockModeType getLockMode()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use TypedQuery.getLockMode()
      The current lock mode for the query or null if a lock mode has not been set.

      The lock mode affects every entity occurring as an item in the SELECT clause, including entities occurring as arguments to constructors. The effect on association join tables, collection tables, and primary and secondary tables of join fetched entities is determined by the lock scope in effect. If no lock scope was explicitly specified, the lock scope defaults to NORMAL.

      If the given lock mode is PESSIMISTIC_READ, PESSIMISTIC_WRITE, or PESSIMISTIC_FORCE_INCREMENT, the lock also affects every entity with an attribute reference occurring in the SELECT clause, except when the attribute reference occurs as an argument to an aggregate function.

      Returns:
      the current lock mode
      Throws:
      IllegalStateException - if the query is not a Jakarta Persistence query language SELECT query or a CriteriaQuery
      Since:
      2.0

    • setCacheRetrieveMode

      @Deprecated(since="4.0", forRemoval=true) Query setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use TypedQuery.setCacheRetrieveMode(CacheRetrieveMode)
      Set the cache retrieval mode in effect during query execution. This cache retrieval mode overrides the cache retrieve mode of the entity manager.
      Parameters:
      cacheRetrieveMode - The new cache retrieval mode
      Returns:
      the same query instance
      Since:
      3.2

    • setCacheStoreMode

      @Deprecated(since="4.0", forRemoval=true) Query setCacheStoreMode(CacheStoreMode cacheStoreMode)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use TypedQuery.setCacheStoreMode(CacheStoreMode)
      Set the cache storage mode in effect during query execution. This cache storage mode overrides the cache storage mode of the entity manager.
      Parameters:
      cacheStoreMode - The new cache storage mode
      Returns:
      the same query instance
      Since:
      3.2

    • getCacheRetrieveMode

      @Deprecated(since="4.0", forRemoval=true) CacheRetrieveMode getCacheRetrieveMode()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use TypedQuery.getCacheRetrieveMode()
      The cache retrieval mode in effect during query execution.
      Returns:
      the current cache retrieval mode set by calling setCacheRetrieveMode(CacheRetrieveMode) or the cache retrieval mode of the persistence context if no cache retrieval mode has been explicitly specified for this query.
      Since:
      3.2

    • getCacheStoreMode

      @Deprecated(since="4.0", forRemoval=true) CacheStoreMode getCacheStoreMode()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use TypedQuery.getCacheStoreMode()
      The cache storage mode in effect during query execution.
      Returns:
      the current cache storage mode set by calling setCacheStoreMode(CacheStoreMode) or the cache storage mode of the persistence context if no cache storage mode has been explicitly specified for this query.
      Since:
      3.2

    • setTimeout

      Query setTimeout(Integer timeout)
      Set the query timeout, in milliseconds. This is a hint, and is an alternative to setting the hint jakarta.persistence.query.timeout.
      Parameters:
      timeout - the timeout, in milliseconds, or null to indicate no timeout
      Returns:
      the same query instance
      Since:
      3.2

    • setTimeout

      Query setTimeout(Timeout timeout)
      Set the query timeout. This is a hint.
      Parameters:
      timeout - the timeout, or null to indicate no timeout
      Returns:
      the same query instance
      Since:
      4.0

    • getTimeout

      Integer getTimeout()
      The query timeout, in milliseconds, or null for no timeout.
      Since:
      3.2

    • unwrap

      <T> T unwrap(Class<T> type)
      Return an object of the specified type to allow access to a provider-specific API. If the provider implementation of Query does not support the given type, the PersistenceException is thrown.
      Parameters:
      type - The type of the object to be returned. This is usually either the underlying class implementing Query or an interface it implements.
      Returns:
      an instance of the specified class
      Throws:
      PersistenceException - if the provider does not support the given type
      Since:
      2.0