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