Method Detail

• getResultList

  java.util.List getResultList()

  Execute a SELECT query and return the query results as an untyped List.

  Returns:

  a list of the results

  Throws:

  java.lang.IllegalStateException - if called for a Java 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

• getResultStream

  default java.util.stream.Stream getResultStream()

  Execute a SELECT query and return the query results as an untyped java.util.stream.Stream. By default this method delegates to getResultList().stream(), however persistence provider may choose to override this method to provide additional capabilities.

  Returns:

  a stream of the results

  Throws:

  java.lang.IllegalStateException - if called for a Java 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

  Since:

  2.2

  See Also:

  Stream, getResultList()

• getSingleResult

  java.lang.Object getSingleResult()

  Execute a SELECT query that returns a single untyped result.

  Returns:

  the result

  Throws:

  NoResultException - if there is no result

  NonUniqueResultException - if more than one result

  java.lang.IllegalStateException - if called for a Java 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

• executeUpdate

  int executeUpdate()

  Execute an update or delete statement.

  Returns:

  the number of entities updated or deleted

  Throws:

  java.lang.IllegalStateException - if called for a Java 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

• setMaxResults

  Query setMaxResults(int maxResult)

  Set the maximum number of results to retrieve.

  Parameters:

  maxResult - maximum number of results to retrieve

  Returns:

  the same query instance

  Throws:

  java.lang.IllegalArgumentException - if the argument is negative

• getMaxResults

  int getMaxResults()

  The maximum number of results the query object was set to retrieve. Returns Integer.MAX_VALUE if setMaxResults was not applied to the query object.

  Returns:

  maximum number of results

  Since:

  2.0

• setFirstResult

  Query setFirstResult(int startPosition)

  Set the position of the first result to retrieve.

  Parameters:

  startPosition - position of the first result, numbered from 0

  Returns:

  the same query instance

  Throws:

  java.lang.IllegalArgumentException - if the argument is negative

• getFirstResult

  int getFirstResult()

  The position of the first result the query object was set to retrieve. Returns 0 if setFirstResult was not applied to the query object.

  Returns:

  position of the first result

  Since:

  2.0

• setHint

  Query setHint(java.lang.String hintName,
                java.lang.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 - name of the property or hint

  value - value for the property or hint

  Returns:

  the same query instance

  Throws:

  java.lang.IllegalArgumentException - if the second argument is not valid for the implementation

• getHints

  java.util.Map<java.lang.String,java.lang.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> param,
                         T value)

  Bind the value of a Parameter object.

  Parameters:

  param - parameter object

  value - parameter value

  Returns:

  the same query instance

  Throws:

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

  Since:

  2.0

• setParameter

  Query setParameter(Parameter<java.util.Calendar> param,
                     java.util.Calendar value,
                     TemporalType temporalType)

  Bind an instance of java.util.Calendar to a Parameter object.

  Parameters:

  param - parameter object

  value - parameter value

  temporalType - temporal type

  Returns:

  the same query instance

  Throws:

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

  Since:

  2.0

• setParameter

  Query setParameter(Parameter<java.util.Date> param,
                     java.util.Date value,
                     TemporalType temporalType)

  Bind an instance of java.util.Date to a Parameter object.

  Parameters:

  param - parameter object

  value - parameter value

  temporalType - temporal type

  Returns:

  the same query instance

  Throws:

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

  Since:

  2.0

• setParameter

  Query setParameter(java.lang.String name,
                     java.lang.Object value)

  Bind an argument value to a named parameter.

  Parameters:

  name - parameter name

  value - parameter value

  Returns:

  the same query instance

  Throws:

  java.lang.IllegalArgumentException - if the parameter name does not correspond to a parameter of the query or if the argument is of incorrect type

• setParameter

  Query setParameter(java.lang.String name,
                     java.util.Calendar value,
                     TemporalType temporalType)

  Bind an instance of java.util.Calendar to a named parameter.

  Parameters:

  name - parameter name

  value - parameter value

  temporalType - temporal type

  Returns:

  the same query instance

  Throws:

  java.lang.IllegalArgumentException - if the parameter name does not correspond to a parameter of the query or if the value argument is of incorrect type

• setParameter

  Query setParameter(java.lang.String name,
                     java.util.Date value,
                     TemporalType temporalType)

  Bind an instance of java.util.Date to a named parameter.

  Parameters:

  name - parameter name

  value - parameter value

  temporalType - temporal type

  Returns:

  the same query instance

  Throws:

  java.lang.IllegalArgumentException - if the parameter name does not correspond to a parameter of the query or if the value argument is of incorrect type

• setParameter

  Query setParameter(int position,
                     java.lang.Object value)

  Bind an argument value to a positional parameter.

  Parameters:

  position - position

  value - parameter value

  Returns:

  the same query instance

  Throws:

  java.lang.IllegalArgumentException - if position does not correspond to a positional parameter of the query or if the argument is of incorrect type

• setParameter

  Query setParameter(int position,
                     java.util.Calendar value,
                     TemporalType temporalType)

  Bind an instance of java.util.Calendar to a positional parameter.

  Parameters:

  position - position

  value - parameter value

  temporalType - temporal type

  Returns:

  the same query instance

  Throws:

  java.lang.IllegalArgumentException - if position does not correspond to a positional parameter of the query or if the value argument is of incorrect type

