001/* 002 * Copyright (c) 2008, 2009, 2011 Oracle, Inc. All rights reserved. 003 * 004 * This program and the accompanying materials are made available under the 005 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0 006 * which accompanies this distribution. The Eclipse Public License is available 007 * at http://www.eclipse.org/legal/epl-v10.html and the Eclipse Distribution License 008 * is available at http://www.eclipse.org/org/documents/edl-v10.php. 009 */ 010package javax.persistence; 011 012import java.util.Calendar; 013import java.util.Date; 014import java.util.List; 015 016/** 017 * Interface used to control the execution of typed queries. 018 * 019 * @param <X> query result type 020 * @see Query 021 * @see Parameter 022 * @since Java Persistence 2.0 023 */ 024public interface TypedQuery<X> extends Query { 025 /** 026 * Execute a SELECT query and return the query results 027 * as a typed List. 028 * 029 * @return a list of the results 030 * @throws IllegalStateException if called for a Java 031 * Persistence query language UPDATE or DELETE statement 032 * @throws QueryTimeoutException if the query execution exceeds 033 * the query timeout value set and only the statement is 034 * rolled back 035 * @throws TransactionRequiredException if a lock mode has 036 * been set and there is no transaction 037 * @throws PessimisticLockException if pessimistic locking 038 * fails and the transaction is rolled back 039 * @throws LockTimeoutException if pessimistic locking 040 * fails and only the statement is rolled back 041 * @throws PersistenceException if the query execution exceeds 042 * the query timeout value set and the transaction 043 * is rolled back 044 */ 045 List<X> getResultList(); 046 047 /** 048 * Execute a SELECT query that returns a single result. 049 * 050 * @return the result 051 * @throws NoResultException if there is no result 052 * @throws NonUniqueResultException if more than one result 053 * @throws IllegalStateException if called for a Java 054 * Persistence query language UPDATE or DELETE statement 055 * @throws QueryTimeoutException if the query execution exceeds 056 * the query timeout value set and only the statement is 057 * rolled back 058 * @throws TransactionRequiredException if a lock mode has 059 * been set and there is no transaction 060 * @throws PessimisticLockException if pessimistic locking 061 * fails and the transaction is rolled back 062 * @throws LockTimeoutException if pessimistic locking 063 * fails and only the statement is rolled back 064 * @throws PersistenceException if the query execution exceeds 065 * the query timeout value set and the transaction 066 * is rolled back 067 */ 068 X getSingleResult(); 069 070 /** 071 * Set the maximum number of results to retrieve. 072 * 073 * @param maxResult maximum number of results to retrieve 074 * @return the same query instance 075 * @throws IllegalArgumentException if the argument is negative 076 */ 077 TypedQuery<X> setMaxResults(int maxResult); 078 079 /** 080 * Set the position of the first result to retrieve. 081 * 082 * @param startPosition position of the first result, 083 * numbered from 0 084 * @return the same query instance 085 * @throws IllegalArgumentException if the argument is negative 086 */ 087 TypedQuery<X> setFirstResult(int startPosition); 088 089 /** 090 * Set a query property or hint. The hints elements may be used 091 * to specify query properties and hints. Properties defined by 092 * this specification must be observed by the provider. 093 * Vendor-specific hints that are not recognized by a provider 094 * must be silently ignored. Portable applications should not 095 * rely on the standard timeout hint. Depending on the database 096 * in use and the locking mechanisms used by the provider, 097 * this hint may or may not be observed. 098 * 099 * @param hintName name of property or hint 100 * @param value value for the property or hint 101 * @return the same query instance 102 * @throws IllegalArgumentException if the second argument is not 103 * valid for the implementation 104 */ 105 TypedQuery<X> setHint(String hintName, Object value); 106 107 /** 108 * Bind the value of a <code>Parameter</code> object. 109 * 110 * @param param parameter object 111 * @param value parameter value 112 * @return the same query instance 113 * @throws IllegalArgumentException if the parameter 114 * does not correspond to a parameter of the 115 * query 116 */ 117 <T> TypedQuery<X> setParameter(Parameter<T> param, T value); 118 119 /** 120 * Bind an instance of <code>java.util.Calendar</code> to a <code>Parameter</code> object. 121 * 122 * @param param parameter object 123 * @param value parameter value 124 * @param temporalType temporal type 125 * @return the same query instance 126 * @throws IllegalArgumentException if the parameter does not 127 * correspond to a parameter of the query 128 */ 129 TypedQuery<X> setParameter(Parameter<Calendar> param, 130 Calendar value, 131 TemporalType temporalType); 132 133 /** 134 * Bind an instance of <code>java.util.Date</code> to a <code>Parameter</code> object. 135 * 136 * @param param parameter object 137 * @param value parameter value 138 * @param temporalType temporal type 139 * @return the same query instance 140 * @throws IllegalArgumentException if the parameter does not 141 * correspond to a parameter of the query 142 */ 143 TypedQuery<X> setParameter(Parameter<Date> param, Date value, 144 TemporalType temporalType); 145 146 /** 147 * Bind an argument to a named parameter. 148 * 149 * @param name parameter name 150 * @param value parameter value 151 * @return the same query instance 152 * @throws IllegalArgumentException if the parameter name does 153 * not correspond to a parameter of the query or if 154 * the argument is of incorrect type 155 */ 156 TypedQuery<X> setParameter(String name, Object value); 157 158 /** 159 * Bind an instance of <code>java.util.Calendar</code> to a named parameter. 160 * 161 * @param name parameter name 162 * @param value parameter value 163 * @param temporalType temporal type 164 * @return the same query instance 165 * @throws IllegalArgumentException if the parameter name does 166 * not correspond to a parameter of the query or if 167 * the value argument is of incorrect type 168 */ 169 TypedQuery<X> setParameter(String name, Calendar value, 170 TemporalType temporalType); 171 172 /** 173 * Bind an instance of <code>java.util.Date</code> to a named parameter. 174 * 175 * @param name parameter name 176 * @param value parameter value 177 * @param temporalType temporal type 178 * @return the same query instance 179 * @throws IllegalArgumentException if the parameter name does 180 * not correspond to a parameter of the query or if 181 * the value argument is of incorrect type 182 */ 183 TypedQuery<X> setParameter(String name, Date value, 184 TemporalType temporalType); 185 186 /** 187 * Bind an argument to a positional parameter. 188 * 189 * @param position position 190 * @param value parameter value 191 * @return the same query instance 192 * @throws IllegalArgumentException if position does not 193 * correspond to a positional parameter of the 194 * query or if the argument is of incorrect type 195 */ 196 TypedQuery<X> setParameter(int position, Object value); 197 198 /** 199 * Bind an instance of <code>java.util.Calendar</code> to a positional 200 * parameter. 201 * 202 * @param position position 203 * @param value parameter value 204 * @param temporalType temporal type 205 * @return the same query instance 206 * @throws IllegalArgumentException if position does not 207 * correspond to a positional parameter of the query 208 * or if the value argument is of incorrect type 209 */ 210 TypedQuery<X> setParameter(int position, Calendar value, 211 TemporalType temporalType); 212 213 /** 214 * Bind an instance of <code>java.util.Date</code> to a positional parameter. 215 * 216 * @param position position 217 * @param value parameter value 218 * @param temporalType temporal type 219 * @return the same query instance 220 * @throws IllegalArgumentException if position does not 221 * correspond to a positional parameter of the query 222 * or if the value argument is of incorrect type 223 */ 224 TypedQuery<X> setParameter(int position, Date value, 225 TemporalType temporalType); 226 227 /** 228 * Set the flush mode type to be used for the query execution. 229 * The flush mode type applies to the query regardless of the 230 * flush mode type in use for the entity manager. 231 * 232 * @param flushMode flush mode 233 * @return the same query instance 234 */ 235 TypedQuery<X> setFlushMode(FlushModeType flushMode); 236 237 /** 238 * Set the lock mode type to be used for the query execution. 239 * 240 * @param lockMode lock mode 241 * @return the same query instance 242 * @throws IllegalStateException if the query is found not to 243 * be a Java Persistence query language SELECT query 244 * or a Criteria API query 245 */ 246 TypedQuery<X> setLockMode(LockModeType lockMode); 247}