1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 package javax.jdo;
23 import java.io.Serializable;
24 import java.util.Collection;
25 import java.util.Map;
26
27 /*** The <code>Query</code> interface allows applications to obtain persistent
28 * instances, values, and aggregate data
29 * from the data store.
30 *
31 * The {@link PersistenceManager} is the factory for <code>Query</code>
32 * instances. There may be many <code>Query</code> instances associated with a
33 * <code>PersistenceManager</code>. Multiple queries might be executed
34 * simultaneously by different threads, but the implementation might choose to
35 * execute them serially. In either case, the implementation must be thread
36 * safe.
37 *
38 * <P>There are three required elements in a <code>Query</code>: the class of
39 * the results, the candidate collection of instances, and the filter.
40 *
41 * <P>There are optional elements: parameter declarations, variable
42 * declarations, import statements, ordering and grouping specifications,
43 * result and result class, the range of results,
44 * and flags indicating whether the query result
45 * is unique and whether the query can be modified.
46 * <P>The query namespace is modeled after methods in Java:
47 * <ul>
48 * <li><code>setClass</code> corresponds to the class definition
49 * <li><code>declareParameters</code> corresponds to formal parameters of a
50 * method
51 * <li><code>declareVariables</code> corresponds to local variables of a method
52 * <li><code>setFilter</code> and <code>setOrdering</code> correspond to the
53 * method body
54 * </ul>
55 * <P>There are two namespaces in queries. Type names have their own
56 * namespace that is separate from the namespace for fields, variables
57 * and parameters.
58 * <P>The method <code>setClass</code> introduces the name of the candidate
59 * class in the type namespace. The method <code>declareImports</code>
60 * introduces the names of the imported class or interface types in the type
61 * namespace. Imported type names must be unique. When used (e.g. in a parameter
62 * declaration, cast expression, etc.) a type name must be the name of the
63 * candidate class, the name of a class or interface imported by method
64 * <code>declareImports</code>, or denote a class or interface from the same
65 * package as the candidate class.
66 * <P>The method <code>setClass</code> introduces the names of the candidate
67 * class fields.
68 * <P>The method <code>declareParameters</code> introduces the names of the
69 * parameters. A name introduced by <code>declareParameters</code> hides the
70 * name of a candidate class field of the same name. Parameter names must be
71 * unique.
72 * <P>The method <code>declareVariables</code> introduces the names of the
73 * variables. A name introduced by <code>declareVariables</code> hides the name
74 * of a candidate class field if equal. Variable names must be unique and must
75 * not conflict with parameter names.
76 * <P>The result of the query by default is a list of result class instances,
77 * but might be specified via <code>setResult</code>. The class of the result
78 * by default is the candidate class, but might be specified via
79 * <code>setResultClass</code>.
80 * <P>A hidden field may be accessed using the 'this' qualifier:
81 * <code>this.fieldName</code>.
82 * <P>The <code>Query</code> interface provides methods which execute the query
83 * based on the parameters given. They return a single instance or a
84 * <code>List</code> of result class instances which the
85 * user can iterate to get results. The signature
86 * of the <code>execute</code> methods specifies that they return an
87 * <code>Object</code> which must be cast to the appropriate result by the user.
88 * <P>Any parameters passed to the <code>execute</code> methods are used only
89 * for this execution, and are not remembered for future execution.
90 * @version 2.0
91 */
92
93 public interface Query extends Serializable {
94
95 /***
96 * The string constant used as the first argument to
97 * {@link PersistenceManager#newQuery(String,Object)} to identify that the
98 * created query should obey the JDOQL syntax and semantic rules.
99 * <p>This is the default query language used when creating a query with any
100 * of the other {@link PersistenceManager#newQuery} methods, except
101 * {@link PersistenceManager#newQuery(Object)}, which uses the query
102 * language of the compiled query template object passed to that method.</p>
103 * @since 2.0
104 */
105 String JDOQL = "javax.jdo.query.JDOQL";
106
107 /***
108 * The string constant used as the first argument to {@link
109 * PersistenceManager#newQuery(String,Object)} to identify that
110 * the created query should use SQL semantics. This is only
111 * meaningful for relational JDO implementations.
112 * <p>If this is used, the <code>Object</code> argument to the
113 * {@link PersistenceManager#newQuery(String,Object)} method
114 * should be a <code>String</code> containing a SQL
115 * <code>SELECT</code> statement.</p>
116 * @since 2.0
117 */
118 String SQL = "javax.jdo.query.SQL";
119
120 /*** Set the class of the candidate instances of the query.
121 * <P>The class specifies the class
122 * of the candidates of the query. Elements of the candidate collection
123 * that are of the specified class are filtered before being
124 * put into the result <code>Collection</code>.
125 *
126 * @param cls the <code>Class</code> of the candidate instances.
127 */
128 void setClass(Class cls);
129
130 /*** Set the candidate <code>Extent</code> to query.
131 * @param pcs the candidate <code>Extent</code>.
132 */
133 void setCandidates(Extent pcs);
134
135 /*** Set the candidate <code>Collection</code> to query.
136 * @param pcs the candidate <code>Collection</code>.
137 */
138 void setCandidates(Collection pcs);
139
140 /*** Set the filter for the query.
141 *
142 * <P>The filter specification is a <code>String</code> containing a Boolean
143 * expression that is to be evaluated for each of the instances
144 * in the candidate collection. If the filter is not specified,
145 * then it defaults to "true", which has the effect of filtering
146 * the input <code>Collection</code> only for class type.
147 * <P>An element of the candidate collection is returned in the result if:
148 * <ul><li>it is assignment compatible to the candidate <code>Class</code>
149 * of the <code>Query</code>; and
150 * <li>for all variables there exists a value for which the filter
151 * expression evaluates to <code>true</code>.
152 * </ul>
153 * <P>The user may denote uniqueness in the filter expression by
154 * explicitly declaring an expression (for example, <code>e1 != e2</code>).
155 * <P>Rules for constructing valid expressions follow the Java
156 * language, except for these differences:
157 * <ul>
158 * <li>Equality and ordering comparisons between primitives and instances
159 * of wrapper classes are valid.
160 * <li>Equality and ordering comparisons of <code>Date</code> fields and
161 * <code>Date</code> parameters are valid.
162 * <li>White space (non-printing characters space, tab, carriage
163 * return, and line feed) is a separator and is otherwise ignored.
164 * <li>The assignment operators <code>=</code>, <code>+=</code>, etc. and
165 * pre- and post-increment and -decrement are not supported. Therefore,
166 * there are no side effects from evaluation of any expressions.
167 * <li>Methods, including object construction, are not supported, except
168 * for <code>Collection.contains(Object o)</code>,
169 * <code>Collection.isEmpty()</code>,
170 * <code>String.startsWith(String s)</code>, and
171 * <code>String.endsWith(String e)</code>. Implementations might choose to
172 * support non-mutating method calls as non-standard extensions.
173 * <li>Navigation through a <code>null</code>-valued field, which would
174 * throw <code>NullPointerException</code>, is treated as if the filter
175 * expression returned <code>false</code> for the evaluation of the current
176 * set of variable values. Other values for variables might still qualify
177 * the candidate instance for inclusion in the result set.
178 * <li>Navigation through multi-valued fields (<code>Collection</code>
179 * types) is specified using a variable declaration and the
180 * <code>Collection.contains(Object o)</code> method.
181 * </ul>
182 * <P>Identifiers in the expression are considered to be in the name
183 * space of the specified class, with the addition of declared imports,
184 * parameters and variables. As in the Java language, <code>this</code> is a
185 * reserved word which means the element of the collection being evaluated.
186 * <P>Navigation through single-valued fields is specified by the Java
187 * language syntax of <code>field_name.field_name....field_name</code>.
188 * <P>A JDO implementation is allowed to reorder the filter expression
189 * for optimization purposes.
190 * @param filter the query filter.
191 */
192 void setFilter(String filter);
193
194 /*** Set the import statements to be used to identify the fully qualified
195 * name of variables or parameters. Parameters and unbound variables might
196 * come from a different class from the candidate class, and the names
197 * need to be declared in an import statement to eliminate ambiguity.
198 * Import statements are specified as a <code>String</code> with
199 * semicolon-separated statements.
200 * <P>The <code>String</code> parameter to this method follows the syntax of
201 * the import statement of the Java language.
202 * @param imports import statements separated by semicolons.
203 */
204 void declareImports(String imports);
205
206 /*** Declare the list of parameters query execution.
207 *
208 * The parameter declaration is a <code>String</code> containing one or more
209 * query parameter declarations separated with commas. Each parameter named
210 * in the parameter declaration must be bound to a value when
211 * the query is executed.
212 * <P>The <code>String</code> parameter to this method follows the syntax
213 * for formal parameters in the Java language.
214 * @param parameters the list of parameters separated by commas.
215 */
216 void declareParameters(String parameters);
217
218 /*** Declare the unbound variables to be used in the query. Variables
219 * might be used in the filter, and these variables must be declared
220 * with their type. The unbound variable declaration is a
221 * <code>String</code> containing one or more unbound variable declarations
222 * separated with semicolons. It follows the syntax for local variables in
223 * the Java language.
224 * @param variables the variables separated by semicolons.
225 */
226 void declareVariables(String variables);
227
228 /*** Set the ordering specification for the result <code>Collection</code>.
229 * The ordering specification is a <code>String</code> containing one or
230 * more ordering declarations separated by commas.
231 *
232 * <P>Each ordering declaration is the name of the field on which
233 * to order the results followed by one of the following words:
234 * "<code>ascending</code>" or "<code>descending</code>".
235 *
236 *<P>The field must be declared in the candidate class or must be
237 * a navigation expression starting with a field in the candidate class.
238 *
239 *<P>Valid field types are primitive types except <code>boolean</code>;
240 * wrapper types except <code>Boolean</code>; <code>BigDecimal</code>;
241 * <code>BigInteger</code>; <code>String</code>; and <code>Date</code>.
242 * @param ordering the ordering specification.
243 */
244 void setOrdering(String ordering);
245
246 /*** Set the ignoreCache option. The default value for this option was
247 * set by the <code>PersistenceManagerFactory</code> or the
248 * <code>PersistenceManager</code> used to create this <code>Query</code>.
249 *
250 * The ignoreCache option setting specifies whether the query should execute
251 * entirely in the back end, instead of in the cache. If this flag is set
252 * to <code>true</code>, an implementation might be able to optimize the
253 * query execution by ignoring changed values in the cache. For optimistic
254 * transactions, this can dramatically improve query response times.
255 * @param ignoreCache the setting of the ignoreCache option.
256 */
257 void setIgnoreCache(boolean ignoreCache);
258
259 /*** Get the ignoreCache option setting.
260 * @return the ignoreCache option setting.
261 * @see #setIgnoreCache
262 */
263 boolean getIgnoreCache();
264
265 /*** Verify the elements of the query and provide a hint to the query to
266 * prepare and optimize an execution plan.
267 */
268 void compile();
269
270 /*** Execute the query and return the filtered Collection.
271 * @return the filtered <code>Collection</code>.
272 * @see #executeWithArray(Object[] parameters)
273 */
274 Object execute();
275
276 /*** Execute the query and return the filtered <code>Collection</code>.
277 * @return the filtered <code>Collection</code>.
278 * @see #executeWithArray(Object[] parameters)
279 * @param p1 the value of the first parameter declared.
280 */
281 Object execute(Object p1);
282
283 /*** Execute the query and return the filtered <code>Collection</code>.
284 * @return the filtered <code>Collection</code>.
285 * @see #executeWithArray(Object[] parameters)
286 * @param p1 the value of the first parameter declared.
287 * @param p2 the value of the second parameter declared.
288 */
289 Object execute(Object p1, Object p2);
290
291 /*** Execute the query and return the filtered <code>Collection</code>.
292 * @return the filtered <code>Collection</code>.
293 * @see #executeWithArray(Object[] parameters)
294 * @param p1 the value of the first parameter declared.
295 * @param p2 the value of the second parameter declared.
296 * @param p3 the value of the third parameter declared.
297 */
298 Object execute(Object p1, Object p2, Object p3);
299
300 /*** Execute the query and return the filtered <code>Collection</code>. The
301 * query is executed with the parameters set by the <code>Map</code> values.
302 * Each <code>Map</code> entry consists of a key which is the name of the
303 * parameter in the <code>declareParameters</code> method, and a value which
304 * is the value used in the <code>execute</code> method. The keys in the
305 * <code>Map</code> and the declared parameters must exactly match or a
306 * <code>JDOUserException</code> is thrown.
307 * @return the filtered <code>Collection</code>.
308 * @see #executeWithArray(Object[] parameters)
309 * @param parameters the <code>Map</code> containing all of the parameters.
310 */
311 Object executeWithMap (Map parameters);
312
313 /*** Execute the query and return the filtered <code>Collection</code>.
314 *
315 * <P>The execution of the query obtains the values of the parameters and
316 * matches them against the declared parameters in order. The names
317 * of the declared parameters are ignored. The type of
318 * the declared parameters must match the type of the passed parameters,
319 * except that the passed parameters might need to be unwrapped to get
320 * their primitive values.
321 *
322 * <P>The filter, import, declared parameters, declared variables, and
323 * ordering statements are verified for consistency.
324 *
325 * <P>Each element in the candidate <code>Collection</code> is examined to
326 * see that it is assignment compatible to the <code>Class</code> of the
327 * query. It is then evaluated by the Boolean expression of the filter.
328 * The element passes the filter if there exist unique values for all
329 * variables for which the filter expression evaluates to <code>true</code>.
330 * @return the filtered <code>Collection</code>.
331 * @param parameters the <code>Object</code> array with all of the
332 * parameters.
333 */
334 Object executeWithArray (Object[] parameters);
335
336 /*** Get the <code>PersistenceManager</code> associated with this
337 * <code>Query</code>.
338 *
339 * <P>If this <code>Query</code> was restored from a serialized form, it has
340 * no <code>PersistenceManager</code>, and this method returns
341 * <code>null</code>.
342 * @return the <code>PersistenceManager</code> associated with this
343 * <code>Query</code>.
344 */
345 PersistenceManager getPersistenceManager();
346
347 /*** Close a query result and release any resources associated with it. The
348 * parameter is the return from <code>execute(...)</code> and might have
349 * iterators open on it. Iterators associated with the query result are
350 * invalidated: they return <code>false</code> to <code>hasNext()</code>
351 * and throw <code>NoSuchElementException</code> to <code>next()</code>.
352 * @param queryResult the result of <code>execute(...)</code> on this
353 * <code>Query</code> instance.
354 */
355 void close (Object queryResult);
356
357 /*** Close all query results associated with this <code>Query</code>
358 * instance, and release all resources associated with them. The query
359 * results might have iterators open on them. Iterators associated with the
360 * query results are invalidated:
361 * they return <code>false</code> to <code>hasNext()</code> and throw
362 * <code>NoSuchElementException</code> to <code>next()</code>.
363 */
364 void closeAll ();
365
366 /***
367 * Set the grouping expressions, optionally including a "having"
368 * clause. When grouping is specified, each result expression
369 * must either be an expression contained in the grouping, or an
370 * aggregate evaluated once per group.
371 *
372 * @param group a comma-delimited list of expressions, optionally
373 * followed by the "having" keyword and a boolean expression
374 * @since 2.0
375 */
376 void setGrouping (String group);
377
378 /***
379 * Specify that only the first result of the query should be
380 * returned, rather than a collection. The execute method will
381 * return null if the query result size is 0.
382 * @since 2.0
383 * @param unique if true, only one element is returned
384 */
385 void setUnique (boolean unique);
386
387 /***
388 * Specifies what type of data this query should return. If this
389 * is unset or set to <code>null</code>, this query returns
390 * instances of the query's candidate class. If set, this query
391 * will return expressions, including field values (projections) and
392 * aggregate function results.
393 * @param data a comma-delimited list of expressions
394 * (fields, functions on fields, or aggregate functions)
395 * to return from this query
396 * @since 2.0
397 */
398 void setResult (String data);
399
400 /***
401 * Specify the type of object in which to return each element of
402 * the result of invoking {@link #execute} or one of its siblings.
403 * If the result is not set or set to null, the result class defaults
404 * to the candidate class of the query. If the result consists of one
405 * expression, the result class defaults to the type of that expression.
406 * If the result consists of more than one expression, the result class
407 * defaults to Object[].
408 * The result class may be specified to be one of the java.lang classes
409 * Character, Boolean, Byte, Short, Integer, Long, Float, Double, String,
410 * or Object[]; or one of the java.math classes BigInteger or BigDecimal;
411 * or the java.util class Date; or one of the java.sql classes Date,
412 * Time, or Timestamp; or a user-defined class.
413 * <P>If there are multiple result expressions, the result class
414 * must be able to hold all elements of the result specification
415 * or a JDOUserException is thrown.
416 *<P>If there is only one result expression, the result class must be
417 * assignable from the type of the result expression or must be able
418 * to hold all elements of the result specification. A single value
419 * must be able to be coerced into the specified result class
420 * (treating wrapper classes as equivalent to their unwrapped
421 * primitive types) or by matching. If the result class does not satisfy
422 * these conditions, a JDOUserException is thrown.
423 *<P>A constructor of a result class specified in the setResult method
424 * will be used if the results specification matches the parameters
425 * of the constructor by position and type. If more than one constructor
426 * satisfies the requirements, the JDO implementation chooses one of them.
427 * If no constructor satisfies the results requirements, or if the result
428 * class is specified via the setResultClass method, the following
429 * requirements apply:
430 * <ul>
431 * <li>A user-defined result class must have a no-args constructor and
432 * one or more public <code>set</code> or <code>put</code> methods or
433 * fields.
434 * <li>Each result expression must match one of:
435 * <ul>
436 * <li>a public field that matches the name of the result expression
437 * and is of the type (treating wrapper types equivalent to primitive
438 * types) of the result expression;
439 * <li>or if no public field matches the name and type, a public
440 * <code>set</code method that returns void and matches the name of the
441 * result expression and takes a single parameter which is the
442 * exact type of the result expression;
443 * <li>or if neither of the above applies,a public method must be found
444 * with the signature <code>void put(Object, Object)</code>.
445 * During processing of the results,
446 * the first argument is the name of the result expression and
447 * the second argument is the value from the query result.
448 * </ul>
449 * </ul>
450 * Portable result classes do not invoke any persistence behavior
451 * during their no-args constructor or <code>set</code methods.
452 * @param cls the result class
453 * @since 2.0
454 */
455 void setResultClass (Class cls);
456
457 /***
458 * Set the range of results to return. The execution of the query is
459 * modified to return only a subset of results. If the filter would
460 * normally return 100 instances, and fromIncl is set to 50, and
461 * toExcl is set to 70, then the first 50 results that would have
462 * been returned are skipped, the next 20 results are returned and the
463 * remaining 30 results are ignored. An implementation should execute
464 * the query such that the range algorithm is done at the data store.
465 * @param fromIncl 0-based inclusive start index
466 * @param toExcl 0-based exclusive end index, or
467 * {@link Long#MAX_VALUE} for no limit.
468 * @since 2.0
469 */
470 void setRange (long fromIncl, long toExcl);
471
472 /***
473 * Set the range of results to return. The parameter is a String
474 * containing a comma-separated fromIncl and toExcl. The fromIncl and
475 * toExcl can be either String representations of long values, or can
476 * be parameters identified with a leading ":". For example,
477 * <code>setRange("50, 70");</code> or
478 * <code>setRange(":from, :to");</code> or
479 * <code>setRange("50, :to");</code>.
480 * The execution of the query is
481 * modified to return only a subset of results. If the filter would
482 * normally return 100 instances, and fromIncl is set to 50, and
483 * toExcl is set to 70, then the first 50 results that would have
484 * been returned are skipped, the next 20 results are returned and the
485 * remaining 30 results are ignored. An implementation should execute
486 * the query such that the range algorithm is done at the data store.
487 * @param fromInclToExcl comma-separated fromIncl and toExcl values
488 * @see #setRange(long, long)
489 * @since 2.0
490 */
491 void setRange (String fromInclToExcl);
492
493 /***
494 * Add a vendor-specific extension to this query. The key and value
495 * are not standard.
496 * An implementation must ignore keys that are not recognized.
497 * @param key the key of the extension
498 * @param value the value of the extension
499 * @since 2.0
500 */
501 void addExtension (String key, Object value);
502
503 /***
504 * Set multiple extensions, or use null to clear all extensions.
505 * Map keys and values are not standard.
506 * An implementation must ignore entries that are not recognized.
507 * @param extensions the map of extensions
508 * @see #addExtension
509 * @since 2.0
510 */
511 void setExtensions (Map extensions);
512
513 /***
514 * Returns the <code>FetchPlan</code> used by this
515 * <code>Query</code>. Modifications of the returned fetch plan will not
516 * cause this query's owning <code>PersistenceManager</code>'s
517 * <code>FetchPlan</code> to be modified.
518 * @since 2.0
519 * @return the fetch plan used by this query
520 */
521 FetchPlan getFetchPlan ();
522
523 /***
524 * Deletes all the instances of the candidate class that pass the
525 * filter.
526 * @see #deletePersistentAll()
527 * @param parameters for the query
528 * @return the number of instances of the candidate class that were deleted
529 * @since 2.0
530 */
531 long deletePersistentAll (Object[] parameters);
532
533 /***
534 * Deletes all the instances of the candidate class that pass the
535 * filter.
536 * @see #deletePersistentAll()
537 * @param parameters for the query
538 * @return the number of instances of the candidate class that were deleted
539 * @since 2.0
540 */
541 long deletePersistentAll (Map parameters);
542
543 /***
544 * Deletes all the instances of the candidate class that pass the
545 * filter. Returns the number of instances of the candidate
546 * class that were deleted, specifically not including the number
547 * of dependent and embedded instances.
548 * <P>Dirty instances of affected classes in the cache are first
549 * flushed to the datastore. Instances in the cache or brought into
550 * the cache as a result of executing one of the
551 * <code>deletePersistentAll</code>
552 * methods undergo life cycle changes as if <code>deletePersistent</code>
553 * were called on them.
554 * <P>Specifically, if the class of deleted instances implements the
555 * delete callback interface, the corresponding callback methods
556 * are called on the deleted instances. Similarly, if there are
557 * lifecycle listeners registered for delete events on affected
558 * classes, the listener is called for each appropriate deleted instance.
559 * <P>Before returning control to the application, instances of affected
560 * classes in the cache are refreshed to reflect whether they were
561 * deleted from the datastore.
562 *
563 * @return the number of instances of the candidate class that were deleted
564 * @since 2.0
565 */
566 long deletePersistentAll ();
567
568 /***
569 * The unmodifiable flag, when set, disallows further
570 * modification of the query, except for specifying the range,
571 * result class, and ignoreCache option.
572 * The unmodifiable flag can also be set in metadata.
573 * @since 2.0
574 */
575 void setUnmodifiable();
576
577 /***
578 * The unmodifiable flag, when set, disallows further
579 * modification of the query, except for specifying the range,
580 * result class, and ignoreCache option.
581 * @return the current setting of the flag
582 * @since 2.0
583 */
584 boolean isUnmodifiable();
585
586 }