| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!--NewPage--> |
| <HTML> |
| <HEAD> |
| <!-- Generated by javadoc (build 1.5.0_05) on Wed Mar 29 15:04:36 PST 2006 --> |
| <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <TITLE> |
| Query (JDO2 API 2.0) |
| </TITLE> |
| |
| <META NAME="keywords" CONTENT="javax.jdo.Query interface"> |
| |
| <LINK REL ="stylesheet" TYPE="text/css" HREF="../../stylesheet.css" TITLE="Style"> |
| |
| <SCRIPT type="text/javascript"> |
| function windowTitle() |
| { |
| parent.document.title="Query (JDO2 API 2.0)"; |
| } |
| </SCRIPT> |
| <NOSCRIPT> |
| </NOSCRIPT> |
| |
| </HEAD> |
| |
| <BODY BGCOLOR="white" onload="windowTitle();"> |
| |
| |
| <!-- ========= START OF TOP NAVBAR ======= --> |
| <A NAME="navbar_top"><!-- --></A> |
| <A HREF="#skip-navbar_top" title="Skip navigation links"></A> |
| <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> |
| <TR> |
| <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> |
| <A NAME="navbar_top_firstrow"><!-- --></A> |
| <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> |
| <TR ALIGN="center" VALIGN="top"> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD> |
| <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/Query.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> |
| </TR> |
| </TABLE> |
| </TD> |
| <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> |
| </EM> |
| </TD> |
| </TR> |
| |
| <TR> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| <A HREF="../../javax/jdo/PersistenceManagerFactory.html" title="interface in javax.jdo"><B>PREV CLASS</B></A> |
| <A HREF="../../javax/jdo/Transaction.html" title="interface in javax.jdo"><B>NEXT CLASS</B></A></FONT></TD> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| <A HREF="../../index.html?javax/jdo/Query.html" target="_top"><B>FRAMES</B></A> |
| <A HREF="Query.html" target="_top"><B>NO FRAMES</B></A> |
| <SCRIPT type="text/javascript"> |
| <!-- |
| if(window==top) { |
| document.writeln('<A HREF="../../allclasses-noframe.html"><B>All Classes</B></A>'); |
| } |
| //--> |
| </SCRIPT> |
| <NOSCRIPT> |
| <A HREF="../../allclasses-noframe.html"><B>All Classes</B></A> |
| </NOSCRIPT> |
| |
| |
| </FONT></TD> |
| </TR> |
| <TR> |
| <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> |
| SUMMARY: NESTED | <A HREF="#field_summary">FIELD</A> | CONSTR | <A HREF="#method_summary">METHOD</A></FONT></TD> |
| <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> |
| DETAIL: <A HREF="#field_detail">FIELD</A> | CONSTR | <A HREF="#method_detail">METHOD</A></FONT></TD> |
| </TR> |
| </TABLE> |
| <A NAME="skip-navbar_top"></A> |
| <!-- ========= END OF TOP NAVBAR ========= --> |
| |
| <HR> |
| <!-- ======== START OF CLASS DATA ======== --> |
| <H2> |
| <FONT SIZE="-1"> |
| javax.jdo</FONT> |
| <BR> |
| Interface Query</H2> |
| <DL> |
| <DT><B>All Superinterfaces:</B> <DD>java.io.Serializable</DD> |
| </DL> |
| <HR> |
| <DL> |
| <DT><PRE>public interface <B>Query</B><DT>extends java.io.Serializable</DL> |
| </PRE> |
| |
| <P> |
| The <code>Query</code> interface allows applications to obtain persistent |
| instances, values, and aggregate data |
| from the data store. |
| |
| The <A HREF="../../javax/jdo/PersistenceManager.html" title="interface in javax.jdo"><CODE>PersistenceManager</CODE></A> is the factory for <code>Query</code> |
| instances. There may be many <code>Query</code> instances associated with a |
| <code>PersistenceManager</code>. Multiple queries might be executed |
| simultaneously by different threads, but the implementation might choose to |
| execute them serially. In either case, the implementation must be thread |
| safe. |
| |
| <P>There are three required elements in a <code>Query</code>: the class of |
| the results, the candidate collection of instances, and the filter. |
| |
| <P>There are optional elements: parameter declarations, variable |
| declarations, import statements, ordering and grouping specifications, |
| result and result class, the range of results, |
| and flags indicating whether the query result |
| is unique and whether the query can be modified. |
| <P>The query namespace is modeled after methods in Java: |
| <ul> |
| <li><code>setClass</code> corresponds to the class definition |
| <li><code>declareParameters</code> corresponds to formal parameters of a |
| method |
| <li><code>declareVariables</code> corresponds to local variables of a method |
| <li><code>setFilter</code> and <code>setOrdering</code> correspond to the |
| method body |
| </ul> |
| <P>There are two namespaces in queries. Type names have their own |
| namespace that is separate from the namespace for fields, variables |
| and parameters. |
| <P>The method <code>setClass</code> introduces the name of the candidate |
| class in the type namespace. The method <code>declareImports</code> |
| introduces the names of the imported class or interface types in the type |
| namespace. Imported type names must be unique. When used (e.g. in a parameter |
| declaration, cast expression, etc.) a type name must be the name of the |
| candidate class, the name of a class or interface imported by method |
| <code>declareImports</code>, or denote a class or interface from the same |
| package as the candidate class. |
| <P>The method <code>setClass</code> introduces the names of the candidate |
| class fields. |
| <P>The method <code>declareParameters</code> introduces the names of the |
| parameters. A name introduced by <code>declareParameters</code> hides the |
| name of a candidate class field of the same name. Parameter names must be |
| unique. |
| <P>The method <code>declareVariables</code> introduces the names of the |
| variables. A name introduced by <code>declareVariables</code> hides the name |
| of a candidate class field if equal. Variable names must be unique and must |
| not conflict with parameter names. |
| <P>The result of the query by default is a list of result class instances, |
| but might be specified via <code>setResult</code>. The class of the result |
| by default is the candidate class, but might be specified via |
| <code>setResultClass</code>. |
| <P>A hidden field may be accessed using the 'this' qualifier: |
| <code>this.fieldName</code>. |
| <P>The <code>Query</code> interface provides methods which execute the query |
| based on the parameters given. They return a single instance or a |
| <code>List</code> of result class instances which the |
| user can iterate to get results. The signature |
| of the <code>execute</code> methods specifies that they return an |
| <code>Object</code> which must be cast to the appropriate result by the user. |
| <P>Any parameters passed to the <code>execute</code> methods are used only |
| for this execution, and are not remembered for future execution. |
| <P> |
| |
| <P> |
| <DL> |
| <DT><B>Version:</B></DT> |
| <DD>2.0</DD> |
| </DL> |
| <HR> |
| |
| <P> |
| <!-- =========== FIELD SUMMARY =========== --> |
| |
| <A NAME="field_summary"><!-- --></A> |
| <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> |
| <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> |
| <TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> |
| <B>Field Summary</B></FONT></TH> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE>static java.lang.String</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#JDOQL">JDOQL</A></B></CODE> |
| |
| <BR> |
| The string constant used as the first argument to |
| <A HREF="../../javax/jdo/PersistenceManager.html#newQuery(java.lang.String, java.lang.Object)"><CODE>PersistenceManager.newQuery(String,Object)</CODE></A> to identify that the |
| created query should obey the JDOQL syntax and semantic rules.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE>static java.lang.String</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#SQL">SQL</A></B></CODE> |
| |
| <BR> |
| The string constant used as the first argument to <A HREF="../../javax/jdo/PersistenceManager.html#newQuery(java.lang.String, java.lang.Object)"><CODE>PersistenceManager.newQuery(String,Object)</CODE></A> to identify that |
| the created query should use SQL semantics.</TD> |
| </TR> |
| </TABLE> |
| |
| <!-- ========== METHOD SUMMARY =========== --> |
| |
| <A NAME="method_summary"><!-- --></A> |
| <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> |
| <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> |
| <TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> |
| <B>Method Summary</B></FONT></TH> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#addExtension(java.lang.String, java.lang.Object)">addExtension</A></B>(java.lang.String key, |
| java.lang.Object value)</CODE> |
| |
| <BR> |
| Add a vendor-specific extension to this query.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#close(java.lang.Object)">close</A></B>(java.lang.Object queryResult)</CODE> |
| |
| <BR> |
| Close a query result and release any resources associated with it.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#closeAll()">closeAll</A></B>()</CODE> |
| |
| <BR> |
| Close all query results associated with this <code>Query</code> |
| instance, and release all resources associated with them.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#compile()">compile</A></B>()</CODE> |
| |
| <BR> |
| Verify the elements of the query and provide a hint to the query to |
| prepare and optimize an execution plan.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#declareImports(java.lang.String)">declareImports</A></B>(java.lang.String imports)</CODE> |
| |
| <BR> |
| Set the import statements to be used to identify the fully qualified |
| name of variables or parameters.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#declareParameters(java.lang.String)">declareParameters</A></B>(java.lang.String parameters)</CODE> |
| |
| <BR> |
| Declare the list of parameters query execution.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#declareVariables(java.lang.String)">declareVariables</A></B>(java.lang.String variables)</CODE> |
| |
| <BR> |
| Declare the unbound variables to be used in the query.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> long</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#deletePersistentAll()">deletePersistentAll</A></B>()</CODE> |
| |
| <BR> |
| Deletes all the instances of the candidate class that pass the |
| filter.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> long</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#deletePersistentAll(java.util.Map)">deletePersistentAll</A></B>(java.util.Map parameters)</CODE> |
| |
| <BR> |
| Deletes all the instances of the candidate class that pass the |
| filter.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> long</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#deletePersistentAll(java.lang.Object[])">deletePersistentAll</A></B>(java.lang.Object[] parameters)</CODE> |
| |
| <BR> |
| Deletes all the instances of the candidate class that pass the |
| filter.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> java.lang.Object</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#execute()">execute</A></B>()</CODE> |
| |
| <BR> |
| Execute the query and return the filtered Collection.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> java.lang.Object</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#execute(java.lang.Object)">execute</A></B>(java.lang.Object p1)</CODE> |
| |
| <BR> |
| Execute the query and return the filtered <code>Collection</code>.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> java.lang.Object</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#execute(java.lang.Object, java.lang.Object)">execute</A></B>(java.lang.Object p1, |
| java.lang.Object p2)</CODE> |
| |
| <BR> |
| Execute the query and return the filtered <code>Collection</code>.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> java.lang.Object</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#execute(java.lang.Object, java.lang.Object, java.lang.Object)">execute</A></B>(java.lang.Object p1, |
| java.lang.Object p2, |
| java.lang.Object p3)</CODE> |
| |
| <BR> |
| Execute the query and return the filtered <code>Collection</code>.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> java.lang.Object</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#executeWithArray(java.lang.Object[])">executeWithArray</A></B>(java.lang.Object[] parameters)</CODE> |
| |
| <BR> |
| Execute the query and return the filtered <code>Collection</code>.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> java.lang.Object</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#executeWithMap(java.util.Map)">executeWithMap</A></B>(java.util.Map parameters)</CODE> |
| |
| <BR> |
| Execute the query and return the filtered <code>Collection</code>.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> <A HREF="../../javax/jdo/FetchPlan.html" title="interface in javax.jdo">FetchPlan</A></CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#getFetchPlan()">getFetchPlan</A></B>()</CODE> |
| |
| <BR> |
| Returns the <code>FetchPlan</code> used by this |
| <code>Query</code>.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> boolean</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#getIgnoreCache()">getIgnoreCache</A></B>()</CODE> |
| |
| <BR> |
| Get the ignoreCache option setting.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> <A HREF="../../javax/jdo/PersistenceManager.html" title="interface in javax.jdo">PersistenceManager</A></CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#getPersistenceManager()">getPersistenceManager</A></B>()</CODE> |
| |
| <BR> |
| Get the <code>PersistenceManager</code> associated with this |
| <code>Query</code>.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> boolean</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#isUnmodifiable()">isUnmodifiable</A></B>()</CODE> |
| |
| <BR> |
| The unmodifiable flag, when set, disallows further |
| modification of the query, except for specifying the range, |
| result class, and ignoreCache option.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#setCandidates(java.util.Collection)">setCandidates</A></B>(java.util.Collection pcs)</CODE> |
| |
| <BR> |
| Set the candidate <code>Collection</code> to query.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#setCandidates(javax.jdo.Extent)">setCandidates</A></B>(<A HREF="../../javax/jdo/Extent.html" title="interface in javax.jdo">Extent</A> pcs)</CODE> |
| |
| <BR> |
| Set the candidate <code>Extent</code> to query.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#setClass(java.lang.Class)">setClass</A></B>(java.lang.Class cls)</CODE> |
| |
| <BR> |
| Set the class of the candidate instances of the query.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#setExtensions(java.util.Map)">setExtensions</A></B>(java.util.Map extensions)</CODE> |
| |
| <BR> |
| Set multiple extensions, or use null to clear all extensions.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#setFilter(java.lang.String)">setFilter</A></B>(java.lang.String filter)</CODE> |
| |
| <BR> |
| Set the filter for the query.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#setGrouping(java.lang.String)">setGrouping</A></B>(java.lang.String group)</CODE> |
| |
| <BR> |
| Set the grouping expressions, optionally including a "having" |
| clause.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#setIgnoreCache(boolean)">setIgnoreCache</A></B>(boolean ignoreCache)</CODE> |
| |
| <BR> |
| Set the ignoreCache option.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#setOrdering(java.lang.String)">setOrdering</A></B>(java.lang.String ordering)</CODE> |
| |
| <BR> |
| Set the ordering specification for the result <code>Collection</code>.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#setRange(long, long)">setRange</A></B>(long fromIncl, |
| long toExcl)</CODE> |
| |
| <BR> |
| Set the range of results to return.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#setRange(java.lang.String)">setRange</A></B>(java.lang.String fromInclToExcl)</CODE> |
| |
| <BR> |
| Set the range of results to return.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#setResult(java.lang.String)">setResult</A></B>(java.lang.String data)</CODE> |
| |
| <BR> |
| Specifies what type of data this query should return.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#setResultClass(java.lang.Class)">setResultClass</A></B>(java.lang.Class cls)</CODE> |
| |
| <BR> |
| Specify the type of object in which to return each element of |
| the result of invoking <A HREF="../../javax/jdo/Query.html#execute()"><CODE>execute()</CODE></A> or one of its siblings.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#setUnique(boolean)">setUnique</A></B>(boolean unique)</CODE> |
| |
| <BR> |
| Specify that only the first result of the query should be |
| returned, rather than a collection.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> |
| <CODE> void</CODE></FONT></TD> |
| <TD><CODE><B><A HREF="../../javax/jdo/Query.html#setUnmodifiable()">setUnmodifiable</A></B>()</CODE> |
| |
| <BR> |
| The unmodifiable flag, when set, disallows further |
| modification of the query, except for specifying the range, |
| result class, and ignoreCache option.</TD> |
| </TR> |
| </TABLE> |
| |
| <P> |
| |
| <!-- ============ FIELD DETAIL =========== --> |
| |
| <A NAME="field_detail"><!-- --></A> |
| <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> |
| <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> |
| <TH ALIGN="left" COLSPAN="1"><FONT SIZE="+2"> |
| <B>Field Detail</B></FONT></TH> |
| </TR> |
| </TABLE> |
| |
| <A NAME="JDOQL"><!-- --></A><H3> |
| JDOQL</H3> |
| <PRE> |
| static final java.lang.String <B>JDOQL</B></PRE> |
| <DL> |
| <DD>The string constant used as the first argument to |
| <A HREF="../../javax/jdo/PersistenceManager.html#newQuery(java.lang.String, java.lang.Object)"><CODE>PersistenceManager.newQuery(String,Object)</CODE></A> to identify that the |
| created query should obey the JDOQL syntax and semantic rules. |
| <p>This is the default query language used when creating a query with any |
| of the other <A HREF="../../javax/jdo/PersistenceManager.html#newQuery()"><CODE>PersistenceManager.newQuery()</CODE></A> methods, except |
| <A HREF="../../javax/jdo/PersistenceManager.html#newQuery(java.lang.Object)"><CODE>PersistenceManager.newQuery(Object)</CODE></A>, which uses the query |
| language of the compiled query template object passed to that method.</p> |
| <P> |
| <DL> |
| <DT><B>Since:</B></DT> |
| <DD>2.0</DD> |
| <DT><B>See Also:</B><DD><A HREF="../../constant-values.html#javax.jdo.Query.JDOQL">Constant Field Values</A></DL> |
| </DL> |
| <HR> |
| |
| <A NAME="SQL"><!-- --></A><H3> |
| SQL</H3> |
| <PRE> |
| static final java.lang.String <B>SQL</B></PRE> |
| <DL> |
| <DD>The string constant used as the first argument to <A HREF="../../javax/jdo/PersistenceManager.html#newQuery(java.lang.String, java.lang.Object)"><CODE>PersistenceManager.newQuery(String,Object)</CODE></A> to identify that |
| the created query should use SQL semantics. This is only |
| meaningful for relational JDO implementations. |
| <p>If this is used, the <code>Object</code> argument to the |
| <A HREF="../../javax/jdo/PersistenceManager.html#newQuery(java.lang.String, java.lang.Object)"><CODE>PersistenceManager.newQuery(String,Object)</CODE></A> method |
| should be a <code>String</code> containing a SQL |
| <code>SELECT</code> statement.</p> |
| <P> |
| <DL> |
| <DT><B>Since:</B></DT> |
| <DD>2.0</DD> |
| <DT><B>See Also:</B><DD><A HREF="../../constant-values.html#javax.jdo.Query.SQL">Constant Field Values</A></DL> |
| </DL> |
| |
| <!-- ============ METHOD DETAIL ========== --> |
| |
| <A NAME="method_detail"><!-- --></A> |
| <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> |
| <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> |
| <TH ALIGN="left" COLSPAN="1"><FONT SIZE="+2"> |
| <B>Method Detail</B></FONT></TH> |
| </TR> |
| </TABLE> |
| |
| <A NAME="setClass(java.lang.Class)"><!-- --></A><H3> |
| setClass</H3> |
| <PRE> |
| void <B>setClass</B>(java.lang.Class cls)</PRE> |
| <DL> |
| <DD>Set the class of the candidate instances of the query. |
| <P>The class specifies the class |
| of the candidates of the query. Elements of the candidate collection |
| that are of the specified class are filtered before being |
| put into the result <code>Collection</code>. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>cls</CODE> - the <code>Class</code> of the candidate instances.</DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="setCandidates(javax.jdo.Extent)"><!-- --></A><H3> |
| setCandidates</H3> |
| <PRE> |
| void <B>setCandidates</B>(<A HREF="../../javax/jdo/Extent.html" title="interface in javax.jdo">Extent</A> pcs)</PRE> |
| <DL> |
| <DD>Set the candidate <code>Extent</code> to query. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>pcs</CODE> - the candidate <code>Extent</code>.</DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="setCandidates(java.util.Collection)"><!-- --></A><H3> |
| setCandidates</H3> |
| <PRE> |
| void <B>setCandidates</B>(java.util.Collection pcs)</PRE> |
| <DL> |
| <DD>Set the candidate <code>Collection</code> to query. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>pcs</CODE> - the candidate <code>Collection</code>.</DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="setFilter(java.lang.String)"><!-- --></A><H3> |
| setFilter</H3> |
| <PRE> |
| void <B>setFilter</B>(java.lang.String filter)</PRE> |
| <DL> |
| <DD>Set the filter for the query. |
| |
| <P>The filter specification is a <code>String</code> containing a Boolean |
| expression that is to be evaluated for each of the instances |
| in the candidate collection. If the filter is not specified, |
| then it defaults to "true", which has the effect of filtering |
| the input <code>Collection</code> only for class type. |
| <P>An element of the candidate collection is returned in the result if: |
| <ul><li>it is assignment compatible to the candidate <code>Class</code> |
| of the <code>Query</code>; and |
| <li>for all variables there exists a value for which the filter |
| expression evaluates to <code>true</code>. |
| </ul> |
| <P>The user may denote uniqueness in the filter expression by |
| explicitly declaring an expression (for example, <code>e1 != e2</code>). |
| <P>Rules for constructing valid expressions follow the Java |
| language, except for these differences: |
| <ul> |
| <li>Equality and ordering comparisons between primitives and instances |
| of wrapper classes are valid. |
| <li>Equality and ordering comparisons of <code>Date</code> fields and |
| <code>Date</code> parameters are valid. |
| <li>White space (non-printing characters space, tab, carriage |
| return, and line feed) is a separator and is otherwise ignored. |
| <li>The assignment operators <code>=</code>, <code>+=</code>, etc. and |
| pre- and post-increment and -decrement are not supported. Therefore, |
| there are no side effects from evaluation of any expressions. |
| <li>Methods, including object construction, are not supported, except |
| for <code>Collection.contains(Object o)</code>, |
| <code>Collection.isEmpty()</code>, |
| <code>String.startsWith(String s)</code>, and |
| <code>String.endsWith(String e)</code>. Implementations might choose to |
| support non-mutating method calls as non-standard extensions. |
| <li>Navigation through a <code>null</code>-valued field, which would |
| throw <code>NullPointerException</code>, is treated as if the filter |
| expression returned <code>false</code> for the evaluation of the current |
| set of variable values. Other values for variables might still qualify |
| the candidate instance for inclusion in the result set. |
| <li>Navigation through multi-valued fields (<code>Collection</code> |
| types) is specified using a variable declaration and the |
| <code>Collection.contains(Object o)</code> method. |
| </ul> |
| <P>Identifiers in the expression are considered to be in the name |
| space of the specified class, with the addition of declared imports, |
| parameters and variables. As in the Java language, <code>this</code> is a |
| reserved word which means the element of the collection being evaluated. |
| <P>Navigation through single-valued fields is specified by the Java |
| language syntax of <code>field_name.field_name....field_name</code>. |
| <P>A JDO implementation is allowed to reorder the filter expression |
| for optimization purposes. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>filter</CODE> - the query filter.</DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="declareImports(java.lang.String)"><!-- --></A><H3> |
| declareImports</H3> |
| <PRE> |
| void <B>declareImports</B>(java.lang.String imports)</PRE> |
| <DL> |
| <DD>Set the import statements to be used to identify the fully qualified |
| name of variables or parameters. Parameters and unbound variables might |
| come from a different class from the candidate class, and the names |
| need to be declared in an import statement to eliminate ambiguity. |
| Import statements are specified as a <code>String</code> with |
| semicolon-separated statements. |
| <P>The <code>String</code> parameter to this method follows the syntax of |
| the import statement of the Java language. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>imports</CODE> - import statements separated by semicolons.</DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="declareParameters(java.lang.String)"><!-- --></A><H3> |
| declareParameters</H3> |
| <PRE> |
| void <B>declareParameters</B>(java.lang.String parameters)</PRE> |
| <DL> |
| <DD>Declare the list of parameters query execution. |
| |
| The parameter declaration is a <code>String</code> containing one or more |
| query parameter declarations separated with commas. Each parameter named |
| in the parameter declaration must be bound to a value when |
| the query is executed. |
| <P>The <code>String</code> parameter to this method follows the syntax |
| for formal parameters in the Java language. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>parameters</CODE> - the list of parameters separated by commas.</DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="declareVariables(java.lang.String)"><!-- --></A><H3> |
| declareVariables</H3> |
| <PRE> |
| void <B>declareVariables</B>(java.lang.String variables)</PRE> |
| <DL> |
| <DD>Declare the unbound variables to be used in the query. Variables |
| might be used in the filter, and these variables must be declared |
| with their type. The unbound variable declaration is a |
| <code>String</code> containing one or more unbound variable declarations |
| separated with semicolons. It follows the syntax for local variables in |
| the Java language. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>variables</CODE> - the variables separated by semicolons.</DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="setOrdering(java.lang.String)"><!-- --></A><H3> |
| setOrdering</H3> |
| <PRE> |
| void <B>setOrdering</B>(java.lang.String ordering)</PRE> |
| <DL> |
| <DD>Set the ordering specification for the result <code>Collection</code>. |
| The ordering specification is a <code>String</code> containing one or |
| more ordering declarations separated by commas. |
| |
| <P>Each ordering declaration is the name of the field on which |
| to order the results followed by one of the following words: |
| "<code>ascending</code>" or "<code>descending</code>". |
| |
| <P>The field must be declared in the candidate class or must be |
| a navigation expression starting with a field in the candidate class. |
| |
| <P>Valid field types are primitive types except <code>boolean</code>; |
| wrapper types except <code>Boolean</code>; <code>BigDecimal</code>; |
| <code>BigInteger</code>; <code>String</code>; and <code>Date</code>. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>ordering</CODE> - the ordering specification.</DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="setIgnoreCache(boolean)"><!-- --></A><H3> |
| setIgnoreCache</H3> |
| <PRE> |
| void <B>setIgnoreCache</B>(boolean ignoreCache)</PRE> |
| <DL> |
| <DD>Set the ignoreCache option. The default value for this option was |
| set by the <code>PersistenceManagerFactory</code> or the |
| <code>PersistenceManager</code> used to create this <code>Query</code>. |
| |
| The ignoreCache option setting specifies whether the query should execute |
| entirely in the back end, instead of in the cache. If this flag is set |
| to <code>true</code>, an implementation might be able to optimize the |
| query execution by ignoring changed values in the cache. For optimistic |
| transactions, this can dramatically improve query response times. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>ignoreCache</CODE> - the setting of the ignoreCache option.</DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="getIgnoreCache()"><!-- --></A><H3> |
| getIgnoreCache</H3> |
| <PRE> |
| boolean <B>getIgnoreCache</B>()</PRE> |
| <DL> |
| <DD>Get the ignoreCache option setting. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| |
| <DT><B>Returns:</B><DD>the ignoreCache option setting.<DT><B>See Also:</B><DD><A HREF="../../javax/jdo/Query.html#setIgnoreCache(boolean)"><CODE>setIgnoreCache(boolean)</CODE></A></DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="compile()"><!-- --></A><H3> |
| compile</H3> |
| <PRE> |
| void <B>compile</B>()</PRE> |
| <DL> |
| <DD>Verify the elements of the query and provide a hint to the query to |
| prepare and optimize an execution plan. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| </DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="execute()"><!-- --></A><H3> |
| execute</H3> |
| <PRE> |
| java.lang.Object <B>execute</B>()</PRE> |
| <DL> |
| <DD>Execute the query and return the filtered Collection. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| |
| <DT><B>Returns:</B><DD>the filtered <code>Collection</code>.<DT><B>See Also:</B><DD><A HREF="../../javax/jdo/Query.html#executeWithArray(java.lang.Object[])"><CODE>executeWithArray(Object[] parameters)</CODE></A></DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="execute(java.lang.Object)"><!-- --></A><H3> |
| execute</H3> |
| <PRE> |
| java.lang.Object <B>execute</B>(java.lang.Object p1)</PRE> |
| <DL> |
| <DD>Execute the query and return the filtered <code>Collection</code>. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>p1</CODE> - the value of the first parameter declared. |
| <DT><B>Returns:</B><DD>the filtered <code>Collection</code>.<DT><B>See Also:</B><DD><A HREF="../../javax/jdo/Query.html#executeWithArray(java.lang.Object[])"><CODE>executeWithArray(Object[] parameters)</CODE></A></DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="execute(java.lang.Object, java.lang.Object)"><!-- --></A><H3> |
| execute</H3> |
| <PRE> |
| java.lang.Object <B>execute</B>(java.lang.Object p1, |
| java.lang.Object p2)</PRE> |
| <DL> |
| <DD>Execute the query and return the filtered <code>Collection</code>. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>p1</CODE> - the value of the first parameter declared.<DD><CODE>p2</CODE> - the value of the second parameter declared. |
| <DT><B>Returns:</B><DD>the filtered <code>Collection</code>.<DT><B>See Also:</B><DD><A HREF="../../javax/jdo/Query.html#executeWithArray(java.lang.Object[])"><CODE>executeWithArray(Object[] parameters)</CODE></A></DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="execute(java.lang.Object, java.lang.Object, java.lang.Object)"><!-- --></A><H3> |
| execute</H3> |
| <PRE> |
| java.lang.Object <B>execute</B>(java.lang.Object p1, |
| java.lang.Object p2, |
| java.lang.Object p3)</PRE> |
| <DL> |
| <DD>Execute the query and return the filtered <code>Collection</code>. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>p1</CODE> - the value of the first parameter declared.<DD><CODE>p2</CODE> - the value of the second parameter declared.<DD><CODE>p3</CODE> - the value of the third parameter declared. |
| <DT><B>Returns:</B><DD>the filtered <code>Collection</code>.<DT><B>See Also:</B><DD><A HREF="../../javax/jdo/Query.html#executeWithArray(java.lang.Object[])"><CODE>executeWithArray(Object[] parameters)</CODE></A></DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="executeWithMap(java.util.Map)"><!-- --></A><H3> |
| executeWithMap</H3> |
| <PRE> |
| java.lang.Object <B>executeWithMap</B>(java.util.Map parameters)</PRE> |
| <DL> |
| <DD>Execute the query and return the filtered <code>Collection</code>. The |
| query is executed with the parameters set by the <code>Map</code> values. |
| Each <code>Map</code> entry consists of a key which is the name of the |
| parameter in the <code>declareParameters</code> method, and a value which |
| is the value used in the <code>execute</code> method. The keys in the |
| <code>Map</code> and the declared parameters must exactly match or a |
| <code>JDOUserException</code> is thrown. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>parameters</CODE> - the <code>Map</code> containing all of the parameters. |
| <DT><B>Returns:</B><DD>the filtered <code>Collection</code>.<DT><B>See Also:</B><DD><A HREF="../../javax/jdo/Query.html#executeWithArray(java.lang.Object[])"><CODE>executeWithArray(Object[] parameters)</CODE></A></DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="executeWithArray(java.lang.Object[])"><!-- --></A><H3> |
| executeWithArray</H3> |
| <PRE> |
| java.lang.Object <B>executeWithArray</B>(java.lang.Object[] parameters)</PRE> |
| <DL> |
| <DD>Execute the query and return the filtered <code>Collection</code>. |
| |
| <P>The execution of the query obtains the values of the parameters and |
| matches them against the declared parameters in order. The names |
| of the declared parameters are ignored. The type of |
| the declared parameters must match the type of the passed parameters, |
| except that the passed parameters might need to be unwrapped to get |
| their primitive values. |
| |
| <P>The filter, import, declared parameters, declared variables, and |
| ordering statements are verified for consistency. |
| |
| <P>Each element in the candidate <code>Collection</code> is examined to |
| see that it is assignment compatible to the <code>Class</code> of the |
| query. It is then evaluated by the Boolean expression of the filter. |
| The element passes the filter if there exist unique values for all |
| variables for which the filter expression evaluates to <code>true</code>. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>parameters</CODE> - the <code>Object</code> array with all of the |
| parameters. |
| <DT><B>Returns:</B><DD>the filtered <code>Collection</code>.</DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="getPersistenceManager()"><!-- --></A><H3> |
| getPersistenceManager</H3> |
| <PRE> |
| <A HREF="../../javax/jdo/PersistenceManager.html" title="interface in javax.jdo">PersistenceManager</A> <B>getPersistenceManager</B>()</PRE> |
| <DL> |
| <DD>Get the <code>PersistenceManager</code> associated with this |
| <code>Query</code>. |
| |
| <P>If this <code>Query</code> was restored from a serialized form, it has |
| no <code>PersistenceManager</code>, and this method returns |
| <code>null</code>. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| |
| <DT><B>Returns:</B><DD>the <code>PersistenceManager</code> associated with this |
| <code>Query</code>.</DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="close(java.lang.Object)"><!-- --></A><H3> |
| close</H3> |
| <PRE> |
| void <B>close</B>(java.lang.Object queryResult)</PRE> |
| <DL> |
| <DD>Close a query result and release any resources associated with it. The |
| parameter is the return from <code>execute(...)</code> and might have |
| iterators open on it. Iterators associated with the query result are |
| invalidated: they return <code>false</code> to <code>hasNext()</code> |
| and throw <code>NoSuchElementException</code> to <code>next()</code>. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>queryResult</CODE> - the result of <code>execute(...)</code> on this |
| <code>Query</code> instance.</DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="closeAll()"><!-- --></A><H3> |
| closeAll</H3> |
| <PRE> |
| void <B>closeAll</B>()</PRE> |
| <DL> |
| <DD>Close all query results associated with this <code>Query</code> |
| instance, and release all resources associated with them. The query |
| results might have iterators open on them. Iterators associated with the |
| query results are invalidated: |
| they return <code>false</code> to <code>hasNext()</code> and throw |
| <code>NoSuchElementException</code> to <code>next()</code>. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| </DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="setGrouping(java.lang.String)"><!-- --></A><H3> |
| setGrouping</H3> |
| <PRE> |
| void <B>setGrouping</B>(java.lang.String group)</PRE> |
| <DL> |
| <DD>Set the grouping expressions, optionally including a "having" |
| clause. When grouping is specified, each result expression |
| must either be an expression contained in the grouping, or an |
| aggregate evaluated once per group. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>group</CODE> - a comma-delimited list of expressions, optionally |
| followed by the "having" keyword and a boolean expression<DT><B>Since:</B></DT> |
| <DD>2.0</DD> |
| </DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="setUnique(boolean)"><!-- --></A><H3> |
| setUnique</H3> |
| <PRE> |
| void <B>setUnique</B>(boolean unique)</PRE> |
| <DL> |
| <DD>Specify that only the first result of the query should be |
| returned, rather than a collection. The execute method will |
| return null if the query result size is 0. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>unique</CODE> - if true, only one element is returned<DT><B>Since:</B></DT> |
| <DD>2.0</DD> |
| </DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="setResult(java.lang.String)"><!-- --></A><H3> |
| setResult</H3> |
| <PRE> |
| void <B>setResult</B>(java.lang.String data)</PRE> |
| <DL> |
| <DD>Specifies what type of data this query should return. If this |
| is unset or set to <code>null</code>, this query returns |
| instances of the query's candidate class. If set, this query |
| will return expressions, including field values (projections) and |
| aggregate function results. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>data</CODE> - a comma-delimited list of expressions |
| (fields, functions on fields, or aggregate functions) |
| to return from this query<DT><B>Since:</B></DT> |
| <DD>2.0</DD> |
| </DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="setResultClass(java.lang.Class)"><!-- --></A><H3> |
| setResultClass</H3> |
| <PRE> |
| void <B>setResultClass</B>(java.lang.Class cls)</PRE> |
| <DL> |
| <DD>Specify the type of object in which to return each element of |
| the result of invoking <A HREF="../../javax/jdo/Query.html#execute()"><CODE>execute()</CODE></A> or one of its siblings. |
| If the result is not set or set to null, the result class defaults |
| to the candidate class of the query. If the result consists of one |
| expression, the result class defaults to the type of that expression. |
| If the result consists of more than one expression, the result class |
| defaults to Object[]. |
| The result class may be specified to be one of the java.lang classes |
| Character, Boolean, Byte, Short, Integer, Long, Float, Double, String, |
| or Object[]; or one of the java.math classes BigInteger or BigDecimal; |
| or the java.util class Date; or one of the java.sql classes Date, |
| Time, or Timestamp; or a user-defined class. |
| <P>If there are multiple result expressions, the result class |
| must be able to hold all elements of the result specification |
| or a JDOUserException is thrown. |
| <P>If there is only one result expression, the result class must be |
| assignable from the type of the result expression or must be able |
| to hold all elements of the result specification. A single value |
| must be able to be coerced into the specified result class |
| (treating wrapper classes as equivalent to their unwrapped |
| primitive types) or by matching. If the result class does not satisfy |
| these conditions, a JDOUserException is thrown. |
| <P>A constructor of a result class specified in the setResult method |
| will be used if the results specification matches the parameters |
| of the constructor by position and type. If more than one constructor |
| satisfies the requirements, the JDO implementation chooses one of them. |
| If no constructor satisfies the results requirements, or if the result |
| class is specified via the setResultClass method, the following |
| requirements apply: |
| <ul> |
| <li>A user-defined result class must have a no-args constructor and |
| one or more public <code>set</code> or <code>put</code> methods or |
| fields. |
| <li>Each result expression must match one of: |
| <ul> |
| <li>a public field that matches the name of the result expression |
| and is of the type (treating wrapper types equivalent to primitive |
| types) of the result expression; |
| <li>or if no public field matches the name and type, a public |
| <code>set</code method that returns void and matches the name of the |
| result expression and takes a single parameter which is the |
| exact type of the result expression; |
| <li>or if neither of the above applies,a public method must be found |
| with the signature <code>void put(Object, Object)</code>. |
| During processing of the results, |
| the first argument is the name of the result expression and |
| the second argument is the value from the query result. |
| </ul> |
| </ul> |
| Portable result classes do not invoke any persistence behavior |
| during their no-args constructor or <code>set</code methods. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>cls</CODE> - the result class<DT><B>Since:</B></DT> |
| <DD>2.0</DD> |
| </DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="setRange(long, long)"><!-- --></A><H3> |
| setRange</H3> |
| <PRE> |
| void <B>setRange</B>(long fromIncl, |
| long toExcl)</PRE> |
| <DL> |
| <DD>Set the range of results to return. The execution of the query is |
| modified to return only a subset of results. If the filter would |
| normally return 100 instances, and fromIncl is set to 50, and |
| toExcl is set to 70, then the first 50 results that would have |
| been returned are skipped, the next 20 results are returned and the |
| remaining 30 results are ignored. An implementation should execute |
| the query such that the range algorithm is done at the data store. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>fromIncl</CODE> - 0-based inclusive start index<DD><CODE>toExcl</CODE> - 0-based exclusive end index, or |
| <CODE>Long.MAX_VALUE</CODE> for no limit.<DT><B>Since:</B></DT> |
| <DD>2.0</DD> |
| </DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="setRange(java.lang.String)"><!-- --></A><H3> |
| setRange</H3> |
| <PRE> |
| void <B>setRange</B>(java.lang.String fromInclToExcl)</PRE> |
| <DL> |
| <DD>Set the range of results to return. The parameter is a String |
| containing a comma-separated fromIncl and toExcl. The fromIncl and |
| toExcl can be either String representations of long values, or can |
| be parameters identified with a leading ":". For example, |
| <code>setRange("50, 70");</code> or |
| <code>setRange(":from, :to");</code> or |
| <code>setRange("50, :to");</code>. |
| The execution of the query is |
| modified to return only a subset of results. If the filter would |
| normally return 100 instances, and fromIncl is set to 50, and |
| toExcl is set to 70, then the first 50 results that would have |
| been returned are skipped, the next 20 results are returned and the |
| remaining 30 results are ignored. An implementation should execute |
| the query such that the range algorithm is done at the data store. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>fromInclToExcl</CODE> - comma-separated fromIncl and toExcl values<DT><B>Since:</B></DT> |
| <DD>2.0</DD> |
| <DT><B>See Also:</B><DD><A HREF="../../javax/jdo/Query.html#setRange(long, long)"><CODE>setRange(long, long)</CODE></A></DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="addExtension(java.lang.String, java.lang.Object)"><!-- --></A><H3> |
| addExtension</H3> |
| <PRE> |
| void <B>addExtension</B>(java.lang.String key, |
| java.lang.Object value)</PRE> |
| <DL> |
| <DD>Add a vendor-specific extension to this query. The key and value |
| are not standard. |
| An implementation must ignore keys that are not recognized. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>key</CODE> - the key of the extension<DD><CODE>value</CODE> - the value of the extension<DT><B>Since:</B></DT> |
| <DD>2.0</DD> |
| </DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="setExtensions(java.util.Map)"><!-- --></A><H3> |
| setExtensions</H3> |
| <PRE> |
| void <B>setExtensions</B>(java.util.Map extensions)</PRE> |
| <DL> |
| <DD>Set multiple extensions, or use null to clear all extensions. |
| Map keys and values are not standard. |
| An implementation must ignore entries that are not recognized. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>extensions</CODE> - the map of extensions<DT><B>Since:</B></DT> |
| <DD>2.0</DD> |
| <DT><B>See Also:</B><DD><A HREF="../../javax/jdo/Query.html#addExtension(java.lang.String, java.lang.Object)"><CODE>addExtension(java.lang.String, java.lang.Object)</CODE></A></DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="getFetchPlan()"><!-- --></A><H3> |
| getFetchPlan</H3> |
| <PRE> |
| <A HREF="../../javax/jdo/FetchPlan.html" title="interface in javax.jdo">FetchPlan</A> <B>getFetchPlan</B>()</PRE> |
| <DL> |
| <DD>Returns the <code>FetchPlan</code> used by this |
| <code>Query</code>. Modifications of the returned fetch plan will not |
| cause this query's owning <code>PersistenceManager</code>'s |
| <code>FetchPlan</code> to be modified. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| |
| <DT><B>Returns:</B><DD>the fetch plan used by this query<DT><B>Since:</B></DT> |
| <DD>2.0</DD> |
| </DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="deletePersistentAll(java.lang.Object[])"><!-- --></A><H3> |
| deletePersistentAll</H3> |
| <PRE> |
| long <B>deletePersistentAll</B>(java.lang.Object[] parameters)</PRE> |
| <DL> |
| <DD>Deletes all the instances of the candidate class that pass the |
| filter. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>parameters</CODE> - for the query |
| <DT><B>Returns:</B><DD>the number of instances of the candidate class that were deleted<DT><B>Since:</B></DT> |
| <DD>2.0</DD> |
| <DT><B>See Also:</B><DD><A HREF="../../javax/jdo/Query.html#deletePersistentAll()"><CODE>deletePersistentAll()</CODE></A></DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="deletePersistentAll(java.util.Map)"><!-- --></A><H3> |
| deletePersistentAll</H3> |
| <PRE> |
| long <B>deletePersistentAll</B>(java.util.Map parameters)</PRE> |
| <DL> |
| <DD>Deletes all the instances of the candidate class that pass the |
| filter. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Parameters:</B><DD><CODE>parameters</CODE> - for the query |
| <DT><B>Returns:</B><DD>the number of instances of the candidate class that were deleted<DT><B>Since:</B></DT> |
| <DD>2.0</DD> |
| <DT><B>See Also:</B><DD><A HREF="../../javax/jdo/Query.html#deletePersistentAll()"><CODE>deletePersistentAll()</CODE></A></DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="deletePersistentAll()"><!-- --></A><H3> |
| deletePersistentAll</H3> |
| <PRE> |
| long <B>deletePersistentAll</B>()</PRE> |
| <DL> |
| <DD>Deletes all the instances of the candidate class that pass the |
| filter. Returns the number of instances of the candidate |
| class that were deleted, specifically not including the number |
| of dependent and embedded instances. |
| <P>Dirty instances of affected classes in the cache are first |
| flushed to the datastore. Instances in the cache or brought into |
| the cache as a result of executing one of the |
| <code>deletePersistentAll</code> |
| methods undergo life cycle changes as if <code>deletePersistent</code> |
| were called on them. |
| <P>Specifically, if the class of deleted instances implements the |
| delete callback interface, the corresponding callback methods |
| are called on the deleted instances. Similarly, if there are |
| lifecycle listeners registered for delete events on affected |
| classes, the listener is called for each appropriate deleted instance. |
| <P>Before returning control to the application, instances of affected |
| classes in the cache are refreshed to reflect whether they were |
| deleted from the datastore. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| |
| <DT><B>Returns:</B><DD>the number of instances of the candidate class that were deleted<DT><B>Since:</B></DT> |
| <DD>2.0</DD> |
| </DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="setUnmodifiable()"><!-- --></A><H3> |
| setUnmodifiable</H3> |
| <PRE> |
| void <B>setUnmodifiable</B>()</PRE> |
| <DL> |
| <DD>The unmodifiable flag, when set, disallows further |
| modification of the query, except for specifying the range, |
| result class, and ignoreCache option. |
| The unmodifiable flag can also be set in metadata. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| <DT><B>Since:</B></DT> |
| <DD>2.0</DD> |
| </DL> |
| </DD> |
| </DL> |
| <HR> |
| |
| <A NAME="isUnmodifiable()"><!-- --></A><H3> |
| isUnmodifiable</H3> |
| <PRE> |
| boolean <B>isUnmodifiable</B>()</PRE> |
| <DL> |
| <DD>The unmodifiable flag, when set, disallows further |
| modification of the query, except for specifying the range, |
| result class, and ignoreCache option. |
| <P> |
| <DD><DL> |
| </DL> |
| </DD> |
| <DD><DL> |
| |
| <DT><B>Returns:</B><DD>the current setting of the flag<DT><B>Since:</B></DT> |
| <DD>2.0</DD> |
| </DL> |
| </DD> |
| </DL> |
| <!-- ========= END OF CLASS DATA ========= --> |
| <HR> |
| |
| |
| <!-- ======= START OF BOTTOM NAVBAR ====== --> |
| <A NAME="navbar_bottom"><!-- --></A> |
| <A HREF="#skip-navbar_bottom" title="Skip navigation links"></A> |
| <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> |
| <TR> |
| <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> |
| <A NAME="navbar_bottom_firstrow"><!-- --></A> |
| <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> |
| <TR ALIGN="center" VALIGN="top"> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD> |
| <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/Query.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> |
| </TR> |
| </TABLE> |
| </TD> |
| <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> |
| </EM> |
| </TD> |
| </TR> |
| |
| <TR> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| <A HREF="../../javax/jdo/PersistenceManagerFactory.html" title="interface in javax.jdo"><B>PREV CLASS</B></A> |
| <A HREF="../../javax/jdo/Transaction.html" title="interface in javax.jdo"><B>NEXT CLASS</B></A></FONT></TD> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| <A HREF="../../index.html?javax/jdo/Query.html" target="_top"><B>FRAMES</B></A> |
| <A HREF="Query.html" target="_top"><B>NO FRAMES</B></A> |
| <SCRIPT type="text/javascript"> |
| <!-- |
| if(window==top) { |
| document.writeln('<A HREF="../../allclasses-noframe.html"><B>All Classes</B></A>'); |
| } |
| //--> |
| </SCRIPT> |
| <NOSCRIPT> |
| <A HREF="../../allclasses-noframe.html"><B>All Classes</B></A> |
| </NOSCRIPT> |
| |
| |
| </FONT></TD> |
| </TR> |
| <TR> |
| <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> |
| SUMMARY: NESTED | <A HREF="#field_summary">FIELD</A> | CONSTR | <A HREF="#method_summary">METHOD</A></FONT></TD> |
| <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> |
| DETAIL: <A HREF="#field_detail">FIELD</A> | CONSTR | <A HREF="#method_detail">METHOD</A></FONT></TD> |
| </TR> |
| </TABLE> |
| <A NAME="skip-navbar_bottom"></A> |
| <!-- ======== END OF BOTTOM NAVBAR ======= --> |
| |
| <HR> |
| Copyright © 2005-2006 Apache Software Foundation. All Rights Reserved. |
| </BODY> |
| </HTML> |
