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