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 * @return the filtered <code>Collection</code>.
273 * @see #executeWithArray(Object[] parameters)
274 */
275 Object execute();
276
277 /*** Execute the query and return the filtered <code>Collection</code>.
278 * @return the filtered <code>Collection</code>.
279 * @see #executeWithArray(Object[] parameters)
280 * @param p1 the value of the first parameter declared.
281 */
282 Object execute(Object p1);
283
284 /*** Execute the query and return the filtered <code>Collection</code>.
285 * @return the filtered <code>Collection</code>.
286 * @see #executeWithArray(Object[] parameters)
287 * @param p1 the value of the first parameter declared.
288 * @param p2 the value of the second parameter declared.
289 */
290 Object execute(Object p1, Object p2);
291
292 /*** Execute the query and return the filtered <code>Collection</code>.
293 * @return the filtered <code>Collection</code>.
294 * @see #executeWithArray(Object[] parameters)
295 * @param p1 the value of the first parameter declared.
296 * @param p2 the value of the second parameter declared.
297 * @param p3 the value of the third parameter declared.
298 */
299 Object execute(Object p1, Object p2, Object p3);
300
301 /*** Execute the query and return the filtered <code>Collection</code>. The
302 * query is executed with the parameters set by the <code>Map</code> values.
303 * Each <code>Map</code> entry consists of a key which is the name of the
304 * parameter in the <code>declareParameters</code> method, and a value which
305 * is the value used in the <code>execute</code> method. The keys in the
306 * <code>Map</code> and the declared parameters must exactly match or a
307 * <code>JDOUserException</code> is thrown.
308 * @return the filtered <code>Collection</code>.
309 * @see #executeWithArray(Object[] parameters)
310 * @param parameters the <code>Map</code> containing all of the parameters.
311 */
312 Object executeWithMap (Map parameters);
313
314 /*** Execute the query and return the filtered <code>Collection</code>.
315 *
316 * <P>The execution of the query obtains the values of the parameters and
317 * matches them against the declared parameters in order. The names
318 * of the declared parameters are ignored. The type of
319 * the declared parameters must match the type of the passed parameters,
320 * except that the passed parameters might need to be unwrapped to get
321 * their primitive values.
322 *
323 * <P>The filter, import, declared parameters, declared variables, and
324 * ordering statements are verified for consistency.
325 *
326 * <P>Each element in the candidate <code>Collection</code> is examined to
327 * see that it is assignment compatible to the <code>Class</code> of the
328 * query. It is then evaluated by the Boolean expression of the filter.
329 * The element passes the filter if there exist unique values for all
330 * variables for which the filter expression evaluates to <code>true</code>.
331 * @return the filtered <code>Collection</code>.
332 * @param parameters the <code>Object</code> array with all of the
333 * parameters.
334 */
335 Object executeWithArray (Object... parameters);
336
337 /*** Get the <code>PersistenceManager</code> associated with this
338 * <code>Query</code>.
339 *
340 * <P>If this <code>Query</code> was restored from a serialized form, it has
341 * no <code>PersistenceManager</code>, and this method returns
342 * <code>null</code>.
343 * @return the <code>PersistenceManager</code> associated with this
344 * <code>Query</code>.
345 */
346 PersistenceManager getPersistenceManager();
347
348 /*** Close a query result and release any resources associated with it. The
349 * parameter is the return from <code>execute(...)</code> and might have
350 * iterators open on it. Iterators associated with the query result are
351 * invalidated: they return <code>false</code> to <code>hasNext()</code>
352 * and throw <code>NoSuchElementException</code> to <code>next()</code>.
353 * @param queryResult the result of <code>execute(...)</code> on this
354 * <code>Query</code> instance.
355 */
356 void close (Object queryResult);
357
358 /*** Close all query results associated with this <code>Query</code>
359 * instance, and release all resources associated with them. The query
360 * results might have iterators open on them. Iterators associated with the
361 * query results are invalidated:
362 * they return <code>false</code> to <code>hasNext()</code> and throw
363 * <code>NoSuchElementException</code> to <code>next()</code>.
364 */
365 void closeAll ();
366
367 /***
368 * Set the grouping expressions, optionally including a "having"
369 * clause. When grouping is specified, each result expression
370 * must either be an expression contained in the grouping, or an
371 * aggregate evaluated once per group.
372 *
373 * @param group a comma-delimited list of expressions, optionally
374 * followed by the "having" keyword and a boolean expression
375 * @since 2.0
376 */
377 void setGrouping (String group);
378
379 /***
380 * Specify that only the first result of the query should be
381 * returned, rather than a collection. The execute method will
382 * return null if the query result size is 0.
383 * @since 2.0
384 * @param unique if true, only one element is returned
385 */
386 void setUnique (boolean unique);
387
388 /***
389 * Specifies what type of data this query should return. If this
390 * is unset or set to <code>null</code>, this query returns
391 * instances of the query's candidate class. If set, this query
392 * will return expressions, including field values (projections) and
393 * aggregate function results.
394 * @param data a comma-delimited list of expressions
395 * (fields, functions on fields, or aggregate functions)
396 * to return from this query
397 * @since 2.0
398 */
399 void setResult (String data);
400
401 /***
402 * Specify the type of object in which to return each element of
403 * the result of invoking {@link #execute} or one of its siblings.
404 * If the result is not set or set to null, the result class defaults
405 * to the candidate class of the query. If the result consists of one
406 * expression, the result class defaults to the type of that expression.
407 * If the result consists of more than one expression, the result class
408 * defaults to Object[].
409 * The result class may be specified to be one of the java.lang classes
410 * Character, Boolean, Byte, Short, Integer, Long, Float, Double, String,
411 * or Object[]; or one of the java.math classes BigInteger or BigDecimal;
412 * or the java.util class Date; or one of the java.sql classes Date,
413 * Time, or Timestamp; or a user-defined class.
414 * <P>If there are multiple result expressions, the result class
415 * must be able to hold all elements of the result specification
416 * or a JDOUserException is thrown.
417 *<P>If there is only one result expression, the result class must be
418 * assignable from the type of the result expression or must be able
419 * to hold all elements of the result specification. A single value
420 * must be able to be coerced into the specified result class
421 * (treating wrapper classes as equivalent to their unwrapped
422 * primitive types) or by matching. If the result class does not satisfy
423 * these conditions, a JDOUserException is thrown.
424 *<P>A constructor of a result class specified in the setResult method
425 * will be used if the results specification matches the parameters
426 * of the constructor by position and type. If more than one constructor
427 * satisfies the requirements, the JDO implementation chooses one of them.
428 * If no constructor satisfies the results requirements, or if the result
429 * class is specified via the setResultClass method, the following
430 * requirements apply:
431 * <ul>
432 * <li>A user-defined result class must have a no-args constructor and
433 * one or more public <code>set</code> or <code>put</code> methods or
434 * fields.
435 * <li>Each result expression must match one of:
436 * <ul>
437 * <li>a public field that matches the name of the result expression
438 * and is of the type (treating wrapper types equivalent to primitive
439 * types) of the result expression;
440 * <li>or if no public field matches the name and type, a public
441 * <code>set</code method that returns void and matches the name of the
442 * result expression and takes a single parameter which is the
443 * exact type of the result expression;
444 * <li>or if neither of the above applies,a public method must be found
445 * with the signature <code>void put(Object, Object)</code>.
446 * During processing of the results,
447 * the first argument is the name of the result expression and
448 * the second argument is the value from the query result.
449 * </ul>
450 * </ul>
451 * Portable result classes do not invoke any persistence behavior
452 * during their no-args constructor or <code>set</code methods.
453 * @param cls the result class
454 * @since 2.0
455 */
456 void setResultClass (Class cls);
457
458 /***
459 * Set the range of results to return. The execution of the query is
460 * modified to return only a subset of results. If the filter would
461 * normally return 100 instances, and fromIncl is set to 50, and
462 * toExcl is set to 70, then the first 50 results that would have
463 * been returned are skipped, the next 20 results are returned and the
464 * remaining 30 results are ignored. An implementation should execute
465 * the query such that the range algorithm is done at the data store.
466 * @param fromIncl 0-based inclusive start index
467 * @param toExcl 0-based exclusive end index, or
468 * {@link Long#MAX_VALUE} for no limit.
469 * @since 2.0
470 */
471 void setRange (long fromIncl, long toExcl);
472
473 /***
474 * Set the range of results to return. The parameter is a String
475 * containing a comma-separated fromIncl and toExcl. The fromIncl and
476 * toExcl can be either String representations of long values, or can
477 * be parameters identified with a leading ":". For example,
478 * <code>setRange("50, 70");</code> or
479 * <code>setRange(":from, :to");</code> or
480 * <code>setRange("50, :to");</code>.
481 * The execution of the query is
482 * modified to return only a subset of results. If the filter would
483 * normally return 100 instances, and fromIncl is set to 50, and
484 * toExcl is set to 70, then the first 50 results that would have
485 * been returned are skipped, the next 20 results are returned and the
486 * remaining 30 results are ignored. An implementation should execute
487 * the query such that the range algorithm is done at the data store.
488 * @param fromInclToExcl comma-separated fromIncl and toExcl values
489 * @see #setRange(long, long)
490 * @since 2.0
491 */
492 void setRange (String fromInclToExcl);
493
494 /***
495 * Add a vendor-specific extension to this query. The key and value
496 * are not standard.
497 * An implementation must ignore keys that are not recognized.
498 * @param key the key of the extension
499 * @param value the value of the extension
500 * @since 2.0
501 */
502 void addExtension (String key, Object value);
503
504 /***
505 * Set multiple extensions, or use null to clear all extensions.
506 * Map keys and values are not standard.
507 * An implementation must ignore entries that are not recognized.
508 * @param extensions the map of extensions
509 * @see #addExtension
510 * @since 2.0
511 */
512 void setExtensions (Map extensions);
513
514 /***
515 * Returns the <code>FetchPlan</code> used by this
516 * <code>Query</code>. Modifications of the returned fetch plan will not
517 * cause this query's owning <code>PersistenceManager</code>'s
518 * <code>FetchPlan</code> to be modified.
519 * @since 2.0
520 * @return the fetch plan used by this query
521 */
522 FetchPlan getFetchPlan ();
523
524 /***
525 * Deletes all the instances of the candidate class that pass the
526 * filter.
527 * @see #deletePersistentAll()
528 * @param parameters for the query
529 * @return the number of instances of the candidate class that were deleted
530 * @since 2.0
531 */
532 long deletePersistentAll (Object... parameters);
533
534 /***
535 * Deletes all the instances of the candidate class that pass the
536 * filter.
537 * @see #deletePersistentAll()
538 * @param parameters for the query
539 * @return the number of instances of the candidate class that were deleted
540 * @since 2.0
541 */
542 long deletePersistentAll (Map parameters);
543
544 /***
545 * Deletes all the instances of the candidate class that pass the
546 * filter. Returns the number of instances of the candidate
547 * class that were deleted, specifically not including the number
548 * of dependent and embedded instances.
549 * <P>Dirty instances of affected classes in the cache are first
550 * flushed to the datastore. Instances in the cache or brought into
551 * the cache as a result of executing one of the
552 * <code>deletePersistentAll</code>
553 * methods undergo life cycle changes as if <code>deletePersistent</code>
554 * were called on them.
555 * <P>Specifically, if the class of deleted instances implements the
556 * delete callback interface, the corresponding callback methods
557 * are called on the deleted instances. Similarly, if there are
558 * lifecycle listeners registered for delete events on affected
559 * classes, the listener is called for each appropriate deleted instance.
560 * <P>Before returning control to the application, instances of affected
561 * classes in the cache are refreshed to reflect whether they were
562 * deleted from the datastore.
563 *
564 * @return the number of instances of the candidate class that were deleted
565 * @since 2.0
566 */
567 long deletePersistentAll ();
568
569 /***
570 * The unmodifiable flag, when set, disallows further
571 * modification of the query, except for specifying the range,
572 * result class, and ignoreCache option.
573 * The unmodifiable flag can also be set in metadata.
574 * @since 2.0
575 */
576 void setUnmodifiable();
577
578 /***
579 * The unmodifiable flag, when set, disallows further
580 * modification of the query, except for specifying the range,
581 * result class, and ignoreCache option.
582 * @return the current setting of the flag
583 * @since 2.0
584 */
585 boolean isUnmodifiable();
586
587 /***
588 * Add a subquery to this query.
589 * @param sub the subquery to add to this Query
590 * @param variableDeclaration the name of the variable in the outer query
591 * to bind the results of the subquery
592 * @param candidateCollectionExpression the candidate collection
593 * of the subquery as an expression using terms of the outer query
594 * @see #addSubquery(Query sub, String variableDeclaration,
595 * String candidateCollectionExpression, String... parameters)
596 * @since 2.1
597 */
598 void addSubquery
599 (Query sub, String variableDeclaration,
600 String candidateCollectionExpression);
601
602 /***
603 * Add a subquery to this query.
604 * The String version of the method binds the named expression
605 * to the parameter implictly or explicitly declared in the
606 * subquery.
607 * @param sub the subquery to add to this Query
608 * @param variableDeclaration the name of the variable
609 * to be used in this Query
610 * @param candidateCollectionExpression the candidate collection
611 * to apply to the subquery
612 * @param parameter the expression from the outer query to bind
613 * the parameter in the subquery
614 * @see #addSubquery(Query sub, String variableDeclaration,
615 * String candidateCollectionExpression, String... parameters)
616 * @since 2.1
617 */
618 void addSubquery
619 (Query sub, String variableDeclaration,
620 String candidateCollectionExpression, String parameter);
621
622 /***
623 * Add a subquery to this query.
624 * A subquery is composed as a Query and subsequently attached
625 * to a different query (the outer query) by calling this method.
626 * The query parameter instance is unmodified as a result of the
627 * addSubquery or subsequent execution of the outer query.
628 * Only some of the query parts are copied for use as the subquery.
629 * The parts copied include the candidate class, filter, parameter
630 * declarations, variable declarations, imports, ordering specification,
631 * uniqueness, result specification, and grouping specification.
632 * The association with a PersistenceManager, the candidate collection
633 * or extent, result class, and range limits are not used.
634 * The String parameters are trimmed of white space.
635 * The variableDeclaration parameter is the name of the variable
636 * containing the results of the subquery execution. If the same value
637 * of variableDeclaration is used to add multiple subqueries, the
638 * subquery replaces the previous subquery for the same named variable.
639 * If the subquery parameter is null, the variable is unset,
640 * effectively making the variable named in the variableDeclaration
641 * unbound. If the trimmed value is the empty String, or the parameter
642 * is null, then JDOUserException is thrown.
643 * The candidateCollectionExpression is the expression from the
644 * outer query that represents the candidates over which the subquery
645 * is evaluated. If the trimmed value is the empty String, or the
646 * parameter is null, then the candidate collection is the extent
647 * of the candidate class.
648 * The String... version of the method binds the named expressions in
649 * turn to parameters in the order in which they are declared in the
650 * subquery, or in the order they are found in the filter if not
651 * explicitly declared in the subquery.
652 * @param sub the subquery to add to this Query
653 * @param variableDeclaration the name of the variable in the outer query
654 * to bind the results of the subquery
655 * @param candidateCollectionExpression the candidate collection
656 * of the subquery as an expression using terms of the outer query
657 * @param parameters the expressions from the outer query to bind
658 * the parameters in the subquery
659 * @since 2.1
660 */
661 void addSubquery
662 (Query sub, String variableDeclaration,
663 String candidateCollectionExpression, String... parameters);
664
665 /***
666 * Add a subquery to this query.
667 * The Map version of the method treats the key of each map entry as
668 * the name of the parameter in the subquery, with or without the
669 * leading ":", and the value as the name of the expression in the
670 * outer query. If the trimmed expression is the empty String for
671 * either the parameter or the value of the String[], or for any
672 * map key or value, that expression is ignored.
673 * @param sub the subquery to add to this Query
674 * @param variableDeclaration the name of the variable
675 * to be used in this Query
676 * @param candidateCollectionExpression the candidate collection
677 * to apply to the subquery
678 * @param parameters the expressions from the outer query to bind
679 * the parameter in the subquery
680 * @see #addSubquery(Query sub, String variableDeclaration,
681 * String candidateCollectionExpression, String... parameters)
682 * @since 2.1
683 */
684 void addSubquery
685 (Query sub, String variableDeclaration,
686 String candidateCollectionExpression, Map parameters);
687
688 }