Package org.hibernate.query

Interface QueryProducer

All Known Subinterfaces:

EventSource, QueryProducerImplementor, Session, SessionImplementor, SharedSessionContract, SharedSessionContractImplementor, StatelessSession

All Known Implementing Classes:

AbstractSharedSessionContract, SessionDelegatorBaseImpl, SessionImpl, SessionLazyDelegator, SharedSessionDelegatorBaseImpl, StatelessSessionImpl

public interface QueryProducer

Contract for things that can produce instances of Query and NativeQuery. Implementors include Session and StatelessSession. Many operations of the interface have the same or very similar signatures to operations of EntityManager. They are declared here to allow reuse by StatelessSession.

Unlike the corresponding operations of EntityManager, operations for creating untyped instances of Query are all marked as deprecated. Clients must migrate to the use of the equivalent operations which accept a Class and return a typed Query.

Method Summary

Modifier and Type	Method	Description
MutationQuery	createMutationQuery(CriteriaDelete deleteQuery)	Create a MutationQuery from the given delete criteria tree
MutationQuery	createMutationQuery(CriteriaUpdate updateQuery)	Create a MutationQuery from the given update criteria tree
MutationQuery	createMutationQuery(String hqlString)	Create a MutationQuery reference for the given HQL insert, update, or delete statement.
MutationQuery	createMutationQuery(JpaCriteriaInsert insertSelect)	Create a MutationQuery from the given insert criteria tree
MutationQuery	createMutationQuery(JpaCriteriaInsertSelect insertSelect)	Create a MutationQuery from the given insert-select criteria tree
MutationQuery	createNamedMutationQuery(String name)	Create a MutationQuery instance for the given named insert, update, or delete HQL query.
Query	createNamedQuery(String name)	Deprecated. use createNamedQuery(String, Class)
<R> Query<R>	createNamedQuery(String name, Class<R> resultClass)	Create a typed Query instance for the given named query.
SelectionQuery<?>	createNamedSelectionQuery(String name)	Deprecated. use createNamedSelectionQuery(String, Class)
<R> SelectionQuery<R>	createNamedSelectionQuery(String name, Class<R> resultType)	Create a SelectionQuery instance for the named NamedQuery with the given result type.
MutationQuery	createNativeMutationQuery(String sqlString)	Create a NativeQuery instance for the given native SQL statement.
NativeQuery	createNativeQuery(String sqlString)	Deprecated. use createNativeQuery(String, Class)
<R> NativeQuery<R>	createNativeQuery(String sqlString, Class<R> resultClass)	Create a NativeQuery instance for the given native SQL query using an implicit mapping to the specified Java type.
<R> NativeQuery<R>	createNativeQuery(String sqlString, Class<R> resultClass, String tableAlias)	Create a NativeQuery instance for the given native SQL query using an implicit mapping to the specified Java entity type.
NativeQuery	createNativeQuery(String sqlString, String resultSetMappingName)	Deprecated. use createNativeQuery(String, String, Class)
<R> NativeQuery<R>	createNativeQuery(String sqlString, String resultSetMappingName, Class<R> resultClass)	Create a NativeQuery instance for the given native SQL query using an explicit mapping to the specified Java type.
Query	createQuery(CriteriaDelete deleteQuery)	Deprecated. use createMutationQuery(CriteriaDelete)
<R> Query<R>	createQuery(CriteriaQuery<R> criteriaQuery)	Create a Query for the given JPA CriteriaQuery.
Query	createQuery(CriteriaUpdate updateQuery)	Deprecated. use createMutationQuery(CriteriaUpdate)
<R> Query<R>	createQuery(TypedQueryReference<R> typedQueryReference)	Create a typed Query instance for the given typed query reference.
Query	createQuery(String queryString)	Deprecated. use createQuery(String, Class), createSelectionQuery(String, Class), or createMutationQuery(String) depending on intention
<R> Query<R>	createQuery(String queryString, Class<R> resultClass)	Create a typed Query instance for the given HQL query string and given query result type.
<R> SelectionQuery<R>	createSelectionQuery(CriteriaQuery<R> criteria)	Create a SelectionQuery reference for the given CriteriaQuery.
SelectionQuery<?>	createSelectionQuery(String hqlString)	Deprecated. Use createSelectionQuery(String, Class)
<R> SelectionQuery<R>	createSelectionQuery(String hqlString, Class<R> resultType)	Create a SelectionQuery instance for the given HQL query string and given query result type.
NativeQuery	getNamedNativeQuery(String name)	Deprecated. use createNamedQuery(String, Class)
NativeQuery	getNamedNativeQuery(String name, String resultSetMapping)	Deprecated. use createNamedQuery(String, Class)
Query	getNamedQuery(String queryName)	Deprecated. use createNamedQuery(String, Class)

