KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > jdo > 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 JavaDoc;
24 import java.util.Collection JavaDoc;
25 import java.util.Map JavaDoc;
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 JavaDoc {
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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc execute(Object JavaDoc 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 JavaDoc execute(Object JavaDoc p1, Object JavaDoc 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 JavaDoc execute(Object JavaDoc p1, Object JavaDoc p2, Object JavaDoc 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 JavaDoc executeWithMap (Map JavaDoc 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 JavaDoc executeWithArray (Object JavaDoc[] 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc key, Object JavaDoc 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 JavaDoc 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 JavaDoc[] 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 JavaDoc 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
Popular Tags