org.hibernate

Interface SQLQuery

All Superinterfaces:

BasicQueryContract, Query, SynchronizeableQuery

All Known Implementing Classes:

SQLQueryImpl

public interface SQLQuery
extends Query, SynchronizeableQuery

Represents a "native sql" query. 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 know how to properly 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

Nested Classes

Modifier and Type	Interface and Description
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

Modifier and Type	Method and Description
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.
List<NativeSQLQueryReturn>	getQueryReturns() Retrieve the returns associated with this query.
boolean	isCallable() Is this native-SQL query known to be callable?
SQLQuery	setResultSetMapping(String name) Use a predefined named result-set mapping.

Methods inherited from interface org.hibernate.Query

addQueryHint, executeUpdate, getComment, getFirstResult, getLockOptions, getMaxResults, getNamedParameters, getQueryString, getReturnAliases, 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

Methods inherited from interface org.hibernate.BasicQueryContract

getCacheMode, getCacheRegion, getFetchSize, getFlushMode, getReturnTypes, getTimeout, isCacheable, isReadOnly

Methods inherited from interface org.hibernate.SynchronizeableQuery

getSynchronizedQuerySpaces

Method Detail

addSynchronizedQuerySpace

SQLQuery addSynchronizedQuerySpace(String querySpace)

Description copied from interface: SynchronizeableQuery

Adds a query space.

Specified by:

addSynchronizedQuerySpace in interface SynchronizeableQuery

Parameters:

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

Returns:

this, for method chaining

addSynchronizedEntityName

SQLQuery addSynchronizedEntityName(String entityName)
                            throws MappingException

Description copied from interface: SynchronizeableQuery

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

Specified by:

addSynchronizedEntityName in interface SynchronizeableQuery

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

Description copied from interface: SynchronizeableQuery

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

Specified by:

addSynchronizedEntityClass in interface SynchronizeableQuery

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

isCallable

boolean isCallable()

Is this native-SQL query known to be callable?

Returns:

true if the query is known to be callable; false otherwise.

getQueryReturns

List<NativeSQLQueryReturn> getQueryReturns()

Retrieve the returns associated with this query.

Returns:

The return descriptors

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