Method Details

createQuery

@Deprecated(since="6.0")
Query createQuery(String queryString)

Deprecated.

use createQuery(String, Class), createSelectionQuery(String, Class), or createMutationQuery(String) depending on intention

Create a Query instance for the given HQL query, or HQL insert, update, or delete statement.

If a query has no explicit select list, the select list is inferred:

• if there is exactly one root entity in the from clause, then that root entity is the only element of the select list, or
• otherwise, if there are multiple root entities in the from clause, then the select list contains every root entity and every non-fetch joined entity.

Parameters:

queryString - The HQL query

Returns:

The Query instance for manipulation and execution

See Also:

• EntityManager.createQuery(String)

API Note:

Returns a raw Query type instead of a wildcard type Query<?>, to match the signature of the JPA method EntityManager.createQuery(String).

Implementation Note:

This method interprets some queries with an implicit select list in a quite unintuitive way. In some future release, this method will be modified to throw an exception when passed a query with a missing select. For now, use createQuery(String, Class) to avoid ambiguity.

createQuery

<R> Query<R> createQuery(String queryString,
 Class<R> resultClass)

Create a typed Query instance for the given HQL query string and given query result type.

• If the query has a single item in the select list, then the select item must be assignable to the given result type.
• Otherwise, if there are multiple select items, then the select items will be packaged into an instance of the result type. The result type must have an appropriate constructor with parameter types matching the select items, or it must be one of the types Object[], List, Map, or Tuple.

If a query has no explicit select list, the select list is inferred from the given query result type:

• if the result type is an entity type, the query must have exactly one root entity in the from clause, it must be assignable to the result type, and the inferred select list will contain just that entity, or
• otherwise, the select list contains every root entity and every non-fetch joined entity, and each query result will be packaged into an instance of the result type, just as specified above.

The returned Query may be executed by calling Query.getResultList() or Query.getSingleResult().

Parameters:

queryString - The HQL query

resultClass - The type of the query result

Returns:

The Query instance for manipulation and execution

See Also:

• EntityManager.createQuery(String,Class)

createQuery

<R> Query<R> createQuery(TypedQueryReference<R> typedQueryReference)

Create a typed Query instance for the given typed query reference.

Parameters:

typedQueryReference - the type query reference

Returns:

The Query instance for execution

Throws:

IllegalArgumentException - if a query has not been defined with the name of the typed query reference or if the query result is found to not be assignable to result class of the typed query reference

See Also:

• EntityManager.createQuery(TypedQueryReference)

createQuery

<R> Query<R> createQuery(CriteriaQuery<R> criteriaQuery)

Create a Query for the given JPA CriteriaQuery.

createQuery

@Deprecated(since="6.0")
Query createQuery(CriteriaUpdate updateQuery)

Deprecated.

use createMutationQuery(CriteriaUpdate)

Create a MutationQuery for the given JPA CriteriaUpdate

createQuery

@Deprecated(since="6.0")
Query createQuery(CriteriaDelete deleteQuery)

Deprecated.

use createMutationQuery(CriteriaDelete)

Create a MutationQuery for the given JPA CriteriaDelete

createNativeQuery

@Deprecated(since="6.0")
NativeQuery createNativeQuery(String sqlString)

Deprecated.

use createNativeQuery(String, Class)

Create a NativeQuery instance for the given native SQL query.

Parameters:

sqlString - a native SQL query string

Returns:

The NativeQuery instance for manipulation and execution

See Also:

• EntityManager.createNativeQuery(String)

createNativeQuery

<R> NativeQuery<R> createNativeQuery(String sqlString,
 Class<R> resultClass)

Create a NativeQuery instance for the given native SQL query using an implicit mapping to the specified Java type.

• If the given class is an entity class, this method is equivalent to createNativeQuery(sqlString).addEntity(resultClass).
• If the given class has a registered JavaType, then the query must return a result set with a single column whose JdbcType is compatible with that JavaType.
• Otherwise, the select items will be packaged into an instance of the result type. The result type must have an appropriate constructor with parameter types matching the select items, or it must be one of the types Object[], List, Map, or Tuple.

