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 * (C) 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
014package com.ibm.rational.wvcm.stp.cq;
015
016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018import java.io.File;
019import java.io.OutputStream;
020import java.util.HashMap;
021import java.util.List;
022import java.util.Map;
023
024import javax.wvcm.Feedback;
025import javax.wvcm.WvcmException;
026import javax.wvcm.PropertyNameList.PropertyName;
027import javax.wvcm.PropertyRequestItem.PropertyRequest;
028
029import com.ibm.rational.wvcm.stp.StpProvider;
030import com.ibm.rational.wvcm.stp.cq.CqFieldValue.ValueType;
031import com.ibm.rational.wvcm.stpex.StpExBase;
032import com.ibm.rational.wvcm.stpex.StpExEnumeration;
033import 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>&lt;parent-folder-path&gt;</i>/<i>&lt;query-name&gt;</i>@<i>&lt;db-set&gt;</i>/<i>&lt;user-db&gt;</i>
043 * </pre>
044 * 
045 * where <i>&lt;parent-folder-path&gt;</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 */
051public 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}