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   VERSANT_OPTIONS = "versantOptions";
49      /**
50       * @deprecated Use {@link #VERSANT_OPTIONS} instead.
51       */
52      public static final String   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   fetchGroupName);
62  
63      public String   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  [] 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  [] 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  [] getEvictionClasses();
206 
207     /**
208      * The projection to use.
209      */
210     public void setResult(String   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   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   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   getImports();
249 
250     /**
251      * Get the query parameter declarations.
252      */
253     public String   getParameters();
254 
255     /**
256      * Get the query variable declarations.
257      */
258     public String   getVariables();
259 
260     /**
261      * Get the query ordering expression.
262      */
263     public String   getOrdering();
264 
265     /**
266      * Get the query grouping expression.
267      */
268     public String   getGrouping();
269 
270     /**
271      * Get the query result expression.
272      */
273     public String   getResult();
274 
275     /**
276      * Has the unique flag been set?
277      */
278     public boolean isUnique();
279 
280 }
281
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags