## 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

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

Copyright © 2001-2012 Red Hat, Inc. All Rights Reserved.