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; 015import java.util.Map; 016import java.util.Set; 017 018/** 019 * Interface used to control query execution. 020 * 021 * @see TypedQuery 022 * @see Parameter 023 * @since Java Persistence 1.0 024 */ 025public interface Query { 026 027 /** 028 * Execute a SELECT query and return the query results 029 * as an untyped List. 030 * 031 * @return a list of the results 032 * @throws IllegalStateException if called for a Java 033 * Persistence query language UPDATE or DELETE statement 034 * @throws QueryTimeoutException if the query execution exceeds 035 * the query timeout value set and only the statement is 036 * rolled back 037 * @throws TransactionRequiredException if a lock mode has 038 * been set and there is no transaction 039 * @throws PessimisticLockException if pessimistic locking 040 * fails and the transaction is rolled back 041 * @throws LockTimeoutException if pessimistic locking 042 * fails and only the statement is rolled back 043 * @throws PersistenceException if the query execution exceeds 044 * the query timeout value set and the transaction 045 * is rolled back 046 */ 047 List getResultList(); 048 049 /** 050 * Execute a SELECT query that returns a single untyped result. 051 * 052 * @return the result 053 * @throws NoResultException if there is no result 054 * @throws NonUniqueResultException if more than one result 055 * @throws IllegalStateException if called for a Java 056 * Persistence query language UPDATE or DELETE statement 057 * @throws QueryTimeoutException if the query execution exceeds 058 * the query timeout value set and only the statement is 059 * rolled back 060 * @throws TransactionRequiredException if a lock mode has 061 * been set and there is no transaction 062 * @throws PessimisticLockException if pessimistic locking 063 * fails and the transaction is rolled back 064 * @throws LockTimeoutException if pessimistic locking 065 * fails and only the statement is rolled back 066 * @throws PersistenceException if the query execution exceeds 067 * the query timeout value set and the transaction 068 * is rolled back 069 */ 070 Object getSingleResult(); 071 072 /** 073 * Execute an update or delete statement. 074 * 075 * @return the number of entities updated or deleted 076 * @throws IllegalStateException if called for a Java 077 * Persistence query language SELECT statement or for 078 * a criteria query 079 * @throws TransactionRequiredException if there is 080 * no transaction 081 * @throws QueryTimeoutException if the statement execution 082 * exceeds the query timeout value set and only 083 * the statement is rolled back 084 * @throws PersistenceException if the query execution exceeds 085 * the query timeout value set and the transaction 086 * is rolled back 087 */ 088 int executeUpdate(); 089 090 /** 091 * Set the maximum number of results to retrieve. 092 * 093 * @param maxResult maximum number of results to retrieve 094 * @return the same query instance 095 * @throws IllegalArgumentException if the argument is negative 096 */ 097 Query setMaxResults(int maxResult); 098 099 /** 100 * The maximum number of results the query object was set to 101 * retrieve. Returns <code>Integer.MAX_VALUE</code> if <code>setMaxResults</code> was not 102 * applied to the query object. 103 * 104 * @return maximum number of results 105 * @since Java Persistence 2.0 106 */ 107 int getMaxResults(); 108 109 /** 110 * Set the position of the first result to retrieve. 111 * 112 * @param startPosition position of the first result, 113 * numbered from 0 114 * @return the same query instance 115 * @throws IllegalArgumentException if the argument is negative 116 */ 117 Query setFirstResult(int startPosition); 118 119 /** 120 * The position of the first result the query object was set to 121 * retrieve. Returns 0 if <code>setFirstResult</code> was not applied to the 122 * query object. 123 * 124 * @return position of the first result 125 * @since Java Persistence 2.0 126 */ 127 int getFirstResult(); 128 129 /** 130 * Set a query property or hint. The hints elements may be used 131 * to specify query properties and hints. Properties defined by 132 * this specification must be observed by the provider. 133 * Vendor-specific hints that are not recognized by a provider 134 * must be silently ignored. Portable applications should not 135 * rely on the standard timeout hint. Depending on the database 136 * in use and the locking mechanisms used by the provider, 137 * this hint may or may not be observed. 138 * 139 * @param hintName name of the property or hint 140 * @param value value for the property or hint 141 * @return the same query instance 142 * @throws IllegalArgumentException if the second argument is not 143 * valid for the implementation 144 */ 145 Query setHint(String hintName, Object value); 146 147 /** 148 * Get the properties and hints and associated values that are 149 * in effect for the query instance. 150 * 151 * @return query properties and hints 152 * @since Java Persistence 2.0 153 */ 154 Map<String, Object> getHints(); 155 156 /** 157 * Bind the value of a <code>Parameter</code> object. 158 * 159 * @param param parameter object 160 * @param value parameter value 161 * @param <T> type 162 * @return the same query instance 163 * @throws IllegalArgumentException if the parameter 164 * does not correspond to a parameter of the 165 * query 166 * @since Java Persistence 2.0 167 */ 168 <T> Query setParameter(Parameter<T> param, T value); 169 170 /** 171 * Bind an instance of <code>java.util.Calendar</code> to a <code>Parameter</code> object. 172 * 173 * @param param parameter object 174 * @param value parameter value 175 * @param temporalType temporal type 176 * @return the same query instance 177 * @throws IllegalArgumentException if the parameter does not 178 * correspond to a parameter of the query 179 * @since Java Persistence 2.0 180 */ 181 Query setParameter(Parameter<Calendar> param, Calendar value, 182 TemporalType temporalType); 183 184 /** 185 * Bind an instance of <code>java.util.Date</code> to a <code>Parameter</code> object. 186 * 187 * @param param parameter object 188 * @param value parameter value 189 * @param temporalType temporal type 190 * @return the same query instance 191 * @throws IllegalArgumentException if the parameter does not 192 * correspond to a parameter of the query 193 * @since Java Persistence 2.0 194 */ 195 Query setParameter(Parameter<Date> param, Date value, 196 TemporalType temporalType); 197 198 /** 199 * Bind an argument to a named parameter. 200 * 201 * @param name parameter name 202 * @param value parameter value 203 * @return the same query instance 204 * @throws IllegalArgumentException if the parameter name does 205 * not correspond to a parameter of the query or if 206 * the argument is of incorrect type 207 */ 208 Query setParameter(String name, Object value); 209 210 /** 211 * Bind an instance of <code>java.util.Calendar</code> to a named parameter. 212 * 213 * @param name parameter name 214 * @param value parameter value 215 * @param temporalType temporal type 216 * @return the same query instance 217 * @throws IllegalArgumentException if the parameter name does 218 * not correspond to a parameter of the query or if 219 * the value argument is of incorrect type 220 */ 221 Query setParameter(String name, Calendar value, 222 TemporalType temporalType); 223 224 /** 225 * Bind an instance of <code>java.util.Date</code> to a named parameter. 226 * 227 * @param name parameter name 228 * @param value parameter value 229 * @param temporalType temporal type 230 * @return the same query instance 231 * @throws IllegalArgumentException if the parameter name does 232 * not correspond to a parameter of the query or if 233 * the value argument is of incorrect type 234 */ 235 Query setParameter(String name, Date value, 236 TemporalType temporalType); 237 238 /** 239 * Bind an argument to a positional parameter. 240 * 241 * @param position position 242 * @param value parameter value 243 * @return the same query instance 244 * @throws IllegalArgumentException if position does not 245 * correspond to a positional parameter of the 246 * query or if the argument is of incorrect type 247 */ 248 Query setParameter(int position, Object value); 249 250 /** 251 * Bind an instance of <code>java.util.Calendar</code> to a positional 252 * parameter. 253 * 254 * @param position position 255 * @param value parameter value 256 * @param temporalType temporal type 257 * @return the same query instance 258 * @throws IllegalArgumentException if position does not 259 * correspond to a positional parameter of the query or 260 * if the value argument is of incorrect type 261 */ 262 Query setParameter(int position, Calendar value, 263 TemporalType temporalType); 264 265 /** 266 * Bind an instance of <code>java.util.Date</code> to a positional parameter. 267 * 268 * @param position position 269 * @param value parameter value 270 * @param temporalType temporal type 271 * @return the same query instance 272 * @throws IllegalArgumentException if position does not 273 * correspond to a positional parameter of the query or 274 * if the value argument is of incorrect type 275 */ 276 Query setParameter(int position, Date value, 277 TemporalType temporalType); 278 279 /** 280 * Get the parameter objects corresponding to the declared 281 * parameters of the query. 282 * Returns empty set if the query has no parameters. 283 * This method is not required to be supported for native 284 * queries. 285 * 286 * @return set of the parameter objects 287 * @throws IllegalStateException if invoked on a native 288 * query when the implementation does not support 289 * this use 290 * @since Java Persistence 2.0 291 */ 292 Set<Parameter<?>> getParameters(); 293 294 /** 295 * Get the parameter object corresponding to the declared 296 * parameter of the given name. 297 * This method is not required to be supported for native 298 * queries. 299 * 300 * @param name parameter name 301 * @return parameter object 302 * @throws IllegalArgumentException if the parameter of the 303 * specified name does not exist 304 * @throws IllegalStateException if invoked on a native 305 * query when the implementation does not support 306 * this use 307 * @since Java Persistence 2.0 308 */ 309 Parameter<?> getParameter(String name); 310 311 /** 312 * Get the parameter object corresponding to the declared 313 * parameter of the given name and type. 314 * This method is required to be supported for criteria queries 315 * only. 316 * 317 * @param name parameter name 318 * @param type type 319 * @param <T> type 320 * @return parameter object 321 * @throws IllegalArgumentException if the parameter of the 322 * specified name does not exist or is not assignable 323 * to the type 324 * @throws IllegalStateException if invoked on a native 325 * query or Java Persistence query language query when 326 * the implementation does not support this use 327 * @since Java Persistence 2.0 328 */ 329 <T> Parameter<T> getParameter(String name, Class<T> type); 330 331 /** 332 * Get the parameter object corresponding to the declared 333 * positional parameter with the given position. 334 * This method is not required to be supported for native 335 * queries. 336 * 337 * @param position position 338 * @return parameter object 339 * @throws IllegalArgumentException if the parameter with the 340 * specified position does not exist 341 * @throws IllegalStateException if invoked on a native 342 * query when the implementation does not support 343 * this use 344 * @since Java Persistence 2.0 345 */ 346 Parameter<?> getParameter(int position); 347 348 /** 349 * Get the parameter object corresponding to the declared 350 * positional parameter with the given position and type. 351 * This method is not required to be supported by the provider. 352 * 353 * @param position position 354 * @param type type 355 * @param <T> Type 356 * @return parameter object 357 * @throws IllegalArgumentException if the parameter with the 358 * specified position does not exist or is not assignable 359 * to the type 360 * @throws IllegalStateException if invoked on a native 361 * query or Java Persistence query language query when 362 * the implementation does not support this use 363 * @since Java Persistence 2.0 364 */ 365 <T> Parameter<T> getParameter(int position, Class<T> type); 366 367 /** 368 * Return a boolean indicating whether a value has been bound 369 * to the parameter. 370 * 371 * @param param parameter object 372 * @return boolean indicating whether parameter has been bound 373 * @since Java Persistence 2.0 374 */ 375 boolean isBound(Parameter<?> param); 376 377 /** 378 * Return the value bound to the parameter. 379 * 380 * @param param parameter object 381 * @param <T> Type 382 * @return parameter value 383 * @throws IllegalArgumentException if the parameter is not 384 * a parameter of the query 385 * @throws IllegalStateException if the parameter has not been 386 * been bound 387 * @since Java Persistence 2.0 388 */ 389 <T> T getParameterValue(Parameter<T> param); 390 391 /** 392 * Return the value bound to the named parameter. 393 * 394 * @param name parameter name 395 * @return parameter value 396 * @throws IllegalStateException if the parameter has not been 397 * been bound 398 * @throws IllegalArgumentException if the parameter of the 399 * specified name does not exist 400 * @since Java Persistence 2.0 401 */ 402 Object getParameterValue(String name); 403 404 /** 405 * Return the value bound to the positional parameter. 406 * 407 * @param position position 408 * @return parameter value 409 * @throws IllegalStateException if the parameter has not been 410 * been bound 411 * @throws IllegalArgumentException if the parameter with the 412 * specified position does not exist 413 * @since Java Persistence 2.0 414 */ 415 Object getParameterValue(int position); 416 417 /** 418 * Set the flush mode type to be used for the query execution. 419 * The flush mode type applies to the query regardless of the 420 * flush mode type in use for the entity manager. 421 * 422 * @param flushMode flush mode 423 * @return the same query instance 424 */ 425 Query setFlushMode(FlushModeType flushMode); 426 427 /** 428 * Get the flush mode in effect for the query execution. 429 * If a flush mode has not been set for the query object, 430 * returns the flush mode in effect for the entity manager. 431 * 432 * @return flush mode 433 * @since Java Persistence 2.0 434 */ 435 FlushModeType getFlushMode(); 436 437 /** 438 * Set the lock mode type to be used for the query execution. 439 * 440 * @param lockMode lock mode 441 * @return the same query instance 442 * @throws IllegalStateException if the query is found not to be 443 * a Java Persistence query language SELECT query 444 * or a Criteria API query 445 * @since Java Persistence 2.0 446 */ 447 Query setLockMode(LockModeType lockMode); 448 449 /** 450 * Get the current lock mode for the query. 451 * 452 * @return lock mode 453 * @throws IllegalStateException if the query is found not to be 454 * a Java Persistence query language SELECT query or 455 * a Criteria API query 456 * @since Java Persistence 2.0 457 */ 458 LockModeType getLockMode(); 459 460 /** 461 * Return an object of the specified type to allow access to 462 * the provider-specific API. If the provider's query 463 * implementation does not support the specified class, the 464 * <code>PersistenceException</code> is thrown. 465 * 466 * @param cls the class of the object to be returned. This is 467 * normally either the underlying query 468 * implementation class or an interface that it 469 * implements. 470 * @param <T> Type 471 * @return an instance of the specified class 472 * @throws PersistenceException if the provider does not support 473 * the call 474 * @since Java Persistence 2.0 475 */ 476 <T> T unwrap(Class<T> cls); 477}