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      * <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 }