2 实体操作
2.6 Q UERY API
2.6.1 Query 接口
package javax.persistence;
import java.util.Calendar;
import java.util.Date;
import java.util.List;
/**
* Interface used to control query execution.
*/
public interface Query { /**
* Execute a SELECT query and return the query results * as a List.
* @return a list of the results
* @throws IllegalStateException if called for a Java
*Persistence query language UPDATE or DELETE statement */
public List getResultList();
/**
* Execute a SELECT query that returns a single result.
* @return the result
* @throws NoResultException if there is no result
* @throws NonUniqueResultException if more than one result * @throws IllegalStateException if called for a Java
*Persistence query language UPDATE or DELETE statement */
public Object getSingleResult();
/**
* Execute an update or delete statement.
* @return the number of entities updated or deleted * @throws IllegalStateException if called for a Java *Persistence query language SELECT statement * @throws TransactionRequiredException if there is * no transaction
*/
public int executeUpdate();
/**
* Set the maximum number of results to retrieve.
* @param maxResult
* @return the same query instance
* @throws IllegalArgumentException if argument is negative */
public Query setMaxResults(int maxResult);
/**
* Set the position of the first result to retrieve.
* @param start position of the first result, numbered from 0 * @return the same query instance
* @throws IllegalArgumentException if argument is negative */
public Query setFirstResult(int startPosition);
/**
* Set an implementation-specific hint.
* If the hint name is not recognized, it is silently ignored.
* @param hintName * @param value
* @return the same query instance
*@throwsIllegalArgumentExceptionifthesecondargumentisnot *valid for the implementation
*/
public Query setHint(String hintName, Object value);
/**
* Bind an argument to a named parameter.
* @param name the parameter name * @param value
* @return the same query instance
* @throws IllegalArgumentException if parameter name does not *correspond to parameter in query string
*or argument is of incorrect type */
public Query setParameter(String name, Object value);
/**
* Bind an instance of java.util.Date to a named parameter.
* @param name * @param value
* @param temporalType
* @return the same query instance
* @throws IllegalArgumentException if parameter name does not *correspond to parameter in query string
*/
public Query setParameter(String name, Date value, TemporalType
temporalType);
/**
* Bind an instance of java.util.Calendar to a named parameter.
* @param name * @param value
* @param temporalType
* @return the same query instance
* @throws IllegalArgumentException if parameter name does not *correspond to parameter in query string
*/
public Query setParameter(String name, Calendar value, Temporal- Type temporalType);
/**
* Bind an argument to a positional parameter.
* @param position * @param value
* @return the same query instance
* @throws IllegalArgumentException if position does not *correspond to positional parameter of query
*or argument is of incorrect type */
public Query setParameter(int position, Object value);
/**
* Bind an instance of java.util.Date to a positional parameter.
* @param position * @param value
* @param temporalType
* @return the same query instance
* @throws IllegalArgumentException if position does not *correspond to positional parameter of query
*/
publicQuerysetParameter(intposition,Datevalue,TemporalType temporalType);
/**
* Bind an instance of java.util.Calendar to a positional param- eter.
* @param position * @param value
* @param temporalType
* @return the same query instance
* @throws IllegalArgumentException if position does not *correspond to positional parameter of query
*/
publicQuerysetParameter(intposition,Calendarvalue,Temporal- Type temporalType);
/**
* Set the flush mode type to be used for the query execution.
* The flush mode type applies to the query regardless of the * flush mode type in use for the entity manager.
* @param flushMode */
public Query setFlushMode(FlushModeType flushMode);
}
一个由多个 select 表达式组成 SELECT 语句的查询的结果是 Object[]。如果
SELECT 语句只有一个 select 表达式，查询结果是 Object。当使用本地 SQL 查询 时，SQL 查询结果集映射（看 2.6.6 章节）决定了返回多少项（实体，标量值等）。
如果返回多个项，查询结果是 Object[]。如果只返回一项或指定了结果的类，则 查询结果是 Object。
如果参数的名称和查询语句内的命名参数不一致，或者如果指定的位置值和 查 询 语 句 内 的 位 置 参 数 不 一 致 ， 或 者 参 数 的 类 型 不 匹 配 ， 则 抛 出 IllegalArgumentException。可以在参数绑定的时候抛出异常，或者执行查询失败。
在涉及多个表连接的查询上使用 setMaxResults 或 setFirstResult 的影响没有 定义。
除了 executeUpdate 方法外的查询方法不要求在一个事务上下文中调用。尤 其 getResultList 和 getSingleReslut 方法不要求在一个事务上下文中调用。如果使 用带事务范围持久化上下文的实体管理器，则查询的结果实体是托管的；如果使 用带扩展持久化上下文的实体管理器，则查询结果实体会受到管理。参照第 4 章的在事务外部使用实体管理器和持久化上下文类型。
除了 NoResultException 和 NonUniqueResultException 以外其他的由 Query 接口的方法抛出的运行时异常都会引起当前事务回滚。
2.6.1.1 举例