Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.persistence
Interface Query

All Known Subinterfaces:
  TypedQuery<X>

    public interface Query

Interface used to control query execution.

Since:
  Java Persistence 1.0
See Also:
  `TypedQuery`, `Parameter`

Method Summary
`int` | `executeUpdate()` Execute an update or delete statement.
`int` | `getFirstResult()` The position of the first result the query object was set to retrieve.
`FlushModeType` | `getFlushMode()` Get the flush mode in effect for the query execution.
`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.
`LockModeType` | `getLockMode()` Get the current lock mode for the query.
`int` | `getMaxResults()` The maximum number of results the query object was set to retrieve.
`Parameter<?>` | `getParameter(int position)` Get the parameter object corresponding to the declared positional parameter with the given position.
`
`<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.
`Parameter<?>` | `getParameter(java.lang.String name)` Get the parameter object corresponding to the declared parameter of the given name.
`
`<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.
`java.util.Set<Parameter<?>>` | `getParameters()` Get the parameter objects corresponding to the declared parameters of the query.
`java.lang.Object` | `getParameterValue(int position)` Return the value bound to the positional parameter.
`
`<T> T`
` | `getParameterValue(Parameter<T> param)` Return the value bound to the parameter.
`java.lang.Object` | `getParameterValue(java.lang.String name)` Return the value bound to the named parameter.
`java.util.List` | `getResultList()` Execute a SELECT query and return the query results as an untyped List.
`java.lang.Object` | `getSingleResult()` Execute a SELECT query that returns a single untyped result.
`boolean` | `isBound(Parameter<?> param)` Return a boolean indicating whether a value has been bound to the parameter.
`Query` | `setFirstResult(int startPosition)` Set the position of the first result to retrieve.
`Query` | `setFlushMode(FlushModeType flushMode)` Set the flush mode type to be used for the query execution.
`Query` | `setHint(java.lang.String hintName, java.lang.Object value)` Set a query property or hint.
`Query` | `setLockMode(LockModeType lockMode)` Set the lock mode type to be used for the query execution.
`Query` | `setMaxResults(int maxResult)` Set the maximum number of results to retrieve.
`Query` | `setParameter(int position, java.util.Calendar value, TemporalType temporalType)` Bind an instance of `java.util.Calendar` to a positional parameter.
`Query` | `setParameter(int position, java.util.Date value, TemporalType temporalType)` Bind an instance of `java.util.Date` to a positional parameter.
`Query` | `setParameter(int position, java.lang.Object value)` Bind an argument to a positional parameter.
`Query` | `setParameter(Parameter<java.util.Calendar> param, java.util.Calendar value, TemporalType temporalType)` Bind an instance of `java.util.Calendar` to a `Parameter` object.
`Query` | `setParameter(Parameter<java.util.Date> param, java.util.Date value, TemporalType temporalType)` Bind an instance of `java.util.Date` to a `Parameter` object.
`
`<T> Query`
` | `setParameter(Parameter<T> param, T value)` Bind the value of a `Parameter` object.
`Query` | `setParameter(java.lang.String name, java.util.Calendar value, TemporalType temporalType)` Bind an instance of `java.util.Calendar` to a named parameter.
`Query` | `setParameter(java.lang.String name, java.util.Date value, TemporalType temporalType)` Bind an instance of `java.util.Date` to a named parameter.
`Query` | `setParameter(java.lang.String name, java.lang.Object value)` Bind an argument to a named parameter.
`
`<T> T`
` | `unwrap(java.lang.Class<T> cls)` Return an object of the specified type to allow access to the provider-specific API.

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 has been set and there is no 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

### 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 has been set and there is no 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
    `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:
    Java Persistence 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:
    Java Persistence 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:
    Java Persistence 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:
    Java Persistence 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:
    Java Persistence 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:
    Java Persistence 2.0

### setParameter

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

  Bind an argument 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 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:
    Java Persistence 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:
    Java Persistence 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 Java Persistence query language query when the implementation does not support this use
  Since:
    Java Persistence 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:
    Java Persistence 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 Java Persistence query language query when the implementation does not support this use
  Since:
    Java Persistence 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:
    Java Persistence 2.0

### getParameterValue

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

  Return the value bound to the parameter.

  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:
    Java Persistence 2.0

### getParameterValue

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

  Return the value bound to the named parameter.

  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:
    Java Persistence 2.0

### getParameterValue

    java.lang.Object getParameterValue(int position)

  Return the value bound to the positional parameter.

  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:
    Java Persistence 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:
    Java Persistence 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 Java Persistence query language SELECT query or a Criteria API query
  Since:
    Java Persistence 2.0

### getLockMode

    LockModeType getLockMode()

  Get the current lock mode for the query.

  Returns:
    lock mode
  Throws:
    `java.lang.IllegalStateException` - if the query is found not to be a Java Persistence query language SELECT query or a Criteria API query
  Since:
    Java Persistence 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:
    Java Persistence 2.0

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD