KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > versant > core > jdo > VersantQuery


1
2 /*
3  * Copyright (c) 1998 - 2005 Versant Corporation
4  * All rights reserved. This program and the accompanying materials
5  * are made available under the terms of the Eclipse Public License v1.0
6  * which accompanies this distribution, and is available at
7  * http://www.eclipse.org/legal/epl-v10.html
8  *
9  * Contributors:
10  * Versant Corporation - initial API and implementation
11  */

12 package com.versant.core.jdo;
13
14 import javax.jdo.Query;
15
16 /**
17  * <p>This interface provides additional Open Access specific query properties.
18  * There are two ways to use these properties in your applications:</p>
19  * <ol>
20  * <li>Cast the Query returned by PersistenceManager.newQuery(...) to a
21  * VersantQuery and call the setXXX methods. This is clear in code
22  * but non-portable to other JDO implementations.
23  * <li>Add a 'String versantOptions' parameter to the query and specify a
24  * semicolon delimited String of property=value pairs when the query is
25  * executed. Portability is maintained as other JDO implementations should
26  * ignore this parameter.
27  * </ol>
28  * <p/>
29  * <p>Example using casting:</p>
30  * <pre>
31  * VersantQuery q = (VersantQuery)pm.newQuery(Item.class);
32  * q.setFetchGroup("codeOnly");
33  * q.setRandomAccess(true);
34  * Collection ans = (Collection)q.execute();
35  * ...
36  * </pre>
37  * <p/>
38  * <p>Example using versantOptions parameter:</p>
39  * <pre>
40  * Query q = pm.newQuery(Item.class);
41  * q.declareParameters("String versantOptions");
42  * Collection ans = (Collection)q.execute("fetchGroup=codeOnly;randomAccess=true");
43  * ...
44  * </pre>
45  */

46 public interface VersantQuery extends Query {
47
48     public static final String JavaDoc VERSANT_OPTIONS = "versantOptions";
49     /**
50      * @deprecated Use {@link #VERSANT_OPTIONS} instead.
51      */

52     public static final String JavaDoc JDO_GENIE_OPTIONS = "jdoGenieOptions";
53
54     /**
55      * Select the fetch group used to execute the query. JDO Genie fetch groups
56      * control exactly which fields are returned in each instance. They
57      * also make it possible to fetch other referenced instances and
58      * collections at the same time i.e. you can prefetch a large part
59      * of your object graph with a single query.
60      */

61     public void setFetchGroup(String JavaDoc fetchGroupName);
62
63     public String JavaDoc getFetchGroup();
64
65     /**
66      * Indicate that random access to query results is required or not. If this
67      * is true then the collection returned by execute can be cast to a
68      * List and the get(index) method can be used to get any entry in the list.
69      * JDO Genie must use a scrollable JDBC ResultSet to provide this
70      * functionality. This may use more database resources (cursors etc.)
71      * than a normal forward only ResultSet. This option is useful for paged
72      * results i.e. you only want a few results from position n onwards.
73      */

74     public void setRandomAccess(boolean on);
75
76     public boolean isRandomAccess();
77
78     /**
79      * Limit the number of instances to be returned. If this property has
80      * been set and {@link #setFetchSize} is not set then the batchSize
81      * is set to maxRows.
82      *
83      * @see #setFetchSize
84      * @see #getMaxRows
85      */

86     public void setMaxRows(int amount);
87
88     /**
89      * The maximum number of instances to return.
90      *
91      * @see #setMaxRows
92      */

93     public int getMaxRows();
94
95     /**
96      * Set the number of instances fetched per server round trip. This
97      * property controls JDO Genie's own batching and is also passed
98      * through to JDBC drivers that support this. If this property is
99      * not set and maxRows is set then the default is maxRows.
100      *
101      * @see #getFetchSize
102      */

103     public void setFetchSize(int value);
104
105     /**
106      * The number of instances fetched from server per round trip.
107      *
108      * @see #setFetchSize
109      */

110     public int getFetchSize();
111
112     /**
113      * <p>Normally when size() is called on the Collection returned by executing
114      * a non-randomAccess Query all of the results are fetched in one operation
115      * to detirmine the size of the collection. If this property is true then
116      * a 'select count(*) ...' version of the query is used to count the
117      * results. Subsequent calls to to size() after the first call will revert
118      * to normal behaviour and resolve all of the results.</p>
119      * <p/>
120      * <p>Note that the actual number of results might differ to those first
121      * returned by size() when this option is used. This can happen if new
122      * rows that meet the filter criteria are inserted after the
123      * 'select count(*)...' query has run but before the normal 'select ...'
124      * to fetch the data. This may be possible even in a non-optimistic
125      * transaction depending on how the database handles locking.</p>
126      *
127      * @see #setRandomAccess(boolean)
128      * @see #isCountStarOnSize()
129      */

130     public void setCountStarOnSize(boolean on);
131
132     /**
133      * Has the count(*) option been set?
134      *
135      * @see #setCountStarOnSize(boolean)
136      */

137     public boolean isCountStarOnSize();
138
139     /**
140      * This property is a hint to JDO Genie that the number of instances
141      * returned by the query us limited. If it is true then collections and
142      * maps are fetched in bulk using parallel queries derived from the
143      * orginal filter expression. If it is false then individual queries are
144      * issued for each collection or map for each instance in the result.
145      * The default setting is false.
146      */

147     public void setBounded(boolean value);
148
149     /**
150      * Has the bounded option been set?
151      *
152      * @see #setBounded(boolean)
153      */

154     public boolean isBounded();
155
156     /**
157      * Get the query plan for this query. This will include the SQL and
158      * possibly also a query plan for the SQL from the database itself.
159      * The params are as for executeWithArray.
160      *
161      * @see #executeWithArray
162      */

163     public VersantQueryPlan getPlan(Object JavaDoc[] params);
164
165     /**
166      * <p>Register classes that will cause the cached results of this query to
167      * be evicted if any of its instances are modified. These replace any
168      * previously set classes. JDO Genie will automatically pickup the
169      * candidate class and classes involved in the filter or ordering. You
170      * only need to call this method if you are using inline SQL to touch
171      * tables for classes not otherwise involved in the query. Here is an
172      * example:</p>
173      * <p/>
174      * <code>Query q = pm.newQuery(Order.class);<br>
175      * String aclCheck = "$1 in (select $1 from acl where user_id = " + userId + ")";<br>
176      * q.setFilter("owner.sql(\"" + aclCheck + "\")");<br>
177      * ((VersantQuery)q).setEvictionClasses(new[]{Acl.class}, true);<br>
178      * // make sure query result is evicted if acl table(class) changes<br>
179      * ...<br></code>
180      *
181      * @param includeSubclasses Recursively add subclasses (if any)
182      * @see #setEvictionClasses(int[])
183      */

184     public void setEvictionClasses(Class JavaDoc[] classes, boolean includeSubclasses);
185
186     /**
187      * Register the indexes of classes that will cause the cached results of
188      * this query to be evicted if any of its instances are modified. This
189      * performs the same function as the method accepting a Class[] but
190      * is faster as the index for each class does not have to be found.
191      *
192      * @see #setEvictionClasses(Class[], boolean)
193      * @see com.versant.core.jdo.VersantPersistenceManagerFactory#getClassIndexes(Class[], boolean)
194      */

195     public void setEvictionClasses(int[] classIndexes);
196
197     /**
198      * Get the registered eviction classes. This does not return classes
199      * automatically picked up by JDO Genie (e.g. the candidate class). This
200      * may return null if there are no registered eviction classes.
201      *
202      * @see #setEvictionClasses(Class[], boolean)
203      * @see #setEvictionClasses(int[])
204      */

205     public Class JavaDoc[] getEvictionClasses();
206
207     /**
208      * The projection to use.
209      */

210     public void setResult(String JavaDoc result);
211
212     /**
213      * Grouping exp to use.
214      * This is used in conjunction with projection queries.
215      *
216      * @see #setResult(java.lang.String)
217      */

218     public void setGrouping(String JavaDoc grouping);
219
220     /**
221      * Specify that there is a single result of the query.
222      */

223     public void setUnique(boolean unique);
224
225     /**
226      * Get the filter for the query.
227      */

228     public String JavaDoc getFilter();
229
230     /**
231      * Can the results of the query go into the level 2 cache or come from the
232      * level 2 cache? If this property is set then it overrides the default
233      * decision. Normally JDOQL query results are added to the level 2 cache
234      * if all classes involved have a cache strategy of yes or all. SQL query
235      * results are not normally cached.
236      * <p/>
237      * You might want to use this for a large JDOQL query if you know that
238      * caching the results will not benefit the application. Or you could
239      * use it to cache the results of an SQL query.
240      *
241      * @see #setEvictionClasses(int[])
242      */

243     public void setCacheable(boolean on);
244
245     /**
246      * Get the query imports.
247      */

248     public String JavaDoc getImports();
249
250     /**
251      * Get the query parameter declarations.
252      */

253     public String JavaDoc getParameters();
254
255     /**
256      * Get the query variable declarations.
257      */

258     public String JavaDoc getVariables();
259
260     /**
261      * Get the query ordering expression.
262      */

263     public String JavaDoc getOrdering();
264
265     /**
266      * Get the query grouping expression.
267      */

268     public String JavaDoc getGrouping();
269
270     /**
271      * Get the query result expression.
272      */

273     public String JavaDoc getResult();
274
275     /**
276      * Has the unique flag been set?
277      */

278     public boolean isUnique();
279
280 }
281
Popular Tags