Query


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  /*
25   * Query.java
26   *
27   * Created on February 25, 2000
28   */
29   
30  package com.sun.jdo.api.persistence.support;
31  import java.io.Serializable  ;
32  import java.util.Collection  ;
33  import java.util.Map  ;
34  
35  /** The Query interface allows applications to obtain persistent instances
36   * from the data store.
37   *
38   * The @link PersistenceManager is the factory for Query instances.  There
39   * may be many Query instances associated with a PersistenceManager.  Multiple
40   * queries might be executed simultaneously by different threads, but the
41   * implementation might choose to execute them serially.  In either case, the
42   * implementation must be thread safe.
43   *
44   * <P>There are three required elements in a Query: 
45   * the class of the candidate instances,
46   * the candidate collection of instances, and the filter.
47   *
48   * <P>There are optional elements: parameter declarations, variable
49   * declarations, import statements, and an ordering specification.
50   *
51   * @author Craig Russell
52   * @version 0.1
53   */
54  
55  public interface Query extends java.io.Serializable   
56  {
57      /** Set the class of the candidate instances of the query.
58       * <P>The class is a PersistenceCapable class which specifies the class
59       * of the candidates of the query.  Elements of the candidate collection
60       * that are of the specified class are filtered before being
61       * put into the result Collection.
62       * @param cls the Class of the candidate instances.
63       */
64      void setClass(Class   cls);
65      
66      /** Set the candidate Collection to query.
67       * @param pcs the Candidate collection.
68       */
69      void setCandidates(Collection   pcs);
70      
71      /** Set the filter for the query.
72       *
73       * The filter is a Java-like boolean expression used to select elements of the
74       * candidate Collection.
75       * @param filter the query filter.
76       */
77      void setFilter(String   filter);
78      
79      /** Set the import statements to be used to identify the package name of
80       * variables or parameters.
81       * @param imports import statements separated by semicolons.
82       */
83      void declareImports(String   imports);
84      
85      /** Set the parameter list for query execution.
86       *
87       * The types and names of execution parameters are specified as a String
88       * separated by commas, similar to formal method declarations.
89       *
90       * @param parameters the list of parameters separated by commas.
91       */
92      void declareParameters(String   parameters);
93      /** Declare the unbound variables to be used in the query.
94       *
95       * @param variables the variables separated by semicolons.
96       */
97      void declareVariables(String   variables);
98      
99      /** Bind the ordering declarations to the query instance.
100      * The ordering consists of one or more ordering declarations separated by commas. 
101      * Each ordering declaration is the name of the field in the name scope of the
102      * candidate class followed by one of the following words: ascending or descending.
103      *
104      * @param ordering the ordering declarations separated by comma.
105      */
106     void setOrdering (String   ordering);
107 
108     /**
109      * Set the result of the query.
110      * <p>
111      * The query result is an optional keyword distinct followed by a Java 
112      * expression, which tells what values are to be returned by the JDO query.
113      * If the result is not specified, then it defaults to "distinct this", 
114      * which has the effect of returning the elements of the candidates 
115      * that match the filter.
116      */
117     void setResult(String   result);
118 
119     /** Sets the prefetchEnabled option.
120      *
121      * The prefetchEnabled option specifies whether prefetch of relationship
122      * fields should be enabled for this query. The prefetch is enabled by
123      * default if such fields are part of DFG. A user needs to explicitely 
124      * disable prefetch for any particular query if the related instances 
125      * will not be used in this transaction.
126      *
127      * @param prefetchEnabled the setting of the prefetchEnabled option.
128      */ 
129     void setPrefetchEnabled(boolean prefetchEnabled);
130     
131     /** Set the ignoreCache option.
132      *
133      * The ignoreCache option setting specifies whether the query should execute
134      * entirely in the back end, instead of in the cache.
135      * @param ignoreCache the setting of the ignoreCache option.
136      */
137     void setIgnoreCache(boolean ignoreCache);
138     
139     /** Get the ignoreCache option setting.
140      * @return the ignoreCache option setting.
141      * @see #setIgnoreCache
142      */
143     boolean getIgnoreCache();
144     
145     /** Verify the elements of the query and provide a hint to the query to
146      * prepare and optimize an execution plan.
147      */
148     void compile();
149     
150     /** Execute the query and return the filtered Collection.
151      * @return the filtered Collection.
152      * @see #executeWithArray (Object[] parameters)
153      */
154     Object   execute();
155     
156     /** Execute the query and return the filtered Collection.
157      * @return the filtered Collection.
158      * @see #executeWithArray (Object[] parameters)
159      * @param p1 the value of the first parameter declared.
160      */
161     Object   execute(Object   p1);
162     
163     /** Execute the query and return the filtered Collection.
164      * @return the filtered Collection.
165      * @see #executeWithArray (Object[] parameters)
166      * @param p1 the value of the first parameter declared.
167      * @param p2 the value of the second parameter declared.
168      */
169     Object   execute(Object   p1, Object   p2);
170     
171     /** Execute the query and return the filtered Collection.
172      * @return the filtered Collection.
173      * @see #executeWithArray (Object[] parameters)
174      * @param p1 the value of the first parameter declared.
175      * @param p2 the value of the second parameter declared.
176      * @param p3 the value of the third parameter declared.
177      */
178     Object   execute(Object   p1, Object   p2, Object   p3);
179     
180     /** Execute the query and return the filtered Collection.
181      * @return the filtered Collection.
182      * @see #executeWithArray (Object[] parameters)
183      * @param parameters the Map containing all of the parameters.
184      */
185     Object   executeWithMap (Map   parameters);
186     
187     /** Execute the query and return the filtered Collection.
188      *
189      * <P>The execution of the query obtains the values of the parameters and
190      * matches them against the declared parameters in order.  The type of
191      * the declared parameters must match the type of the passed parameters,
192      * except that the passed parameters might need to be unwrapped to get
193      * their primitive values.
194      *
195      * <P>The filter, import, declared parameters, declared variables, and
196      * ordering statements are verified for consistency.
197      *
198      * <P>Each element in the candidate Collection is examined to see that it
199      * is assignment compatible to the Class of the query.  It is then evaluated
200      * by the boolean expression of the filter.  The element passes the filter
201      * if there exist unique values for all variables for which the filter
202      * expression evaluates to true.
203      * @return the filtered Collection.
204      * @param parameters the Object array with all of the parameters.
205      */
206     Object   executeWithArray (Object  [] parameters);
207     
208     /** Get the PersistenceManager associated with this Query.
209      *
210      * <P>If this Query has no PersistenceManager return null.
211      * @return the PersistenceManager associated with this Query.
212      */
213     PersistenceManager getPersistenceManager();
214 }
215 
216
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags