001: /**
002: * Objective Database Abstraction Layer (ODAL)
003: * Copyright (c) 2004, The ODAL Development Group
004: * All rights reserved.
005: * For definition of the ODAL Development Group please refer to LICENCE.txt file
006: *
007: * Distributable under LGPL license.
008: * See terms of license at gnu.org.
009: */package com.completex.objective.components.persistency;
010:
011: import com.completex.objective.components.persistency.core.DatabasePolicy;
012: import com.completex.objective.components.persistency.core.Join;
013: import com.completex.objective.components.persistency.core.Union;
014: import com.completex.objective.components.persistency.core.UnionMode;
015: import com.completex.objective.components.persistency.core.impl.LinkIterator;
016:
017: import java.util.List;
018:
019: /**
020: * Represents SQL SELECT statement
021: *
022: * @author Gennady Krizhevsky
023: */
024: public interface Query extends BasicQuery, BasicQueryFactory,
025: Cloneable, ResultableQuery {
026:
027: public static final OrderDirection DIR_ASC = OrderDirection.ASC;
028: public static final OrderDirection DIR_DESC = OrderDirection.DESC;
029:
030: //
031: // Select:
032: //
033:
034: /**
035: * Represents SQL SELECT clause.
036: * Each element of <code>select<code/> parameter will be joined by comma when compiling.
037: *
038: * @param select set of SQL SELECT columns (No 'SELECT' keyword necessary)
039: * @return itself
040: */
041: Query setSelect(String[] select);
042:
043: /**
044: * @return set of SQL SELECT columns
045: */
046: String[] getSelect();
047:
048: /**
049: * Adds columnExpression SQL fragment to SQL SELECT columns
050: *
051: * @param columnExpression
052: * @return itself
053: */
054: Query addToSelect(String columnExpression);
055:
056: /**
057: * Adds columnExpression SQL fragment to SQL SELECT columns
058: *
059: * @param persistentObject persistentObject which MetaTable is used to get columns
060: * @return itself
061: */
062: Query addToSelect(PersistentObjectFactory persistentObject);
063:
064: //
065: // From / Join:
066: //
067:
068: /**
069: * Represents SQL FROM clause.
070: *
071: * @return set of SQL FROM columns
072: */
073: String[] getFrom();
074:
075: /**
076: * Represents SQL FROM clause.
077: *
078: * @return set of SQL FROM columns
079: */
080: List getFromAsList();
081:
082: /**
083: * Represents SQL FROM clause.
084: * Each element of <code>from<code/> parameter will be joined by comma when compiling.
085: *
086: * @param from set of SQL FROM columns (No 'SELECT' keyword necessary)
087: * @return itself
088: */
089: Query setFrom(String[] from);
090:
091: /**
092: * Adds tableExpression SQL fragment to SQL FROM tables
093: *
094: * @param tableExpression
095: * @return itself
096: */
097: Query addToFrom(String tableExpression);
098:
099: /**
100: * Addes new Join object to this query
101: *
102: * @param firstTableName
103: * @return new Join object
104: * @see Join
105: */
106: Join addJoin(String firstTableName);
107:
108: /**
109: * Creates new Join object
110: *
111: * @param firstTableName
112: * @return new Join object
113: * @see Join
114: */
115: Join newJoin(String firstTableName);
116:
117: /**
118: * @return Join object or null if not set or added
119: */
120: Join getJoin();
121:
122: /**
123: * @param join Join object
124: * @return itself
125: */
126: Query setJoin(Join join);
127:
128: //
129: // Where:
130: //
131:
132: /**
133: * Adds SQL fragment to WHERE clause
134: *
135: * @param sql
136: * @return itself
137: */
138: Query addToWhere(String sql);
139:
140: /**
141: * Adds SQL fragment to WHERE clause prepended with " AND "
142: *
143: * @param sql
144: * @return itself
145: */
146: Query andToWhere(String sql);
147:
148: /**
149: * Adds SQL fragment to WHERE clause prepended with " OR "
150: *
151: * @param sql
152: * @return itself
153: */
154: Query orToWhere(String sql);
155:
156: /**
157: * Adds SQL fragment to WHERE clause based on PersistentObject values which are joined by "AND".
158: * Only placeholders are added to the query statement. Use
159: * <t>Query.addAllParameters(persistentObject.toParameters())</t>
160: * to add the parameters.
161: *
162: * @param persistentObject
163: * @return itself
164: */
165: Query addToWhere(PersistentObject persistentObject);
166:
167: /**
168: * Adds SQL fragment to WHERE clause based on PersistentObject values which are joined by "AND"
169: * and prepended with " AND ".
170: * Only placeholders are added to the query statement. Use
171: * <t>Query.addAllParameters(persistentObject.toParameters())</t>
172: * to add the parameters.
173: *
174: * @param persistentObject
175: * @return itself
176: */
177: Query andToWhere(PersistentObject persistentObject);
178:
179: /**
180: * Adds SQL fragment to WHERE clause based on PersistentObject values which are joined by "AND"
181: * and prepended with " OR ".
182: * Only placeholders are added to the query statement. Use
183: * <t>Query.addAllParameters(persistentObject.toParameters())</t>
184: * to add the parameters.
185: *
186: * @param persistentObject
187: * @return itself
188: */
189: Query orToWhere(PersistentObject persistentObject);
190:
191: /**
192: * Adds SQL fragment to WHERE clause based on PersistentObject values which are joined by "AND".
193: *
194: * @param persistentObject
195: * @param addParameters if true then not only placeholders are added to the query statement but
196: * <t>Query.addAllParameters(persistentObject.toParameters())</t> is issued internally
197: * to add the parameters.
198: * Make sure that all the paramters that are supposed to go before these paramters are set.
199: * @return itself
200: */
201: Query addToWhere(PersistentObject persistentObject,
202: boolean addParameters);
203:
204: /**
205: * Adds SQL fragment to WHERE clause based on PersistentObject values which are joined by "AND"
206: * and prepended with " AND ".
207: *
208: * @param persistentObject
209: * @param addParameters if true then not only placeholders are added to the query statement but
210: * <t>Query.addAllParameters(persistentObject.toParameters())</t> is issued internally
211: * to add the parameters.
212: * Make sure that all the paramters that are supposed to go before these paramters are set.
213: * @return itself
214: */
215: Query andToWhere(PersistentObject persistentObject,
216: boolean addParameters);
217:
218: /**
219: * Adds SQL fragment to WHERE clause based on PersistentObject values which are joined by "AND"
220: * and prepended with " OR ".
221: *
222: * @param persistentObject
223: * @param addParameters if true then not only placeholders are added to the query statement but
224: * <t>Query.addAllParameters(persistentObject.toParameters())</t> is issued internally
225: * to add the parameters.
226: * Make sure that all the paramters that are supposed to go before these paramters are set.
227: * @return itself
228: */
229: Query orToWhere(PersistentObject persistentObject,
230: boolean addParameters);
231:
232: /**
233: * Adds parameter placeholder to WHERE clause and adds parameter to the query.
234: * Make sure that all the paramters that are supposed to go before this paramter are set.
235: *
236: * @param parameter
237: * @return itself
238: */
239: Query addToWhere(Parameter parameter);
240:
241: /**
242: * Set SQL WHERE clause w/o 'WHERE' keyword
243: *
244: * @param sql
245: * @return itself
246: */
247: Query setWhere(String sql);
248:
249: /**
250: * Returns SQL WHERE clause w/o 'WHERE' keyword
251: *
252: * @return SQL WHERE clause
253: */
254: String getWhere();
255:
256: Query addToChainedColumns(int columnIndex, String tableName,
257: String columnName);
258:
259: QueryDefinition.ChainedColumn[] getChainedColumns();
260:
261: boolean hasChainedColumns();
262:
263: void clearChainedColumns();
264:
265: //
266: // Order By:
267: //
268:
269: /**
270: * Represents SQL ORDER BY clause.
271: * Each element of <code>orderBy<code/> parameter will be joined by comma when compiling.
272: *
273: * @param orderBy set of SQL ORDER BY columns (No 'ORDER BY' keyword necessary)
274: * @return itself
275: */
276: Query setOrderBy(String[] orderBy);
277:
278: /**
279: * Returns set of SQL ORDER BY columns
280: *
281: * @return set of SQL ORDER BY columns
282: */
283: String[] getOrderBy();
284:
285: /**
286: * Adds columnExpression SQL fragment to SQL ORDER BY columns
287: *
288: * @param columnExpression
289: * @param direction Ascending or descending
290: * @return itself
291: */
292: Query addToOrderBy(String columnExpression, OrderDirection direction);
293:
294: /**
295: * Adds columnExpression SQL fragment to SQL ORDER BY columns with default direction
296: *
297: * @param columnExpression
298: * @return itself
299: */
300: Query addToOrderBy(String columnExpression);
301:
302: //
303: // Group By:
304: //
305:
306: /**
307: * Represents SQL GROUP BY clause.
308: * Each element of <code>groupBy<code/> parameter will be joined by comma when compiling.
309: *
310: * @param groupBy set of SQL GROUP BY columns (No 'GROUP BY' keyword necessary)
311: * @return itself
312: */
313: Query setGroupBy(String[] groupBy);
314:
315: /**
316: * Returns set of SQL GROUP BY columns
317: *
318: * @return set of SQL GROUP BY columns
319: */
320: String[] getGroupBy();
321:
322: /**
323: * Adds columnExpression SQL fragment to SQL GROUP BY columns
324: *
325: * @param columnExpression
326: * @return itself
327: */
328: Query addToGroupBy(String columnExpression);
329:
330: //
331: // Having:
332: //
333:
334: /**
335: * Sets SQL HAVING clause
336: *
337: * @param sql
338: * @return itself
339: */
340: Query setHaving(String sql);
341:
342: /**
343: * @return SQL HAVING clause
344: */
345: String getHaving();
346:
347: /**
348: * Adds SQL fragment to HAVING clause
349: *
350: * @param sql
351: * @return itself
352: */
353: Query addToHaving(String sql);
354:
355: /**
356: * Adds SQL fragment to HAVING clause prepended with " AND "
357: *
358: * @param sql
359: * @return itself
360: */
361: Query andToHaving(String sql);
362:
363: /**
364: * Adds SQL fragment to HAVING clause prepended with " OR "
365: *
366: * @param sql
367: * @return itself
368: */
369: Query orToHaving(String sql);
370:
371: //
372: // Distinct:
373: //
374:
375: /**
376: * @param distinct true if query is to return unique values
377: * @return itself
378: */
379: Query setDistinct(boolean distinct);
380:
381: /**
382: * @return true if query is to return unique values
383: */
384: boolean isDistinct();
385:
386: //
387: // Lock:
388: //
389:
390: /**
391: * Sets query lock
392: *
393: * @param lockType LockType
394: * @return itself
395: * @see LockType
396: */
397: Query setLocked(LockType lockType);
398:
399: /**
400: * Sets query lock
401: *
402: * @param lockType LockType
403: * @param forUpdateOf array of fields used in "for update of" SQL fragment
404: * @return itself
405: * @see LockType
406: */
407: Query setLocked(LockType lockType, String[] forUpdateOf);
408:
409: /**
410: * Returns set of columns of lock clause
411: *
412: * @return set of columns of lock clause
413: */
414: String[] getForUpdateOf();
415:
416: /**
417: * Returns true if query has lock clause
418: *
419: * @return true if query has lock clause
420: */
421: boolean isLocked();
422:
423: /**
424: * Returns true if lock clause of type that will wait untinl another process will free resource
425: *
426: * @return true if lock clause of type that will wait untinl another process will free resource
427: */
428: boolean isWait();
429:
430: /**
431: * Sets lock timeout. In future may be used as query timeout as well
432: *
433: * @param timeout
434: */
435: void setTimeout(long timeout);
436:
437: /**
438: * Gets lock timeout. In future may be used as query timeout as well
439: *
440: * @return timeout
441: */
442: long getTimeout();
443:
444: //
445: // Star:
446: //
447:
448: /**
449: * Sets mode of select. If <code>useSelectStar<code/> set true then select clause will look like:
450: * "SELECT * ...". Should be used carefully since if SQL has column that does not exist in the object
451: * used as data container then execution will fail
452: *
453: * @param useSelectStar
454: */
455: void setUseSelectStar(boolean useSelectStar);
456:
457: /**
458: * @return true then select clause will look like:
459: * "SELECT * ..."
460: */
461: boolean isUseSelectStar();
462:
463: /**
464: * Sets query to use star in select clauses and names of PersistentObject columns when
465: * retrieving from ResultSet. It should be used carefully since if there are repetitive SQL
466: * names it can cause incorrect results
467: */
468: void useStarAndColumnNames();
469:
470: /**
471: * Unsets use of star in select clauses and names of PersistentObject columns when
472: * retrieving from ResultSet.
473: */
474: void unuseStarAndColumnNames();
475:
476: //
477: // Functions:
478: //
479:
480: /**
481: * Returns 'REGULAR EXPRESSION LIKE' SQL fragment
482: *
483: * @param expression
484: * @param pattern
485: * @param matches
486: * @return regular expression like SQL fragment
487: */
488: String rlike(String expression, String pattern, boolean matches);
489:
490: //
491: // Limit:
492: //
493:
494: /**
495: * Set min and max values in LIMIT clause
496: *
497: * @param min
498: * @param max
499: * @return itself
500: */
501: Query setLimit(int min, int max);
502:
503: /**
504: * Set max value in LIMIT clause
505: *
506: * @param max
507: * @return itself
508: */
509: Query setLimit(int max);
510:
511: /**
512: * @return min value in LIMIT clause
513: */
514: int getLimitMin();
515:
516: //
517: // Union:
518: //
519:
520: /**
521: * Creates and adds Union - representation of UNION clause - to this query.
522: *
523: * @param query <code>Query<code/> to be added with UNION clause
524: * @return created <code>Union<code/>
525: * @see Union
526: */
527: Union union(Query query);
528:
529: /**
530: * Creates and adds Union - representation of UNION clause - to this query.
531: *
532: * @param query <code>Query<code/> to be added with UNION ALL clause
533: * @return created <code>Union<code/>
534: * @see Union
535: */
536: Union unionAll(Query query);
537:
538: /**
539: * Creates and adds Union - representation of UNION clause - to this query.
540: *
541: * @param query <code>Query<code/> to be added with UNION or UNION ALL clause
542: * @param mode Parameter to control if this is UNION or UNION ALL clause
543: * @return created <code>Union<code/>
544: * @see Union
545: */
546: Union union(Query query, UnionMode mode);
547:
548: //
549: // Parameters:
550: //
551:
552: /**
553: * Returns array of UNION sub-query parameters. If this is not a UNION query
554: * array will have 0-length
555: *
556: * @return Parameters[] array of UNION sub-query parameters
557: * @see Parameters
558: * @see Union
559: */
560: Parameters[] collectInnerUnionParameters();
561:
562: /**
563: * Returns Parameters set for this query
564: *
565: * @return Parameters Parameters set for this query
566: */
567: Parameters getParameters();
568:
569: /**
570: * Set query parameters
571: *
572: * @param parameters
573: * @return itself
574: */
575: Query setParameters(Object[] parameters);
576:
577: /**
578: * Set query parameters
579: *
580: * @param parameters
581: * @return itself
582: */
583: Query setParameters(Parameters parameters);
584:
585: /**
586: * Add query parameter of type that will be determined by Persistency
587: *
588: * @param parameter
589: * @return itself
590: */
591: Query addParameter(Object parameter);
592:
593: /**
594: * Add query parameter of <code>ColumnType<code/> type
595: *
596: * @param type
597: * @param parameter - value or instance of Parameter class
598: * @return itself
599: * @throws OdalRuntimePersistencyException
600: * if the value is already of Parameter type and type != null
601: */
602: Query addParameter(ColumnType type, Object parameter);
603:
604: /**
605: * Add parameters to the end of parameter list
606: *
607: * @param parameters
608: * @return itself
609: */
610: Query addAllParameters(Parameters parameters);
611:
612: /**
613: * Add parameters starting from certain index
614: *
615: * @param index 0-based Offset index
616: * @param parameters
617: * @return itself
618: */
619: Query addAllParameters(int index, Parameters parameters);
620:
621: /**
622: * Add parameters to the end of parameter list
623: *
624: * @return itself
625: */
626: Query addAllParameters(Object[] values);
627:
628: /**
629: * Adds array of Parameters objects
630: *
631: * @param parameters
632: * @return itself
633: */
634: Query addParametersArray(Parameters[] parameters);
635:
636: //
637: // Compillation:
638: //
639:
640: /**
641: * Compiles query which makes it immutable
642: *
643: * @param databasePolicy
644: * @return compiled query (itself)
645: */
646: Query compile(DatabasePolicy databasePolicy);
647:
648: /**
649: * Compiles query which makes it immutable
650: *
651: * @return compiled query (itself)
652: * @throws OdalRuntimePersistencyException
653: * if DatabasePolicy is not set but is required for compillation
654: */
655: Query compile();
656:
657: /**
658: * Returns true if query is copiled
659: *
660: * @return true if query is copiled
661: */
662: boolean isCompiled();
663:
664: /**
665: * Decompiles query which makes it mutable
666: */
667: void decompile();
668:
669: //
670: // Children:
671: //
672:
673: /**
674: * Returns <code>LinkIterator<code/> of child queries
675: *
676: * @return <code>LinkIterator<code/>
677: * @see LinkIterator
678: */
679: LinkIterator linkIterator();
680:
681: /**
682: * Add child link with specific name
683: *
684: * @param link
685: * @throws NullPointerException if link has no name set
686: * @see Link
687: */
688: void addChild(Link link);
689:
690: /**
691: * Get child link with specific name
692: *
693: * @param name
694: * @return child link
695: */
696: Link getChild(String name);
697:
698: /**
699: * Returns child link by name. If child is not found - retruns null
700: *
701: * @return child link by name
702: */
703: Link child(String name);
704:
705: /**
706: * @return true if this query has children
707: */
708: boolean hasChildren();
709:
710: //
711: // Clone/new instance:
712: //
713:
714: /**
715: * @return deep copy of this query
716: * @throws CloneNotSupportedException
717: */
718: Object clone() throws CloneNotSupportedException;
719:
720: /**
721: * @return copy of this query which is non-compiled even if the original is
722: */
723: Query newNonCompiledQuery();
724:
725: //
726: // Key:
727: //
728: Object toKey();
729:
730: /**
731: * Returns between clause
732: *
733: * @param value1
734: * @param value2
735: * @return between clause
736: */
737: String between(String value1, String value2);
738:
739: /**
740: * Returns lower clause
741: *
742: * @param value
743: * @return lower clause
744: */
745: String lower(String value);
746:
747: /**
748: * Returns upper clause
749: *
750: * @param value
751: * @return upper clause
752: */
753: String upper(String value);
754:
755: /**
756: * Returns singleQuoted string
757: *
758: * @param value
759: * @return singleQuoted string
760: */
761: String singleQuote(String value);
762:
763: /**
764: * Returns SQL string including inlined queries
765: *
766: * @return SQL string including inlined queries
767: */
768: String getResolvedSql();
769:
770: /**
771: * Sets inline mode
772: *
773: * @see Link.InlineMode
774: * @param childName child link name
775: * @param joinMode join mode
776: */
777: void setInlineMode(String childName, Link.InlineMode joinMode);
778:
779: /**
780: * Returns child query by name
781: *
782: * @param childName child query name
783: * @return child query
784: */
785: Query getChildQuery(String childName);
786: }
|