• setParameter

  Query setParameter(int position,
                     java.util.Date value,
                     TemporalType temporalType)

  Bind an instance of java.util.Date to a positional parameter.

  Parameters:

  position - position

  value - parameter value

  temporalType - temporal type

  Returns:

  the same query instance

  Throws:

  java.lang.IllegalArgumentException - if position does not correspond to a positional parameter of the query or if the value argument is of incorrect type

• getParameters

  java.util.Set<Parameter<?>> getParameters()

  Get the parameter objects corresponding to the declared parameters of the query. Returns empty set if the query has no parameters. This method is not required to be supported for native queries.

  Returns:

  set of the parameter objects

  Throws:

  java.lang.IllegalStateException - if invoked on a native query when the implementation does not support this use

  Since:

  2.0

• getParameter

  Parameter<?> getParameter(java.lang.String name)

  Get the parameter object corresponding to the declared parameter of the given name. This method is not required to be supported for native queries.

  Parameters:

  name - parameter name

  Returns:

  parameter object

  Throws:

  java.lang.IllegalArgumentException - if the parameter of the specified name does not exist

  java.lang.IllegalStateException - if invoked on a native query when the implementation does not support this use

  Since:

  2.0

• getParameter

  <T> Parameter<T> getParameter(java.lang.String name,
                                java.lang.Class<T> type)

  Get the parameter object corresponding to the declared parameter of the given name and type. This method is required to be supported for criteria queries only.

  Parameters:

  name - parameter name

  type - type

  Returns:

  parameter object

  Throws:

  java.lang.IllegalArgumentException - if the parameter of the specified name does not exist or is not assignable to the type

  java.lang.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 corresponding to the declared positional parameter with the given position. This method is not required to be supported for native queries.

  Parameters:

  position - position

  Returns:

  parameter object

  Throws:

  java.lang.IllegalArgumentException - if the parameter with the specified position does not exist

  java.lang.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,
                                java.lang.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 - position

  type - type

  Returns:

  parameter object

  Throws:

  java.lang.IllegalArgumentException - if the parameter with the specified position does not exist or is not assignable to the type

  java.lang.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<?> param)

  Return a boolean indicating whether a value has been bound to the parameter.

  Parameters:

  param - parameter object

  Returns:

  boolean indicating whether parameter has been bound

  Since:

  2.0

• getParameterValue

  <T> T getParameterValue(Parameter<T> param)

  Return the input value bound to the parameter. (Note that OUT parameters are unbound.)

  Parameters:

  param - parameter object

  Returns:

  parameter value

  Throws:

  java.lang.IllegalArgumentException - if the parameter is not a parameter of the query

  java.lang.IllegalStateException - if the parameter has not been been bound

  Since:

  2.0

• getParameterValue

  java.lang.Object getParameterValue(java.lang.String name)

  Return the input value bound to the named parameter. (Note that OUT parameters are unbound.)

  Parameters:

  name - parameter name

  Returns:

  parameter value

  Throws:

  java.lang.IllegalStateException - if the parameter has not been been bound

  java.lang.IllegalArgumentException - if the parameter of the specified name does not exist

  Since:

  2.0

• getParameterValue

  java.lang.Object getParameterValue(int position)

  Return the input value bound to the positional parameter. (Note that OUT parameters are unbound.)

  Parameters:

  position - position

  Returns:

  parameter value

  Throws:

  java.lang.IllegalStateException - if the parameter has not been been bound

  java.lang.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 for the query execution. The flush mode type applies to the query regardless of the flush mode type in use for the entity manager.

  Parameters:

  flushMode - flush mode

  Returns:

  the same query instance

• getFlushMode

  FlushModeType getFlushMode()

  Get the flush mode in effect for the query execution. If a flush mode has not been set for the query object, returns the flush mode in effect for the entity manager.

  Returns:

  flush mode

  Since:

  2.0

• setLockMode

  Query setLockMode(LockModeType lockMode)

  Set the lock mode type to be used for the query execution.

  Parameters:

  lockMode - lock mode

  Returns:

  the same query instance

  Throws:

  java.lang.IllegalStateException - if the query is found not to be a Jakarta Persistence query language SELECT query or a CriteriaQuery query

  Since:

  2.0

• getLockMode

  LockModeType getLockMode()

  Get the current lock mode for the query. Returns null if a lock mode has not been set on the query object.

  Returns:

  lock mode

  Throws:

  java.lang.IllegalStateException - if the query is found not to be a Jakarta Persistence query language SELECT query or a Criteria API query

  Since:

  2.0

• unwrap

  <T> T unwrap(java.lang.Class<T> cls)

  Return an object of the specified type to allow access to the provider-specific API. If the provider's query implementation does not support the specified class, the PersistenceException is thrown.

  Parameters:

  cls - the class of the object to be returned. This is normally either the underlying query implementation class or an interface that it implements.

  Returns:

  an instance of the specified class

  Throws:

  PersistenceException - if the provider does not support the call

  Since:

  2.0