001 /*
002 * file CqQuery.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * com.ibm.rational.wvcm.stp.cq.CqQuery
008 *
009 * © Copyright IBM Corporation 2004, 2008. All Rights Reserved.
010 * Note to U.S. Government Users Restricted Rights: Use, duplication or
011 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
012 */
013
014 package com.ibm.rational.wvcm.stp.cq;
015
016 import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018 import java.io.File;
019 import java.io.OutputStream;
020 import java.util.HashMap;
021 import java.util.List;
022 import java.util.Map;
023
024 import javax.wvcm.Feedback;
025 import javax.wvcm.WvcmException;
026 import javax.wvcm.PropertyNameList.PropertyName;
027 import javax.wvcm.PropertyRequestItem.PropertyRequest;
028
029 import com.ibm.rational.wvcm.stp.StpProvider;
030 import com.ibm.rational.wvcm.stp.cq.CqFieldValue.ValueType;
031 import com.ibm.rational.wvcm.stpex.StpExBase;
032 import com.ibm.rational.wvcm.stpex.StpExEnumeration;
033 import com.ibm.rational.wvcm.stpex.StpExEnumerationBase;
034
035 /**
036 * A proxy interface for ClearQuest query and chart resources.
037 * <p>
038 * The user-friendly specification for the location of a query or chart has the
039 * form
040 *
041 * <pre>
042 * <b>cq.query:</b><i><parent-folder-path></i>/<i><query-name></i>@<i><db-set></i>/<i><user-db></i>
043 * </pre>
044 *
045 * where <i><parent-folder-path></i> is a sequence of one or more path
046 * segments separated by the slash character, wherein each segment denotes a
047 * query folder immediately contained by its predecessor in the sequence. The
048 * first segment is either "Public Queries" or "Personal Queries" (or the
049 * localization of one of these).
050 */
051 public interface CqQuery extends CqQueryFolderItem
052 {
053 /**
054 * An interface specifying a set of optional parameters that may be passed
055 * to
056 * {@link CqQuery#doExecute(File, Feedback, com.ibm.rational.wvcm.stp.cq.CqQuery.FileOptions, com.ibm.rational.wvcm.stp.cq.CqQuery.FilterLeaf[]) CqQuery.doExecute},
057 * {@link CqQuery#doMakeChart(OutputStream, Feedback, com.ibm.rational.wvcm.stp.cq.CqQuery.ChartOptions, com.ibm.rational.wvcm.stp.cq.CqQuery.FilterLeaf[]) CqQuery.doMakeChart},
058 * {@link CqRecordType#doQuery(String, File, Feedback, com.ibm.rational.wvcm.stp.cq.CqQuery.FileOptions) CqRecordType.doQuery},
059 * or
060 * {@link CqReport#doMakeReport(OutputStream, long, long, com.ibm.rational.wvcm.stp.cq.CqQuery.FilterLeaf[]) CqReport.doMakeReport}
061 * to control the execution of queries and the generation of charts and
062 * reports.
063 * <p>
064 * Each method returns a value for one parameter. If that method returns
065 * <b>null</b> a system-defined default value will be used as the value for
066 * that parameter.
067 */
068 interface CommonOptions
069 {
070 /**
071 * @return The largest row number that the query may return. This is the
072 * maximum number of rows allowed in the result set <i>only</i>
073 * if the <code>targetRow</code> parameter is 1. In general,
074 * the maximum number of rows returned by an execution of the
075 * query will be the smallest of
076 * <ul>
077 * <li>the <code>maxRows</code> parameter,
078 * <li>the value of
079 * <code>1+getRowNumberLimit()-targetRow</code>, and
080 * <li><code>1+CqResultSet.getRowNumberHardLimit()-targetRows</code>
081 * </ul>. If <b>null</b>, the value of
082 * CqResultSet.getRowNumberSoftLimit() will be used.
083 *
084 * @see CqResultSet#getRowNumberHardLimit()
085 * @see CqResultSet#getRowNumberSoftLimit()
086 * @see CqResultSet#isRowNumberLimitExceeded()
087 */
088 Long getRowNumberLimit();
089
090 /**
091 * @return The properties of the query being executed that should be
092 * retrieved and returned with the result set. If <b>null</b>,
093 * CqResultSet().getQuery will return <b>null</b>; otherwise it
094 * will return a CqQuery proxy populated with the properties
095 * requested.
096 *
097 * @see CqResultSet#getQuery()
098 */
099 PropertyRequest getQueryPropertyRequest();
100
101 }
102
103 /**
104 * An extension of the CommonOptions interface specifying an additional set
105 * of parameters applying only to the generation of charts.
106 */
107 interface ChartOptions extends CommonOptions
108 {
109 /**
110 * The possible chart image formats
111 */
112 public static enum ImageFormat implements StpExEnumeration
113 {
114 /** Generate the chart in JPEG format */
115 JPEG,
116
117 /** Generate the chart in PNG format */
118 PNG;
119 }
120
121 /**
122 * Returns the requested height of the chart image in pixels.
123 *
124 * @return The height of the image in pixels.
125 */
126 Long getHeight();
127
128 /**
129 * Returns the compression format requested for the chart image.
130 *
131 * @return An ImageFormat enumerator specifying whether the generated
132 * chart image should use JPEG or PNG compression format.
133 */
134 ImageFormat getImageFormat();
135
136 /**
137 * Returns whether or not the compression of the image should be
138 * optimized.
139 *
140 * @return <b>true</b> if the compression is to be optimized.
141 */
142 Boolean getIsCompressionOptimized();
143
144 /**
145 * Returns whether the chart image is to be rendered in grey scale or
146 * color.
147 *
148 * @return If <b>true</b>, the chart image will be in grey scale, not
149 * color.
150 */
151 Boolean getIsGreyScale();
152
153 /**
154 * Returns whether or not a PNG image should be interlaced.
155 *
156 * @return If <b>true</b>, a PNG image will be interlaced.
157 */
158 Boolean getIsInterlaced();
159
160 /**
161 * Returns whether or not a JPEG image is to use progressive
162 * compression.
163 *
164 * @return If <b>true</b>, progressive compression will be used in the
165 * JPEG format.
166 */
167 Boolean getIsProgressive();
168
169 /**
170 * Returns the requested quality of JPEG compression, expressed as an
171 * integer between 1 (maximum compression) and 100 (maximum fidelity).
172 *
173 * @return An Integer between 1 and 100.
174 */
175 Integer getQuality();
176
177 /**
178 * Returns the requested width of the chart image.
179 *
180 * @return An Long specifying the requested width of the chart image in
181 * pixels.
182 */
183 Long getWidth();
184 }
185
186 /**
187 * Instances of this class provide the default values for each attribute
188 * specified by the ChartOptions interface, which is the same behavior
189 * exhibited when using <b>null</b> for a ChartOptions object. Clients can
190 * provide non-default attribute values by defining and instantiating a
191 * subclass of this class that overrides select methods to provide the
192 * desired non-default value.
193 * <p>
194 * Using a class instance creation expression, for example, one could define
195 * a ChartOptions object for requesting a row limit of 10000 as follows...
196 *
197 * <pre>
198 * ChartOptions TEN_THOUSAND_ROWS = new ChartOptionsClass(){
199 * public Long getRowNumberLimit() { return 10000; };
200 * };
201 * </pre>
202 */
203 public static class ChartOptionsClass implements ChartOptions
204 {
205 public Long getHeight()
206 {
207 return null;
208 }
209
210 public ImageFormat getImageFormat()
211 {
212 return null;
213 }
214
215 public Boolean getIsCompressionOptimized()
216 {
217 return null;
218 }
219
220 public Boolean getIsGreyScale()
221 {
222 return null;
223 }
224
225 public Boolean getIsInterlaced()
226 {
227 return null;
228 }
229
230 public Boolean getIsProgressive()
231 {
232 return null;
233 }
234
235 public Integer getQuality()
236 {
237 return null;
238 }
239
240 public Long getWidth()
241 {
242 return null;
243 }
244
245 public Long getRowNumberLimit()
246 {
247 return null;
248 }
249
250 public PropertyRequest getQueryPropertyRequest()
251 {
252 return null;
253 }
254 }
255
256 /**
257 * An instance of ChartOptions that requests the chart in PNG format.
258 * Provided as a convenience for specifying this commonly used option.
259 */
260 CqQuery.ChartOptions PNG_CHART = new CqQuery.ChartOptionsClass()
261 {
262 public ImageFormat getImageFormat()
263 {
264 return ImageFormat.PNG;
265 }
266 };
267
268 /**
269 * An extension of the CommonOptions interface specifying an additional set
270 * of parameters applying only to the generation of query result sets.
271 */
272 interface ListOptions extends CommonOptions
273 {
274 /**
275 * If TRUE, the total number of rows generated by the query will be
276 * computed by the sever and returned as the value of
277 * {@link CqResultSet#getRowCount()}. All of these rows will be in the
278 * response only if maxRows is at least as great as the row count. If
279 * FALSE, no count is computed; CqResultSet.getRowCount() returns -1. In
280 * this latter case, if the number of elements in the response is equal
281 * to maxRows, there is no way to tell if there were more rows in the
282 * result set not returned by the response.
283 *
284 * @return TRUE if doExeute/doQuery is to compute and return a count of
285 * the number of resources that match the filter (whether or not
286 * those resources are actually returned from the server); FALSE
287 * or <b>null</b> if only the maximum number of records are to
288 * be returned with no indication whether or not there might be
289 * more.
290 */
291 Boolean getEnableRowCount();
292
293 /**
294 * @return The maximum number of characters that are to be included in
295 * each row of the response for each multi-line text display
296 * field. If <b>null</b>, the default limit established by the
297 * server will be applied.
298 */
299 Long getMaxMultiLineTextLength();
300
301 /**
302 * As the value returned by getValueConvertionData(), suppresses all
303 * data conversions.
304 */
305 DisplayField[] NO_CONVERSION = new DisplayField[0];
306
307 /**
308 * As the value returned by getValueConvertionData(), causes NULL_IMAGE
309 * strings to be converted to <b>null</b>s.
310 */
311 DisplayField[] NULL_CONVERSION = new DisplayField[0];
312
313 /**
314 * As the value returned by getValueConvertionData(), causes each
315 * NULL_IMAGE string to be converted to <b>null</b> and each other
316 * string to be converted to the native Java data type specified for the
317 * column in {@link CqResultSet#getColumnTypes()}.
318 * <p>
319 * Since an SQL-based query has no controlling DisplayField[] array,
320 * this conversion is for SQL-based query uses only rudimentary types.
321 */
322 DisplayField[] FULL_CONVERSION = new DisplayField[0];
323
324 /**
325 * Specifies how CqRowData is to interpret the string data for a row
326 * when computing the Object[] returned by CqRowData.getValues().
327 * <p>
328 * If this method returns the distinguished value NO_CONVERSION, the
329 * array returned by CqRowData.getValues() will be the same array of
330 * Strings returned by CqRowData.getStrings(); otherwise, getValues()
331 * will return an array of native Java objects obtained by converting
332 * the string image in each column to an object of the type specified
333 * for the column in the DisplayField[] returned by this option.
334 * (NULL_IMAGE Strings will be converted to <b>null</b>).
335 * <p>
336 * Enabling this conversion will require some extra overhead in
337 * executing the query since the type information must be collected for
338 * each column and that may require additional round-trips to the server
339 * if not already specified in the DisplayField[] returned by this
340 * option. Conversion to Java objects for a particular row is not
341 * attempted, however, until the getValues() method is invoked on that
342 * row.
343 * <p>
344 * The default behavior is to use the type information returned by
345 * {@link CqResultSet#getColumnTypes()} to perform the conversion when
346 * requested.
347 * <p>
348 * Another possible return is a non-empty DisplayField[], which is
349 * useful primarily when the query is SQL based. For a SQL-based query,
350 * the client must provide the detailed type information based on it's
351 * knowledge of the fields returned by the SQL statement it is using. An
352 * explicit DisplayField[] might also be returned to avoid an extra
353 * round-trip to the server to obtain the DISPLAY_FIELD information. The
354 * DisplayField[] used to define a query or used in the invocation of
355 * CqFieldDefinition.doQuery would always be a suitable return value,
356 * but lighter weight DisplayField[]s will often do as well.
357 * <p>
358 * If an explicit DisplayField[] is returned, the number of visible
359 * fields in the array must be the same as the number of items returned
360 * by CqRowData.getStrings(). Each visible DisplayField must define at
361 * least one of its Path, FieldType, Aggregation or Function attributes.
362 * The remaining attributes are ignored. If only the Path attribute is
363 * specified, the FieldType will be obtained from the last
364 * CqFieldDefinition of that Path (requesting that information from the
365 * server if necessary).
366 * <p>
367 * If the Aggregation attribute is COUNT, the other attributes are
368 * ignored and the column value is converted to an Integer.
369 * <p>
370 * If the Function attribute is not <b>null</b> and not NONE, the other
371 * attributes are ignored and the column value is converted to a Date
372 * object.
373 * <p>
374 * If the FieldType is RESOURCE or RESOURCE_LIST, the Path attribute
375 * must be specified so that the type of the resource referenced by that
376 * path can be determined. (The CqFieldDefintion.REFERENCED_RECORD_TYPE
377 * property is used for this purpose and will be obtained from the
378 * server if not defined by the last proxy in the Path.)
379 *
380 * @return NO_CONVERSION, NULL_CONVERSION, FULL_CONVERSION, or a
381 * DisplayField[] specifying a visible field for each value
382 * returned for a row.
383 */
384 DisplayField[] getValueConversionData();
385 }
386
387 /**
388 * Instances of this class provide the default values for each attribute
389 * specified by the ListOptions interface, which is the same behavior
390 * exhibited when using <b>null</b> for a ListOptions object. Clients can
391 * provide non-default attribute values by defining and instantiating a
392 * subclass of this class that overrides select methods to provide the
393 * desired non-default value.
394 * <p>
395 * Using a class instance creation expression, for example, one could define
396 * a ListOptions object for requesting row counts as follows...
397 *
398 * <pre>
399 * ListOptions COUNT_ROWS = new ListOptionsClass(){
400 * public Boolean getEnableRowCount() { return Boolean.TRUE; };
401 * };
402 * </pre>
403 */
404 public static class ListOptionsClass implements ListOptions
405 {
406 public Boolean getEnableRowCount()
407 {
408 return null;
409 };
410
411 public Long getMaxMultiLineTextLength()
412 {
413 return null;
414 };
415
416 public DisplayField[] getValueConversionData()
417 {
418 return null;
419 }
420
421 public Long getRowNumberLimit()
422 {
423 return null;
424 }
425
426 public PropertyRequest getQueryPropertyRequest()
427 {
428 return null;
429 }
430 }
431
432 /**
433 * An instance of ListOptions that enables the row count option for a query
434 * execution. Provided as a convenience for specifying this commonly used
435 * option.
436 */
437 CqQuery.ListOptions COUNT_ROWS = new CqQuery.ListOptionsClass()
438 {
439 public Boolean getEnableRowCount()
440 {
441 return Boolean.TRUE;
442 };
443 };
444
445 /**
446 * An interface through which a client may, optionally, specify values for
447 * various attributes that control the behavior of executing a query to a
448 * stream.
449 */
450 interface FileOptions
451 {
452 /**
453 * @return The maximum number of characters that are to be included in
454 * each row of the response for each multi-line text display
455 * field.
456 */
457 Long getMaxMultiLineTextLength();
458
459 /**
460 * @return The delimiter to use in those file formats that use a
461 * delimiter.
462 */
463 String getDelimiter();
464
465 /**
466 * @return A String containing additional options for specifying the
467 * form and content of the result set file.
468 */
469 String getOptions();
470 }
471
472 /**
473 * Instances of this class provide the default values for each attribute
474 * specified by the FileOptions interface, which is the same behavior
475 * exhibited when using <b>null</b> for a FileOptions parameter. Clients
476 * can provide non-default attribute values by defining and instantiating a
477 * subclass of this class that overrides select methods to provide the
478 * desired non-default value.
479 * <p>
480 * Using a class instance creation expression, for example, one could define
481 * a FileOptions object for requesting the use of tabs as the file
482 * delimiter...
483 *
484 * <pre>
485 * FileOptions USE_TABS = new FileOptionsClass(){
486 * public String getDelimiter() { return "\t"; };
487 * };
488 * </pre>
489 */
490 public static class FileOptionsClass implements FileOptions
491 {
492 public Long getMaxMultiLineTextLength()
493 {
494 return null;
495 };
496
497 public String getDelimiter()
498 {
499 return null;
500 }
501
502 public String getOptions()
503 {
504 return null;
505 }
506 }
507
508 /**
509 * An enumeration of the possible types of queries.
510 */
511 public static enum QueryType implements StpExEnumeration
512 {
513 /** The query generates a list of data, a result set. */
514 LIST,
515
516 /** The query generates a formatted report. */
517 REPORT,
518
519 /** The query generates a chart. */
520 CHART;
521 }
522
523 /**
524 * The description of a column of the result set generated by a query. The
525 * main element of a DisplayField is the field of a record that is displayed
526 * in the corresponding column of the result set. Some display fields may
527 * not be visible in the display but will be used only to sort and group the
528 * result set.
529 */
530 public interface DisplayField
531 {
532 /**
533 * Supported DisplayField sort options
534 */
535 public static enum SortType implements StpExEnumeration
536 {
537 /**
538 * The display field does not participate in sorting the result set
539 */
540 NO_SORT,
541
542 /** The display field values are sorted in ascending order */
543 ASCENDING,
544
545 /** The display field values are sorted in descending order */
546 DESCENDING;
547 }
548
549 /**
550 * Supported display field aggregate functions. When these aggregate
551 * functions are used, the result set will have only one row. The value
552 * in the column of that row will be computed as a function of the
553 * values in this display field in all records selected by the query
554 * filter.
555 */
556 public static enum Aggregation implements StpExEnumeration
557 {
558 /** The column is not aggregated */
559 NO_AGGREGATION,
560
561 /**
562 * The number of non-<b>null</b> field values associated with this
563 * column.
564 */
565 COUNT,
566
567 /** The sum of the field values associated with his column */
568 SUM,
569
570 /** The average of the field values associated with this column */
571 AVERAGE,
572
573 /**
574 * The minimum value of the field values associated with this column
575 */
576 MINIMUM,
577
578 /**
579 * The maximum value of the field values associated with this column
580 */
581 MAXIMUM;
582 }
583
584 /**
585 * The functions that can be applied to a DisplayField of type DATE_TIME
586 */
587 public static enum Function implements StpExEnumeration
588 {
589 /** No function has been associated with this field */
590 NONE,
591
592 /** The day portion of the field value. For example, 8/29/2002. */
593 DAY,
594
595 /**
596 * The week number of the year and the year, separated by a comma.
597 * For example, 35,2002 for 8/29/2002 (the 35th week of the year).
598 */
599 WEEK,
600
601 /**
602 * The first of the month. For example, 8/1/2002 for the field
603 * value, 8/29/2002.
604 */
605 MONTH,
606
607 /**
608 * The date that is the first of the year. For example, 1/1/2002 for
609 * the field value, 8/29/2002.
610 */
611 YEAR;
612 }
613
614 /**
615 * The value types for result set rows
616 */
617 public static enum FieldType implements StpExEnumeration
618 {
619 /** An initial value for ValueType variables */
620 UNKNOWN(ValueType.UNKNOWN),
621
622 /**
623 * A single-line of text up to 254 characters. Leading and trailing
624 * whitespace is trimmed when stored in a record.
625 */
626 SHORT_STRING(ValueType.SHORT_STRING),
627
628 /**
629 * An arbitrarily long string of characters, possibly containing one
630 * or more newline characters.
631 */
632 MULTILINE_STRING(ValueType.MULTILINE_STRING),
633
634 /**
635 * An arbitrarily large string of uninterpreted data bits
636 */
637 BINARY(ValueType.UNKNOWN),
638
639 /** An integer in the range -9999999999 to 9999999999 */
640 INTEGER(ValueType.INTEGER),
641
642 /**
643 * A GMT date/time between 12:00:01 AM January 1, 1970 and 11:59:59
644 * PM January 18, 2038.
645 */
646 DATE_TIME(ValueType.DATE_TIME),
647
648 /** A floating point value */
649 FLOAT(ValueType.FLOAT),
650
651 /** A reference field */
652 REFERENCE(ValueType.RESOURCE),
653
654 /** A record id (alphanumeric) field */
655 ID(ValueType.ID),
656
657 /** A database id (integer) field */
658 DBID(ValueType.DBID),
659
660 /** The name of a record's current state */
661 STATE(ValueType.STATE),
662
663 /** The type of a record's current state */
664 STATE_TYPE(ValueType.STATE_TYPE),
665
666 /** A record's record type name */
667 RECORD_TYPE(ValueType.RECORD_TYPE);
668
669 /**
670 * @return The CqFieldValue.ValueType to which this
671 * DisplayField.FieldType equates; ValueType.UNKNOWN if
672 * there is no equivalent ValueType.
673 */
674 public ValueType valueType()
675 {
676 return m_valueType;
677 }
678
679 private FieldType(ValueType valueType)
680 {
681 m_valueType = valueType;
682 }
683
684 private ValueType m_valueType;
685 }
686
687 /**
688 * Returns the aggregate function that is applied to the field path of
689 * each selected record to compute the value for the result set.
690 *
691 * @return An Aggregation type code indicating which, if any, aggregate
692 * function will be used to compute this display field.
693 */
694 Aggregation getAggregation();
695
696 /**
697 * Sets the aggregate function for this display field.
698 *
699 * @param aggregation An Aggregation type code. Must not be <b> null</b>.
700 */
701 void setAggregation(Aggregation aggregation);
702
703 /**
704 * Returns the description of the field from the schema.
705 *
706 * @return A String containing the description associated with this
707 * field in the schema definition.
708 */
709 String getDescription();
710
711 /**
712 * Returns the FieldType of the display field. This is the data type of
713 * the field specified by the Path attribute unless the display field is
714 * aggregated, in which case the aggregation function determines this
715 * value: <i>e.g.</i>, getFieldType would return INT for aggregates of
716 * IDs.
717 *
718 * @return The CqFieldValue for this display field.
719 */
720
721 FieldType getFieldType();
722
723 /**
724 * Returns the simple scalar function that is to be applied to this
725 * DisplayField (<i>e.g.</i> month(date))
726 *
727 * @return A Function enumerator specifying the scalar function that is
728 * to be applied to the field before inclusion in the result
729 * set.
730 */
731 Function getFunction();
732
733 /**
734 * Sets the simple scalar function that is to be applied to this
735 * DisplayField before inclusion in the result set.
736 *
737 * @param function The Function enumerator specifying the function.
738 */
739 void setFunction(Function function);
740
741 /**
742 * Returns whether or not the field is in a group-by clause.
743 *
744 * @return <b>true</b> if the result set is grouped by this display
745 * field; otherwise <b>false</b>.
746 */
747 boolean getIsGroupBy();
748
749 /**
750 * Sets whether or not this field is in the group-by clause when
751 * aggregation functions are used.
752 *
753 * @param isGroupBy If <b>true</b>, this field is in the group-by
754 * clause.
755 */
756 void setIsGroupBy(boolean isGroupBy);
757
758 /**
759 * Returns whether or not this field can be used in a query filter.
760 *
761 * @return <b>true</b> if and only if this field can be used in a
762 * filtering expression.
763 */
764 boolean getIsLegalForFilter();
765
766 /**
767 * Returns whether or not this display field occupies a column in the
768 * result set. Some display fields are used only for sorting, grouping,
769 * or filtering and need not be included in the record data returned by
770 * the query.
771 *
772 * @return <b>true</b> if and only if this display field is included in
773 * the result set.
774 */
775 boolean getIsVisible();
776
777 /**
778 * Sets whether or not this display field occupies a column in the
779 * result set
780 *
781 * @param isVisible <b>true</b> if this display field is to be included
782 * in the result set; <b>false</b> otherwise.
783 */
784 void setIsVisible(boolean isVisible);
785
786 /**
787 * Returns the label for the column of the result set that contains
788 * values from this display field.
789 *
790 * @return A character image that may be used as the heading for the
791 * column of the display in which values from this field are
792 * rendered. Will never be <b>null</b>.
793 */
794 String getLabel();
795
796 /**
797 * Sets the label for the column of the result set that contains values
798 * from this display field.
799 *
800 * @param label A String containing the label for the display field
801 * column. Must not be <b>null</b>.
802 */
803 void setLabel(String label);
804
805 /**
806 * Returns the field path that describes the data source for this
807 * display field.
808 *
809 * @return A specification of the property from which the value for this
810 * display field is obtained. The path consists of one or more
811 * properties, each represented by a PropertyName object. The
812 * first property in the path is a property of the query's
813 * primary resource type. All properties in the path, except for
814 * the last field, must be resource-valued properties, and in
815 * each case, the property that follows the resource-valued
816 * property must be a property of the resource type referenced
817 * by the preceding resource-valued property. Will never be <b>
818 * null</b>.
819 */
820 public CqFieldDefinition[] getPath();
821
822 /**
823 * Sets the field path that describes the data source for this display
824 * field.
825 *
826 * @param arg An non-empty array of CqFieldDefinition objects specifying
827 * a property path as described in the documentation for
828 * {@link DisplayField#getPath()}. Must not be <b>null</b>.
829 */
830 public void setPath(CqFieldDefinition... arg);
831
832 /**
833 * Returns the character image of the field path that is the data source
834 * for this display field. This value is computed once and cached for
835 * future use.
836 *
837 * @return A dot-separated list of the names of the properties in the
838 * field path. Will never be <b>null</b>. Will be <b>""</b> if
839 * not yet set.
840 */
841 public String getPathName();
842
843 /**
844 * Returns a code indicating how this field path participates in the
845 * sorting of result set records: ascending, descending or not at all.
846 *
847 * @return A SortType code indicating how this display field is sorted.
848 */
849 public SortType getSortType();
850
851 /**
852 * Sets the SortType code for this display field.
853 *
854 * @param sortType A SortType code. Must not be <b>null</b>.
855 */
856 public void setSortType(SortType sortType);
857
858 /**
859 * Returns the sort order for fields participating in the sort (SortType
860 * not equal NO_SORT). The field having sort order 1 is the primary sort
861 * key; sort order 2 is the secondary sort key, and so forth.
862 *
863 * @return A positive number indicating this display field's ordinal
864 * position within the sort key, or zero if this display field
865 * is not in the sort key.
866 */
867 public long getSortOrder();
868
869 /**
870 * Sets the sort order position for this display field.
871 *
872 * @param sortOrder A non-negative integer.
873 */
874 public void setSortOrder(long sortOrder);
875
876 }
877
878 /**
879 * The conjunction or disjunction of subexpressions within a query filter
880 * expression. This structure is used to represent a node within the filter
881 * expression tree. It represents the logical conjunction (ANDing) or
882 * disjunction (ORing) of filter subexpressions.
883 */
884 public interface FilterNode extends CqQuery.Filter
885 {
886 /**
887 * Returns the n-th operand of the conjunction or disjunction.
888 *
889 * @param n The 0-based index of the operand desired. Must not exceed
890 * the number of operands defined for the Operation of this
891 * node.
892 *
893 * @return A Filter structure representing the n-th operand of the
894 * subexpression. Will never be <b>null</b>.
895 */
896 public CqQuery.Filter getOperand(int n);
897
898 /**
899 * Returns the first operand of this FilterNode.
900 *
901 * @return {@link #getOperand(int) getOperand(0)}
902 */
903 public CqQuery.Filter getOperand();
904
905 /**
906 * Returns the number of operands in this node.
907 *
908 * @return The number of operands currently specified in this node.
909 */
910 public int getOperandCount();
911
912 /**
913 * Returns all operands of the conjunction or disjunction represented by
914 * this node.
915 *
916 * @return A vector of FilterNode structures representing the operands
917 * of the subexpression. Will never be <b>null</b>.
918 */
919 public CqQuery.Filter[] getOperands();
920
921 /**
922 * Sets all operands of the conjunction or disjunction represented by
923 * this node.
924 *
925 * @param list An array of Filter objects representing the operands of
926 * this FilterNode.
927 */
928 public void setOperands(CqQuery.Filter... list);
929 }
930
931 /**
932 * A field/value comparison within a query filter expression; the leaf of a
933 * query filter expression. This structure is also used for specifying a
934 * dynamic filter value.
935 */
936 public interface FilterLeaf extends CqQuery.Filter
937 {
938 /**
939 * A code indicating how the target of the comparison is being
940 * specified.
941 * <p>
942 * A TargetType is paired with each target value in a FilterLeaf.
943 * <p>
944 * For a dynamic filter, the target type is PROMPTED. The target value
945 * is the prompt that can be shown to a user to indicate to that user
946 * what value that user should provide. Prior to executing the query,
947 * the prompt should be replaced by the user-provided value and the
948 * target type adjusted appropriately.
949 * <p>
950 * If the target type is USER, YESTERDAY, TODAY, or TOMMORROW, the
951 * target value should be <b>null</b> since the target value is
952 * implicit in the target type code.
953 * <p>
954 * In ClearQuest, filter targets are always expressed as strings. In
955 * this API targets may be specified by any Java Object. If the target
956 * Object is not a Date, Object.toString() will be applied to it to
957 * obtain the string to pass to ClearQuest. If the target value is null,
958 * the empty string ("") is used.
959 * <p>
960 * If the target value is a Date, the Date will be converted to a String
961 * formated as expected by ClearQuest, using the value of
962 * {@link com.ibm.rational.wvcm.stp.StpProvider#getUserTimeZone()}. The
963 * target type with which the Date value is paired determines the format
964 * used.
965 * <p>
966 * If the target value is specified by a String it is not usually
967 * modified by the client. But, the value may be reformated by the
968 * client if the client knows that the source field or target value is
969 * supposed to be a date/time specification or if the UNKNOWN target
970 * type is used.
971 */
972 public static enum TargetType implements StpExEnumeration
973 {
974 /**
975 * Unspecified target type; the <b>null</b> TargetTyoe value. If
976 * used in a setTarget call, heuristics will be applied to the
977 * associated target value in an attempt to recognize it as a time
978 * specification and reformat it to the format expected by
979 * ClearQuest if needed.
980 */
981 UNKNOWN,
982
983 /**
984 * Target is a constant value. If the field is of type DATE_TIME,
985 * the target type will be converted to DATE_TIME unless the target
986 * value is specified as a String and that string contains no time
987 * component, in which case the target type will be converted to
988 * DATE_ONLY.
989 */
990 CONSTANT,
991
992 /** Target is a user-supplied value */
993 PROMPTED,
994
995 /** Target is the current user */
996 USER,
997
998 /** Target is yesterday's date */
999 YESTERDAY,
1000
1001 /** Target is today's date */
1002 TODAY,
1003
1004 /** Target is tomorrow's date */
1005 TOMORROW,
1006
1007 /**
1008 * Target is the specification for a date-only target. The field
1009 * value is to be compared against the 24 hour interval for the
1010 * specified date. If a Date object is used to specify the target
1011 * value, only the date portion of that object will be used in the
1012 * filter, where the date is determined using the current client
1013 * time zone defined in the provider. If a String is used to specify
1014 * the target value and that specification has a time component,
1015 * the string will be parsed to a Date using the client time zone
1016 * and then formatted as a date-only string as just described.
1017 */
1018 DATE_ONLY,
1019
1020 /**
1021 * Target is the specification for a date and time target. The field
1022 * value is to be compared against the precise time denoted by the
1023 * target value. If a Date object is used to specify the target
1024 * value its value will be used in the filter. If a String is used
1025 * to specify the target value and the String contains no time
1026 * component, the value will be converted to midnight on the date
1027 * specified in the client time zone.
1028 */
1029 DATE_TIME,
1030 }
1031
1032 /**
1033 * Returns the field path designating the source of the comparison.
1034 *
1035 * @return A specification of the record field whose value will be
1036 * compared against the target value(s) in this filter. The path
1037 * consists of one or more record fields each represented by a
1038 * {@link CqFieldDefinition CqFieldDefinition} object. The first
1039 * field in the path is a field of the query's primary record
1040 * type. All fields in the path, except for the last field, must
1041 * be reference-type fields, and in each case, the field that
1042 * follows the reference field must be a field of the record
1043 * type referenced by the preceding reference field. Will never
1044 * be <b>null</b>.
1045 */
1046 public CqFieldDefinition[] getSource();
1047
1048 /**
1049 * Returns the character image of the field path designating the source
1050 * of the comparison
1051 *
1052 * @return The returned image consists of the field names of the field
1053 * path separated one from the other by a dot symbol. Will never
1054 * be <b>null</b>.
1055 */
1056 public String getSourceName();
1057
1058 /**
1059 * Returns the number of targets in this comparison expression Each
1060 * comparison operation requires a different number of targets ranging
1061 * from none (IS_NULL, IS_NOT_NULL) to many (IS_IN_SET, IS_NOT_IN_SET).
1062 *
1063 * @return The number of comparison targets currently specified for this
1064 * comparison.
1065 */
1066 public int getTargetCount();
1067
1068 /**
1069 * Returns the target type code for the n-th target of the comparison.
1070 *
1071 * @param index The 0-based index of the desired target. Must be less
1072 * than the target count.
1073 *
1074 * @return The target type code for the n-th target of the comparison.
1075 */
1076 public FilterLeaf.TargetType getTargetType(int index);
1077
1078 /**
1079 * Returns the target type code for the first target.
1080 *
1081 * @return getTargetType(0)
1082 */
1083 public FilterLeaf.TargetType getTargetType();
1084
1085 /**
1086 * Returns the n-th target value of the comparison.
1087 *
1088 * @param index The 0-based index of the desired target. Must be less
1089 * than the target count.
1090 *
1091 * @return The character image of the the n-th target. Will never be
1092 * <b>null</b>.
1093 */
1094 public String getTarget(int index);
1095
1096 /**
1097 * Returns the first target of the comparison.
1098 *
1099 * @return {@link #getTarget(int) getTarget(0)}.
1100 */
1101 public String getTarget();
1102
1103 /**
1104 * Sets the first target of the comparison and resets the target count
1105 * to 1.
1106 *
1107 * @param targettype
1108 * The type of the first target value. Cannot be <b> null</b>.
1109 * @param target
1110 * The first target value. The value provided will be
1111 * converted to a String object appropriate to the TargetType
1112 * specified. If null and a string value is required, the
1113 * empty string ("") will be used.
1114 */
1115 public void setTarget(FilterLeaf.TargetType targettype,
1116 Object target);
1117
1118 /**
1119 * Sets the first target of the comparison and resets the target count
1120 * to 1.
1121 *
1122 * @param targetType A FilterLeaf.TargetType enumerator specifying the
1123 * type of the first target. This TargetType must be
1124 * TODAY, TOMORROW, YESTERDAY, or USER
1125 */
1126 public void setTarget(FilterLeaf.TargetType targetType);
1127
1128 /**
1129 * Add the type and value for an additional target of the comparison.
1130 *
1131 * @param targetType The type of the additional target value. Cannot be
1132 * <b> null</b>.
1133 * @param target The additional target. The value provided will be
1134 * converted to a String object appropriate to the TargetType
1135 * specified. If null and a string value is required, the
1136 * empty string ("") will be used.
1137 */
1138 public void addTarget(FilterLeaf.TargetType targetType,
1139 Object target);
1140
1141 /**
1142 * Returns a list of all the target values for the comparison. If the
1143 * TargetType of the target is TODAY, TOMORROW, YESTERDAY, or USER, the
1144 * value is <b>null</b>
1145 *
1146 * @return A list of String elements, each containing the character
1147 * image of a target value. Will never be <b>null</b>.
1148 */
1149 public List<String> getTargets();
1150
1151 /**
1152 * Returns an array of all the target types for the comparison
1153 * corresponding to the vector of values returned by {@link
1154 * CqQuery.FilterLeaf#getTargets() FilterLeaf.getTargets()}.
1155 *
1156 * @return A vector of TargetType codes corresponding in order to the
1157 * values returned by {@link CqQuery.FilterLeaf#getTargets()
1158 * FilterLeaf.getTargets()}.
1159 */
1160 public TargetType[] getTargetTypes();
1161
1162 /**
1163 * Set the types and values of multiple targets for the comparison.
1164 *
1165 * @param targetTypes
1166 * An array of target type codes designating the way the
1167 * corresponding values in the targets parameter are
1168 * specified.
1169 * @param targets
1170 * An array of Object elements, each containing a target
1171 * value for the comparison. Cannot be <b>null</b>. The
1172 * values provided will be converted to a String objects
1173 * appropriate to the TargetTypes specified. If <b>null</b>
1174 * and a string value is required, the empty string ("") will
1175 * be used.
1176 */
1177 void setTargets(TargetType[] targetTypes,
1178 List<Object> targets);
1179
1180 /**
1181 * Set the type and value for each targets for the comparison.
1182 *
1183 * @param targets
1184 * An array of TargetType codes and other Object values
1185 * designating the new targets of the comparison operation.
1186 * <p>
1187 * Nominally, this argument is an array of alternating
1188 * TargetType and target value Objects specifying,
1189 * respectively, the type and value of each filter target.
1190 * However, for USER, YESTERDAY, TODAY, and TOMORROW target
1191 * types, the associated <b>null</b> value may be elided. If
1192 * a target value is not preceded by a target type, then the
1193 * target type is assumed to be CONSTANT or UNKNOWN. Thus,
1194 * although a TargetType may always be specified for each
1195 * target value, a TargetType entry is is <i>required</i>
1196 * only when specifying a PROMPTED, DATE_ONLY, or DATE_TIME
1197 * target type.
1198 * <p>
1199 * Initially, an untyped value is assumed to be of type
1200 * UNKNOWN, which means heuristics will be applied to the
1201 * value to determine whether or not the value is a date/time
1202 * value that needs to be converted to a form acceptable to
1203 * ClearQuest. If, however, the CONSTANT type was used
1204 * previously in the array, an untyped value is assumed to be
1205 * of type CONSTANT, which means the value will be converted
1206 * only if the field type is known to be DATE_TIME.
1207 * <p>
1208 * May be <b>null</b> or empty to specify no targets for the
1209 * comparison operation.
1210 */
1211 void setTargets(Object... targets);
1212 }
1213
1214 /**
1215 * A query filter expression or a subexpression thereof.
1216 *
1217 * <p>
1218 * This structure represents a node within the filter expression tree. As a
1219 * FilterNode, it represents the logical conjunction (ANDing) or disjunction
1220 * (ORing) of filter subexpressions. As a FilterLeaf, it represents the
1221 * comparison of a field with one or more constant values.
1222 */
1223
1224 public interface Filter
1225 {
1226 /**
1227 * An enumeration of the logical operations and comparisons that can be
1228 * used to combine the operands of a Filter subexpression.
1229 */
1230 public static enum Operation implements StpExEnumeration
1231 {
1232 /** A FilterNode with an unspecified operation */
1233 UNSPECIFIED,
1234
1235 /** A FilterNode representing the logical AND of its operands */
1236 CONJUNCTION,
1237
1238 /** A FilterNode representing the logical OR of its operands */
1239 DISJUNCTION,
1240
1241 /** A FilterLeaf with an unspecified comparison */
1242 UNSPECIFIED_COMPARISON,
1243
1244 /** test the source and target for equality */
1245 IS_EQUAL,
1246
1247 /** test the source and target for inequality */
1248 IS_NOT_EQUAL,
1249
1250 /** test that the source is strictly less than the target */
1251 IS_LESS_THAN,
1252
1253 /** test that the source is less than or equal to the target */
1254 IS_LESS_THAN_OR_EQUAL,
1255
1256 /** test that the source is strictly greater than the target */
1257 IS_GREATER_THAN,
1258
1259 /** test that the source is greater than or equal to the target */
1260 IS_GREATER_THAN_OR_EQUAL,
1261
1262 /** test that the target is a substring of the source */
1263 HAS_SUBSTRING,
1264
1265 /** test that the target is not a substring of the source */
1266 HAS_NO_SUBSTRING,
1267
1268 /** test that the source is between the two target values */
1269 IS_BETWEEN,
1270
1271 /** test that the source is not between the two targets */
1272 IS_NOT_BETWEEN,
1273
1274 /** test that the source is <b>null</b> */
1275 IS_NULL,
1276
1277 /** test that the source is not <b>null</b> */
1278 IS_NOT_NULL,
1279
1280 /** test that the source is equal to one of the targets */
1281 IS_IN_SET,
1282
1283 /** test that the source is not equal to any of the targets */
1284 IS_NOT_IN_SET;
1285 }
1286
1287 /**
1288 * Returns the logical operation that is to be used to combine the
1289 * operands of this subexpression. You can use the operation code to
1290 * determine what kind of subexpression this structure represents before
1291 * casting it to a FilterNode or FilterLeaf. Operations UNSPECIFIED,
1292 * CONJUNCTION and DISJUNCTION indicate a FilterNode; the remaining
1293 * Operations indicate a FilterLeaf.
1294 *
1295 * @return The Operation enumerator for the logical or comparison
1296 * operator of this node.
1297 */
1298 public Operation getOperation();
1299
1300 /**
1301 * Set the operation code for a Filter subexpression.
1302 *
1303 * @param op The new operation code. The code must be consistent with
1304 * the most complete subclass of this object.
1305 */
1306 public void setOperation(Operation op);
1307 }
1308
1309 /**
1310 * A special field path token designating the aggregated key fields of a
1311 * ClearQuest record, for use in specifying query filters and display
1312 * fields.
1313 */
1314 CqFieldDefinition[] UNIQUE_KEY_FIELD_PATH = new CqFieldDefinition[0];
1315
1316 /**
1317 * Returns the position/column number of the display field having the given
1318 * label. Requires that the DISPLAY_FIELDS property is defined for this
1319 * proxy.
1320 *
1321 * @param label A String containing the column label for the desired display
1322 * field.
1323 *
1324 * @return 0 if the label cannot be found amongst the visible display fields
1325 * of the query; otherwise the ordinal position of the display field
1326 * among the columns of the result set.
1327 *
1328 * @throws WvcmException If the DISPLAY_FIELDS property is not defined for
1329 * this proxy.
1330 */
1331 long columnNumber(String label) throws WvcmException;
1332
1333 /**
1334 * Creates a new query at the location specified by this proxy and delivers
1335 * it to the database. This proxy must define the PRIMARY_RECORD_TYPE
1336 * property and one of the properties DISPLAY_FIELDS or SQL.
1337 *
1338 * @param feedback Requests the properties desired in the proxy returned by
1339 * this operation.
1340 * @return A proxy for the newly created query populated with the properties
1341 * requested by the feedback argument.
1342 * @throws WvcmException If a resource already exists at the location
1343 * defined by this proxy or if the new query cannot be delivered
1344 * to the database for any number of reasons.
1345 */
1346 CqQuery doCreateQuery(Feedback feedback) throws WvcmException;
1347
1348 /**
1349 * Creates a new query at the location specified by this proxy and delivers
1350 * it to the database. This proxy must always define the PRIMARY_RECORD_TYPE
1351 * property. At least one of the properties DISPLAY_FIELDS or SQL must be
1352 * defined if the new query is to be delivered to the database.
1353 *
1354 * @param feedback Requests the properties desired in the proxy returned by
1355 * this operation.
1356 * @param deliveryOrder A deliver order list specifying the resources to be
1357 * delivered to the database after this resource is successfully
1358 * created.
1359 * @return A proxy for the newly created query populated with the properties
1360 * requested by the feedback argument.
1361 * @throws WvcmException If a resource already exists at the location
1362 * defined by this proxy or if the resources specified by the
1363 * deliveryOrder argument cannot be delivered to the database.
1364 */
1365 CqQuery doCreateQuery(Feedback feedback,
1366 List<CqContextResource> deliveryOrder)
1367 throws WvcmException;
1368
1369 /**
1370 * Executes this query on the server and returns rows of the result set as
1371 * requested.
1372 *
1373 * @param targetRow The 1-based index of a row of the result set that must
1374 * be included in the response to this request. The target row
1375 * values will be the values returned in the first RowData object
1376 * of the iterator.
1377 * @param maxRows The maximum number of rows of the result set that should
1378 * be included in the response to this request. A value of
1379 * Long.MAX_VALUE will request all rows in the result set; If
1380 * this parameter is 0, no rows are requested. If the query does
1381 * not generate all of the rows requested, it is not an error.
1382 * @param options An instance of ListOptions that specifies optional
1383 * attributes for controlling the performance of the query or its
1384 * response. May be <b>null</b>, in which case server-specified
1385 * values will be used for each attribute.
1386 * @param dynamicFilters Some queries require selected portions of the
1387 * filter to be specified dynamically at the time the query is
1388 * executed. These filter values must be specified in the
1389 * dynamicFilters vector in the order defined by the query. See
1390 * {@link CqQuery#DYNAMIC_FILTERS Query#DYNAMIC_FILTERS}. May be
1391 * <b>null</b> if the query has no parameters.
1392 *
1393 * @return A CqResultSet presenting the rows of the result set in the order
1394 * returned by the query.
1395 *
1396 * @throws WvcmException if any errors occur during the execution of the
1397 * query or the formation of the response.
1398 */
1399 CqResultSet doExecute(long targetRow,
1400 long maxRows,
1401 ListOptions options,
1402 FilterLeaf... dynamicFilters) throws WvcmException;
1403
1404 /**
1405 * Executes this query and writes the result set to a text file
1406 *
1407 * @param results The File into which the result set is to be written. Must
1408 * not be <b>null</b>.
1409 * @param feedback A Feedback instance specifying properties to be returned
1410 * from the operation in the CqQuery proxy. May be <b>null</b>.
1411 * @param options A StreamOptions instance specifying various options to
1412 * control the format of the generated output.
1413 * @param dynamicFilters Some queries require selected portions of the
1414 * filter to be specified dynamically at the time the query is
1415 * executed. These filter values must be specified in the
1416 * dynamicFilters vector in the order defined by the query. See
1417 * {@link CqQuery#DYNAMIC_FILTERS Query#DYNAMIC_FILTERS}. May be
1418 * <b>null</b> if the query has no parameters.
1419 * @return A CqQuery proxy for the query that was executed, populated with
1420 * the property values requested by the feedback parameter.
1421 * @throws WvcmException
1422 */
1423 CqQuery doExecute(File results,
1424 Feedback feedback,
1425 FileOptions options,
1426 FilterLeaf... dynamicFilters) throws WvcmException;
1427
1428 /**
1429 * Executes this query and formats the results into a chart.
1430 *
1431 * @param chartImage An OutputStream to which the generated chart image will
1432 * be written.
1433 * @param feedback A Feedback instance specifying properties to be returned
1434 * from the operation in the CqQuery proxy. May be <b>null</b>.
1435 * @param options A ChartOptions object specifying the attributes of the
1436 * generated chart.
1437 * @param dynamicFilters Any dynamic filters needed to execute the query.
1438 * @return A proxy for this query populated with the properties specified by
1439 * the Feedback argument.
1440 * @throws WvcmException Thrown if the chart cannot be generated as
1441 * requested.
1442 */
1443 CqQuery doMakeChart(OutputStream chartImage,
1444 Feedback feedback,
1445 ChartOptions options,
1446 FilterLeaf... dynamicFilters) throws WvcmException;
1447
1448 /**
1449 * An array containing a {@link CqQuery.FilterLeaf FilterLeaf} structure
1450 * for each of the query's dynamic filters. This property is computed from
1451 * the PROMPTED leaves of the filter defined by the FILTERING property.
1452 */
1453 PropertyName<CqQuery.FilterLeaf[]> DYNAMIC_FILTERS =
1454 new PropertyName<CqQuery.FilterLeaf[]>(PROPERTY_NAMESPACE,
1455 "dynamic-filters");
1456
1457 /**
1458 * Returns the value of the {@link CqQuery#DYNAMIC_FILTERS DYNAMIC_FILTERS}
1459 * property as defined by this proxy.
1460 *
1461 * @return An array of FilterLeaf objects, each representing one of the
1462 * dynamic filters defined for this query. An empty array if the
1463 * query's filtering expression has no PROMPTED FieldLeaf instances.
1464 *
1465 * @throws WvcmException if this proxy does not define a value for the
1466 * {@link CqQuery#DYNAMIC_FILTERS DYNAMIC_FILTERS} property.
1467 */
1468 CqQuery.FilterLeaf[] getDynamicFilters() throws WvcmException;
1469
1470 /**
1471 * Whether or not any fields of the query are aggregated.
1472 */
1473 PropertyName<Boolean> IS_AGGREGATED =
1474 new PropertyName<Boolean>(StpExBase.PROPERTY_NAMESPACE, "is-aggregated");
1475
1476 /**
1477 * Returns the value of the {@link CqQuery#IS_AGGREGATED IS_AGGREGATED}
1478 * property as defined by this proxy.
1479 *
1480 * @return <b>true</b> if this query contains any aggregated display
1481 * fields; <b>false</b> otherwise.
1482 *
1483 * @throws WvcmException if this proxy does not define a value for the
1484 * {@link CqQuery#IS_AGGREGATED IS_AGGREGATED} property.
1485 */
1486 boolean getIsAggregated() throws WvcmException;
1487
1488 /**
1489 * Whether or not the query is defined on a family of record types as
1490 * opposed to being defined on a single record type.
1491 */
1492 PropertyName<Boolean> IS_MULTITYPE =
1493 new PropertyName<Boolean>(StpExBase.PROPERTY_NAMESPACE, "is-multitype");
1494
1495 /**
1496 * Returns the value of the {@link CqQuery#IS_MULTITYPE IS_MULTITYPE}
1497 * property as defined by this proxy.
1498 *
1499 * @return <b>true</b> if this query is defined on a family of record
1500 * types; <b>false</b> if it is defined on a single record type.
1501 *
1502 * @throws WvcmException if this proxy does not define a value for the
1503 * {@link CqQuery#IS_MULTITYPE IS_MULTITYPE} property.
1504 */
1505 boolean getIsMultitype() throws WvcmException;
1506
1507 /**
1508 * Whether or not SQL has been generated for the query
1509 */
1510 PropertyName<Boolean> IS_SQL_GENERATED =
1511 new PropertyName<Boolean>(StpExBase.PROPERTY_NAMESPACE,
1512 "is-sql-generated");
1513
1514 /**
1515 * Returns the value of the
1516 * {@link CqQuery#IS_SQL_GENERATED IS_SQL_GENERATED} property as defined by
1517 * this proxy.
1518 *
1519 * @return <b>true</b> if SQL has been generated for this query; <b>false</b>
1520 * if the SQL has been provided by the user.
1521 *
1522 * @throws WvcmException if this proxy does not define a value for the
1523 * {@link CqQuery#IS_SQL_GENERATED IS_SQL_GENERATED} property.
1524 */
1525 boolean getIsSqlGenerated() throws WvcmException;
1526
1527 /**
1528 * The record type of the records that are targeted by the query.
1529 */
1530 PropertyName<CqRecordType> PRIMARY_RECORD_TYPE =
1531 new PropertyName<CqRecordType>(PROPERTY_NAMESPACE,
1532 "primary-record-type");
1533
1534 /**
1535 * Returns the value of the {@link CqQuery#PRIMARY_RECORD_TYPE
1536 * PRIMARY_RECORD_TYPE} property as defined by this proxy.
1537 *
1538 * @return A CqRecordType proxy for the primary resource type of this query.
1539 * Will never be <b>null</b>.
1540 *
1541 * @throws WvcmException if this proxy does not define a value for the
1542 * {@link CqQuery#PRIMARY_RECORD_TYPE PRIMARY_RECORD_TYPE}
1543 * property.
1544 */
1545 CqRecordType getPrimaryRecordType() throws WvcmException;
1546
1547 /**
1548 * Defines a new value for the {@link CqQuery#PRIMARY_RECORD_TYPE
1549 * PRIMARY_RECORD_TYPE} property of this proxy.
1550 *
1551 * @param primaryRecordType A CqRecordType object representing the new
1552 * primary record type for this query definition.
1553 */
1554 void setPrimaryRecordType(CqRecordType primaryRecordType);
1555
1556 /**
1557 * Whether this query generates a list, report, or chart
1558 */
1559 PropertyName<CqQuery.QueryType> QUERY_TYPE =
1560 new PropertyName<CqQuery.QueryType>(StpExBase.PROPERTY_NAMESPACE,
1561 "query-type");
1562
1563 /**
1564 * Returns the value of the {@link CqQuery#QUERY_TYPE QUERY_TYPE} property
1565 * as defined by this proxy.
1566 *
1567 * @return A QueryType enumerator identifying the type of this query.
1568 *
1569 * @throws WvcmException if this proxy does not define a value for the
1570 * {@link CqQuery#QUERY_TYPE QUERY_TYPE} property.
1571 */
1572 CqQuery.QueryType getQueryType() throws WvcmException;
1573
1574 /**
1575 * The SQL associated with the query.
1576 */
1577 PropertyName<String> SQL =
1578 new PropertyName<String>(StpExBase.PROPERTY_NAMESPACE, "sql");
1579
1580 /**
1581 * Returns the value of the {@link CqQuery#SQL SQL} property as defined by
1582 * this proxy.
1583 *
1584 * @return A String containing the SQL statement for this query.
1585 *
1586 * @throws WvcmException if this proxy does not define a value for the
1587 * {@link CqQuery#SQL SQL} property.
1588 */
1589 String getSql() throws WvcmException;
1590
1591 /**
1592 * Defines a new value for the {@link CqQuery#SQL SQL} property of this
1593 * proxy.
1594 *
1595 * @param sql A String object containing the SQL statement for the query.
1596 */
1597 void setSql(String sql);
1598
1599 /**
1600 * An array containing a {@link DisplayField DisplayField} structure for
1601 * each column of the result set generated by this query.
1602 */
1603 PropertyName<DisplayField[]> DISPLAY_FIELDS =
1604 new PropertyName<DisplayField[]>(StpExBase.PROPERTY_NAMESPACE,
1605 "display-fields");
1606
1607 /**
1608 * Returns the value of the {@link CqQuery#DISPLAY_FIELDS DISPLAY_FIELDS}
1609 * property as defined by this proxy.
1610 *
1611 * @return An array of DisplayField structures describing the columns of the
1612 * result set generated by the query.
1613 *
1614 * @throws WvcmException if this proxy does not define a value for the
1615 * {@link CqQuery#DISPLAY_FIELDS DISPLAY_FIELDS} property.
1616 */
1617 DisplayField[] getDisplayFields() throws WvcmException;
1618
1619 /**
1620 * Defines a new value for the {@link CqQuery#DISPLAY_FIELDS DISPLAY_FIELDS}
1621 * property of this proxy.
1622 *
1623 * @param displayFields An array of DisplayField objects representing the
1624 * new display fields of the query.
1625 */
1626 void setDisplayFields(DisplayField... displayFields);
1627
1628 /**
1629 * A {@link CqQuery.Filter Filter} node representing the logical expression
1630 * that is used to filter records to form each row of the result set.
1631 */
1632 PropertyName<CqQuery.Filter> FILTERING =
1633 new PropertyName<CqQuery.Filter>(StpExBase.PROPERTY_NAMESPACE,
1634 "filtering");
1635
1636 /**
1637 * Returns the value of the {@link CqQuery#FILTERING FILTERING} property as
1638 * defined by this proxy.
1639 *
1640 * @return A Filter object representing the filter expression defined by
1641 * this query definition. Will never be <b>null</b>.
1642 *
1643 * @throws WvcmException if this proxy does not define a value for the
1644 * {@link CqQuery#FILTERING FILTERING} property.
1645 */
1646 CqQuery.Filter getFiltering() throws WvcmException;
1647
1648 /**
1649 * Defines a new value for the {@link CqQuery#FILTERING FILTERING} property
1650 * of this proxy.
1651 *
1652 * @param filter A Filter object representing the new filtering to be used
1653 * in this query definition.
1654 */
1655 void setFiltering(CqQuery.Filter filter);
1656 }