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