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.type.CollectionFactory;
016: import com.completex.objective.util.PropertyMap;
017:
018: import java.util.Set;
019: import java.util.List;
020: import java.util.Map;
021: import java.util.HashMap;
022: import java.io.Serializable;
023:
024: /**
025: * @author Gennady Krizhevsky
026: */
027: public interface QueryDefinition /*extends BasicQuery*/{
028:
029: public static final BasicQuery.OrderDirection DIR_ASC = BasicQuery.OrderDirection.ASC;
030: public static final BasicQuery.OrderDirection DIR_DESC = BasicQuery.OrderDirection.DESC;
031:
032: //
033: // Select:
034: //
035: /**
036: * Represents SQL SELECT clause.
037: * Each element of <code>select<code/> parameter will be joined by comma when compiling.
038: *
039: * @param select set of SQL SELECT columns (No 'SELECT' keyword necessary)
040: * @return itself
041: */
042: QueryDefinition setSelect(String[] select);
043:
044: /**
045: * Represents SQL SELECT clause.
046: * Each element of <code>select<code/> parameter will be joined by comma when compiling.
047: *
048: * @param select set of SQL SELECT columns (No 'SELECT' keyword necessary)
049: * @return itself
050: */
051: QueryDefinition setSelect(List select);
052:
053: /**
054: * @return set of SQL SELECT columns
055: */
056: String[] getSelect();
057:
058: /**
059: * Adds columnExpression SQL fragment to SQL SELECT columns
060: *
061: * @param columnExpression
062: * @return itself
063: */
064: QueryDefinition addToSelect(String columnExpression);
065:
066: /**
067: * Adds columnExpression SQL fragment to SQL SELECT columns
068: *
069: * @param persistentObject persistentObject which MetaTable is used to get columns
070: * @return itself
071: */
072: QueryDefinition addToSelect(PersistentObjectFactory persistentObject);
073:
074: //
075: // From / Join:
076: //
077:
078: /**
079: * Represents SQL FROM clause.
080: *
081: * @return set of SQL FROM columns
082: */
083: String[] getFrom();
084:
085: /**
086: * Represents SQL FROM clause.
087: * Each element of <code>from<code/> parameter will be joined by comma when compiling.
088: *
089: * @param from set of SQL FROM columns (No 'SELECT' keyword necessary)
090: * @return itself
091: */
092: QueryDefinition setFrom(String[] from);
093:
094: /**
095: * Adds tableExpression SQL fragment to SQL FROM tables
096: *
097: * @param tableExpression
098: * @return itself
099: */
100: QueryDefinition addToFrom(String tableExpression);
101:
102: /**
103: * Addes new Join object to this query
104: *
105: * @param firstTableName
106: * @return new Join object
107: * @see Join
108: */
109: Join addJoin(String firstTableName);
110:
111: /**
112: * Creates new Join object
113: *
114: * @param firstTableName
115: * @return new Join object
116: * @see Join
117: */
118: Join newJoin(String firstTableName);
119:
120: /**
121: * @return Join object or null if not set or added
122: */
123: Join getJoin();
124:
125: /**
126: * @param join Join object
127: * @return itself
128: */
129: QueryDefinition setJoin(Join join);
130:
131: //
132: // Where:
133: //
134: /**
135: * Adds SQL fragment to WHERE clause
136: *
137: * @param sql
138: * @return itself
139: */
140: QueryDefinition addToWhere(String sql);
141:
142: /**
143: * Adds SQL fragment to WHERE clause prepended with " AND "
144: *
145: * @param sql
146: * @return itself
147: */
148: QueryDefinition andToWhere(String sql);
149:
150: /**
151: * Adds SQL fragment to WHERE clause prepended with " OR "
152: *
153: * @param sql
154: * @return itself
155: */
156: QueryDefinition orToWhere(String sql);
157:
158: /**
159: * Adds SQL fragment to WHERE clause based on PersistentObject values which are joined by "AND"
160: *
161: * @param persistentObject
162: * @return itself
163: */
164: public QueryDefinition addToWhere(PersistentObject persistentObject);
165:
166: /**
167: * Adds SQL fragment to WHERE clause based on PersistentObject values which are joined by "AND"
168: * and prepended with " AND "
169: *
170: * @param persistentObject
171: * @return itself
172: */
173: public QueryDefinition andToWhere(PersistentObject persistentObject);
174:
175: /**
176: * Adds SQL fragment to WHERE clause based on PersistentObject values which are joined by "AND"
177: * and prepended with " OR "
178: *
179: * @param persistentObject
180: * @return itself
181: */
182: public QueryDefinition orToWhere(PersistentObject persistentObject);
183:
184: /**
185: * Set SQL WHERE clause w/o 'WHERE' keyword
186: *
187: * @param sql
188: * @return itself
189: */
190: QueryDefinition setWhere(String sql);
191:
192: /**
193: * Returns SQL WHERE clause w/o 'WHERE' keyword
194: *
195: * @return SQL WHERE clause
196: */
197: String getWhere();
198:
199: //
200: // Order By:
201: //
202: /**
203: * Represents SQL ORDER BY clause.
204: * Each element of <code>orderBy<code/> parameter will be joined by comma when compiling.
205: *
206: * @param orderBy set of SQL ORDER BY columns (No 'ORDER BY' keyword necessary)
207: * @return itself
208: */
209: QueryDefinition setOrderBy(String[] orderBy);
210:
211: /**
212: * Represents SQL ORDER BY clause.
213: * Each element of <code>orderBy<code/> parameter will be joined by comma when compiling.
214: *
215: * @param orderBy set of SQL ORDER BY columns (No 'ORDER BY' keyword necessary)
216: * @return itself
217: */
218: QueryDefinition setOrderBy(List orderBy);
219:
220: /**
221: * Returns set of SQL ORDER BY columns
222: *
223: * @return set of SQL ORDER BY columns
224: */
225: String[] getOrderBy();
226:
227: /**
228: * Adds columnExpression SQL fragment to SQL ORDER BY columns
229: *
230: * @param columnExpression
231: * @param direction Ascending or descending
232: * @return itself
233: */
234: QueryDefinition addToOrderBy(String columnExpression,
235: Query.OrderDirection direction);
236:
237: /**
238: * Adds columnExpression SQL fragment to SQL ORDER BY columns with default direction
239: *
240: * @param columnExpression
241: * @return itself
242: */
243: QueryDefinition addToOrderBy(String columnExpression);
244:
245: //
246: // Group By:
247: //
248: /**
249: * Represents SQL GROUP BY clause.
250: * Each element of <code>groupBy<code/> parameter will be joined by comma when compiling.
251: *
252: * @param groupBy set of SQL GROUP BY columns (No 'GROUP BY' keyword necessary)
253: * @return itself
254: */
255: QueryDefinition setGroupBy(String[] groupBy);
256:
257: /**
258: * Returns set of SQL GROUP BY columns
259: *
260: * @return set of SQL GROUP BY columns
261: */
262: String[] getGroupBy();
263:
264: /**
265: * Adds columnExpression SQL fragment to SQL GROUP BY columns
266: *
267: * @param columnExpression
268: * @return itself
269: */
270: QueryDefinition addToGroupBy(String columnExpression);
271:
272: //
273: // Having:
274: //
275: /**
276: * Sets SQL HAVING clause
277: *
278: * @param sql
279: * @return itself
280: */
281: QueryDefinition setHaving(String sql);
282:
283: /**
284: * @return SQL HAVING clause
285: */
286: String getHaving();
287:
288: /**
289: * Adds SQL fragment to HAVING clause
290: *
291: * @param sql
292: * @return itself
293: */
294: QueryDefinition addToHaving(String sql);
295:
296: /**
297: * Adds SQL fragment to HAVING clause prepended with " AND "
298: *
299: * @param sql
300: * @return itself
301: */
302: QueryDefinition andToHaving(String sql);
303:
304: /**
305: * Adds SQL fragment to HAVING clause prepended with " OR "
306: *
307: * @param sql
308: * @return itself
309: */
310: QueryDefinition orToHaving(String sql);
311:
312: //
313: // Distinct:
314: //
315: /**
316: * @param distinct true if query is to return unique values
317: * @return itself
318: */
319: QueryDefinition setDistinct(boolean distinct);
320:
321: /**
322: * @return true if query is to return unique values
323: */
324: boolean isDistinct();
325:
326: //
327: // Lock:
328: //
329: /**
330: * Sets query lock
331: *
332: * @param lockType
333: * @return itself
334: * @see LockType
335: */
336: QueryDefinition setLocked(LockType lockType);
337:
338: /**
339: * Sets query lock
340: *
341: * @param lockType
342: * @param forUpdateOf
343: * @return itself
344: * @see LockType
345: */
346: QueryDefinition setLocked(LockType lockType, String[] forUpdateOf);
347:
348: /**
349: * Returns set of columns of lock clause
350: *
351: * @return set of columns of lock clause
352: */
353: String[] getForUpdateOf();
354:
355: /**
356: * Returns true if query has lock clause
357: *
358: * @return true if query has lock clause
359: */
360: boolean isLocked();
361:
362: /**
363: * Returns true if lock clause of type that will wait untinl another process will free resource
364: *
365: * @return true if lock clause of type that will wait untinl another process will free resource
366: */
367: boolean isWait();
368:
369: /**
370: * Sets lock timeout. In future may be used as query timeout as well
371: *
372: * @param timeout
373: */
374: void setTimeout(long timeout);
375:
376: /**
377: * Gets lock timeout. In future may be used as query timeout as well
378: *
379: * @return timeout
380: */
381: long getTimeout();
382:
383: //
384: // Star:
385: //
386: /**
387: * Sets mode of select. If <code>useSelectStar<code/> set true then select clause will look like:
388: * "SELECT * ...". Should be used carefully since if SQL has column that does not exist in the object
389: * used as data container then execution will fail
390: *
391: * @param useSelectStar
392: */
393: void setUseSelectStar(boolean useSelectStar);
394:
395: /**
396: * @return true then select clause will look like:
397: * "SELECT * ..."
398: */
399: boolean isUseSelectStar();
400:
401: void setUseColumnNames(boolean useColumnNames);
402:
403: boolean isUseColumnNames();
404:
405: /**
406: * Sets query to use star in select clauses and names of PersistentObject columns when
407: * retrieving from ResultSet. It should be used carefully since if there are repetitive SQL
408: * names it can cause incorrect results
409: */
410: void useStarAndColumnNames();
411:
412: /**
413: * Unsets use of star in select clauses and names of PersistentObject columns when
414: * retrieving from ResultSet.
415: */
416: void unuseStarAndColumnNames();
417:
418: //
419: // Limit:
420: //
421: /**
422: * Set min and max values in LIMIT clause
423: *
424: * @param min
425: * @param max
426: * @return itself
427: */
428: QueryDefinition setLimit(int min, int max);
429:
430: /**
431: * Set max value in LIMIT clause
432: *
433: * @param max
434: * @return itself
435: */
436: QueryDefinition setLimit(int max);
437:
438: /**
439: * @return min value in LIMIT clause
440: */
441: int getLimitMin();
442:
443: /**
444: * @return max value in LIMIT clause
445: */
446: int getLimitMax();
447:
448: //
449: // Union:
450: //
451: /**
452: * Creates and adds Union - representation of UNION clause - to this query.
453: *
454: * @param queryDefinition <code>QueryDefinition<code/> to be added with UNION clause
455: * @return created <code>Union<code/>
456: * @see Union
457: */
458: Union union(QueryDefinition queryDefinition);
459:
460: /**
461: * Creates and adds Union - representation of UNION clause - to this query.
462: *
463: * @param queryDefinition <code>QueryDefinition<code/> to be added with UNION ALL clause
464: * @return created <code>Union<code/>
465: * @see Union
466: */
467: Union unionAll(QueryDefinition queryDefinition);
468:
469: /**
470: * Creates and adds Union - representation of UNION clause - to this query.
471: *
472: * @param queryDefinition <code>QueryDefinition<code/> to be added with UNION or UNION ALL clause
473: * @param mode Parameter to control if this is UNION or UNION ALL clause
474: * @return created <code>Union<code/>
475: * @see Union
476: */
477: Union union(QueryDefinition queryDefinition, UnionMode mode);
478:
479: /**
480: * Returns true if this is UNION query
481: *
482: * @return true if this is UNION query
483: */
484: boolean isUnion();
485:
486: /**
487: * Returns number of union sub-queries
488: *
489: * @return number of union sub-queries
490: */
491: int unionSize();
492:
493: /**
494: * Returns Union object of this query
495: *
496: * @return Returns Union object of this query
497: */
498: Union getUnion();
499:
500: //
501: // Compillation:
502: //
503: /**
504: * Compiles query which makes it immutable
505: *
506: * @param databasePolicy
507: * @return compiled query (itself)
508: */
509: QueryDefinition compile(DatabasePolicy databasePolicy);
510:
511: /**
512: * Compiles query which makes it immutable
513: *
514: * @return compiled query (itself)
515: * @throws OdalRuntimePersistencyException
516: * if DatabasePolicy is not set but is required for compillation
517: */
518: QueryDefinition compile();
519:
520: /**
521: * Returns true if query is copiled
522: *
523: * @return true if query is copiled
524: */
525: boolean isCompiled();
526:
527: /**
528: * Compiles call which makes it immutable
529: *
530: * @param databasePolicy
531: * @return itself
532: */
533: QueryDefinition compileCall(DatabasePolicy databasePolicy);
534:
535: /**
536: * Compiles call which makes it immutable
537: *
538: * @return itself
539: * @throws OdalRuntimePersistencyException
540: * if DatabasePolicy is not set but is required for compillation
541: */
542: QueryDefinition compileCall();
543:
544: /**
545: * Decompiles query which makes it mutable. Resets internal sql string to null.
546: */
547: void decompile();
548:
549: // //
550: // // Pagination:
551: // //
552: // /**
553: // * Sets page size in records
554: // *
555: // * @param pageSize page size in records
556: // * @return itself
557: // */
558: // QueryDefinition setPageSize(long pageSize);
559: //
560: // /**
561: // * Returns page size
562: // *
563: // * @return page size
564: // */
565: // long getPageSize();
566: //
567: // /**
568: // * Set 0-based offset from which records to be retrieved
569: // *
570: // * @param offset
571: // */
572: // void setOffset(long offset);
573: //
574: // /**
575: // * Returns 0-based offset from which records to be retrieved
576: // *
577: // * @return 0-based offset from which records to be retrieved
578: // */
579: // long getOffset();
580:
581: // /**
582: // * Sets page parameters in terms of <code>BasicQuery.Page<code/>
583: // *
584: // * @param page
585: // * @return itself
586: // */
587: // QueryDefinition setPage(Page page);
588:
589: //
590: // Result Factories:
591: //
592:
593: /**
594: * Sets singular result factory.
595: *
596: * @param singularResultFactory singular result factory
597: */
598: void setSingularResultFactory(
599: PersistentObjectFactory singularResultFactory);
600:
601: /**
602: * Returns singular result factory. Used when retrieving
603: * data from ResultSet.
604: *
605: * @see PersistentObjectFactory
606: * @return singular result factory
607: */
608: PersistentObjectFactory getSingularResultFactory();
609:
610: /**
611: * Nullifies singular result factory
612: */
613: void nullifySingularResultFactory();
614:
615: /**
616: * Sets multiple result factory. Multiple result factory
617: * is used when retrieving data from ResultSet to instantiate
618: * proper Collection type.
619: *
620: * @param multipleResultFactory multiple result factory
621: */
622: void setMultipleResultFactory(
623: CollectionFactory multipleResultFactory);
624:
625: /**
626: * Returns multiple result factory
627: *
628: * @return multiple result factory
629: */
630: CollectionFactory getMultipleResultFactory();
631:
632: //
633: /**
634: * Set set of fields excluded from being populated. Field names coincide with column names if
635: * singularResultFactory is set or those of <code>ResultSet<code/> if not
636: *
637: * @param excludeFields
638: */
639: void setExcludedFields(Set excludeFields);
640:
641: //
642: // Query type:
643: //
644: /**
645: * Sets flag if query is of Disconnected Page Query type.
646: * Disconnected Page Query object when executed brings only one page of results.
647: *
648: * @param disconnectedPageQuery flag if query is of Disconnected Page Query type.
649: */
650: void setDisconnectedPageQuery(boolean disconnectedPageQuery);
651:
652: /**
653: * Returns true if query is of Disconnected Page Query type.
654: *
655: * @return true if query is of Disconnected Page Query type.
656: */
657: boolean isDisconnectedPageQuery();
658:
659: /**
660: * Returns true if sql != null && join == null && from == null && singularResultFactory == null;
661: *
662: * @return true if sql != null && join == null && from == null && singularResultFactory == null;
663: */
664: boolean isAdHoc();
665:
666: /**
667: * Returns call body which is internal part of call SQL:
668: * "sp( ?, ? )", for instance.
669: *
670: * @return call body body which is internal part of call SQL:
671: * "sp( ?, ? )", for instance.
672: */
673: String getCallBody();
674:
675: /**
676: * Sets call body which is internal part of call SQL:
677: * "sp( ?, ? )", for instance.
678: *
679: * @param callBody
680: */
681: void setCallBody(String callBody);
682:
683: /**
684: * Returns true if this call represents database function
685: *
686: * @return true if this call represents database function
687: */
688: boolean isFunction();
689:
690: /**
691: * Sets the flag to indicate if this call represents database function
692: *
693: * @param function indicates if this call represents database function
694: */
695: void setFunction(boolean function);
696:
697: /**
698: * Sets SQL statement and indicates that it is done by internal process
699: *
700: * @param sql
701: */
702: void setSqlInternal(String sql);
703:
704: /**
705: * Returns true if SQL is set by "user"
706: *
707: * @return true if SQL is set by "user"
708: */
709: boolean isExternallySetSql();
710:
711: /**
712: * Return DatabasePolicy used
713: *
714: * @return DatabasePolicy used
715: */
716: DatabasePolicy getDatabasePolicy();
717:
718: /**
719: * Return sql that is produced by this definition
720: *
721: * @return sql that is produced by this definition
722: */
723: String getSql();
724:
725: /**
726: * Returns current CompoundColumnFilter. If filter is not set - creates a new instance of it before that.
727: *
728: * @return CompoundColumnFilter
729: */
730: CompoundColumnFilter columnFilters();
731:
732: /**
733: * Return column filter set for this query
734: *
735: * @return column filter set for this query
736: */
737: CompoundColumnFilter getCompoundColumnFilter();
738:
739: /**
740: * Sets column filter that allows for sparsely populated result objects
741: *
742: * @see CompoundColumnFilter
743: * @param columnFilter
744: */
745: void setCompoundColumnFilter(CompoundColumnFilter columnFilter);
746:
747: boolean isColumnFiltersEmpty();
748:
749: List getFromAsList();
750:
751: void addToChainedColumns(int columnIndex, String tableName,
752: String columnName);
753:
754: boolean hasChainedColumns();
755:
756: ChainedColumn[] getChainedColumns();
757:
758: void clearChainedColumns();
759:
760: Set getUsedTableAliases();
761:
762: String[] extractNonUsedTableAliases();
763:
764: boolean isCombinedInline();
765:
766: void setCombinedInline();
767:
768: public static class ChainedColumn implements Serializable, Mappable {
769: private int columnIndex;
770: private String tableName;
771: private String columnName;
772: private static final String TAG_COLUMN_INDEX = "columnIndex";
773: private static final String TAG_TABLE_NAME = "tableName";
774: private static final String TAG_COLUMN_NAME = "columnName";
775:
776: public ChainedColumn(Map map) {
777: fromMap(map);
778: }
779:
780: public ChainedColumn(int columnIndex, String tableName,
781: String columnName) {
782: this .columnIndex = columnIndex;
783: this .tableName = tableName;
784: this .columnName = columnName;
785: }
786:
787: public int getColumnIndex() {
788: return columnIndex;
789: }
790:
791: public void setColumnIndex(int columnIndex) {
792: this .columnIndex = columnIndex;
793: }
794:
795: public String getTableName() {
796: return tableName;
797: }
798:
799: public void setTableName(String tableName) {
800: this .tableName = tableName;
801: }
802:
803: public String getColumnName() {
804: return columnName;
805: }
806:
807: public void setColumnName(String columnName) {
808: this .columnName = columnName;
809: }
810:
811: public Map toMap() {
812: HashMap map = new HashMap();
813: map.put(TAG_COLUMN_INDEX, String.valueOf(columnIndex));
814: map.put(TAG_TABLE_NAME, tableName);
815: map.put(TAG_COLUMN_NAME, columnName);
816: return map;
817: }
818:
819: public void fromMap(Map map) {
820: PropertyMap propertyMap = PropertyMap.toPropertyMap(map);
821: columnIndex = propertyMap.getInt(TAG_COLUMN_INDEX, true);
822: tableName = propertyMap.getProperty(TAG_TABLE_NAME, true);
823: columnName = propertyMap.getProperty(TAG_COLUMN_NAME, true);
824: }
825:
826: }
827: }
|