Query


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> 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      * Add a vendor-specific extension to this query. The key and value
461      * are not standard.
462      * An implementation must ignore keys that are not recognized.
463      * @param key the key of the extension
464      * @param value the value of the extension
465      * @since 2.0
466      */
467     void addExtension (String   key, Object   value);
468 
469     /**
470      * Set multiple extensions, or use null to clear all extensions.
471      * Map keys and values are not standard.
472      * An implementation must ignore entries that are not recognized.
473      * @param extensions the map of extensions
474      * @see #addExtension
475      * @since 2.0
476      */
477     void setExtensions (Map   extensions);
478 
479     /**
480      * Returns the <code>FetchPlan</code> used by this
481      * <code>Query</code>. Modifications of the returned fetch plan will not
482      * cause this query's owning <code>PersistenceManager</code>'s
483      * <code>FetchPlan</code> to be modified.
484      * @since 2.0
485      * @return the fetch plan used by this query
486      */
487     FetchPlan getFetchPlan ();
488 
489     /**
490      * Deletes all the instances of the candidate class that pass the
491      * filter.
492      * @see #deletePersistentAll()
493      * @param parameters for the query
494      * @return the number of instances of the candidate class that were deleted
495      * @since 2.0
496      */
497     long deletePersistentAll (Object  [] parameters);
498 
499     /**
500      * Deletes all the instances of the candidate class that pass the
501      * filter.
502      * @see #deletePersistentAll()
503      * @param parameters for the query
504      * @return the number of instances of the candidate class that were deleted
505      * @since 2.0
506      */
507     long deletePersistentAll (Map   parameters);
508 
509     /**
510      * Deletes all the instances of the candidate class that pass the
511      * filter. Returns the number of instances of the candidate
512      * class that were deleted, specifically not including the number
513      * of dependent and embedded instances.
514      * <P>Dirty instances of affected classes in the cache are first
515      * flushed to the datastore. Instances in the cache or brought into
516      * the cache as a result of executing one of the 
517      * <code>deletePersistentAll</code>
518      * methods undergo life cycle changes as if <code>deletePersistent</code>
519      * were called on them.
520      * <P>Specifically, if the class of deleted instances implements the
521      * delete callback interface, the corresponding callback methods
522      * are called on the deleted instances. Similarly, if there are
523      * lifecycle listeners registered for delete events on affected
524      * classes, the listener is called for each appropriate deleted instance.
525      * <P>Before returning control to the application, instances of affected
526      * classes in the cache are refreshed to reflect whether they were
527      * deleted from the datastore.
528      * 
529      * @return the number of instances of the candidate class that were deleted
530      * @since 2.0
531      */
532     long deletePersistentAll ();
533     
534     /**
535      * The unmodifiable flag, when set, disallows further 
536      * modification of the query, except for specifying the range, 
537      * result class, and ignoreCache option.
538      * The unmodifiable flag can also be set in metadata.
539      * @since 2.0
540       */
541     void setUnmodifiable();
542 
543     /**
544      * The unmodifiable flag, when set, disallows further 
545      * modification of the query, except for specifying the range, 
546      * result class, and ignoreCache option.
547      * @return the current setting of the flag
548      * @since 2.0
549       */
550     boolean isUnmodifiable();
551 
552 }
553 
554
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags