View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    * 
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software 
12   * distributed under the License is distributed on an "AS IS" BASIS, 
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
14   * See the License for the specific language governing permissions and 
15   * limitations under the License.
16   */
17  
18  /*
19   * Query.java
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 }