Java tutorial
/* * Hibernate, Relational Persistence for Idiomatic Java * * License: GNU Lesser General Public License (LGPL), version 2.1 or later. * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>. */ package org.hibernate; import java.util.Calendar; import java.util.Collection; import java.util.Date; import java.util.List; import java.util.Map; import javax.persistence.FlushModeType; import javax.persistence.Parameter; import javax.persistence.TemporalType; import org.hibernate.engine.query.spi.sql.NativeSQLQueryReturn; import org.hibernate.query.NativeQuery; import org.hibernate.query.QueryParameter; import org.hibernate.type.Type; /** * Represents a "native sql" query. * * Allows the user to define certain aspects about its execution, such as:<ul> * <li> * result-set value mapping (see below) * </li> * <li> * Tables used via {@link #addSynchronizedQuerySpace}, {@link #addSynchronizedEntityName} and * {@link #addSynchronizedEntityClass}. 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. * </li> * </ul> * * In terms of result-set mapping, there are 3 approaches to defining:<ul> * <li> * If this represents a named sql query, the mapping could be associated with the query as part * of its metadata * </li> * <li> * A pre-defined (defined in metadata and named) mapping can be associated with * {@link #setResultSetMapping} * </li> * <li> * Defined locally per the various {@link #addEntity}, {@link #addRoot}, {@link #addJoin}, * {@link #addFetch} and {@link #addScalar} methods * </li> * </ul> * * @author Gavin King * @author Steve Ebersole * * @deprecated (since 5.2) use {@link NativeQuery} instead. */ @Deprecated public interface SQLQuery<T> extends Query<T>, SynchronizeableQuery<T> { /** * Use a predefined named result-set mapping. This might be defined by a {@code <result-set/>} element in a * Hibernate <tt>hbm.xml</tt> file or through a {@link javax.persistence.SqlResultSetMapping} annotation. * * @param name The name of the mapping to use. * * @return this, for method chaining */ SQLQuery<T> setResultSetMapping(String name); /** * Is this native-SQL query known to be callable? * * @return {@code true} if the query is known to be callable; {@code false} otherwise. */ boolean isCallable(); /** * Retrieve the returns associated with this query. * * @return The return descriptors */ List<NativeSQLQueryReturn> getQueryReturns(); /** * Declare a scalar query result. Hibernate will attempt to automatically detect the underlying type. * <p/> * Functions like {@code <return-scalar/>} in {@code hbm.xml} or {@link javax.persistence.ColumnResult} * * @param columnAlias The column alias in the result-set to be processed as a scalar result * * @return {@code this}, for method chaining */ SQLQuery<T> addScalar(String columnAlias); /** * Declare a scalar query result. * <p/> * Functions like {@code <return-scalar/>} in {@code hbm.xml} or {@link javax.persistence.ColumnResult} * * @param columnAlias The column alias in the result-set to be processed as a scalar result * @param type The Hibernate type as which to treat the value. * * @return {@code this}, for method chaining */ SQLQuery<T> addScalar(String columnAlias, Type type); /** * Add a new root return mapping, returning a {@link NativeQuery.RootReturn} to allow further definition. * * @param tableAlias The SQL table alias to map to this entity * @param entityName The name of the entity. * * @return The return config object for further control. * * @since 3.6 */ RootReturn addRoot(String tableAlias, String entityName); /** * Add a new root return mapping, returning a {@link NativeQuery.RootReturn} to allow further definition. * * @param tableAlias The SQL table alias to map to this entity * @param entityType The java type of the entity. * * @return The return config object for further control. * * @since 3.6 */ RootReturn addRoot(String tableAlias, 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 * <p/> * Use {@link #addRoot} if you need further control of the mapping * * @param entityName The entity name that is the root return of the query. * * @return {@code this}, for method chaining */ SQLQuery<T> addEntity(String entityName); /** * Declare a "root" entity. * * @param tableAlias The SQL table alias * @param entityName The entity name * * @return {@code this}, for method chaining */ SQLQuery<T> addEntity(String tableAlias, String entityName); /** * Declare a "root" entity, specifying a lock mode. * * @param tableAlias The SQL table alias * @param entityName The entity name * @param lockMode The lock mode for this return. * * @return {@code this}, for method chaining */ SQLQuery<T> addEntity(String tableAlias, String entityName, LockMode lockMode); /** * Declare a "root" entity, without specifying an alias. The expectation here is that the table alias is the * same as the unqualified entity name * * @param entityType The java type of the entity to add as a root * * @return {@code this}, for method chaining */ SQLQuery<T> addEntity(Class entityType); /** * Declare a "root" entity. * * @param tableAlias The SQL table alias * @param entityType The java type of the entity to add as a root * * @return {@code this}, for method chaining */ SQLQuery<T> addEntity(String tableAlias, Class entityType); /** * Declare a "root" entity, specifying a lock mode. * * @param tableAlias The SQL table alias * @param entityClass The entity Class * @param lockMode The lock mode for this return. * * @return {@code this}, for method chaining */ SQLQuery<T> addEntity(String tableAlias, Class entityClass, LockMode lockMode); /** * Declare a join fetch result. * * @param tableAlias The SQL table alias for the data to be mapped to this fetch * @param ownerTableAlias Identify the table alias of the owner of this association. Should match the alias of a * previously added root or fetch * @param joinPropertyName The name of the property being join fetched. * * @return The return config object for further control. * * @since 3.6 */ FetchReturn addFetch(String tableAlias, String ownerTableAlias, String joinPropertyName); /** * Declare a join fetch result. * * @param tableAlias The SQL table alias for the data to be mapped to this fetch * @param path The association path ([owner-alias].[property-name]). * * @return {@code this}, for method chaining */ SQLQuery<T> addJoin(String tableAlias, String path); /** * Declare a join fetch result. * * @param tableAlias The SQL table alias for the data to be mapped to this fetch * @param ownerTableAlias Identify the table alias of the owner of this association. Should match the alias of a * previously added root or fetch * @param joinPropertyName The name of the property being join fetched. * * @return {@code this}, for method chaining * * @since 3.6 */ SQLQuery<T> addJoin(String tableAlias, String ownerTableAlias, String joinPropertyName); /** * Declare a join fetch result, specifying a lock mode. * * @param tableAlias The SQL table alias for the data to be mapped to this fetch * @param path The association path ([owner-alias].[property-name]). * @param lockMode The lock mode for this return. * * @return {@code this}, for method chaining */ SQLQuery<T> addJoin(String tableAlias, String path, LockMode lockMode); /** * Allows access to further control how properties within a root or join fetch are mapped back from the result set. * Generally used in composite value scenarios. */ interface ReturnProperty { /** * Add a column alias to this property mapping. * * @param columnAlias The column alias. * * @return {@code this}, for method chaining */ ReturnProperty addColumnAlias(String columnAlias); } /** * Allows access to further control how root returns are mapped back from result sets. */ interface RootReturn { /** * Set the lock mode for this return. * * @param lockMode The new lock mode. * * @return {@code this}, for method chaining */ RootReturn setLockMode(LockMode lockMode); /** * Name the column alias that identifies the entity's discriminator. * * @param columnAlias The discriminator column alias * * @return {@code this}, for method chaining */ RootReturn setDiscriminatorAlias(String columnAlias); /** * Add a simple property-to-one-column mapping. * * @param propertyName The name of the property. * @param columnAlias The name of the column * * @return {@code this}, for method chaining */ RootReturn addProperty(String propertyName, String columnAlias); /** * Add a property, presumably with more than one column. * * @param propertyName The name of the property. * * @return The config object for further control. */ ReturnProperty addProperty(String propertyName); } /** * Allows access to further control how join fetch returns are mapped back from result sets. */ interface FetchReturn { /** * Set the lock mode for this return. * * @param lockMode The new lock mode. * * @return {@code this}, for method chaining */ FetchReturn setLockMode(LockMode lockMode); /** * Add a simple property-to-one-column mapping. * * @param propertyName The name of the property. * @param columnAlias The name of the column * * @return {@code this}, for method chaining */ FetchReturn addProperty(String propertyName, String columnAlias); /** * Add a property, presumably with more than one column. * * @param propertyName The name of the property. * * @return The config object for further control. */ ReturnProperty addProperty(String propertyName); } // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ // overrides @Override SQLQuery<T> addSynchronizedQuerySpace(String querySpace); @Override SQLQuery<T> addSynchronizedEntityName(String entityName) throws MappingException; @Override SQLQuery<T> addSynchronizedEntityClass(Class entityClass) throws MappingException; @Override NativeQuery<T> setHibernateFlushMode(FlushMode flushMode); @Override NativeQuery<T> setFlushMode(FlushModeType flushMode); @Override NativeQuery<T> setCacheMode(CacheMode cacheMode); @Override NativeQuery<T> setCacheable(boolean cacheable); @Override NativeQuery<T> setCacheRegion(String cacheRegion); @Override NativeQuery<T> setTimeout(int timeout); @Override NativeQuery<T> setFetchSize(int fetchSize); @Override NativeQuery<T> setReadOnly(boolean readOnly); @Override NativeQuery<T> setLockOptions(LockOptions lockOptions); @Override NativeQuery<T> setLockMode(String alias, LockMode lockMode); @Override NativeQuery<T> setComment(String comment); @Override NativeQuery<T> addQueryHint(String hint); @Override <P> NativeQuery<T> setParameter(QueryParameter<P> parameter, P val); @Override <P> NativeQuery<T> setParameter(Parameter<P> param, P value); @Override NativeQuery<T> setParameter(String name, Object val); @Override NativeQuery<T> setParameter(int position, Object val); @Override <P> NativeQuery<T> setParameter(QueryParameter<P> parameter, P val, Type type); @Override NativeQuery<T> setParameter(String name, Object val, Type type); @Override NativeQuery<T> setParameter(int position, Object val, Type type); @Override <P> NativeQuery<T> setParameter(QueryParameter<P> parameter, P val, TemporalType temporalType); @Override <P> NativeQuery<T> setParameter(String name, P val, TemporalType temporalType); @Override <P> NativeQuery<T> setParameter(int position, P val, TemporalType temporalType); @Override <P> NativeQuery<T> setParameterList(QueryParameter<P> parameter, Collection<P> values); @Override NativeQuery<T> setParameterList(String name, Collection values); @Override NativeQuery<T> setParameterList(String name, Collection values, Type type); @Override NativeQuery<T> setParameterList(String name, Object[] values, Type type); @Override NativeQuery<T> setParameterList(String name, Object[] values); @Override NativeQuery<T> setProperties(Object bean); @Override NativeQuery<T> setProperties(Map bean); @Override NativeQuery<T> setParameter(Parameter<Calendar> param, Calendar value, TemporalType temporalType); @Override NativeQuery<T> setParameter(Parameter<Date> param, Date value, TemporalType temporalType); @Override NativeQuery<T> setParameter(String name, Calendar value, TemporalType temporalType); @Override NativeQuery<T> setParameter(String name, Date value, TemporalType temporalType); @Override NativeQuery<T> setParameter(int position, Calendar value, TemporalType temporalType); @Override NativeQuery<T> setParameter(int position, Date value, TemporalType temporalType); @Override NativeQuery<T> setFlushMode(FlushMode flushMode); }