001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: */
019: package org.apache.openjpa.persistence;
020:
021: import java.util.Calendar;
022: import java.util.Collection;
023: import java.util.Date;
024: import java.util.Map;
025: import javax.persistence.FlushModeType;
026: import javax.persistence.Query;
027: import javax.persistence.TemporalType;
028:
029: import org.apache.openjpa.kernel.QueryFlushModes;
030: import org.apache.openjpa.kernel.QueryHints;
031: import org.apache.openjpa.kernel.QueryOperations;
032:
033: /**
034: * Interface implemented by OpenJPA queries.
035: *
036: * @since 0.4.0
037: * @author Abe White
038: * @published
039: */
040: public interface OpenJPAQuery extends Query {
041:
042: /**
043: * Hint key for specifying the number of rows to optimize for.
044: */
045: public static final String HINT_RESULT_COUNT = QueryHints.HINT_RESULT_COUNT;
046:
047: /**
048: * The owning entity manager.
049: */
050: public OpenJPAEntityManager getEntityManager();
051:
052: /**
053: * Query language.
054: */
055: public String getLanguage();
056:
057: /**
058: * Query operation type.
059: */
060: public QueryOperationType getOperation();
061:
062: /**
063: * Fetch plan for controlling the loading of results.
064: */
065: public FetchPlan getFetchPlan();
066:
067: /**
068: * Query string.
069: */
070: public String getQueryString();
071:
072: /**
073: * Whether to ignore changes in the current transaction.
074: */
075: public boolean getIgnoreChanges();
076:
077: /**
078: * Whether to ignore changes in the current transaction.
079: */
080: public OpenJPAQuery setIgnoreChanges(boolean ignore);
081:
082: /**
083: * Return the candidate collection, or <code>null</code> if an
084: * extent was specified instead of a collection.
085: */
086: public Collection getCandidateCollection();
087:
088: /**
089: * Set a collection of candidates.
090: */
091: public OpenJPAQuery setCandidateCollection(Collection coll);
092:
093: /**
094: * Query result element type.
095: */
096: public Class getResultClass();
097:
098: /**
099: * Query result element type.
100: */
101: public OpenJPAQuery setResultClass(Class type);
102:
103: /**
104: * Whether subclasses are included in the query results.
105: */
106: public boolean hasSubclasses();
107:
108: /**
109: * Whether subclasses are included in the query results.
110: */
111: public OpenJPAQuery setSubclasses(boolean subs);
112:
113: /**
114: * Return the 0-based start index for the returned results.
115: */
116: public int getFirstResult();
117:
118: /**
119: * Return the maximum number of results to retrieve.
120: * or {@link Integer#MAX_VALUE} for no limit.
121: */
122: public int getMaxResults();
123:
124: /**
125: * Compile the query.
126: */
127: public OpenJPAQuery compile();
128:
129: /**
130: * Whether this query has positional parameters.
131: */
132: public boolean hasPositionalParameters();
133:
134: /**
135: * The positional parameters for the query; empty array if none or
136: * if query uses named parameters.
137: */
138: public Object[] getPositionalParameters();
139:
140: /**
141: * The named parameters for the query; empty map if none or
142: * if query uses named parameters.
143: */
144: public Map getNamedParameters();
145:
146: /**
147: * Set parameters.
148: */
149: public OpenJPAQuery setParameters(Map params);
150:
151: /**
152: * Set parameters.
153: */
154: public OpenJPAQuery setParameters(Object... params);
155:
156: /**
157: * Close all open query results.
158: */
159: public OpenJPAQuery closeAll();
160:
161: /**
162: * Returns a description of the commands that will be sent to
163: * the datastore in order to execute this query. This will
164: * typically be in the native query language of the database (e.g., SQL).
165: *
166: * @param params the named parameter map for the query invocation
167: */
168: public String[] getDataStoreActions(Map params);
169:
170: public OpenJPAQuery setMaxResults(int maxResult);
171:
172: public OpenJPAQuery setFirstResult(int startPosition);
173:
174: public OpenJPAQuery setHint(String hintName, Object value);
175:
176: public OpenJPAQuery setParameter(String name, Object value);
177:
178: public OpenJPAQuery setParameter(String name, Date value,
179: TemporalType temporalType);
180:
181: public OpenJPAQuery setParameter(String name, Calendar value,
182: TemporalType temporalType);
183:
184: public OpenJPAQuery setParameter(int position, Object value);
185:
186: public OpenJPAQuery setParameter(int position, Date value,
187: TemporalType temporalType);
188:
189: public OpenJPAQuery setParameter(int position, Calendar value,
190: TemporalType temporalType);
191:
192: public OpenJPAQuery setFlushMode(FlushModeType flushMode);
193:
194: /**
195: * Return the current flush mode.
196: */
197: public FlushModeType getFlushMode();
198:
199: /**
200: * @deprecated use the {@link QueryOperationType} instead.
201: */
202: public static final int OP_SELECT = QueryOperations.OP_SELECT;
203:
204: /**
205: * @deprecated use the {@link QueryOperationType} instead.
206: */
207: public static final int OP_DELETE = QueryOperations.OP_DELETE;
208:
209: /**
210: * @deprecated use the {@link QueryOperationType} instead.
211: */
212: public static final int OP_UPDATE = QueryOperations.OP_DELETE;
213:
214: /**
215: * @deprecated use the {@link FlushModeType} enum instead.
216: */
217: public static final int FLUSH_TRUE = QueryFlushModes.FLUSH_TRUE;
218:
219: /**
220: * @deprecated use the {@link FlushModeType} enum instead.
221: */
222: public static final int FLUSH_FALSE = QueryFlushModes.FLUSH_FALSE;
223:
224: /**
225: * @deprecated use the {@link FlushModeType} enum instead.
226: */
227: public static final int FLUSH_WITH_CONNECTION = QueryFlushModes.FLUSH_WITH_CONNECTION;
228:
229: /**
230: * @deprecated cast to {@link QueryImpl} instead. This
231: * method pierces the published-API boundary, as does the SPI cast.
232: */
233: public OpenJPAQuery addFilterListener(
234: org.apache.openjpa.kernel.exps.FilterListener listener);
235:
236: /**
237: * @deprecated cast to {@link QueryImpl} instead. This
238: * method pierces the published-API boundary, as does the SPI cast.
239: */
240: public OpenJPAQuery removeFilterListener(
241: org.apache.openjpa.kernel.exps.FilterListener listener);
242:
243: /**
244: * @deprecated cast to {@link QueryImpl} instead. This
245: * method pierces the published-API boundary, as does the SPI cast.
246: */
247: public OpenJPAQuery addAggregateListener(
248: org.apache.openjpa.kernel.exps.AggregateListener listener);
249:
250: /**
251: * @deprecated cast to {@link QueryImpl} instead. This
252: * method pierces the published-API boundary, as does the SPI cast.
253: */
254: public OpenJPAQuery removeAggregateListener(
255: org.apache.openjpa.kernel.exps.AggregateListener listener);
256: }
|