org.hibernate
Interface SQLQuery

All Superinterfaces:

Query

All Known Implementing Classes:

SQLQueryImpl

public interface SQLQuery
extends Query

Represents a "native sql" query and allows the user to define certain aspects about its execution, such as:

• result-set value mapping (see below)
• Tables used via addSynchronizedQuerySpace(java.lang.String), addSynchronizedEntityName(java.lang.String) and addSynchronizedEntityClass(java.lang.Class). This allows Hibernate to properly know how to deal with auto-flush checking as well as cached query results if the results of the query are being cached.

In terms of result-set mapping, there are 3 approaches to defining:

• If this represents a named sql query, the mapping could be associated with the query as part of its metadata
• A pre-defined (defined in metadata and named) mapping can be associated with setResultSetMapping(java.lang.String)
• Defined locally per the various addEntity(java.lang.String), addRoot(java.lang.String, java.lang.String), addJoin(java.lang.String, java.lang.String), addFetch(java.lang.String, java.lang.String, java.lang.String) and addScalar(java.lang.String) methods

Author:

Gavin King, Steve Ebersole

Nested Class Summary

static interface	SQLQuery.FetchReturn Allows access to further control how join fetch returns are mapped back from result sets
static interface	SQLQuery.ReturnProperty Allows access to further control how properties within a root or join fetch are mapped back from the result set.
static interface	SQLQuery.RootReturn Allows access to further control how root returns are mapped back from result sets

Method Summary

SQLQuery	addEntity(Class entityType) Declare a "root" entity, without specifying an alias.
SQLQuery	addEntity(String entityName) Declare a "root" entity, without specifying an alias.
SQLQuery	addEntity(String tableAlias, Class entityType) Declare a "root" entity
SQLQuery	addEntity(String tableAlias, Class entityName, LockMode lockMode) Declare a "root" entity, specifying a lock mode
SQLQuery	addEntity(String tableAlias, String entityName) Declare a "root" entity
SQLQuery	addEntity(String tableAlias, String entityName, LockMode lockMode) Declare a "root" entity, specifying a lock mode
SQLQuery.FetchReturn	addFetch(String tableAlias, String ownerTableAlias, String joinPropertyName) Declare a join fetch result.
SQLQuery	addJoin(String tableAlias, String path) Declare a join fetch result.
SQLQuery	addJoin(String tableAlias, String path, LockMode lockMode) Declare a join fetch result, specifying a lock mode
SQLQuery	addJoin(String tableAlias, String ownerTableAlias, String joinPropertyName) Declare a join fetch result.
SQLQuery.RootReturn	addRoot(String tableAlias, Class entityType) Add a new root return mapping, returning a SQLQuery.RootReturn to allow further definition
SQLQuery.RootReturn	addRoot(String tableAlias, String entityName) Add a new root return mapping, returning a SQLQuery.RootReturn to allow further definition
SQLQuery	addScalar(String columnAlias) Declare a scalar query result.
SQLQuery	addScalar(String columnAlias, Type type) Declare a scalar query result.
SQLQuery	addSynchronizedEntityClass(Class entityClass) Adds an entity for (a) auto-flush checking and (b) query result cache invalidation checking.
SQLQuery	addSynchronizedEntityName(String entityName) Adds an entity name for (a) auto-flush checking and (b) query result cache invalidation checking.
SQLQuery	addSynchronizedQuerySpace(String querySpace) Adds a query space (table name) for (a) auto-flush checking and (b) query result cache invalidation checking
SQLQuery	setResultSetMapping(String name) Use a predefined named result-set mapping.

Methods inherited from interface org.hibernate.Query

executeUpdate, getNamedParameters, getQueryString, getReturnAliases, getReturnTypes, isReadOnly, iterate, list, scroll, scroll, setBigDecimal, setBigDecimal, setBigInteger, setBigInteger, setBinary, setBinary, setBoolean, setBoolean, setByte, setByte, setCacheable, setCacheMode, setCacheRegion, setCalendar, setCalendar, setCalendarDate, setCalendarDate, setCharacter, setCharacter, setComment, setDate, setDate, setDouble, setDouble, setEntity, setEntity, setFetchSize, setFirstResult, setFloat, setFloat, setFlushMode, setInteger, setInteger, setLocale, setLocale, setLockMode, setLockOptions, setLong, setLong, setMaxResults, setParameter, setParameter, setParameter, setParameter, setParameterList, setParameterList, setParameterList, setParameterList, setParameters, setProperties, setProperties, setReadOnly, setResultTransformer, setSerializable, setSerializable, setShort, setShort, setString, setString, setText, setText, setTime, setTime, setTimeout, setTimestamp, setTimestamp, uniqueResult

Method Detail

addSynchronizedQuerySpace

SQLQuery addSynchronizedQuerySpace(String querySpace)

Adds a query space (table name) for (a) auto-flush checking and (b) query result cache invalidation checking

Parameters:

querySpace - The query space to be auto-flushed for this query.

Returns:

this, for method chaining

addSynchronizedEntityName

SQLQuery addSynchronizedEntityName(String entityName)
                                   throws MappingException

Adds an entity name for (a) auto-flush checking and (b) query result cache invalidation checking. Same as addSynchronizedQuerySpace(java.lang.String) for all tables associated with the given entity.

Parameters:

entityName - The name of the entity upon whose defined query spaces we should additionally synchronize.

