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