Interface Query

All Known Subinterfaces:
Statement, StatementOrTypedQuery, 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 of 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.
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

    • getResultList

      @Deprecated(since="4.0", forRemoval=true) @Nonnull 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) @Nonnull 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) @Nullable 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) @Nonnull 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) @Nonnull 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

      @Nonnull Query 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.
      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 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 query properties and hints lacks type safety compared to the use of query options or statement options.

    • getHints

      @Nonnull Map<String,Object> getHints()
      Get the properties and hints and associated values that are in effect for the query instance. Modifying the contents of the returned map does not change the configuration in effect.
      Returns:
      a copy of the query properties and hints currently in effect
      Since:
      2.0

    • setParameter

      @Nonnull <T> Query setParameter(@Nonnull Parameter<T> parameter, @Nullable T value)
      Bind an argument to a parameter of this query respresented as a Parameter object.
      Type Parameters:
      T - the parameter type
      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") @Nonnull Query 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.
      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") @Nonnull Query 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.
      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

      @Nonnull Query setParameter(@Nonnull String name, @Nullable 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

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

      var books =
    em.createNativeQuery("select * from books where :limit is null or pub_date > :limit",
                              Book.class)
        .setParameter("limit", optionalDateLimit, LocalDate.class)
        .getResultList();
      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 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

      @Nonnull <P> Query 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. 
      var amount = MonetaryAmount.of(priceLimit, currency);
var affordableBooks =
    em.createQuery("from Book where price < :amount")
        .setParameter("amount", amount, Book_.price.getType())
        .getResultList();
      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 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

      @Nonnull <P> Query 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. 
      var amount = MonetaryAmount.of(priceLimit, currency);
var affordableBooks =
    em.createQuery("from Book where price < :amount")
        .setConvertedParameter("amount", amount,
                MonetaryAmountConverter.class)
        .getResultList();
      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 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") @Nonnull Query 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.
      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") @Nonnull Query 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.
      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

      @Nonnull Query setParameter(int position, @Nullable 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

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

      var books =
    em.createNativeQuery("select * from books where ?1 is null or pub_date > ?1",
                              Book.class)
        .setParameter(1, optionalDateLimit, LocalDate.class)
        .getResultList();
      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 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

      @Nonnull <P> Query 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. 
      var amount = MonetaryAmount.of(priceLimit, currency);
var affordableBooks =
    em.createQuery("from Book where price < ?1")
        .setParameter(1, amount, Book_.price.getType())
        .getResultList();
      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 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

      @Nonnull <P> Query 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. 
      var amount = MonetaryAmount.of(priceLimit, currency);
var affordableBooks =
    em.createQuery("from Book where price < ?1")
        .setConvertedParameter(1, amount,
                MonetaryAmountConverter.class)
        .getResultList();
      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 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") @Nonnull Query 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.
      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") @Nonnull Query 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.
      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

      @Nonnull 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

      @Nonnull Parameter<?> getParameter(@Nonnull 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

      @Nonnull <T> Parameter<T> getParameter(@Nonnull String name, @Nonnull 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.
      Type Parameters:
      T - the parameter type
      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

      @Nonnull 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

      @Nonnull <T> Parameter<T> getParameter(int position, @Nonnull 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.
      Type Parameters:
      T - the parameter type
      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(@Nonnull 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

      @Nullable <T> T getParameterValue(@Nonnull Parameter<T> parameter)
      Return the input value bound to the parameter. (Note that OUT parameters are unbound.)
      Type Parameters:
      T - the parameter type
      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

      @Nullable Object getParameterValue(@Nonnull 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

      @Nullable 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

    • setQueryFlushMode

      @Nonnull Query 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.
      Parameters:
      flushMode - The new flush mode
      Returns:
      the same query instance
      Since:
      4.0

    • getQueryFlushMode

      @Nonnull QueryFlushMode getQueryFlushMode()
      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 QueryFlushMode.DEFAULT.
      Returns:
      flush mode
      Since:
      4.0

    • setFlushMode

      @Deprecated(since="4.0") @Nonnull Query 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.
      Parameters:
      flushMode - The new flush mode
      Returns:
      the same query instance

    • getFlushMode

      @Deprecated(since="4.0") @Nonnull FlushModeType getFlushMode()
      Deprecated.
      Use getQueryFlushMode().
      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) @Nonnull Query setLockMode(@Nonnull 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) @Nullable 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) @Nonnull Query setCacheRetrieveMode(@Nonnull 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) @Nonnull Query setCacheStoreMode(@Nonnull 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) @Nonnull 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) @Nonnull 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

      @Nonnull Query 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.
      Parameters:
      timeout - the timeout, in milliseconds, or null to indicate no timeout
      Returns:
      the same query instance
      Since:
      3.2

    • setTimeout

      @Nonnull Query setTimeout(@Nullable 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

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

    • unwrap

      @Nonnull <T> T unwrap(@Nonnull 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.
      Type Parameters:
      T - the type of the object to be returned
      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