001: /*
002: * Copyright (c) 1998 - 2005 Versant Corporation
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * Versant Corporation - initial API and implementation
010: */
011: package com.versant.core.jdo;
012:
013: import javax.jdo.Query;
014:
015: /**
016: * <p>This interface provides additional Open Access specific query properties.
017: * There are two ways to use these properties in your applications:</p>
018: * <ol>
019: * <li>Cast the Query returned by PersistenceManager.newQuery(...) to a
020: * VersantQuery and call the setXXX methods. This is clear in code
021: * but non-portable to other JDO implementations.
022: * <li>Add a 'String versantOptions' parameter to the query and specify a
023: * semicolon delimited String of property=value pairs when the query is
024: * executed. Portability is maintained as other JDO implementations should
025: * ignore this parameter.
026: * </ol>
027: * <p/>
028: * <p>Example using casting:</p>
029: * <pre>
030: * VersantQuery q = (VersantQuery)pm.newQuery(Item.class);
031: * q.setFetchGroup("codeOnly");
032: * q.setRandomAccess(true);
033: * Collection ans = (Collection)q.execute();
034: * ...
035: * </pre>
036: * <p/>
037: * <p>Example using versantOptions parameter:</p>
038: * <pre>
039: * Query q = pm.newQuery(Item.class);
040: * q.declareParameters("String versantOptions");
041: * Collection ans = (Collection)q.execute("fetchGroup=codeOnly;randomAccess=true");
042: * ...
043: * </pre>
044: */
045: public interface VersantQuery extends Query {
046:
047: public static final String VERSANT_OPTIONS = "versantOptions";
048: /**
049: * @deprecated Use {@link #VERSANT_OPTIONS} instead.
050: */
051: public static final String JDO_GENIE_OPTIONS = "jdoGenieOptions";
052:
053: /**
054: * Select the fetch group used to execute the query. JDO Genie fetch groups
055: * control exactly which fields are returned in each instance. They
056: * also make it possible to fetch other referenced instances and
057: * collections at the same time i.e. you can prefetch a large part
058: * of your object graph with a single query.
059: */
060: public void setFetchGroup(String fetchGroupName);
061:
062: public String getFetchGroup();
063:
064: /**
065: * Indicate that random access to query results is required or not. If this
066: * is true then the collection returned by execute can be cast to a
067: * List and the get(index) method can be used to get any entry in the list.
068: * JDO Genie must use a scrollable JDBC ResultSet to provide this
069: * functionality. This may use more database resources (cursors etc.)
070: * than a normal forward only ResultSet. This option is useful for paged
071: * results i.e. you only want a few results from position n onwards.
072: */
073: public void setRandomAccess(boolean on);
074:
075: public boolean isRandomAccess();
076:
077: /**
078: * Limit the number of instances to be returned. If this property has
079: * been set and {@link #setFetchSize} is not set then the batchSize
080: * is set to maxRows.
081: *
082: * @see #setFetchSize
083: * @see #getMaxRows
084: */
085: public void setMaxRows(int amount);
086:
087: /**
088: * The maximum number of instances to return.
089: *
090: * @see #setMaxRows
091: */
092: public int getMaxRows();
093:
094: /**
095: * Set the number of instances fetched per server round trip. This
096: * property controls JDO Genie's own batching and is also passed
097: * through to JDBC drivers that support this. If this property is
098: * not set and maxRows is set then the default is maxRows.
099: *
100: * @see #getFetchSize
101: */
102: public void setFetchSize(int value);
103:
104: /**
105: * The number of instances fetched from server per round trip.
106: *
107: * @see #setFetchSize
108: */
109: public int getFetchSize();
110:
111: /**
112: * <p>Normally when size() is called on the Collection returned by executing
113: * a non-randomAccess Query all of the results are fetched in one operation
114: * to detirmine the size of the collection. If this property is true then
115: * a 'select count(*) ...' version of the query is used to count the
116: * results. Subsequent calls to to size() after the first call will revert
117: * to normal behaviour and resolve all of the results.</p>
118: * <p/>
119: * <p>Note that the actual number of results might differ to those first
120: * returned by size() when this option is used. This can happen if new
121: * rows that meet the filter criteria are inserted after the
122: * 'select count(*)...' query has run but before the normal 'select ...'
123: * to fetch the data. This may be possible even in a non-optimistic
124: * transaction depending on how the database handles locking.</p>
125: *
126: * @see #setRandomAccess(boolean)
127: * @see #isCountStarOnSize()
128: */
129: public void setCountStarOnSize(boolean on);
130:
131: /**
132: * Has the count(*) option been set?
133: *
134: * @see #setCountStarOnSize(boolean)
135: */
136: public boolean isCountStarOnSize();
137:
138: /**
139: * This property is a hint to JDO Genie that the number of instances
140: * returned by the query us limited. If it is true then collections and
141: * maps are fetched in bulk using parallel queries derived from the
142: * orginal filter expression. If it is false then individual queries are
143: * issued for each collection or map for each instance in the result.
144: * The default setting is false.
145: */
146: public void setBounded(boolean value);
147:
148: /**
149: * Has the bounded option been set?
150: *
151: * @see #setBounded(boolean)
152: */
153: public boolean isBounded();
154:
155: /**
156: * Get the query plan for this query. This will include the SQL and
157: * possibly also a query plan for the SQL from the database itself.
158: * The params are as for executeWithArray.
159: *
160: * @see #executeWithArray
161: */
162: public VersantQueryPlan getPlan(Object[] params);
163:
164: /**
165: * <p>Register classes that will cause the cached results of this query to
166: * be evicted if any of its instances are modified. These replace any
167: * previously set classes. JDO Genie will automatically pickup the
168: * candidate class and classes involved in the filter or ordering. You
169: * only need to call this method if you are using inline SQL to touch
170: * tables for classes not otherwise involved in the query. Here is an
171: * example:</p>
172: * <p/>
173: * <code>Query q = pm.newQuery(Order.class);<br>
174: * String aclCheck = "$1 in (select $1 from acl where user_id = " + userId + ")";<br>
175: * q.setFilter("owner.sql(\"" + aclCheck + "\")");<br>
176: * ((VersantQuery)q).setEvictionClasses(new[]{Acl.class}, true);<br>
177: * // make sure query result is evicted if acl table(class) changes<br>
178: * ...<br></code>
179: *
180: * @param includeSubclasses Recursively add subclasses (if any)
181: * @see #setEvictionClasses(int[])
182: */
183: public void setEvictionClasses(Class[] classes,
184: 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: }
|