001: /**********************************************************************
002: Copyright (c) 2005 Erik Bengtson and others. All rights reserved.
003: Licensed under the Apache License, Version 2.0 (the "License");
004: you may not use this file except in compliance with the License.
005: You may obtain a copy of the License at
006:
007: http://www.apache.org/licenses/LICENSE-2.0
008:
009: Unless required by applicable law or agreed to in writing, software
010: distributed under the License is distributed on an "AS IS" BASIS,
011: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012: See the License for the specific language governing permissions and
013: limitations under the License.
014:
015:
016: Contributors:
017: ...
018: **********************************************************************/package org.jpox.store.expression;
019:
020: import java.util.HashMap;
021:
022: import org.jpox.ClassLoaderResolver;
023: import org.jpox.store.DatastoreContainerObject;
024: import org.jpox.store.DatastoreIdentifier;
025: import org.jpox.store.StoreManager;
026: import org.jpox.store.mapping.JavaTypeMapping;
027: import org.jpox.store.query.StatementText;
028:
029: /**
030: * Expression for a query in language-independent form.
031: */
032: public interface QueryExpression {
033: /**
034: * Sets the parent QueryExpression of this query. In SQL it can be exemplified as
035: * <code>
036: * SELECT 1 FROM PARENT WHERE EXISTS (SELECT 1 FROM THIS)
037: * </code>
038: * The parent QueryExpression is the nesting SQL.
039: *
040: * @param parentQueryExpr the parent of this query
041: **/
042: void setParent(QueryExpression parentQueryExpr);
043:
044: /**
045: * Accessor for the parent QueryExpression if this is a nested expression.
046: * @return Parent expression
047: */
048: QueryExpression getParent();
049:
050: /**
051: * Method to set the candidate class and alias in use by the query.
052: * The expression is created with a candidate table, yet this could store more than 1 class.
053: * Additionally the "alias" of the candidate table expression is a DatastoreIdentifier whereas
054: * this alias here is a String form.
055: * @param cls The candidate class
056: * @param alias The alias
057: */
058: void setCandidateInformation(Class cls, String alias);
059:
060: /**
061: * Accessor for the candidate class of the query expression.
062: * @return Candidate class
063: */
064: Class getCandidateClass();
065:
066: /**
067: * Accessor for the candidate alias in use by the query.
068: * @return Candidate alias
069: */
070: String getCandidateAlias();
071:
072: /**
073: * Accessor for the expression for the main table of this query.
074: * This is the same as the default table expression except where this is a subquery.
075: * @return Main table expression
076: */
077: LogicSetExpression getMainTableExpression();
078:
079: /**
080: * Accessor for the alias of the main table of this query.
081: * @return Alias for the main table in the query
082: */
083: DatastoreIdentifier getMainTableAlias();
084:
085: /**
086: * Accessor to the table expression for the given alias.
087: * @param alias the alias
088: * @return the TableExpression
089: */
090: LogicSetExpression getTableExpression(DatastoreIdentifier alias);
091:
092: /**
093: * Creates a table expression
094: * @param mainTable the main table
095: * @param alias the alias
096: * @return TableExpression
097: */
098: LogicSetExpression newTableExpression(
099: DatastoreContainerObject mainTable,
100: DatastoreIdentifier alias);
101:
102: /**
103: * Creates a table expression
104: * @param mainTable the main table
105: * @param alias the alias
106: * @param unionQueries Whether to add to any union
107: * @return TableExpression[]
108: */
109: LogicSetExpression[] newTableExpression(
110: DatastoreContainerObject mainTable,
111: DatastoreIdentifier alias, boolean unionQueries);
112:
113: /**
114: * Accessor for the store manager associated with this query.
115: * @return The store manager
116: */
117: StoreManager getStoreManager();
118:
119: /**
120: * Accessor for the ClassLoaderResolver to use with this query statement.
121: * @return ClassLoader resolver
122: */
123: ClassLoaderResolver getClassLoaderResolver();
124:
125: /**
126: * Set whether this statement returns distinct results.
127: * @param distinctResults Whether we return distinct results
128: */
129: void setDistinctResults(boolean distinctResults);
130:
131: /**
132: * Method to define an extension for this query statement allowing control over its behaviour
133: * in generating a query.
134: * @param key Extension key
135: * @param value Value for the key
136: */
137: void addExtension(String key, Object value);
138:
139: /**
140: * Accessor for the value for an extension.
141: * @param key Key for the extension
142: * @return Value for the extension (if any)
143: */
144: Object getValueForExtension(String key);
145:
146: /**
147: * Accessor for the extensions for this expression.
148: * @return Extensions
149: */
150: HashMap getExtensions();
151:
152: /**
153: * Whether this query will return a meta data expression in the SELECT clause
154: * @return hasMetaDataExpression
155: */
156: boolean hasMetaDataExpression();
157:
158: /**
159: * Select the datastore identity column.
160: * @param alias Alias to use for this column
161: * @param unionQueries Whether to select the datastore id column of all unioned tables
162: * @return The position of the column in the result set
163: */
164: int[] selectDatastoreIdentity(String alias, boolean unionQueries);
165:
166: /**
167: * Select the version column.
168: * @param alias Alias to use for this column
169: * @param unionQueries Whether to select the version column of all unioned tables
170: * @return The position of the column in the result set
171: */
172: int[] selectVersion(String alias, boolean unionQueries);
173:
174: /**
175: * Select the column(s) for the specified field in the primary table of the query.
176: * @param fieldName Name of the field
177: * @param alias Alias to use for these column(s)
178: * @param unionQueries Whether to select the field column(s) of all unioned queries.
179: * @return The position of the columns in the result set.
180: */
181: int[] selectField(String fieldName, String alias,
182: boolean unionQueries);
183:
184: /**
185: * Select the columns for a mapping
186: * @param mapping The mapping
187: * @return The index of the columns in the select
188: **/
189: int[] select(JavaTypeMapping mapping);
190:
191: /**
192: * select a new column, add to union queries, if unionQueries is true
193: * @param mapping The mapping
194: * @param unionQueries Whether to add to any union
195: * @return The index of the columns in the select
196: */
197: int[] select(JavaTypeMapping mapping, boolean unionQueries);
198:
199: /**
200: * select an expression; eg: "'Text' as alias"
201: * @param expr The expression to add to the select statement
202: * @return The index of the expression in the select
203: */
204: int selectScalarExpression(ScalarExpression expr);
205:
206: /**
207: * select an expression; eg: "'Text' as alias"
208: * @param expr The expression to add to the select statement
209: * @param unionQueries whether to apply the select in all queries unified by the union clause
210: * @return The index of the expression in the select
211: */
212: int selectScalarExpression(ScalarExpression expr,
213: boolean unionQueries);
214:
215: /**
216: * Select columns, add to union queries, if unionQueries is true
217: * @param alias The alias
218: * @param mapping The mapping
219: * @return The index of the columns in the select
220: */
221: int[] select(DatastoreIdentifier alias, JavaTypeMapping mapping);
222:
223: /**
224: * select columns, add to union queries, if unionQueries is true
225: * @param alias The alias
226: * @param mapping The mapping
227: * @param unionQueries Whether to add to any union
228: * @return The index of the column in the select
229: */
230: int[] select(DatastoreIdentifier alias, JavaTypeMapping mapping,
231: boolean unionQueries);
232:
233: /**
234: * add an condition to the query.
235: * @param condition the Boolean expression
236: */
237: void andCondition(BooleanExpression condition);
238:
239: /**
240: * add an condition to the query and queries involved in the union if unionQuery is true
241: * @param condition the Boolean expression
242: * @param unionQueries whether to apply the condition in all queries unified by the union clause
243: */
244: void andCondition(BooleanExpression condition, boolean unionQueries);
245:
246: /**
247: * Method to add tables/crossJoin but no joins to they, will be output as FROM TABLE1,TABLE2,TABLE3
248: * @param tableExpr table expression
249: * @param unionQueries Whether to apply the alias to unions of this query.
250: **/
251: void crossJoin(LogicSetExpression tableExpr, boolean unionQueries);
252:
253: /**
254: * Method to add tables/alias but no joins to they, will be output as FROM TABLE1,TABLE2,TABLE3
255: * Checks parent expressions until reach the root expression
256: * @param tableExpr table expression
257: **/
258: boolean hasCrossJoin(LogicSetExpression tableExpr);
259:
260: /**
261: * Method to do an inner join to another table, and optionally apply it to
262: * any unions for this query.
263: * @param expr the left hand expression
264: * @param expr2 the right hand expression
265: * @param tblExpr the
266: * @param equals if the join is applied as filter, if use equals or not equals
267: * @param unionQueries whether to apply the inner join in all queries unified by the union clause
268: **/
269: void innerJoin(ScalarExpression expr, ScalarExpression expr2,
270: LogicSetExpression tblExpr, boolean equals,
271: boolean unionQueries);
272:
273: /**
274: * Method to do an inner join to another table.
275: * @param expr the left hand expression
276: * @param expr2 the right hand expression
277: * @param tblExpr The table expression for the table to apply the join
278: * @param equals if the join is applied as filter, if use equals or not equals
279: **/
280: void innerJoin(ScalarExpression expr, ScalarExpression expr2,
281: LogicSetExpression tblExpr, boolean equals);
282:
283: /**
284: * Method to do a left outer join to another table, and optionally apply it
285: * to any unions for this query.
286: * @param expr the left hand expression
287: * @param expr2 the right hand expression
288: * @param tblExpr The table expression for the table to apply the join
289: * @param equals if the join is applied as filter, if use equals or not equals
290: * @param unionQueries Whether to apply to unions of this query.
291: **/
292: void leftOuterJoin(ScalarExpression expr, ScalarExpression expr2,
293: LogicSetExpression tblExpr, boolean equals,
294: boolean unionQueries);
295:
296: /**
297: * Method to do a left outer join to another table.
298: * @param expr the left hand expression
299: * @param expr2 the right hand expression
300: * @param tblExpr The table expression
301: * @param equals if the join is applied as filter, if use equals or not equals
302: **/
303: void leftOuterJoin(ScalarExpression expr, ScalarExpression expr2,
304: LogicSetExpression tblExpr, boolean equals);
305:
306: /**
307: * Method to do a right outer join to another table, and optionally apply it
308: * to any unions for this query.
309: * @param expr the left hand expression
310: * @param expr2 the right hand expression
311: * @param tblExpr The table expression for the table to apply the join
312: * @param equals if the join is applied as filter, if use equals or not equals
313: * @param unionQueries Whether to apply to unions of this query.
314: **/
315: void rightOuterJoin(ScalarExpression expr, ScalarExpression expr2,
316: LogicSetExpression tblExpr, boolean equals,
317: boolean unionQueries);
318:
319: /**
320: * Method to do a right outer join to another table.
321: * @param expr the left hand expression
322: * @param expr2 the right hand expression
323: * @param tblExpr The table expression for the table to apply the join
324: * @param equals if the join is applied as filter, if use equals or not equals
325: **/
326: void rightOuterJoin(ScalarExpression expr, ScalarExpression expr2,
327: LogicSetExpression tblExpr, boolean equals);
328:
329: /**
330: * Method to add a grouping clause to the statement.
331: * Grouping clauses that are implied by the selected columns will be added automatically
332: * so this provides a means to supplement them.
333: * @param expr The group by expression
334: */
335: void addGroupingExpression(ScalarExpression expr);
336:
337: /**
338: * Accessor for the grouping expressions of this statement.
339: * @return The grouping expressions
340: */
341: ScalarExpression[] getGroupingExpressions();
342:
343: /**
344: * Method to set the having clause of the statement.
345: * @param expr The having expression
346: */
347: void setHaving(BooleanExpression expr);
348:
349: /**
350: * Accessor for the having expression of this statement.
351: * @return The having expression
352: */
353: BooleanExpression getHavingExpression();
354:
355: /**
356: * Mutator for the ordering criteria.
357: * @param exprs The expressions to order by
358: * @param descending Whether each expression is ascending/descending
359: **/
360: void setOrdering(ScalarExpression[] exprs, boolean[] descending);
361:
362: /**
363: * Accessor for the ordering expressions of this statement.
364: * @return The ordering expressions
365: */
366: ScalarExpression[] getOrderingExpressions();
367:
368: /**
369: * set the update condition(s) for the query.
370: * @param exprs the Boolean expression
371: */
372: void setUpdates(ScalarExpression[] exprs);
373:
374: /**
375: * Union two QueryExpressions <code>this</code> and <code>qe</code>.
376: * Both QueryExpressions must have the same ScalarExpressions selected,
377: * and they must be in the same select order.
378: * valid:
379: * e.g. a) fieldA, fieldB, fieldE, fieldC
380: * b) fieldA, fieldB, fieldE, fieldC
381: * invalid:
382: * e.g. a) fieldA, fieldE, fieldB, fieldC
383: * b) fieldA, fieldB, fieldE, fieldC
384: *
385: * @param qe the QueryExpression
386: */
387: void union(QueryExpression qe);
388:
389: /**
390: * add an condition to the query.
391: * @param condition the Boolean expression
392: */
393: void iorCondition(BooleanExpression condition);
394:
395: /**
396: * add an condition to the query and queries involved in the union if unionQuery is true
397: * @param condition the Boolean expression
398: * @param unionQueries whether to apply the condition in all queries unified by the union clause
399: */
400: void iorCondition(BooleanExpression condition, boolean unionQueries);
401:
402: /**
403: * Method to add a range constraint on any SELECT.
404: * This typically will use LIMIT/OFFSET where they are supported by
405: * the underlying RDBMS.
406: * @param offset The offset to start from
407: * @param count The number of records to return
408: */
409: void setRangeConstraint(long offset, long count);
410:
411: /**
412: * Set this query is to be used as a as set for the Exists function.
413: * example WHERE EXISTS( QUERY )
414: * @param isExistsSubQuery The isExistsSubQuery to set.
415: */
416: void setExistsSubQuery(boolean isExistsSubQuery);
417:
418: /**
419: * Accessor for the number of ScalarExpression projected.
420: * @return The number of columns in the SELECT
421: **/
422: int getNumberOfScalarExpressions();
423:
424: /**
425: * Method to convert the criteria into a delete statement text.
426: * @return The StatementText
427: **/
428: StatementText toDeleteStatementText();
429:
430: /**
431: * Method to convert the criteria into an update statement text.
432: * @return The StatementText
433: **/
434: StatementText toUpdateStatementText();
435:
436: /**
437: * Method to convert the criteria into the statement text.
438: * @param lock whether to lock the instances using this statement
439: * @return The StatementText
440: **/
441: StatementText toStatementText(boolean lock);
442:
443: /**
444: * Allows reseting the compiled expression
445: */
446: void reset();
447: }
|