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><parent-folder-path></i>/<i><query-name></i>@<i><db-set></i>/<i><user-db></i> 041 * </pre> 042 * 043 * where <i><parent-folder-path></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}