View Javadoc

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