Parameters:

sqlString - The native (SQL) query string

resultClass - The Java type to map results to

Returns:

The NativeQuery instance for manipulation and execution

See Also:

• EntityManager.createNativeQuery(String,Class)

API Note:

Changes in JPA 3.2 required de-typing this to be compilable with their changes

createNativeQuery

<R> NativeQuery<R> createNativeQuery(String sqlString,
 Class<R> resultClass,
 String tableAlias)

Create a NativeQuery instance for the given native SQL query using an implicit mapping to the specified Java entity type.

The given class must be an entity class. This method is equivalent to createNativeQuery(sqlString).addEntity(tableAlias, resultClass).

Parameters:

sqlString - Native (SQL) query string

resultClass - The Java entity class to map results to

tableAlias - The table alias for columns in the result set

Returns:

The NativeQuery instance for manipulation and execution

See Also:

• EntityManager.createNativeQuery(String,Class)

createNativeQuery

@Deprecated(since="6.0")
NativeQuery createNativeQuery(String sqlString,
 String resultSetMappingName)

Deprecated.

use createNativeQuery(String, String, Class)

Create a NativeQuery instance for the given native SQL query using an explicit mapping to the specified Java type.

The given result set mapping name must identify a mapping defined by a SqlResultSetMapping annotation.

Parameters:

sqlString - The native (SQL) query string

resultSetMappingName - The explicit result mapping name

Returns:

The NativeQuery instance for manipulation and execution

See Also:

• EntityManager.createNativeQuery(String,Class)
• SqlResultSetMapping

createNativeQuery

<R> NativeQuery<R> createNativeQuery(String sqlString,
 String resultSetMappingName,
 Class<R> resultClass)

Create a NativeQuery instance for the given native SQL query using an explicit mapping to the specified Java type.

The given result set mapping name must identify a mapping defined by a SqlResultSetMapping annotation.

Parameters:

sqlString - The native (SQL) query string

resultSetMappingName - The explicit result mapping name

Returns:

The NativeQuery instance for manipulation and execution

See Also:

• EntityManager.createNativeQuery(String,Class)
• SqlResultSetMapping

createSelectionQuery

@Deprecated(since="6.3")
SelectionQuery<?> createSelectionQuery(String hqlString)

Deprecated.

Use createSelectionQuery(String, Class)

Create a SelectionQuery reference for the given HQL select statement.

If the statement has no explicit select list, the select list is inferred:

• if there is exactly one root entity in the from clause, then that root entity is the only element of the select list, or
• otherwise, if there are multiple root entities in the from clause, then the select list contains every root entity and every non-fetch joined entity.

Throws:

IllegalSelectQueryException - if the given HQL query is an insert, update or delete query

Implementation Note:

This method interprets some queries with an implicit select list in a quite unintuitive way. In some future release, this method will be modified to throw an exception when passed a query with a missing select. For now, use createSelectionQuery(String, Class) to avoid ambiguity.

createSelectionQuery

<R> SelectionQuery<R> createSelectionQuery(String hqlString,
 Class<R> resultType)

Create a SelectionQuery instance for the given HQL query string and given query result type.

• If the query has a single item in the select list, then the select item must be assignable to the given result type.
• Otherwise, if there are multiple select items, then the select items will be packaged into an instance of the result type. The result type must have an appropriate constructor with parameter types matching the select items, or it must be one of the types Object[], List, Map, or Tuple.

If a query has no explicit select list, the select list is inferred from the given query result type:

• if the result type is an entity type, the query must have exactly one root entity in the from clause, it must be assignable to the result type, and the inferred select list will contain just that entity, or
• otherwise, the select list contains every root entity and every non-fetch joined entity, and each query result will be packaged into an instance of the result type, just as specified above.

The returned Query may be executed by calling Query.getResultList() or Query.getSingleResult().

Parameters:

hqlString - The HQL query as a string

resultType - The Class object representing the query result type

Throws:

IllegalSelectQueryException - if the given HQL query is an insert, update or delete query

See Also:

• EntityManager.createQuery(String)

createSelectionQuery

<R> SelectionQuery<R> createSelectionQuery(CriteriaQuery<R> criteria)

Create a SelectionQuery reference for the given CriteriaQuery.

See Also:

• EntityManager.createQuery(CriteriaQuery)

createMutationQuery