Returns:

this, for method chaining

Throws:

MappingException - Indicates the given name could not be resolved as an entity

addSynchronizedEntityClass

SQLQuery addSynchronizedEntityClass(Class entityClass)
                                    throws MappingException

Adds an entity for (a) auto-flush checking and (b) query result cache invalidation checking. Same as addSynchronizedQuerySpace(java.lang.String) for all tables associated with the given entity.

Parameters:

entityClass - The class of the entity upon whose defined query spaces we should additionally synchronize.

Returns:

this, for method chaining

Throws:

MappingException - Indicates the given class could not be resolved as an entity

setResultSetMapping

SQLQuery setResultSetMapping(String name)

Use a predefined named result-set mapping. This might be defined by a <result-set/> element in a Hibernate hbm.xml file or through a SqlResultSetMapping annotation.

Parameters:

name - The name of the mapping to use.

Returns:

this, for method chaining

addScalar

SQLQuery addScalar(String columnAlias)

Declare a scalar query result. Hibernate will attempt to automatically detect the underlying type.

Functions like <return-scalar/> in hbm.xml or ColumnResult

Parameters:

columnAlias - The column alias in the result-set to be processed as a scalar result

Returns:

this, for method chaining

addScalar

SQLQuery addScalar(String columnAlias,
                   Type type)

Declare a scalar query result.

Functions like <return-scalar/> in hbm.xml or ColumnResult

Parameters:

columnAlias - The column alias in the result-set to be processed as a scalar result

type - The Hibernate type as which to treat the value.

Returns:

this, for method chaining

addRoot

SQLQuery.RootReturn addRoot(String tableAlias,
                            String entityName)

Add a new root return mapping, returning a SQLQuery.RootReturn to allow further definition

Parameters:

tableAlias - The SQL table alias to map to this entity

entityName - The name of the entity.

Returns:

The return config object for further control.

Since:

3.6

addRoot

SQLQuery.RootReturn addRoot(String tableAlias,
                            Class entityType)

Add a new root return mapping, returning a SQLQuery.RootReturn to allow further definition

Parameters:

tableAlias - The SQL table alias to map to this entity

entityType - The java type of the entity.

Returns:

The return config object for further control.

Since:

3.6

addEntity

SQLQuery addEntity(String entityName)

Declare a "root" entity, without specifying an alias. The expectation here is that the table alias is the same as the unqualified entity name

Use addRoot(java.lang.String, java.lang.String) if you need further control of the mapping

Parameters:

entityName - The entity name that is the root return of the query.

Returns:

this, for method chaining

addEntity

SQLQuery addEntity(String tableAlias,
                   String entityName)

Declare a "root" entity

Parameters:

tableAlias - The SQL table alias

entityName - The entity name

Returns:

this, for method chaining

addEntity

SQLQuery addEntity(String tableAlias,
                   String entityName,
                   LockMode lockMode)

Declare a "root" entity, specifying a lock mode

Parameters:

tableAlias - The SQL table alias

entityName - The entity name

lockMode - The lock mode for this return.

Returns:

this, for method chaining

addEntity

SQLQuery addEntity(Class entityType)

Declare a "root" entity, without specifying an alias. The expectation here is that the table alias is the same as the unqualified entity name

Parameters:

entityType - The java type of the entity to add as a root

Returns:

this, for method chaining

addEntity

SQLQuery addEntity(String tableAlias,
                   Class entityType)

Declare a "root" entity

Parameters:

tableAlias - The SQL table alias

entityType - The java type of the entity to add as a root

Returns:

this, for method chaining

addEntity

SQLQuery addEntity(String tableAlias,
                   Class entityName,
                   LockMode lockMode)

Declare a "root" entity, specifying a lock mode

Parameters:

tableAlias - The SQL table alias

entityName - The entity name

lockMode - The lock mode for this return.

Returns:

this, for method chaining

addFetch

SQLQuery.FetchReturn addFetch(String tableAlias,
                              String ownerTableAlias,
                              String joinPropertyName)

Declare a join fetch result.

Parameters:

tableAlias - The SQL table alias for the data to be mapped to this fetch

ownerTableAlias - Identify the table alias of the owner of this association. Should match the alias of a previously added root or fetch

joinPropertyName - The name of the property being join fetched.

Returns:

The return config object for further control.

Since:

3.6

addJoin

SQLQuery addJoin(String tableAlias,
                 String path)

Declare a join fetch result.

Parameters:

tableAlias - The SQL table alias for the data to be mapped to this fetch

path - The association path ([owner-alias].[property-name]).

Returns:

this, for method chaining

addJoin

SQLQuery addJoin(String tableAlias,
                 String ownerTableAlias,
                 String joinPropertyName)

Declare a join fetch result.

Parameters:

tableAlias - The SQL table alias for the data to be mapped to this fetch

ownerTableAlias - Identify the table alias of the owner of this association. Should match the alias of a previously added root or fetch

joinPropertyName - The name of the property being join fetched.

Returns:

this, for method chaining

Since:

3.6

addJoin

SQLQuery addJoin(String tableAlias,
                 String path,
                 LockMode lockMode)

Declare a join fetch result, specifying a lock mode

Parameters:

tableAlias - The SQL table alias for the data to be mapped to this fetch

path - The association path ([owner-alias].[property-name]).

lockMode - The lock mode for this return.

Returns:

this, for method chaining