1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23 package javax.jdo;
24 import java.io.Serializable;
25 import java.util.Collection;
26 import java.util.Map;
27
28 /** The <code>Query</code> interface allows applications to obtain persistent
29 * instances, values, and aggregate data
30 * from the data store.
31 *
32 * The {@link PersistenceManager} is the factory for <code>Query</code>
33 * instances. There may be many <code>Query</code> instances associated with a
34 * <code>PersistenceManager</code>. Multiple queries might be executed
35 * simultaneously by different threads, but the implementation might choose to
36 * execute them serially. In either case, the implementation must be thread
37 * safe.
38 *
39 * <P>There are three required elements in a <code>Query</code>: the class of
40 * the results, the candidate collection of instances, and the filter.
41 *
42 * <P>There are optional elements: parameter declarations, variable
43 * declarations, import statements, ordering and grouping specifications,
44 * result and result class, the range of results,
45 * and flags indicating whether the query result
46 * is unique and whether the query can be modified.
47 * <P>The query namespace is modeled after methods in Java:
48 * <ul>
49 * <li><code>setClass</code> corresponds to the class definition
50 * <li><code>declareParameters</code> corresponds to formal parameters of a
51 * method
52 * <li><code>declareVariables</code> corresponds to local variables of a method
53 * <li><code>setFilter</code> and <code>setOrdering</code> correspond to the
54 * method body
55 * </ul>
56 * <P>There are two namespaces in queries. Type names have their own
57 * namespace that is separate from the namespace for fields, variables
58 * and parameters.
59 * <P>The method <code>setClass</code> introduces the name of the candidate
60 * class in the type namespace. The method <code>declareImports</code>
61 * introduces the names of the imported class or interface types in the type
62 * namespace. Imported type names must be unique. When used (e.g. in a parameter
63 * declaration, cast expression, etc.) a type name must be the name of the
64 * candidate class, the name of a class or interface imported by method
65 * <code>declareImports</code>, or denote a class or interface from the same
66 * package as the candidate class.
67 * <P>The method <code>setClass</code> introduces the names of the candidate
68 * class fields.
69 * <P>The method <code>declareParameters</code> introduces the names of the
70 * parameters. A name introduced by <code>declareParameters</code> hides the
71 * name of a candidate class field of the same name. Parameter names must be
72 * unique.
73 * <P>The method <code>declareVariables</code> introduces the names of the
74 * variables. A name introduced by <code>declareVariables</code> hides the name
75 * of a candidate class field if equal. Variable names must be unique and must
76 * not conflict with parameter names.
77 * <P>The result of the query by default is a list of result class instances,
78 * but might be specified via <code>setResult</code>. The class of the result
79 * by default is the candidate class, but might be specified via
80 * <code>setResultClass</code>.
81 * <P>A hidden field may be accessed using the 'this' qualifier:
82 * <code>this.fieldName</code>.
83 * <P>The <code>Query</code> interface provides methods which execute the query
84 * based on the parameters given. They return a single instance or a
85 * <code>List</code> of result class instances which the
86 * user can iterate to get results. The signature
87 * of the <code>execute</code> methods specifies that they return an
88 * <code>Object</code> which must be cast to the appropriate result by the user.
89 * <P>Any parameters passed to the <code>execute</code> methods are used only
90 * for this execution, and are not remembered for future execution.
91 * @version 2.1
92 */
93
94 public interface Query extends Serializable {
95
96 /**
97 * The string constant used as the first argument to
98 * {@link PersistenceManager#newQuery(String,Object)} to identify that the
99 * created query should obey the JDOQL syntax and semantic rules.
100 * <p>This is the default query language used when creating a query with any
101 * of the other {@link PersistenceManager#newQuery} methods, except
102 * {@link PersistenceManager#newQuery(Object)}, which uses the query
103 * language of the compiled query template object passed to that method.</p>
104 * @since 2.0
105 */
106 String JDOQL = "javax.jdo.query.JDOQL";
107
108 /**
109 * The string constant used as the first argument to {@link
110 * PersistenceManager#newQuery(String,Object)} to identify that
111 * the created query should use SQL semantics. This is only
112 * meaningful for relational JDO implementations.
113 * <p>If this is used, the <code>Object</code> argument to the
114 * {@link PersistenceManager#newQuery(String,Object)} method
115 * should be a <code>String</code> containing a SQL
116 * <code>SELECT</code> statement.</p>
117 * @since 2.0
118 */
119 String SQL = "javax.jdo.query.SQL";
120
121 /** Set the class of the candidate instances of the query.
122 * <P>The class specifies the class
123 * of the candidates of the query. Elements of the candidate collection
124 * that are of the specified class are filtered before being
125 * put into the result <code>Collection</code>.
126 *
127 * @param cls the <code>Class</code> of the candidate instances.
128 */
129 void setClass(Class cls);
130
131 /** Set the candidate <code>Extent</code> to query.
132 * @param pcs the candidate <code>Extent</code>.
133 */
134 void setCandidates(Extent pcs);
135
136 /** Set the candidate <code>Collection</code> to query.
137 * @param pcs the candidate <code>Collection</code>.
138 */
139 void setCandidates(Collection pcs);
140
141 /** Set the filter for the query.
142 *
143 * <P>The filter specification is a <code>String</code> containing a Boolean
144 * expression that is to be evaluated for each of the instances
145 * in the candidate collection. If the filter is not specified,
146 * then it defaults to "true", which has the effect of filtering
147 * the input <code>Collection</code> only for class type.
148 * <P>An element of the candidate collection is returned in the result if:
149 * <ul><li>it is assignment compatible to the candidate <code>Class</code>
150 * of the <code>Query</code>; and
151 * <li>for all variables there exists a value for which the filter
152 * expression evaluates to <code>true</code>.
153 * </ul>
154 * <P>The user may denote uniqueness in the filter expression by
155 * explicitly declaring an expression (for example, <code>e1 != e2</code>).
156 * <P>Rules for constructing valid expressions follow the Java
157 * language, except for these differences:
158 * <ul>
159 * <li>Equality and ordering comparisons between primitives and instances
160 * of wrapper classes are valid.
161 * <li>Equality and ordering comparisons of <code>Date</code> fields and
162 * <code>Date</code> parameters are valid.
163 * <li>White space (non-printing characters space, tab, carriage
164 * return, and line feed) is a separator and is otherwise ignored.
165 * <li>The assignment operators <code>=</code>, <code>+=</code>, etc. and
166 * pre- and post-increment and -decrement are not supported. Therefore,
167 * there are no side effects from evaluation of any expressions.
168 * <li>Methods, including object construction, are not supported, except
169 * for <code>Collection.contains(Object o)</code>,
170 * <code>Collection.isEmpty()</code>,
171 * <code>String.startsWith(String s)</code>, and
172 * <code>String.endsWith(String e)</code>. Implementations might choose to
173 * support non-mutating method calls as non-standard extensions.
174 * <li>Navigation through a <code>null</code>-valued field, which would
175 * throw <code>NullPointerException</code>, is treated as if the filter
176 * expression returned <code>false</code> for the evaluation of the current
177 * set of variable values. Other values for variables might still qualify
178 * the candidate instance for inclusion in the result set.
179 * <li>Navigation through multi-valued fields (<code>Collection</code>
180 * types) is specified using a variable declaration and the
181 * <code>Collection.contains(Object o)</code> method.
182 * </ul>
183 * <P>Identifiers in the expression are considered to be in the name
184 * space of the specified class, with the addition of declared imports,
185 * parameters and variables. As in the Java language, <code>this</code> is a
186 * reserved word which means the element of the collection being evaluated.
187 * <P>Navigation through single-valued fields is specified by the Java
188 * language syntax of <code>field_name.field_name....field_name</code>.
189 * <P>A JDO implementation is allowed to reorder the filter expression
190 * for optimization purposes.
191 * @param filter the query filter.
192 */
193 void setFilter(String filter);
194
195 /** Set the import statements to be used to identify the fully qualified
196 * name of variables or parameters. Parameters and unbound variables might
197 * come from a different class from the candidate class, and the names
198 * need to be declared in an import statement to eliminate ambiguity.
199 * Import statements are specified as a <code>String</code> with
200 * semicolon-separated statements.
201 * <P>The <code>String</code> parameter to this method follows the syntax of
202 * the import statement of the Java language.
203 * @param imports import statements separated by semicolons.
204 */
205 void declareImports(String imports);
206
207 /** Declare the list of parameters query execution.
208 *
209 * The parameter declaration is a <code>String</code> containing one or more
210 * query parameter declarations separated with commas. Each parameter named
211 * in the parameter declaration must be bound to a value when
212 * the query is executed.
213 * <P>The <code>String</code> parameter to this method follows the syntax
214 * for formal parameters in the Java language.
215 * @param parameters the list of parameters separated by commas.
216 */
217 void declareParameters(String parameters);
218
219 /** Declare the unbound variables to be used in the query. Variables
220 * might be used in the filter, and these variables must be declared
221 * with their type. The unbound variable declaration is a
222 * <code>String</code> containing one or more unbound variable declarations
223 * separated with semicolons. It follows the syntax for local variables in
224 * the Java language.
225 * @param variables the variables separated by semicolons.
226 */
227 void declareVariables(String variables);
228
229 /** Set the ordering specification for the result <code>Collection</code>.
230 * The ordering specification is a <code>String</code> containing one or
231 * more ordering declarations separated by commas.
232 *
233 * <P>Each ordering declaration is the name of the field on which
234 * to order the results followed by one of the following words:
235 * "<code>ascending</code>" or "<code>descending</code>".
236 *
237 *<P>The field must be declared in the candidate class or must be
238 * a navigation expression starting with a field in the candidate class.
239 *
240 *<P>Valid field types are primitive types except <code>boolean</code>;
241 * wrapper types except <code>Boolean</code>; <code>BigDecimal</code>;
242 * <code>BigInteger</code>; <code>String</code>; and <code>Date</code>.
243 * @param ordering the ordering specification.
244 */
245 void setOrdering(String ordering);
246
247 /** Set the ignoreCache option. The default value for this option was
248 * set by the <code>PersistenceManagerFactory</code> or the
249 * <code>PersistenceManager</code> used to create this <code>Query</code>.
250 *
251 * The ignoreCache option setting specifies whether the query should execute
252 * entirely in the back end, instead of in the cache. If this flag is set
253 * to <code>true</code>, an implementation might be able to optimize the
254 * query execution by ignoring changed values in the cache. For optimistic
255 * transactions, this can dramatically improve query response times.
256 * @param ignoreCache the setting of the ignoreCache option.
257 */
258 void setIgnoreCache(boolean ignoreCache);
259
260 /** Get the ignoreCache option setting.
261 * @return the ignoreCache option setting.
262 * @see #setIgnoreCache
263 */
264 boolean getIgnoreCache();
265
266 /** Verify the elements of the query and provide a hint to the query to
267 * prepare and optimize an execution plan.
268 */
269 void compile();
270
271 /** Execute the query and return the filtered Collection.
272 * <P>Cancellation of the query using cancel() will result in JDOQueryInterruptedException
273 * being thrown here
274 * @return the filtered <code>Collection</code>.
275 * @see #executeWithArray(Object[] parameters)
276 */
277 Object execute();
278
279 /** Execute the query and return the filtered <code>Collection</code>.
280 * <P>Cancellation of the query using cancel() will result in JDOQueryInterruptedException
281 * being thrown here
282 * @return the filtered <code>Collection</code>.
283 * @see #executeWithArray(Object[] parameters)
284 * @param p1 the value of the first parameter declared.
285 */
286 Object execute(Object p1);
287
288 /** Execute the query and return the filtered <code>Collection</code>.
289 * <P>Cancellation of the query using cancel() will result in JDOQueryInterruptedException
290 * being thrown here
291 * @return the filtered <code>Collection</code>.
292 * @see #executeWithArray(Object[] parameters)
293 * @param p1 the value of the first parameter declared.
294 * @param p2 the value of the second parameter declared.
295 */
296 Object execute(Object p1, Object p2);
297
298 /** Execute the query and return the filtered <code>Collection</code>.
299 * <P>Cancellation of the query using cancel() will result in JDOQueryInterruptedException
300 * being thrown here
301 * @return the filtered <code>Collection</code>.
302 * @see #executeWithArray(Object[] parameters)
303 * @param p1 the value of the first parameter declared.
304 * @param p2 the value of the second parameter declared.
305 * @param p3 the value of the third parameter declared.
306 */
307 Object execute(Object p1, Object p2, Object p3);
308
309 /** Execute the query and return the filtered <code>Collection</code>. The
310 * query is executed with the parameters set by the <code>Map</code> values.
311 * Each <code>Map</code> entry consists of a key which is the name of the
312 * parameter in the <code>declareParameters</code> method, and a value which
313 * is the value used in the <code>execute</code> method. The keys in the
314 * <code>Map</code> and the declared parameters must exactly match or a
315 * <code>JDOUserException</code> is thrown.
316 * <P>Cancellation of the query using cancel() will result in JDOQueryInterruptedException
317 * being thrown here
318 * @return the filtered <code>Collection</code>.
319 * @see #executeWithArray(Object[] parameters)
320 * @param parameters the <code>Map</code> containing all of the parameters.
321 */
322 Object executeWithMap (Map parameters);
323
324 /** Execute the query and return the filtered <code>Collection</code>.
325 *
326 * <P>The execution of the query obtains the values of the parameters and
327 * matches them against the declared parameters in order. The names
328 * of the declared parameters are ignored. The type of
329 * the declared parameters must match the type of the passed parameters,
330 * except that the passed parameters might need to be unwrapped to get
331 * their primitive values.
332 *
333 * <P>The filter, import, declared parameters, declared variables, and
334 * ordering statements are verified for consistency.
335 *
336 * <P>Each element in the candidate <code>Collection</code> is examined to
337 * see that it is assignment compatible to the <code>Class</code> of the
338 * query. It is then evaluated by the Boolean expression of the filter.
339 * The element passes the filter if there exist unique values for all
340 * variables for which the filter expression evaluates to <code>true</code>.
341 * <P>Cancellation of the query using cancel() will result in JDOQueryInterruptedException
342 * being thrown here
343 * @return the filtered <code>Collection</code>.
344 * @param parameters the <code>Object</code> array with all of the
345 * parameters.
346 */
347 Object executeWithArray (Object... parameters);
348
349 /** Get the <code>PersistenceManager</code> associated with this
350 * <code>Query</code>.
351 *
352 * <P>If this <code>Query</code> was restored from a serialized form, it has
353 * no <code>PersistenceManager</code>, and this method returns
354 * <code>null</code>.
355 * @return the <code>PersistenceManager</code> associated with this
356 * <code>Query</code>.
357 */
358 PersistenceManager getPersistenceManager();
359
360 /** Close a query result and release any resources associated with it. The
361 * parameter is the return from <code>execute(...)</code> and might have
362 * iterators open on it. Iterators associated with the query result are
363 * invalidated: they return <code>false</code> to <code>hasNext()</code>
364 * and throw <code>NoSuchElementException</code> to <code>next()</code>.
365 * @param queryResult the result of <code>execute(...)</code> on this
366 * <code>Query</code> instance.
367 */
368 void close (Object queryResult);
369
370 /** Close all query results associated with this <code>Query</code>
371 * instance, and release all resources associated with them. The query
372 * results might have iterators open on them. Iterators associated with the
373 * query results are invalidated:
374 * they return <code>false</code> to <code>hasNext()</code> and throw
375 * <code>NoSuchElementException</code> to <code>next()</code>.
376 */
377 void closeAll ();
378
379 /**
380 * Set the grouping expressions, optionally including a "having"
381 * clause. When grouping is specified, each result expression
382 * must either be an expression contained in the grouping, or an
383 * aggregate evaluated once per group.
384 *
385 * @param group a comma-delimited list of expressions, optionally
386 * followed by the "having" keyword and a boolean expression
387 * @since 2.0
388 */
389 void setGrouping (String group);
390
391 /**
392 * Specify that only the first result of the query should be
393 * returned, rather than a collection. The execute method will
394 * return null if the query result size is 0.
395 * @since 2.0
396 * @param unique if true, only one element is returned
397 */
398 void setUnique (boolean unique);
399
400 /**
401 * Specifies what type of data this query should return. If this
402 * is unset or set to <code>null</code>, this query returns
403 * instances of the query's candidate class. If set, this query
404 * will return expressions, including field values (projections) and
405 * aggregate function results.
406 * @param data a comma-delimited list of expressions
407 * (fields, functions on fields, or aggregate functions)
408 * to return from this query
409 * @since 2.0
410 */
411 void setResult (String data);
412
413 /**
414 * Specify the type of object in which to return each element of
415 * the result of invoking {@link #execute} or one of its siblings.
416 * If the result is not set or set to null, the result class defaults
417 * to the candidate class of the query. If the result consists of one
418 * expression, the result class defaults to the type of that expression.
419 * If the result consists of more than one expression, the result class
420 * defaults to Object[].
421 * The result class may be specified to be one of the java.lang classes
422 * Character, Boolean, Byte, Short, Integer, Long, Float, Double, String,
423 * or Object[]; or one of the java.math classes BigInteger or BigDecimal;
424 * or the java.util class Date; or one of the java.sql classes Date,
425 * Time, or Timestamp; or a user-defined class.
426 * <P>If there are multiple result expressions, the result class
427 * must be able to hold all elements of the result specification
428 * or a JDOUserException is thrown.
429 *<P>If there is only one result expression, the result class must be
430 * assignable from the type of the result expression or must be able
431 * to hold all elements of the result specification. A single value
432 * must be able to be coerced into the specified result class
433 * (treating wrapper classes as equivalent to their unwrapped
434 * primitive types) or by matching. If the result class does not satisfy
435 * these conditions, a JDOUserException is thrown.
436 *<P>A constructor of a result class specified in the setResult method
437 * will be used if the results specification matches the parameters
438 * of the constructor by position and type. If more than one constructor
439 * satisfies the requirements, the JDO implementation chooses one of them.
440 * If no constructor satisfies the results requirements, or if the result
441 * class is specified via the setResultClass method, the following
442 * requirements apply:
443 * <ul>
444 * <li>A user-defined result class must have a no-args constructor and
445 * one or more public <code>set</code> or <code>put</code> methods or
446 * fields.
447 * <li>Each result expression must match one of:
448 * <ul>
449 * <li>a public field that matches the name of the result expression
450 * and is of the type (treating wrapper types equivalent to primitive
451 * types) of the result expression;
452 * <li>or if no public field matches the name and type, a public
453 * <code>set</code method that returns void and matches the name of the
454 * result expression and takes a single parameter which is the
455 * exact type of the result expression;
456 * <li>or if neither of the above applies,a public method must be found
457 * with the signature <code>void put(Object, Object)</code>.
458 * During processing of the results,
459 * the first argument is the name of the result expression and
460 * the second argument is the value from the query result.
461 * </ul>
462 * </ul>
463 * Portable result classes do not invoke any persistence behavior
464 * during their no-args constructor or <code>set</code methods.
465 * @param cls the result class
466 * @since 2.0
467 */
468 void setResultClass (Class cls);
469
470 /**
471 * Set the range of results to return. The execution of the query is
472 * modified to return only a subset of results. If the filter would
473 * normally return 100 instances, and fromIncl is set to 50, and
474 * toExcl is set to 70, then the first 50 results that would have
475 * been returned are skipped, the next 20 results are returned and the
476 * remaining 30 results are ignored. An implementation should execute
477 * the query such that the range algorithm is done at the data store.
478 * @param fromIncl 0-based inclusive start index
479 * @param toExcl 0-based exclusive end index, or
480 * {@link Long#MAX_VALUE} for no limit.
481 * @since 2.0
482 */
483 void setRange (long fromIncl, long toExcl);
484
485 /**
486 * Set the range of results to return. The parameter is a String
487 * containing a comma-separated fromIncl and toExcl. The fromIncl and
488 * toExcl can be either String representations of long values, or can
489 * be parameters identified with a leading ":". For example,
490 * <code>setRange("50, 70");</code> or
491 * <code>setRange(":from, :to");</code> or
492 * <code>setRange("50, :to");</code>.
493 * The execution of the query is
494 * modified to return only a subset of results. If the filter would
495 * normally return 100 instances, and fromIncl is set to 50, and
496 * toExcl is set to 70, then the first 50 results that would have
497 * been returned are skipped, the next 20 results are returned and the
498 * remaining 30 results are ignored. An implementation should execute
499 * the query such that the range algorithm is done at the data store.
500 * @param fromInclToExcl comma-separated fromIncl and toExcl values
501 * @see #setRange(long, long)
502 * @since 2.0
503 */
504 void setRange (String fromInclToExcl);
505
506 /**
507 * Add a vendor-specific extension to this query. The key and value
508 * are not standard.
509 * An implementation must ignore keys that are not recognized.
510 * @param key the key of the extension
511 * @param value the value of the extension
512 * @since 2.0
513 */
514 void addExtension (String key, Object value);
515
516 /**
517 * Set multiple extensions, or use null to clear all extensions.
518 * Map keys and values are not standard.
519 * An implementation must ignore entries that are not recognized.
520 * @param extensions the map of extensions
521 * @see #addExtension
522 * @since 2.0
523 */
524 void setExtensions (Map extensions);
525
526 /**
527 * Returns the <code>FetchPlan</code> used by this
528 * <code>Query</code>. Modifications of the returned fetch plan will not
529 * cause this query's owning <code>PersistenceManager</code>'s
530 * <code>FetchPlan</code> to be modified.
531 * @since 2.0
532 * @return the fetch plan used by this query
533 */
534 FetchPlan getFetchPlan ();
535
536 /**
537 * Deletes all the instances of the candidate class that pass the
538 * filter.
539 * @see #deletePersistentAll()
540 * @param parameters for the query
541 * @return the number of instances of the candidate class that were deleted
542 * @since 2.0
543 */
544 long deletePersistentAll (Object... parameters);
545
546 /**
547 * Deletes all the instances of the candidate class that pass the
548 * filter.
549 * @see #deletePersistentAll()
550 * @param parameters for the query
551 * @return the number of instances of the candidate class that were deleted
552 * @since 2.0
553 */
554 long deletePersistentAll (Map parameters);
555
556 /**
557 * Deletes all the instances of the candidate class that pass the
558 * filter. Returns the number of instances of the candidate
559 * class that were deleted, specifically not including the number
560 * of dependent and embedded instances.
561 * <P>Dirty instances of affected classes in the cache are first
562 * flushed to the datastore. Instances in the cache or brought into
563 * the cache as a result of executing one of the
564 * <code>deletePersistentAll</code>
565 * methods undergo life cycle changes as if <code>deletePersistent</code>
566 * were called on them.
567 * <P>Specifically, if the class of deleted instances implements the
568 * delete callback interface, the corresponding callback methods
569 * are called on the deleted instances. Similarly, if there are
570 * lifecycle listeners registered for delete events on affected
571 * classes, the listener is called for each appropriate deleted instance.
572 * <P>Before returning control to the application, instances of affected
573 * classes in the cache are refreshed to reflect whether they were
574 * deleted from the datastore.
575 *
576 * @return the number of instances of the candidate class that were deleted
577 * @since 2.0
578 */
579 long deletePersistentAll ();
580
581 /**
582 * The unmodifiable flag, when set, disallows further
583 * modification of the query, except for specifying the range,
584 * result class, and ignoreCache option.
585 * The unmodifiable flag can also be set in metadata.
586 * @since 2.0
587 */
588 void setUnmodifiable();
589
590 /**
591 * The unmodifiable flag, when set, disallows further
592 * modification of the query, except for specifying the range,
593 * result class, and ignoreCache option.
594 * @return the current setting of the flag
595 * @since 2.0
596 */
597 boolean isUnmodifiable();
598
599 /**
600 * Add a subquery to this query.
601 * @param sub the subquery to add to this Query
602 * @param variableDeclaration the name of the variable in the outer query
603 * to bind the results of the subquery
604 * @param candidateCollectionExpression the candidate collection
605 * of the subquery as an expression using terms of the outer query
606 * @see #addSubquery(Query sub, String variableDeclaration,
607 * String candidateCollectionExpression, String... parameters)
608 * @since 2.1
609 */
610 void addSubquery
611 (Query sub, String variableDeclaration,
612 String candidateCollectionExpression);
613
614 /**
615 * Add a subquery to this query.
616 * The String version of the method binds the named expression
617 * to the parameter implictly or explicitly declared in the
618 * subquery.
619 * @param sub the subquery to add to this Query
620 * @param variableDeclaration the name of the variable
621 * to be used in this Query
622 * @param candidateCollectionExpression the candidate collection
623 * to apply to the subquery
624 * @param parameter the expression from the outer query to bind
625 * the parameter in the subquery
626 * @see #addSubquery(Query sub, String variableDeclaration,
627 * String candidateCollectionExpression, String... parameters)
628 * @since 2.1
629 */
630 void addSubquery
631 (Query sub, String variableDeclaration,
632 String candidateCollectionExpression, String parameter);
633
634 /**
635 * Add a subquery to this query.
636 * A subquery is composed as a Query and subsequently attached
637 * to a different query (the outer query) by calling this method.
638 * The query parameter instance is unmodified as a result of the
639 * addSubquery or subsequent execution of the outer query.
640 * Only some of the query parts are copied for use as the subquery.
641 * The parts copied include the candidate class, filter, parameter
642 * declarations, variable declarations, imports, ordering specification,
643 * uniqueness, result specification, and grouping specification.
644 * The association with a PersistenceManager, the candidate collection
645 * or extent, result class, and range limits are not used.
646 * The String parameters are trimmed of white space.
647 * The variableDeclaration parameter is the name of the variable
648 * containing the results of the subquery execution. If the same value
649 * of variableDeclaration is used to add multiple subqueries, the
650 * subquery replaces the previous subquery for the same named variable.
651 * If the subquery parameter is null, the variable is unset,
652 * effectively making the variable named in the variableDeclaration
653 * unbound. If the trimmed value is the empty String, or the parameter
654 * is null, then JDOUserException is thrown.
655 * The candidateCollectionExpression is the expression from the
656 * outer query that represents the candidates over which the subquery
657 * is evaluated. If the trimmed value is the empty String, or the
658 * parameter is null, then the candidate collection is the extent
659 * of the candidate class.
660 * The String... version of the method binds the named expressions in
661 * turn to parameters in the order in which they are declared in the
662 * subquery, or in the order they are found in the filter if not
663 * explicitly declared in the subquery.
664 * @param sub the subquery to add to this Query
665 * @param variableDeclaration the name of the variable in the outer query
666 * to bind the results of the subquery
667 * @param candidateCollectionExpression the candidate collection
668 * of the subquery as an expression using terms of the outer query
669 * @param parameters the expressions from the outer query to bind
670 * the parameters in the subquery
671 * @since 2.1
672 */
673 void addSubquery
674 (Query sub, String variableDeclaration,
675 String candidateCollectionExpression, String... parameters);
676
677 /**
678 * Add a subquery to this query.
679 * The Map version of the method treats the key of each map entry as
680 * the name of the parameter in the subquery, with or without the
681 * leading ":", and the value as the name of the expression in the
682 * outer query. If the trimmed expression is the empty String for
683 * either the parameter or the value of the String[], or for any
684 * map key or value, that expression is ignored.
685 * @param sub the subquery to add to this Query
686 * @param variableDeclaration the name of the variable
687 * to be used in this Query
688 * @param candidateCollectionExpression the candidate collection
689 * to apply to the subquery
690 * @param parameters the expressions from the outer query to bind
691 * the parameter in the subquery
692 * @see #addSubquery(Query sub, String variableDeclaration,
693 * String candidateCollectionExpression, String... parameters)
694 * @since 2.1
695 */
696 void addSubquery
697 (Query sub, String variableDeclaration,
698 String candidateCollectionExpression, Map parameters);
699
700 /**
701 * Specify a timeout interval (milliseconds) for any read operations
702 * associated with this query. To unset the explicit timeout for this
703 * query, specify null. For no timeout, specify 0.
704 * If the datastore granularity is larger than milliseconds, the
705 * timeout value will be rounded up to the nearest supported datastore
706 * value.
707 * If a read operation hasn't completed within this interval, executeXXX
708 * will throw a JDODatastoreException.
709 * If multiple datastore operations are required to complete the query,
710 * the timeout value applies to each of them individually.
711 * If the datastore and JDO implementation support timeouts, then
712 * javax.jdo.option.DatastoreTimeout is returned by
713 * PersistenceManagerFactory.supportedOptions().
714 * If timeouts are not supported,this method will throw
715 * JDOUnsupportedOptionException.
716 * @since 3.0
717 * @param interval the timeout interval (milliseconds)
718 */
719 void setDatastoreReadTimeoutMillis(Integer interval);
720
721 /** Get the effective timeout setting for read operations.
722 * If the timeout has not been set on this query explicitly, the effective
723 * datastore read timeout value from the persistence manager is returned.
724 * @see #setDatastoreReadTimeoutMillis(Integer)
725 * @see PersistenceManager#setDatastoreReadTimeoutMillis(Integer)
726 * @return the effective timeout setting (milliseconds).
727 * @since 3.0
728 */
729 Integer getDatastoreReadTimeoutMillis();
730
731 /**
732 * Specify a timeout interval (milliseconds) for any write operations
733 * associated with this query. To unset the explicit timeout for this
734 * query, specify null. For no timeout, specify 0.
735 * If the datastore granularity is larger than milliseconds, the
736 * timeout value will be rounded up to the nearest supported datastore
737 * value.
738 * If a write operation hasn't completed within this interval, deleteXXX
739 * will throw a JDODatastoreException.
740 * If multiple datastore operations are required to complete the query,
741 * the timeout value applies to each of them individually.
742 * If the datastore and JDO implementation support timeouts, then
743 * javax.jdo.option.DatastoreTimeout is returned by
744 * PersistenceManagerFactory.supportedOptions().
745 * If timeouts are not supported,this method will throw
746 * JDOUnsupportedOptionException.
747 * @since 3.0
748 * @param interval the timeout interval (milliseconds)
749 */
750 void setDatastoreWriteTimeoutMillis(Integer interval);
751
752 /** Get the effective timeout setting for write operations.
753 * If the timeout has not been set on this query explicitly, the effective
754 * datastore write timeout value from the persistence manager is returned.
755 * @see #setDatastoreWriteTimeoutMillis(Integer)
756 * @see PersistenceManager#setDatastoreWriteTimeoutMillis(Integer)
757 * @return the effective timeout setting (milliseconds).
758 * @since 3.0
759 */
760 Integer getDatastoreWriteTimeoutMillis();
761
762 /**
763 * Method to cancel any executing queries.
764 * If the underlying datastore doesn't support cancellation of queries this will
765 * throw JDOUnsupportedOptionException.
766 * If the cancellation fails (e.g in the underlying datastore) then this will throw
767 * a JDOException.
768 * @since 3.0
769 */
770 void cancelAll();
771
772 /**
773 * Method to cancel an executing query in the specified thread.
774 * If the underlying datastore doesn't support cancellation of queries this will
775 * throw JDOUnsupportedOptionException.
776 * If the cancellation fails (e.g in the underlying datastore) then this will throw
777 * a JDOException.
778 * @since 3.0
779 */
780 void cancel(Thread thread);
781
782 /**
783 * If <code>true</code>, a lock will be applied to all objects read in this
784 * query.
785 * <P>If <code>false</code> then retrieved objects will not be locked.
786 * If null will fallback to the value for metadata for the class in question.
787 * @param serialize the value of the serializeRead property
788 * @since 3.0
789 */
790 void setSerializeRead(Boolean serialize);
791
792 /**
793 * Return the current value of the serializeRead property.
794 * @return the value of the serializeRead property
795 * @since 3.0
796 */
797 Boolean getSerializeRead();
798 }