MutationQuery createMutationQuery(String hqlString)

Create a MutationQuery reference for the given HQL insert, update, or delete statement.

Throws:

IllegalMutationQueryException - if the given HQL query is a select query

createMutationQuery

MutationQuery createMutationQuery(CriteriaUpdate updateQuery)

Create a MutationQuery from the given update criteria tree

createMutationQuery

MutationQuery createMutationQuery(CriteriaDelete deleteQuery)

Create a MutationQuery from the given delete criteria tree

createMutationQuery

MutationQuery createMutationQuery(JpaCriteriaInsertSelect insertSelect)

Create a MutationQuery from the given insert-select criteria tree

createMutationQuery

MutationQuery createMutationQuery(JpaCriteriaInsert insertSelect)

Create a MutationQuery from the given insert criteria tree

createNativeMutationQuery

MutationQuery createNativeMutationQuery(String sqlString)

Create a NativeQuery instance for the given native SQL statement.

Parameters:

sqlString - a native SQL statement string

Returns:

The NativeQuery instance for manipulation and execution

createNamedQuery

@Deprecated(since="6.0")
Query createNamedQuery(String name)

Deprecated.

use createNamedQuery(String, Class)

Create a typed Query instance for the given named query. The named query might be defined in HQL or in native SQL.

Parameters:

name - the name of a predefined named query

Returns:

The Query instance for manipulation and execution

Throws:

IllegalArgumentException - if a query has not been defined with the given name or if the query string is found to be invalid

See Also:

• EntityManager.createNamedQuery(String)

createNamedQuery

<R> Query<R> createNamedQuery(String name,
 Class<R> resultClass)

Create a typed Query instance for the given named query. The named query might be defined in HQL or in native SQL.

Parameters:

name - the name of a query defined in metadata

resultClass - the type of the query result

Returns:

The Query instance for manipulation and execution

Throws:

IllegalArgumentException - if a query has not been defined with the given name or if the query string is found to be invalid or if the query result is found to not be assignable to the specified type

See Also:

• EntityManager.createNamedQuery(String,Class)

createNamedSelectionQuery

@Deprecated(since="6.3")
SelectionQuery<?> createNamedSelectionQuery(String name)

Deprecated.

use createNamedSelectionQuery(String, Class)

Create a SelectionQuery instance for the named NamedQuery.

Throws:

IllegalSelectQueryException - if the given HQL query is not a select query

UnknownNamedQueryException - if no query has been defined with the given name

Implementation Note:

This method interprets some queries with an implicit select list in a quite unintuitive way. In some future release, this method will be modified to throw an exception when passed a query with a missing select. For now, use createNamedSelectionQuery(String, Class) to avoid ambiguity.

createNamedSelectionQuery

<R> SelectionQuery<R> createNamedSelectionQuery(String name,
 Class<R> resultType)

Create a SelectionQuery instance for the named NamedQuery with the given result type.

Throws:

IllegalSelectQueryException - if the given HQL query is not a select query

UnknownNamedQueryException - if no query has been defined with the given name

createNamedMutationQuery

MutationQuery createNamedMutationQuery(String name)

Create a MutationQuery instance for the given named insert, update, or delete HQL query. The named query might be defined as HQL) or native-SQL.

Throws:

IllegalMutationQueryException - if the given HQL query is a select query

UnknownNamedQueryException - if no query has been defined with the given name

getNamedQuery

@Deprecated(since="6.0")
Query getNamedQuery(String queryName)

Deprecated.

use createNamedQuery(String, Class)

Create a Query instance for the named query.

Parameters:

queryName - the name of a predefined named query

Returns:

The Query instance for manipulation and execution

Throws:

IllegalArgumentException - if a query has not been defined with the given name or if the query string is found to be invalid

getNamedNativeQuery

@Deprecated(since="6.0")
NativeQuery getNamedNativeQuery(String name)

Deprecated.

use createNamedQuery(String, Class)

Get a NativeQuery instance for a named native SQL query

Parameters:

name - The name of the predefined query

Returns:

The NativeQuery instance for manipulation and execution

getNamedNativeQuery

@Deprecated(since="6.0")
NativeQuery getNamedNativeQuery(String name,
 String resultSetMapping)

Deprecated.

use createNamedQuery(String, Class)

Get a NativeQuery instance for a named native SQL query

Parameters:

name - The name of the predefined query

Returns:

The NativeQuery instance for manipulation and execution