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