http://hibernate.org: The core O/RM functionality as provided by Hibernate (Hibernate.org) 
/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * Copyright (c) 2010, Red Hat Inc. or third-party contributors as
 * indicated by the @author tags or express copyright attribution
 * statements applied by the authors.  All third-party contributions are
 * distributed under license by Red Hat Inc.
 *
 * This copyrighted material is made available to anyone wishing to use, modify,
 * copy, or redistribute it subject to the terms and conditions of the GNU
 * Lesser General Public License, as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this distribution; if not, write to:
 * Free Software Foundation, Inc.
 * 51 Franklin Street, Fifth Floor
 * Boston, MA  02110-1301  USA
 */
package org.hibernate;
import java.util.List;

import org.hibernate.engine.query.spi.sql.NativeSQLQueryReturn;
import org.hibernate.type.Type;


Represents a "native sql" query.
Allows the user to define certain aspects about its execution, such as:
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 
    • 
    
  •  Defined locally per the various addEntity, addRoot, addJoin, addFetch and addScalar methods 
    • 



Author:Gavin King, Steve Ebersole
/**
 * 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
 */
public interface SQLQuery extends Query, SynchronizeableQuery {
	@Override
	SQLQuery addSynchronizedQuerySpace(String querySpace);

	@Override
	SQLQuery addSynchronizedEntityName(String entityName) throws MappingException;

	@Override
	SQLQuery addSynchronizedEntityClass(Class entityClass) throws MappingException;

	
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. 
Params:
  • name – The name of the mapping to use.
Returns:this, for method chaining
/**
	 * 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
	 */
	public SQLQuery setResultSetMapping(String name);

	
Is this native-SQL query known to be callable?

Returns:true if the query is known to be callable; false otherwise.
/**
	 * Is this native-SQL query known to be callable?
	 *
	 * @return {@code true} if the query is known to be callable; {@code false} otherwise.
	 */
	public boolean isCallable();

	
Retrieve the returns associated with this query.

Returns:The return descriptors
/**
	 * Retrieve the returns associated with this query.
	 *
	 * @return The return descriptors
	 */
	public List<NativeSQLQueryReturn> getQueryReturns();

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

 Functions like <return-scalar/> in hbm.xml or ColumnResult 
Params:
  • columnAlias – The column alias in the result-set to be processed as a scalar result
Returns:this, for method chaining
/**
	 * 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
	 */
	public SQLQuery addScalar(String columnAlias);

	
Declare a scalar query result.

 Functions like <return-scalar/> in hbm.xml or ColumnResult 
Params:
  • 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
/**
	 * 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
	 */
	public SQLQuery addScalar(String columnAlias, Type type);

	
Add a new root return mapping, returning a RootReturn to allow further definition. 
Params:
  • 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
/**
	 * Add a new root return mapping, returning a {@link 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
	 */
	public RootReturn addRoot(String tableAlias, String entityName);

	
Add a new root return mapping, returning a RootReturn to allow further definition. 
Params:
  • 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
/**
	 * Add a new root return mapping, returning a {@link 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
	 */
	public 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

 Use addRoot if you need further control of the mapping 
Params:
  • entityName – The entity name that is the root return of the query.
Returns:this, for method chaining
/**
	 * 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
	 */
	public SQLQuery addEntity(String entityName);

	
Declare a "root" entity.

Params:
  • tableAlias – The SQL table alias
  • entityName – The entity name
Returns:this, for method chaining
/**
	 * Declare a "root" entity.
	 *
	 * @param tableAlias The SQL table alias
	 * @param entityName The entity name
	 *
	 * @return {@code this}, for method chaining
	 */
	public SQLQuery addEntity(String tableAlias, String entityName);

	
Declare a "root" entity, specifying a lock mode.

Params:
  • tableAlias – The SQL table alias
  • entityName – The entity name
  • lockMode – The lock mode for this return.
Returns:this, for method chaining
/**
	 * 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
	 */
	public SQLQuery 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

Params:
  • entityType – The java type of the entity to add as a root
Returns:this, for method chaining
/**
	 * 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
	 */
	public SQLQuery addEntity(Class entityType);

	
Declare a "root" entity.

Params:
  • tableAlias – The SQL table alias
  • entityType – The java type of the entity to add as a root
Returns:this, for method chaining
/**
	 * 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
	 */
	public SQLQuery addEntity(String tableAlias, Class entityType);

	
Declare a "root" entity, specifying a lock mode.

Params:
  • tableAlias – The SQL table alias
  • entityName – The entity name
  • lockMode – The lock mode for this return.
Returns:this, for method chaining
/**
	 * 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
	 */
	public SQLQuery addEntity(String tableAlias, Class entityName, LockMode lockMode);

	
Declare a join fetch result.

Params:
  • 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
/**
	 * 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
	 */
	public FetchReturn addFetch(String tableAlias, String ownerTableAlias, String joinPropertyName);

	
Declare a join fetch result.

Params:
  • 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
/**
	 * 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
	 */
	public SQLQuery addJoin(String tableAlias, String path);

	
Declare a join fetch result.

Params:
  • 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
/**
	 * 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
	 */
	public SQLQuery addJoin(String tableAlias, String ownerTableAlias, String joinPropertyName);

	
Declare a join fetch result, specifying a lock mode.

Params:
  • 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
/**
	 * 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
	 */
	public SQLQuery 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.

/**
	 * 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.
	 */
	public static interface ReturnProperty {
		
Add a column alias to this property mapping.

Params:
  • columnAlias – The column alias.
Returns:this, for method chaining
/**
		 * Add a column alias to this property mapping.
		 *
		 * @param columnAlias The column alias.
		 *
		 * @return {@code this}, for method chaining
		 */
		public ReturnProperty addColumnAlias(String columnAlias);
	}

	
Allows access to further control how root returns are mapped back from result sets.

/**
	 * Allows access to further control how root returns are mapped back from result sets.
	 */
	public static interface RootReturn {
		
Set the lock mode for this return.

Params:
  • lockMode – The new lock mode.
Returns:this, for method chaining
/**
		 * Set the lock mode for this return.
		 *
		 * @param lockMode The new lock mode.
		 *
		 * @return {@code this}, for method chaining
		 */
		public RootReturn setLockMode(LockMode lockMode);

		
Name the column alias that identifies the entity's discriminator.

Params:
  • columnAlias – The discriminator column alias
Returns:this, for method chaining
/**
		 * Name the column alias that identifies the entity's discriminator.
		 *
		 * @param columnAlias The discriminator column alias
		 *
		 * @return {@code this}, for method chaining
		 */
		public RootReturn setDiscriminatorAlias(String columnAlias);

		
Add a simple property-to-one-column mapping.

Params:
  • propertyName – The name of the property.
  • columnAlias – The name of the column
Returns:this, for method chaining
/**
		 * 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
		 */
		public RootReturn addProperty(String propertyName, String columnAlias);

		
Add a property, presumably with more than one column.

Params:
  • propertyName – The name of the property.
Returns:The config object for further control.
/**
		 * Add a property, presumably with more than one column.
		 *
		 * @param propertyName The name of the property.
		 *
		 * @return The config object for further control.
		 */
		public ReturnProperty addProperty(String propertyName);
	}

	
Allows access to further control how join fetch returns are mapped back from result sets.

/**
	 * Allows access to further control how join fetch returns are mapped back from result sets.
	 */
	public static interface FetchReturn {
		
Set the lock mode for this return.

Params:
  • lockMode – The new lock mode.
Returns:this, for method chaining
/**
		 * Set the lock mode for this return.
		 *
		 * @param lockMode The new lock mode.
		 *
		 * @return {@code this}, for method chaining
		 */
		public FetchReturn setLockMode(LockMode lockMode);

		
Add a simple property-to-one-column mapping.

Params:
  • propertyName – The name of the property.
  • columnAlias – The name of the column
Returns:this, for method chaining
/**
		 * 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
		 */
		public FetchReturn addProperty(String propertyName, String columnAlias);

		
Add a property, presumably with more than one column.

Params:
  • propertyName – The name of the property.
Returns:The config object for further control.
/**
		 * Add a property, presumably with more than one column.
		 *
		 * @param propertyName The name of the property.
		 *
		 * @return The config object for further control.
		 */
		public ReturnProperty addProperty(String propertyName);
	}
}