001/* 002 * IBM and/or HCL Confidential 003 * OCO Source Materials 004 * (C) Copyright IBM Corp. 2004, 2014. All Rights Reserved. 005 * (C) Copyright HCL Technologies Ltd. 2016, 2018 All Rights Reserved 006 * 007 * The source code for this program is not published or otherwise 008 * divested of its trade secrets, irrespective of what has been 009 * deposited with the U.S. Copyright Office. 010 */ 011 012package com.ibm.rational.wvcm.stp.cq; 013 014import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE; 015 016import java.util.Date; 017import java.util.List; 018import java.util.Map; 019 020import javax.wvcm.Feedback; 021import javax.wvcm.Location; 022import javax.wvcm.PropertyNameList.PropertyName; 023import javax.wvcm.ResourceList; 024import javax.wvcm.WvcmException; 025 026import com.ibm.rational.wvcm.stp.StpLocation; 027import com.ibm.rational.wvcm.stp.StpProperty; 028import com.ibm.rational.wvcm.stp.StpRepository; 029import com.ibm.rational.wvcm.stpex.StpExBase; 030import com.ibm.rational.wvcm.stpex.StpExEnumeration; 031 032 033/** 034 * A proxy for a ClearQuest user database 035 * <p> 036 * In addition to representing the physical database, a CqUserDb object also 037 * represents the on-going ClearQuest session between the user and that 038 * database. As such, it represents a user-specific, server-resident area in 039 * which changes to CqContextResources are performed. This server-area is 040 * referred to as the database's <i>change context</i>. Here, the term 041 * <i>change</i> refers to the creation, revision, or deletion of a resource, 042 * its content or its properties as a consequence of some server interaction. 043 * <p> 044 * In general, any changes made to a CqContextResource are held in the change 045 * context area until the client explicitly directs the server to deliver those 046 * changes to the database. Each operation that changes a database object has a 047 * parameter named <code>deliveryOrder</code> (usually the last parameter). 048 * This parameter controls the disposition of the changes after the operation 049 * completes. The parameter is a List<CqContextResource> and specifies the 050 * resources (in the change context) to be delivered to the database and the 051 * order in which those resources are to be delivered. 052 * <p> 053 * If the operation fails, no delivery is attempted. 054 * <p> 055 * Special instances of List<CqContextResource> are defined in the CqProvider 056 * interface as short-cuts for specifying the resources to be delivered. See the 057 * documentation for {@link CqProvider#HOLD}, {@link CqProvider#AUTO}, 058 * {@link CqProvider#DELIVER}, and {@link CqProvider#DELIVER_ALL} for more 059 * information. 060 * <p> 061 * The properties that describe the state of the database's change context are 062 * {@link #CONTEXT_IS_EMPTY}, {@link #MODIFIED_RESOURCES_LIST}, and 063 * {@link #MORIBUND_RESOURCES_LIST}. 064 * <p> 065 * In addition to the operations that modify a CqContextResource, the following 066 * methods are defined by CqUserDb to aid in the management of the database's 067 * change context: {@link #doClearContext(Feedback)}, 068 * {@link #doDeliver(Feedback, List)}, and {@link #doRevert(Feedback, List)}. 069 * <p> 070 * The user-friendly specification for the location of a user database has the 071 * form 072 * 073 * <pre> 074 * <b>cq.userdb:</b><i><db-set></i>/<i><user-db></i> 075 * </pre> 076 * 077 * @see CqContextResource 078 */ 079public interface CqUserDb extends StpRepository, CqDb 080{ 081 /** 082 * Answers whether or not there are modified or moribund resources still in 083 * the change context associated with this user database. 084 */ 085 PropertyName<Boolean> CONTEXT_IS_EMPTY = 086 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "context-is-empty"); 087 088 /** 089 * Returns the value of the {@link #CONTEXT_IS_EMPTY CONTEXT_IS_EMPTY} 090 * property as defined by this proxy. 091 * 092 * @return <b>true</b> if the change context has undelivered resources; 093 * <b>false</b> if there are no modified or moribund resources in 094 * the change context. 095 * 096 * @throws WvcmException if this proxy does not define a value for the 097 * {@link #CONTEXT_IS_EMPTY CONTEXT_IS_EMPTY} property. 098 */ 099 boolean getContextIsEmpty() throws WvcmException; 100 101 /** 102 * A list of the modified resources currently in the database's change 103 * context. The changes made to these resources will not be seen until the 104 * changes are delivered. 105 */ 106 PropertyName<ResourceList<CqContextResource>> MODIFIED_RESOURCES_LIST = 107 new PropertyName<ResourceList<CqContextResource>>(PROPERTY_NAMESPACE, 108 "modified-resources-list"); 109 110 /** 111 * Returns the value of the 112 * {@link #MODIFIED_RESOURCES_LIST MODIFIED_RESOURCES_LIST} property as 113 * defined by this proxy. 114 * 115 * @return A list of the context resources of the database that have been 116 * modified but not yet committed to the database. 117 * 118 * @throws WvcmException if this proxy does not define a value for the 119 * {@link #MODIFIED_RESOURCES_LIST MODIFIED_RESOURCES_LIST} 120 * property. 121 */ 122 ResourceList<CqContextResource> getModifiedResourcesList() 123 throws WvcmException; 124 125 /** 126 * A list of the context resources whose deletion has been initiated but not 127 * yet committed. The deletion will not be visible until these resources are 128 * delivered to the database. The deletion of a moribund resource can be 129 * canceled using the doRevert() method. 130 */ 131 PropertyName<ResourceList<CqContextResource>> MORIBUND_RESOURCES_LIST = 132 new PropertyName<ResourceList<CqContextResource>>(PROPERTY_NAMESPACE, 133 "moribund-resources-list"); 134 135 /** 136 * Returns the value of the 137 * {@link #MORIBUND_RESOURCES_LIST MORIBUND_RESOURCES_LIST} property as 138 * defined by this proxy. 139 * 140 * @return A list of the context resources of the database whose deletion 141 * has been initiated but not yet committed to the database 142 * 143 * @throws WvcmException if this proxy does not define a value for the 144 * {@link #MORIBUND_RESOURCES_LIST MORIBUND_RESOURCES_LIST} 145 * property. 146 */ 147 ResourceList<CqContextResource> getMoribundResourcesList() 148 throws WvcmException; 149 150 /** 151 * The first-level query folder items in this user database. At this level 152 * are just two query folders containing, respectively, the public and 153 * personal query folder items. 154 */ 155 PropertyName<ResourceList<CqQueryFolderItem>> QUERY_FOLDER_ITEMS = 156 new PropertyName<ResourceList<CqQueryFolderItem>>(PROPERTY_NAMESPACE, 157 "query-folder-items"); 158 159 /** 160 * Returns the value of the {@link #QUERY_FOLDER_ITEMS QUERY_FOLDER_ITEMS} 161 * property as defined by this proxy. 162 * 163 * @return A list of two CqQueryFolder proxies; one for the public queries 164 * folder and one for the personal queries folder. 165 * 166 * @throws WvcmException if this proxy does not define a value for the 167 * {@link #QUERY_FOLDER_ITEMS QUERY_FOLDER_ITEMS} property. 168 */ 169 ResourceList<CqQueryFolderItem> getQueryFolderItems() throws WvcmException; 170 171 /** 172 * The CqRecordType that the schema suggests should be used by default when 173 * creating records and when finding records by id. 174 */ 175 PropertyName<CqRecordType> DEFAULT_RECORD_TYPE = 176 new PropertyName<CqRecordType>(PROPERTY_NAMESPACE, 177 "default-record-type"); 178 179 /** 180 * Returns the value of the {@link #DEFAULT_RECORD_TYPE DEFAULT_RECORD_TYPE} 181 * property as defined by this proxy. 182 * 183 * @return A CqRecordType proxy for the default record type defined for this 184 * user database. 185 * 186 * @throws WvcmException if this proxy does not define a value for the 187 * {@link #DEFAULT_RECORD_TYPE DEFAULT_RECORD_TYPE} property. 188 */ 189 CqRecordType getDefaultRecordType() throws WvcmException; 190 191 /** A list of the record types defined by this user database. */ 192 PropertyName<ResourceList<CqRecordType>> RECORD_TYPE_SET = 193 new PropertyName<ResourceList<CqRecordType>>(PROPERTY_NAMESPACE, 194 "record-type-set"); 195 196 /** 197 * Returns the value of the {@link #RECORD_TYPE_SET RECORD_TYPE_SET} 198 * property as defined by this proxy. 199 * 200 * @return A ResourceList containing a CqRecordType proxy for each record 201 * type defined by this user database. 202 * 203 * @throws WvcmException if this proxy does not define a value for the 204 * {@link #RECORD_TYPE_SET RECORD_TYPE_SET} property. 205 */ 206 ResourceList<CqRecordType> getRecordTypeSet() throws WvcmException; 207 208 /** 209 * The query folder containing all queries in this database privately owned 210 * by the current user. 211 */ 212 PropertyName<CqQueryFolder> PERSONAL_FOLDER = 213 new PropertyName<CqQueryFolder>(PROPERTY_NAMESPACE, "personal-folder"); 214 215 /** 216 * Returns the value of the {@link #PERSONAL_FOLDER PERSONAL_FOLDER} 217 * property as defined by this proxy. 218 * 219 * @return A CqQueryFolder proxy for the root folder containing all personal 220 * queries. 221 * 222 * @throws WvcmException if this proxy does not define a value for the 223 * {@link #PERSONAL_FOLDER PERSONAL_FOLDER} property. 224 */ 225 CqQueryFolder getPersonalFolder() throws WvcmException; 226 227 /** The query folder containing all public queries in this database */ 228 PropertyName<CqQueryFolder> PUBLIC_FOLDER = 229 new PropertyName<CqQueryFolder>(PROPERTY_NAMESPACE, "public-folder"); 230 231 /** 232 * Returns the value of the {@link #PUBLIC_FOLDER PUBLIC_FOLDER} property as 233 * defined by this proxy. 234 * 235 * @return A CqQueryFolder proxy for the root query folder that contains all 236 * public queries. 237 * 238 * @throws WvcmException if this proxy does not define a value for the 239 * {@link #PUBLIC_FOLDER PUBLIC_FOLDER} property. 240 */ 241 CqQueryFolder getPublicFolder() throws WvcmException; 242 243 /** 244 * All queries (no charts or reports) defined in this database and 245 * accessible to the current user. 246 */ 247 PropertyName<ResourceList<CqQuery>> ALL_QUERIES = 248 new PropertyName<ResourceList<CqQuery>>(PROPERTY_NAMESPACE, 249 "all-queries"); 250 251 /** 252 * Returns the value of the {@link #ALL_QUERIES ALL_QUERIES} property as 253 * defined by this proxy. 254 * 255 * @return A ResourceList of CqQuery proxies containing all the queries of 256 * type CqQuery.QueryType.LIST defined in this user database. 257 * 258 * @throws WvcmException if this proxy does not define a value for the 259 * {@link #ALL_QUERIES ALL_QUERIES} property. 260 */ 261 ResourceList<CqQuery> getAllQueries() throws WvcmException; 262 263 /** The queries (no charts or reports) owned by the current user */ 264 PropertyName<ResourceList<CqQuery>> PERSONAL_QUERIES = 265 new PropertyName<ResourceList<CqQuery>>(PROPERTY_NAMESPACE, 266 "personal-queries"); 267 268 /** 269 * Returns the value of the {@link #PERSONAL_QUERIES PERSONAL_QUERIES} 270 * property as defined by this proxy. 271 * 272 * @return A ResourceList of CqQuery proxies containing all the personal 273 * queries (no charts or reports) defined in this database for the 274 * current user. 275 * 276 * @throws WvcmException if this proxy does not define a value for the 277 * {@link #PERSONAL_QUERIES PERSONAL_QUERIES} property. 278 */ 279 ResourceList<CqQuery> getPersonalQueries() throws WvcmException; 280 281 /** 282 * The queries (no charts or reports) defined in the public folder of this 283 * database 284 */ 285 PropertyName<ResourceList<CqQuery>> PUBLIC_QUERIES = 286 new PropertyName<ResourceList<CqQuery>>(PROPERTY_NAMESPACE, 287 "public-queries"); 288 289 /** 290 * Returns the value of the {@link #PUBLIC_QUERIES PUBLIC_QUERIES} property 291 * as defined by this proxy. 292 * 293 * @return A ResourceList of CqQuery proxies containing all of the public 294 * queries (no charts or reports) defined in this user database. 295 * 296 * @throws WvcmException if this proxy does not define a value for the 297 * {@link #PUBLIC_QUERIES PUBLIC_QUERIES} property. 298 */ 299 ResourceList<CqQuery> getPublicQueries() throws WvcmException; 300 301 /** 302 * All chart queries defined in this database and accessible to the current 303 * user. 304 */ 305 PropertyName<ResourceList<CqQuery>> ALL_CHARTS = 306 new PropertyName<ResourceList<CqQuery>>(PROPERTY_NAMESPACE, 307 "all-charts"); 308 309 /** 310 * Returns the value of the {@link #ALL_CHARTS ALL_CHARTS} property as 311 * defined by this proxy. 312 * 313 * @return A ResourceList of CqQuery proxies containing all of the chart 314 * queries accessible to the current user. 315 * 316 * @throws WvcmException if this proxy does not define a value for the 317 * {@link #ALL_CHARTS ALL_CHARTS} property. 318 */ 319 ResourceList<CqQuery> getAllCharts() throws WvcmException; 320 321 /** All chart queries owned by the current user. */ 322 PropertyName<ResourceList<CqQuery>> PERSONAL_CHARTS = 323 new PropertyName<ResourceList<CqQuery>>(PROPERTY_NAMESPACE, 324 "personal-charts"); 325 326 /** 327 * Returns the value of the {@link #PERSONAL_CHARTS PERSONAL_CHARTS} 328 * property as defined by this proxy. 329 * 330 * @return A ResourceList containing a CqQuery proxy for each chart query 331 * owned by the current user. 332 * 333 * @throws WvcmException if this proxy does not define a value for the 334 * {@link #PERSONAL_CHARTS PERSONAL_CHARTS} property. 335 */ 336 ResourceList<CqQuery> getPersonalCharts() throws WvcmException; 337 338 /** The chart queries defined in this database */ 339 PropertyName<ResourceList<CqQuery>> PUBLIC_CHARTS = 340 new PropertyName<ResourceList<CqQuery>>(PROPERTY_NAMESPACE, 341 "public-charts"); 342 343 /** 344 * Returns the value of the {@link #PUBLIC_CHARTS PUBLIC_CHARTS} property as 345 * defined by this proxy. 346 * 347 * @return A ResourceList containing a CqQuery proxy for each chart query in 348 * this user database. 349 * 350 * @throws WvcmException if this proxy does not define a value for the 351 * {@link #PUBLIC_CHARTS PUBLIC_CHARTS} property. 352 */ 353 ResourceList<CqQuery> getPublicCharts() throws WvcmException; 354 355 /** 356 * All report queries defined in this database and accessible to the current 357 * user. 358 */ 359 PropertyName<ResourceList<CqReport>> ALL_REPORTS = 360 new PropertyName<ResourceList<CqReport>>(PROPERTY_NAMESPACE, 361 "all-reports"); 362 363 /** 364 * Returns the value of the {@link #ALL_REPORTS ALL_REPORTS} property as 365 * defined by this proxy. 366 * 367 * @return A ResourceList containing a CqQuery proxy for each public report 368 * query and each report query owned by the current user. 369 * 370 * @throws WvcmException if this proxy does not define a value for the 371 * {@link #ALL_REPORTS ALL_REPORTS} property. 372 */ 373 ResourceList<CqReport> getAllReports() throws WvcmException; 374 375 /** All report queries owned by the current user. */ 376 PropertyName<ResourceList<CqReport>> PERSONAL_REPORTS = 377 new PropertyName<ResourceList<CqReport>>(PROPERTY_NAMESPACE, 378 "personal-reports"); 379 380 /** 381 * Returns the value of the {@link #PERSONAL_REPORTS PERSONAL_REPORTS} 382 * property as defined by this proxy. 383 * 384 * @return A ResourceList containing a CqQuery proxy for each report query 385 * owned by the current user. 386 * 387 * @throws WvcmException if this proxy does not define a value for the 388 * {@link #PERSONAL_REPORTS PERSONAL_REPORTS} property. 389 */ 390 ResourceList<CqReport> getPersonalReports() throws WvcmException; 391 392 /** 393 * All reports defined in this database that are accessible to the current 394 * user 395 */ 396 PropertyName<ResourceList<CqReport>> PUBLIC_REPORTS = 397 new PropertyName<ResourceList<CqReport>>(PROPERTY_NAMESPACE, 398 "public-reports"); 399 400 /** 401 * Returns the value of the {@link #PUBLIC_REPORTS PUBLIC_REPORTS} property 402 * as defined by this proxy. 403 * 404 * @return A ResourceList containing a CqQuery proxy for each report query 405 * accessible to the current user. 406 * 407 * @throws WvcmException if this proxy does not define a value for the 408 * {@link #PUBLIC_REPORTS PUBLIC_REPORTS} property. 409 */ 410 ResourceList<CqReport> getPublicReports() throws WvcmException; 411 412 /** The database set that contains this user database */ 413 PropertyName<CqDbSet> DB_SET = 414 new PropertyName<CqDbSet>(PROPERTY_NAMESPACE, "db-set"); 415 416 /** 417 * Returns the value of the {@link #DB_SET DB_SET} property as defined by 418 * this proxy. 419 * 420 * @return A CqDbSet proxy representing the database set that contains this 421 * user database. 422 * 423 * @throws WvcmException if this proxy does not define a value for the 424 * {@link #DB_SET DB_SET} property. 425 */ 426 CqDbSet getDbSet() throws WvcmException; 427 428 /** 429 * The interval at which to check for user timeouts. 430 * 431 * <p> 432 * ClearQuest uses this property to determine how often it should check the 433 * status of user connections. When the specified interval lapses, 434 * ClearQuest checks each user connection for activity. If no activity has 435 * been detected recently, ClearQuest checks the TimeoutInterval property to 436 * see if the user's connection has timed out. 437 */ 438 PropertyName<Long> CHECK_TIMEOUT_INTERVAL = 439 new PropertyName<Long>(PROPERTY_NAMESPACE, "check-timeout-interval"); 440 441 /** 442 * Returns the value of the {@link #CHECK_TIMEOUT_INTERVAL CHECK_TIME 443 * OUT_INTERVAL} property as defined by this proxy. 444 * 445 * @return A long value representing the CHECK_TIMEOUT_INTERVAL in 446 * milliseconds 447 * 448 * @throws WvcmException if this proxy does not define a value for the 449 * {@link #CHECK_TIMEOUT_INTERVAL CHECK_TIMEOUT_INTERVAL} 450 * property. 451 */ 452 long getCheckTimeoutInterval() throws WvcmException; 453 454 /** 455 * The name by which the database vendor installation knows this user 456 * database. 457 */ 458 PropertyName<String> DATABASE_NAME = 459 new PropertyName<String>(PROPERTY_NAMESPACE, "database-name"); 460 461 /** 462 * Returns the value of the {@link #DATABASE_NAME DATABASE_NAME} property as 463 * defined by this proxy. 464 * 465 * @return A String containing the name by which the database vendor 466 * installation knows this user database. 467 * 468 * @throws WvcmException if this proxy does not define a value for the 469 * {@link #DATABASE_NAME DATABASE_NAME} property. 470 */ 471 String getDatabaseName() throws WvcmException; 472 473 /** A list of the dynamic choice lists that are defined in this database */ 474 PropertyName<ResourceList<CqDynamicChoiceList>> DYNAMIC_CHOICE_LISTS = 475 new PropertyName<ResourceList<CqDynamicChoiceList>>(PROPERTY_NAMESPACE, 476 "dynamic-choice-lists"); 477 478 /** 479 * Returns the value of the {@link #DYNAMIC_CHOICE_LISTS} property as 480 * defined by this proxy. 481 * 482 * @return A ResourceList containing a CqDynamicChoiceList proxy for each 483 * dynamic choice list defined in this database. Will never be 484 * <b>null</b>, but may be empty. 485 * 486 * @throws WvcmException if this proxy does not define a value for the 487 * {@link #DYNAMIC_CHOICE_LISTS} property. 488 */ 489 ResourceList<CqDynamicChoiceList> getDynamicChoiceLists() 490 throws WvcmException; 491 492 /** 493 * The logical database name. The name to use in an StpLocation to identify 494 * this database; same as DISPLAY_NAME. 495 */ 496 PropertyName<String> NAME = 497 new PropertyName<String>(PROPERTY_NAMESPACE, "name"); 498 499 /** 500 * Returns the value of the {@link #NAME NAME} property as defined by this 501 * proxy. 502 * 503 * @return A String containing the logical name of this database. 504 * 505 * @throws WvcmException if this proxy does not define a value for the 506 * {@link #NAME NAME} property. 507 */ 508 String getName() throws WvcmException; 509 510 /** 511 * The schema revision currently in use by the database. 512 * <p> 513 * This is a read-only property; it can be viewed but not set. 514 * <p> 515 * To change the schema revision of an existing database, you must upgrade 516 * the database by calling the Upgrade method. If you are creating a new 517 * database, you can set its initial schema revision using the 518 * SetInitialSchemaRev method. 519 */ 520 PropertyName<Long> SCHEMA_REV = 521 new PropertyName<Long>(PROPERTY_NAMESPACE, "schema-rev"); 522 523 /** 524 * Returns the value of the {@link #SCHEMA_REV SCHEMA_REV} property as 525 * defined by this proxy. 526 * 527 * @return A Long containing the schema revision number. 528 * 529 * @throws WvcmException if this proxy does not define a value for the 530 * {@link #SCHEMA_REV SCHEMA_REV} property. 531 */ 532 long getSchemaRev() throws WvcmException; 533 534 /** The name of the server on which this database resides. */ 535 PropertyName<String> SERVER = 536 new PropertyName<String>(PROPERTY_NAMESPACE, "server"); 537 538 /** 539 * Returns the value of the {@link #SERVER SERVER} property as defined by 540 * this proxy. 541 * 542 * @return A String containing the name of the server on which this database 543 * is installed. 544 * 545 * @throws WvcmException if this proxy does not define a value for the 546 * {@link #SERVER SERVER} property. 547 */ 548 String getServer() throws WvcmException; 549 550 /** 551 * The login timeout interval. 552 * 553 * <p> 554 * ClearQuest periodically checks user connections and disconnects users who 555 * have been idle for too long. If a user has been idle for a period of time 556 * greater than the value in this property, ClearQuest disconnects the 557 * user's session at the next tick of the CHECK_TIMEOUT_INTERVAL. 558 */ 559 PropertyName<Long> TIMEOUT_INTERVAL = 560 new PropertyName<Long>(PROPERTY_NAMESPACE, "timeout-interval"); 561 562 /** 563 * Returns the value of the {@link #TIMEOUT_INTERVAL TIMEOUT_INTERVAL} 564 * property as defined by this proxy. 565 * 566 * @return An integer indicating the TIMEOUT_INTERVAL in milliseconds 567 * 568 * @throws WvcmException if this proxy does not define a value for the 569 * {@link #TIMEOUT_INTERVAL TIMEOUT_INTERVAL} property. 570 */ 571 long getTimeoutInterval() throws WvcmException; 572 573 /** the vendor type of the database */ 574 PropertyName<VendorType> VENDOR = 575 new PropertyName<VendorType>(PROPERTY_NAMESPACE, "vendor"); 576 577 /** 578 * An enumeration of the types of vendors of supported databases 579 */ 580 enum VendorType implements StpExEnumeration 581 { 582 /** The VendorType for an SQL Server database */ 583 SQL_SERVER, 584 585 /** The VendorType for an Microsoft Access database */ 586 MS_ACCESS, 587 588 /** The VendorType for an SQL Anywhere database */ 589 SQL_ANYWHERE, 590 591 /** The VendorType for an Oracle database */ 592 ORACLE, 593 594 /** The VendorType for a DB2 database */ 595 DB2; 596 } 597 598 /** 599 * Returns the value of the {@link #VENDOR VENDOR} property as defined by 600 * this proxy. 601 * 602 * @return A VendorType enumerator indicating vendor of the physical 603 * database. 604 * 605 * @throws WvcmException if this proxy does not define a value for the 606 * {@link #VENDOR VENDOR} property. 607 */ 608 VendorType getVendor() throws WvcmException; 609 610 /** The connection options for the physical database. */ 611 PropertyName<String> CONNECT_OPTIONS = 612 new PropertyName<String>(PROPERTY_NAMESPACE, "connect-options"); 613 614 /** 615 * Returns the value of the {@link #CONNECT_OPTIONS CONNECT_OPTIONS} 616 * property as defined by this proxy. 617 * 618 * @return A String containing the vendors connection options. 619 * 620 * @throws WvcmException if this proxy does not define a value for the 621 * {@link #CONNECT_OPTIONS CONNECT_OPTIONS} property. 622 */ 623 String getConnectOptions() throws WvcmException; 624 625 /** 626 * Implements CQSession.GetSessionFeatureLevel 627 */ 628 PropertyName<Long> FEATURE_LEVEL = 629 new PropertyName<Long>(PROPERTY_NAMESPACE, "feature-level"); 630 631 /** 632 * Returns the value of the {@link #FEATURE_LEVEL FEATURE_LEVEL} property as 633 * defined by this proxy. 634 * 635 * @return The value. Will never be <b>null</b>. 636 * 637 * @throws WvcmException if this proxy does not define a value for the 638 * {@link #FEATURE_LEVEL FEATURE_LEVEL} property. 639 */ 640 long getFeatureLevel() throws WvcmException; 641 642 /** 643 * Answers whether or not the current user has logged in as a restricted 644 * user 645 */ 646 PropertyName<Boolean> IS_RESTRICTED_USER = 647 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-restricted-user"); 648 649 /** 650 * Returns the value of the {@link #IS_RESTRICTED_USER IS_RESTRICTED_USER} 651 * property as defined by this proxy. 652 * 653 * @return <b>true</b> if the current user logged in as a restricted user; 654 * <b>false</b> otherwise;. 655 * 656 * @throws WvcmException if this proxy does not define a value for the 657 * {@link #IS_RESTRICTED_USER IS_RESTRICTED_USER} property. 658 */ 659 boolean getIsRestrictedUser() throws WvcmException; 660 661 /** 662 * Answers whether or not the database has been activated for multisite 663 * operations (even if the database is the only existing replica). 664 */ 665 PropertyName<Boolean> IS_MULTISITE_ACTIVATED = 666 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-multisite-activated"); 667 668 /** 669 * Returns the value of the 670 * {@link #IS_MULTISITE_ACTIVATED IS_MULTISITE_ACTIVATED} property as 671 * defined by this proxy. 672 * 673 * @return <b>true</b> if the database has been activated for multisite 674 * operations, even if the database is the only existing replica; 675 * <b>false</b> if not activated. 676 * 677 * @throws WvcmException if this proxy does not define a value for the 678 * {@link #IS_MULTISITE_ACTIVATED IS_MULTISITE_ACTIVATED} 679 * property. 680 */ 681 boolean getIsMultisiteActivated() throws WvcmException; 682 683 /** 684 * The highest feature level supported by the server. 685 */ 686 PropertyName<Long> MAX_COMPATIBLE_FEATURE_LEVEL = 687 new PropertyName<Long>(PROPERTY_NAMESPACE, 688 "max-compatible-feature-level"); 689 690 /** 691 * Returns the value of the 692 * {@link #MAX_COMPATIBLE_FEATURE_LEVEL MAX_COMPATIBLE_FEATURE_LEVEL} 693 * property as defined by this proxy. 694 * 695 * @return A long value designating the highest feature level supported by 696 * the server. 697 * 698 * @throws WvcmException if this proxy does not define a value for the 699 * {@link #MAX_COMPATIBLE_FEATURE_LEVEL MAX_COMPATIBLE_FEATURE_LEVEL} 700 * property. 701 */ 702 long getMaxCompatibleFeatureLevel() throws WvcmException; 703 704 /** 705 * The lowest feature level supported by the server 706 */ 707 PropertyName<Long> MIN_COMPATIBLE_FEATURE_LEVEL = 708 new PropertyName<Long>(PROPERTY_NAMESPACE, 709 "min-compatible-feature-level"); 710 711 /** 712 * Returns the value of the 713 * {@link #MIN_COMPATIBLE_FEATURE_LEVEL MIN_COMPATIBLE_FEATURE_LEVEL} 714 * property as defined by this proxy. 715 * 716 * @return A long value designating the lowest feature level supported by 717 * the server. 718 * 719 * @throws WvcmException if this proxy does not define a value for the 720 * {@link #MIN_COMPATIBLE_FEATURE_LEVEL MIN_COMPATIBLE_FEATURE_LEVEL} 721 * property. 722 */ 723 long getMinCompatibleFeatureLevel() throws WvcmException; 724 725 /** 726 * An extension of the standard PropertyName that may be used by clients to 727 * access named values on the ClearQuest server as CM API properties of this 728 * database. 729 */ 730 public class NamedValueName extends PropertyName<String> 731 { 732 /** 733 * Constructs a PropertyName that denotes the name component of a 734 * ClearQuest session name/value pair. A PropertyRequest with an 735 * instance of this class requests the value associated with the given 736 * name from ClearQuest. Writing a value to the server using an instance 737 * of this PropertyName will cause the value to be associated with the 738 * name during this session. The value is always a String and is 739 * accessible only to this proxy's CqProvider or to hooks fired by this 740 * proxy's CqProvider. 741 * 742 * @param name The name that is to be associated with a value in the 743 * ClearQuest session. 744 */ 745 public NamedValueName(String name) 746 { 747 super(StpExBase.NAMED_VALUE_NAMESPACE, name); 748 } 749 } 750 751 /** 752 * Retrieves the value of a previously requested property named by an 753 * instance of NamedValueName having the same parameters as this method. 754 * This is just shorthand for 755 * <code>getProperty(new NamedValueName(name))</code> 756 * 757 * @param name The name for which a value was requested. 758 * @return A String containing the value of the NameValue property 759 * @throws WvcmException If the NameValue for the given name was not 760 * requested or otherwise not available. 761 */ 762 String getNamedValue(String name) throws WvcmException; 763 764 /** 765 * A defines a new value for a NamedValue property of a given name. The 766 * property is not updated until the next "do" operations is invoked. 767 * Shorthand for <code>setProperty(new NamedValueName(name), value)</code> 768 * 769 * @param name The name of the NamedValue whose value is to be set. 770 * @param value The new value for the NameValue property identified by the 771 * name parameter. 772 */ 773 void setNamedValue(String name, 774 String value); 775 776 /** 777 * A list of all the name/value properties defined for this database 778 * session. This is a pseudo property, similar in concept to 779 * {@link javax.wvcm.Resource#ALL_CUSTOM_PROPERTIES}. When it appears in a 780 * PropertyRequest, the server replies by populating the result proxy with 781 * all named values defined for the database session. The value associated 782 * with a given name can then be retrieved from the proxy using a 783 * NamedValueName for the name. All of the returned named value properties 784 * can be retrieved as an StpProperty.List using the getAllNameValues method 785 * of this resource. 786 */ 787 PropertyName<StpProperty.List<StpProperty<String>>> ALL_NAMED_VALUES = 788 new PropertyName<StpProperty.List<StpProperty<String>>>(PROPERTY_NAMESPACE, 789 "all-named-values"); 790 791 /** 792 * Returns the value of the {@link #ALL_NAMED_VALUES ALL_NAMED_VALUES} 793 * property as defined by this proxy. 794 * 795 * @return A List of StpProperty<String> objects, each representing a 796 * named value defined for this database session. 797 * 798 * @throws WvcmException if this proxy does not define a value for the 799 * {@link #ALL_NAMED_VALUES ALL_NAMED_VALUES} property. 800 */ 801 StpProperty.List<StpProperty<String>> getAllNamedValues() 802 throws WvcmException; 803 804 /** 805 * Defines a new value for the {@link #ALL_NAMED_VALUES ALL_NAMED_VALUES} 806 * property of this proxy. 807 * 808 * @param allNameValues An StpProperty.List associating names to String 809 * values. The entries of this list <b>replace</b> the current 810 * entries in the name/value map accessible to scripts on the 811 * server. If this property is empty or <b>null</b>, the server 812 * map will be emptied. To update individual name/value 813 * associations, use setProperty with a NamedValueName and string 814 * value. 815 */ 816 void setAllNamedValues(StpProperty.List<StpProperty<String>> allNameValues); 817 818 /** 819 * The groups explicitly subscribed to this database. It does not include 820 * the groups implicitly subscribed to this database because their 821 * {@link CqGroup#IS_SUBSCRIBED_TO_ALL_DATABASES} property is <b>true</b>. 822 */ 823 PropertyName<ResourceList<CqGroup>> SUBSCRIBED_GROUPS = 824 new PropertyName<ResourceList<CqGroup>>(PROPERTY_NAMESPACE, 825 "subscribed-groups"); 826 827 /** 828 * Returns the value of the {@link #SUBSCRIBED_GROUPS SUBSCRIBED_GROUPS} 829 * property as defined by this proxy. 830 * 831 * @return A ResourceList containing a CqGroup proxy for each group 832 * explicitly subscribed to this user database. Will never be 833 * <b>null</b>. 834 * 835 * @throws WvcmException if this proxy does not define a value for the 836 * {@link #SUBSCRIBED_GROUPS SUBSCRIBED_GROUPS} property. 837 */ 838 ResourceList<CqGroup> getSubscribedGroups() throws WvcmException; 839 840 /** 841 * The users explicitly subscribed to this database. It does not include the 842 * users implicitly subscribed to this database because their 843 * {@link CqUser#IS_SUBSCRIBED_TO_ALL_DATABASES} property is <b>true</b>. 844 */ 845 PropertyName<ResourceList<CqUser>> SUBSCRIBED_USERS = 846 new PropertyName<ResourceList<CqUser>>(PROPERTY_NAMESPACE, 847 "subscribed-users"); 848 849 /** 850 * Returns the value of the {@link #SUBSCRIBED_USERS SUBSCRIBED_USERS} 851 * property as defined by this proxy. 852 * 853 * @return A ResourceList containing a CqUser proxy for each group 854 * explicitly subscribed to this user database. Will never be 855 * <b>null</b>. 856 * 857 * @throws WvcmException if this proxy does not define a value for the 858 * {@link #SUBSCRIBED_USERS SUBSCRIBED_USERS} property. 859 */ 860 ResourceList<CqUser> getSubscribedUsers() throws WvcmException; 861 862 /** 863 * Answers whether or not the package supporting the integration of 864 * ClearQuest and ReqiuisitePro has been enabled for this user database 865 */ 866 static PropertyName<Boolean> IS_REQUISITE_PRO_ENABLED = 867 new PropertyName<Boolean>(PROPERTY_NAMESPACE, 868 "is-requisite-pro-enabled"); 869 870 /** 871 * Returns the value of the 872 * {@link #IS_REQUISITE_PRO_ENABLED IS_REQUISITE_PRO_ENABLED} property as 873 * defined by this proxy. 874 * 875 * @return <b>true</b> if the RequisitePro package has been enabled on this 876 * database; <b>false</b> otherwise. 877 * 878 * @throws WvcmException if this proxy does not define a value for the 879 * {@link #IS_REQUISITE_PRO_ENABLED IS_REQUISITE_PRO_ENABLED} 880 * property. 881 */ 882 boolean getIsRequisiteProEnabled() throws WvcmException; 883 884 /** 885 * Answers whether or not full-text search has been enabled for this user 886 * database. 887 */ 888 static PropertyName<Boolean> IS_FULL_TEXT_SEARCH_ENABLED = 889 new PropertyName<Boolean>(PROPERTY_NAMESPACE, 890 "is-full-text-search-enabled"); 891 892 /** 893 * Returns the value of the 894 * {@link #IS_FULL_TEXT_SEARCH_ENABLED IS_FULL_TEXT_SEARCH_ENABLED} property 895 * as defined by this proxy. 896 * 897 * @return <b>true</b> if full-text search has been enabled on this 898 * database; <b>false</b> otherwise. 899 * 900 * @throws WvcmException if this proxy does not define a value for the 901 * {@link #IS_FULL_TEXT_SEARCH_ENABLED IS_FULL_TEXT_SEARCH_ENABLED} 902 * property. 903 */ 904 boolean getIsFullTextSearchEnabled() throws WvcmException; 905 906 907 /** 908 * Answers whether or not this database, using the CqProvider of this proxy, 909 * provides support for privileged queries. 910 */ 911 static PropertyName<Boolean> IS_PRIVILEGED_QUERY_ENABLED = 912 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-privileged-query-enabled"); 913 914 /** 915 * Returns the value of the 916 * {@link #IS_PRIVILEGED_QUERY_ENABLED IS_PRIVILEGED_QUERY_ENABLED} property 917 * as defined by this proxy. 918 * 919 * @return <b>true</b> if full-text search has been enabled on this 920 * database; <b>false</b> otherwise. 921 * 922 * @throws WvcmException if this proxy does not define a value for the 923 * {@link #IS_PRIVILEGED_QUERY_ENABLED IS_PRIVILEGED_QUERY_ENABLED} 924 * property. 925 */ 926 boolean getIsPrivilegedQueryEnabled() throws WvcmException; 927 928 /** 929 * Answers whether or not this database, using the CqProvider of this proxy, 930 * provides support for reports, including access to CqReport and 931 * CqReportFormat resources and the generation of reports via 932 * CqReport.doMakeReport(). 933 */ 934 static PropertyName<Boolean> IS_REPORTING_ENABLED = 935 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-reporting-enabled"); 936 937 /** 938 * Returns the value of the 939 * {@link #IS_REPORTING_ENABLED IS_REPORTING_ENABLED} property as defined by 940 * this proxy. 941 * 942 * @return <b>true</b> if CqReport and CqReportFormat resources are 943 * supported by this database through this proxy's CqProvider; 944 * <b>false</b> otherwise. 945 * 946 * @throws WvcmException 947 * if this proxy does not define a value for the 948 * {@link #IS_REPORTING_ENABLED IS_REPORTING_ENABLED} property. 949 */ 950 boolean getIsReportingEnabled() throws WvcmException; 951 952 /** 953 * Answers whether or not this database, using the CqProvider of this proxy, 954 * provides support for the generation of charts via CqQuery.doMakeChart(). 955 */ 956 static PropertyName<Boolean> IS_CHARTING_ENABLED = 957 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-charting-enabled"); 958 959 /** 960 * Returns the value of the {@link #IS_CHARTING_ENABLED IS_CHARTING_ENABLED} 961 * property as defined by this proxy. 962 * 963 * @return <b>true</b> if charting is supported by this database through 964 * this proxy's CqProvider; <b>false</b> otherwise. 965 * 966 * @throws WvcmException 967 * if this proxy does not define a value for the 968 * {@link #IS_CHARTING_ENABLED IS_CHARTING_ENABLED} property. 969 */ 970 boolean getIsChartingEnabled() throws WvcmException; 971 972 /** 973 * Answers whether or not this is a test database 974 */ 975 static PropertyName<Boolean> IS_TEST_DATABASE = 976 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-test-database"); 977 978 /** 979 * Returns the value of the {@link #IS_TEST_DATABASE IS_TEST_DATABASE} 980 * property as defined by this proxy. 981 * 982 * @return <b>true</b> if this user database has been designated a test 983 * database; <b>false</b> otherwise. 984 * 985 * @throws WvcmException if this proxy does not define a value for the 986 * {@link #IS_TEST_DATABASE IS_TEST_DATABASE} 987 * property. 988 */ 989 boolean getIsTestDatabase() throws WvcmException; 990 991 /** 992 * A list of the record types that are being indexed for full-text searches. 993 */ 994 static PropertyName<ResourceList<CqRecordType>> INDEXED_RECORD_TYPES = 995 new PropertyName<ResourceList<CqRecordType>>(PROPERTY_NAMESPACE, 996 "indexed-record-types"); 997 998 /** 999 * Returns the value of the 1000 * {@link #INDEXED_RECORD_TYPES INDEXED_RECORD_TYPES} property as defined by 1001 * this proxy. 1002 * 1003 * @return A ResourceList containing a CqRecordType proxy for any record 1004 * type that is being indexed for use in full-text searches. 1005 * 1006 * @throws WvcmException if this proxy does not define a value for the 1007 * {@link #INDEXED_RECORD_TYPES INDEXED_RECORD_TYPES} property. 1008 */ 1009 ResourceList<CqRecordType> getIndexedRecordTypes() throws WvcmException; 1010 1011 /** 1012 * A list of all report formats defined in this database and accessible to 1013 * the current user. 1014 */ 1015 PropertyName<ResourceList<CqReportFormat>> REPORT_FORMATS = 1016 new PropertyName<ResourceList<CqReportFormat>>(PROPERTY_NAMESPACE, 1017 "report-formats"); 1018 1019 /** 1020 * A list of the record types that are OSLCLinks package enabled. 1021 */ 1022 static PropertyName<ResourceList<CqRecordType>> OSLCLINKS_ENABLED_RECORD_TYPES = 1023 new PropertyName<ResourceList<CqRecordType>>(PROPERTY_NAMESPACE, 1024 "oslclinks-enabled-record-types"); 1025 1026 /** 1027 * Returns the value of the 1028 * {@link #OSLCLINKS_ENABLED_RECORD_TYPES OSLCLINKS_ENABLED_RECORD_TYPES} property as 1029 * defined by this proxy. 1030 * 1031 * @return A ResourceList containing a CqRecordType proxy for any record 1032 * type that is OSLCLinks package enabled 1033 * 1034 * @throws WvcmException if this proxy does not define a value for the 1035 * {@link #OSLCLINKS_ENABLED_RECORD_TYPES OSLCLINKS_ENABLED_RECORD_TYPES} 1036 * property. 1037 */ 1038 ResourceList<CqRecordType> getOslclinksEnabledRecordTypes() throws WvcmException; 1039 1040 /** 1041 * Returns the value of the {@link #REPORT_FORMATS REPORT_FORMATS} property 1042 * as defined by this proxy. 1043 * 1044 * @return A ResourceList containing a CqReportFormat proxy for each report 1045 * format defined in the public and personal query folders . Will 1046 * never be <b>null</b>. 1047 * 1048 * @throws WvcmException if this proxy does not define a value for the 1049 * {@link #REPORT_FORMATS REPORT_FORMATS} property. 1050 */ 1051 ResourceList<CqReportFormat> getReportFormats() throws WvcmException; 1052 1053 /** 1054 * Returns a CqUserInfo structure containing read-only information about the 1055 * user currently logged into this database. 1056 */ 1057 PropertyName<CqUserInfo> USER_INFO = 1058 new PropertyName<CqUserInfo>(PROPERTY_NAMESPACE, "user-info"); 1059 1060 /** 1061 * Returns the value of the {@link #USER_INFO USER_INFO} property as defined 1062 * by this proxy. 1063 * 1064 * @return A CqUserInfo instance containing read-only information about the 1065 * user currently logged into this database. Will never be <b>null</b>. 1066 * 1067 * @throws WvcmException if this proxy does not define a value for the 1068 * {@link #USER_INFO USER_INFO} property. 1069 */ 1070 CqUserInfo getUserInfo() throws WvcmException; 1071 1072 /** 1073 * Returns the value of the {@link #USER_INFO USER_INFO} property as defined 1074 * by this proxy. 1075 * 1076 * @return A CqDb instance (which is a CqUserInfo) containing information about the 1077 * user currently logged into this database. Will never be <b>null</b>. 1078 * 1079 * @throws WvcmException if this proxy does not define a value for the 1080 * {@link #USER_INFO USER_INFO} property. 1081 */ 1082 CqDb getCqDb() throws WvcmException; 1083 1084 /** 1085 * Removes all modified and moribund resources from the change context of 1086 * this database; thereby reverting those resources to their previous, 1087 * unmodified or undeleted state. 1088 * 1089 * @param feedback A Feedback object requesting properties of this database 1090 * and/or properties of the reverted resources to be returned 1091 * from the server after successful completion of the operation. 1092 * 1093 * @throws WvcmException If the resources cannot be reverted. 1094 */ 1095 CqUserDb doClearContext(Feedback feedback) throws WvcmException; 1096 1097 /** 1098 * Selectively delivers (commits) modified resources to the database and/or 1099 * destroys moribund resources from the database and removes them from the 1100 * change context. 1101 * <p> 1102 * NOTE: A ClearQuest query created and delivered in one CqProvider instance 1103 * may not appear in another already-existing CqProvider instance. To make 1104 * them available, create a new CqProvider instance <b>after</b> the 1105 * delivery is complete. 1106 * <p> 1107 * Known places in the implementation that will have this problem include:<br> 1108 * Creation or deletion of a ClearQuest query (modification is OK).<br> 1109 * Creation or deletion of a ClearQuest CqQueryFolder.<br> 1110 * Modification of a ClearQuest CqDynamicChoiceList (creation is not 1111 * supported anyway). 1112 * 1113 * @param feedback A request for specific properties from the resources that 1114 * were directly or indirectly impacted by this operation, which, 1115 * in this case would be the modified resources that were 1116 * delivered by this operation. May be <b>null</b>; in which 1117 * case this information will not be requested from the server. 1118 * @param deliveryOrder The modified and moribund resources currently in 1119 * this change context that are to be delivered or deleted. They 1120 * will be delivered or deleted in the order specified by the 1121 * proxies in the given list. To deliver/delete all 1122 * modified/moribund resources in an arbitrary order, use 1123 * {@link CqProvider#DELIVER_ALL}. Must not be <b>null</b> nor 1124 * any of the other special delivery order constants AUTO, HOLD, 1125 * or DELIVER. 1126 * 1127 * @throws WvcmException if any preconditions are not satisfied or if other 1128 * errors are detected while writing the records to the 1129 * database. 1130 */ 1131 1132 CqUserDb doDeliver(Feedback feedback, 1133 List<CqContextResource> deliveryOrder) 1134 throws WvcmException; 1135 1136 /** 1137 * Selectively reverts modified or moribund resources in this database's 1138 * change context to their previous, unmodified/undeleted state. To revert 1139 * all resources in the change context, in an arbitrary order, use 1140 * {@link #doClearContext(Feedback)}. This operation is semantically 1141 * equivalent to invoking doRevert() on each resource in the given list, but 1142 * will be more efficient because there is only one round-trip to the server 1143 * required. 1144 * <p> 1145 * Note that doRevert removes all changes to the resource from the change 1146 * context. It is not an undo operation, but a revert. If multiple changes 1147 * have been made to a resource (since the last time it was delivered) they 1148 * will all be discarded by doRevert. 1149 * 1150 * @param feedback A request for specific properties from the resources that 1151 * were directly or indirectly impacted by this operation, which, 1152 * in this case would be the modified/moribund resources that 1153 * were reverted by this operation. May be <b>null</b>; in which 1154 * case this information will not be requested from the server. 1155 * @param revertOrder The modified/moribund resources currently in this 1156 * change context to be reverted to their original state. They 1157 * will be reverted/undeleted in the order specified by the 1158 * proxies in this argument. Must not be <b>null</b> nor any of 1159 * the special delivery order constants AUTO, HOLD, DELIVER, or 1160 * DELIVER_ALL. 1161 * 1162 * @throws WvcmException if any preconditions are not satisfied or if other 1163 * errors are detected while writing the records to the 1164 * database. 1165 */ 1166 1167 CqUserDb doRevert(Feedback feedback, 1168 List<CqContextResource> revertOrder) throws WvcmException; 1169 1170 /** 1171 * Searches the database for records having a given display name. 1172 * 1173 * @param displayName A String containing the display name of the record to 1174 * be found. 1175 * 1176 * @param possibleRecordTypes An array of locations containing a 1177 * CqRecordType location for each type of record to be considered 1178 * in the search. May not contain record type family names. May 1179 * be <b>null</b> or empty to force consideration of all record 1180 * types. 1181 * <p> 1182 * The record type array is used to control the search for the 1183 * record identified by the displayName argument. This list of 1184 * record types is iterated and processed in the order given 1185 * until a record is found. If any of the record type locations 1186 * provided in this argument is invalid (such as referring to a 1187 * record type family), an exception is thrown that identifies 1188 * the invalid location. If a null or empty array value is 1189 * provided, all record types defined in the schema are searched, 1190 * with the search order being from the most frequently found 1191 * record type searched first to the least found record type 1192 * being searched last. 1193 * 1194 * @param mode A FindMode enumerator identifying the type of record to 1195 * search for. 1196 * 1197 * @param feedback A Feedback object in which may be requested search 1198 * progress reports and additional properties to be included in 1199 * the result proxy. May be <b>null</b> if no additional 1200 * feedback is needed. 1201 * 1202 * @return A CqRecord proxy representing a record of one of the requested 1203 * types or type categories whose display name matches the given 1204 * displayName argument; <b>null</b> if no such record can be 1205 * found. If a record is found, the returned proxy will be populated 1206 * with the properties requested by the feedback parameter. 1207 * 1208 * @throws WvcmException If the search as specified could not be completed; 1209 * for example, if the database or the specified record types 1210 * are not accessible. If all record types can be searched as 1211 * specified, failure to find a matching record <i>does not</i> 1212 * cause an exception but results in a null result. 1213 */ 1214 CqRecord doFindRecord(String displayName, 1215 FindMode mode, 1216 Feedback feedback, 1217 Location... possibleRecordTypes) throws WvcmException; 1218 1219 /** 1220 * Searches the database for records having a given dbid. 1221 * 1222 * @param dbid The dbid of the record to be found. 1223 * 1224 * @param mode A FindMode enumerator identifying the type of record to 1225 * search for. 1226 * 1227 * @param possibleRecordTypes An array of locations containing a 1228 * CqRecordType location for each type of record to be considered 1229 * in the search. May not contain record type family names. May 1230 * be <b>null</b> or empty to force consideration of all record 1231 * types. 1232 * <p> 1233 * The record type array is used to control the search for the 1234 * record identified by the displayName argument. This list of 1235 * record types is iterated and processed in the order given 1236 * until a record is found. If any of the record type locations 1237 * provided in this argument is invalid (such as referring to a 1238 * record type family), an exception is thrown that identifies 1239 * the invalid location. If a null or empty array value is 1240 * provided, all record types defined in the schema are searched, 1241 * with the search order being from the most frequently found 1242 * record type searched first to the least found record type 1243 * being searched last. 1244 * 1245 * @param feedback A Feedback object in which may be requested search 1246 * progress reports and additional properties to be included in 1247 * the result proxy. May be <b>null</b> if no additional 1248 * feedback is needed. 1249 * 1250 * @return A CqRecord proxy representing a record of one of the requested 1251 * types or type categories whose dbid name matches the given 1252 * dbid argument; <b>null</b> if no such record can be 1253 * found. If a record is found, the returned proxy will be populated 1254 * with the properties requested by the feedback parameter. 1255 * 1256 * @throws WvcmException If the search as specified could not be completed; 1257 * for example, if the database or the specified record types 1258 * are not accessible. If all record types can be searched as 1259 * specified, failure to find a matching record <i>does not</i> 1260 * cause an exception but results in a null result. 1261 1262 * @see #doFindRecord(long, com.ibm.rational.wvcm.stp.cq.CqUserDb.FindMode, 1263 * Feedback, Location[]) 1264 */ 1265 CqRecord doFindRecord(long dbid, 1266 FindMode mode, 1267 Feedback feedback, 1268 Location... possibleRecordTypes) throws WvcmException; 1269 1270 /** 1271 * Enumerates the options for restricting the finding of records based on 1272 * their record class. 1273 */ 1274 enum FindMode implements StpExEnumeration 1275 { 1276 FIND_ANY_RECORD, FIND_STATELESS_RECORD, FIND_STATEFUL_RECORD; 1277 } 1278 1279 /** 1280 * Returns a list of all the resources in the database whose names differ 1281 * from a given name only in their site extensions. Currently, only query 1282 * folder items and records of a stateless record type could possibly need 1283 * site extensions to disambiguate them, so applying this method to any 1284 * other resource is simply a waste of time and is likely to raise an 1285 * exception. 1286 * <p> 1287 * Applying this method to a stateless record type location has a special 1288 * meaning. In that case <i>all</i> instances of that record type that 1289 * require site extension are returned. 1290 * 1291 * @param name A (potentially ambiguous) user-friendly location 1292 * specification for a ClearQuest record, record type, or query 1293 * folder item, whose repo field, if present, must name this 1294 * database. 1295 * 1296 * @param feedback A Feedback object in which may be requested search 1297 * progress reports and additional properties to be included in 1298 * the result proxies. May be <b>null</b> if no additional 1299 * feedback is needed. 1300 * 1301 * @return A ResourceList containing a proxy for each resource in the 1302 * database whose site-extended name differs from the given name 1303 * only in the site extensions used. Will never be <b>null</b> or 1304 * empty. 1305 * 1306 * @throws WvcmException If the database is not accessible, if the given 1307 * name identifies a resource other than a record or query 1308 * folder item in this database, or if the given name cannot be 1309 * extended in any way to name any resource. 1310 */ 1311 ResourceList<CqResource> doFindSiteExtendedNames(StpLocation name, 1312 Feedback feedback) 1313 throws WvcmException; 1314 1315 /** 1316 * Upgrades this database's user and group information to match that of its 1317 * db-set. This method copies the changes from the db-set to the user 1318 * database. You should call this function to upgrade a database after 1319 * making changes to the users and groups of the db-set. 1320 * 1321 * @param feedback Specifies optional feedback to the caller. 1322 * @return A proxy for this user database (after the upgrade is complete), 1323 * whose properties are specified by feedback. 1324 * @throws WvcmException 1325 */ 1326 CqUserDb doUpgradeUsersAndGroups(Feedback feedback) throws WvcmException; 1327 1328 /** 1329 * Verifies that a CqQueryFolderItem of a given type can be created at a 1330 * given location. The operation checks that the characters used in the 1331 * location are valid for the target database and that no resource currently 1332 * exists at the specified location. 1333 * 1334 * @param item A proxy for the item whose location is to be tested. 1335 * 1336 * @param feedback A Feedback object that specifies the properties to be 1337 * included in the result proxy (if a resource exists at the 1338 * specified location). If the argument is null, the properties 1339 * defined by the result proxy are unspecified. 1340 * 1341 * @return If the location is valid and there is no resource currently at 1342 * the specified location, the result is <b>null</b>. If the 1343 * location is valid, but a resource already exists at that 1344 * location, a proxy for that resource is returned, populated with 1345 * any properties requested by the feedback argument. 1346 * 1347 * @throws WvcmException if the location is not valid on the target 1348 * database. 1349 */ 1350 CqQueryFolderItem doValidateLocation(CqQueryFolderItem item, 1351 Feedback feedback) 1352 throws WvcmException; 1353 1354 /** 1355 * The interface for an API object that may be used to define a filter for a 1356 * full-text search of the database. The search key specifies an attribute 1357 * of the database object whose value will be used to select the object for 1358 * inclusion in the result set of the full-text search. In the SearchFilter, 1359 * each SearchKey is associated with a target value that specifies what 1360 * attribute values will cause the object to be selected. 1361 * <p> 1362 * The currently defined SearchKey types are 1363 * <ul> 1364 * <li>{@link SearchLevel}: (SearchKey<String>) selects an object 1365 * having any field matching the specification in the target String. The 1366 * SearchMode enumerator specifies the type of specification to be found in 1367 * the target string. Currently there is only one SearchMode, SIMPLE, which 1368 * represents a full-text search using a simple specification. 1369 * <li>{@link WordMode}: (SearchKey<List<String>>) selects an object 1370 * having any field matching the words in the target list. The WordMode 1371 * enumerator specifies how the target words must match a field to select 1372 * the object. 1373 * <li>{@link DateLimit}: (SearchKey<Date>) selects an object based on 1374 * the relationship between the object's creation or modification date and 1375 * the target date. The DateLimit enumerator specifies which date attribute 1376 * to compare against and the relationship with the target date that will 1377 * select the object. 1378 * <li>{@link CqRecordType}: (SearchKey<Boolean>) selects a record 1379 * based on its record type. If the target value is Boolean.TRUE, a record 1380 * whose record type is the same as the record type denoted by the 1381 * CqRecordType object will be selected. If several CqRecordType keys (with 1382 * TRUE target values) are present in a SearchFilter, a record having anyone 1383 * of those record types is selected. 1384 * <li>{@link CqFieldDefinition}: (SearchKey<List<String>>) selects 1385 * a record having a specific field whose value matches all of the target 1386 * strings. The CqFieldDefinition specifies the record type and the field of 1387 * that record type that must match the target strings. Each target string 1388 * is a simple search specification. 1389 * </ul> 1390 * 1391 * @param <T> The type of object used to specify the value or values that 1392 * will select or reject an object based on the value it has for 1393 * the key attribute. 1394 */ 1395 public static interface SearchKey<T> 1396 {} 1397 1398 /** 1399 * WordMode SearchKeys limit the search results to just those objects that 1400 * contain the targeted words associated with the WordMode key in the 1401 * filter. 1402 */ 1403 public static enum WordMode implements SearchKey<List<String>> 1404 { 1405 /** Match all of the words in the target list */ 1406 ALL, 1407 /** Match all of the words in the target list in the order given */ 1408 EXACT, 1409 /** Match any (at least one) of the words in the target list */ 1410 ANY, 1411 /** Match none (do not match any) of the words in the target list */ 1412 NONE 1413 } 1414 1415 /** 1416 * A DateLimit SearchKey limits the search to just those objects whose 1417 * creation or modification time are in a target range. 1418 */ 1419 public static enum DateLimit implements SearchKey<Date> 1420 { 1421 /** Matches an object created on or after the target date */ 1422 CREATED_AFTER, 1423 1424 /** Matches an object created on or before the target date */ 1425 CREATED_BEFORE, 1426 1427 /** Matches an object modified on or after the target date */ 1428 MODIFIED_AFTER, 1429 1430 /** Matches an object modified on or before the target date */ 1431 MODIFIED_BEFORE 1432 } 1433 1434 /** Specifies a simple search string */ 1435 public static enum SearchLevel implements SearchKey<String> 1436 { 1437 /** Interpret the associated argument as a simple search string and 1438 * match accordingly against that. 1439 */ 1440 SIMPLE 1441 } 1442 1443 /** 1444 * A collection of SearchKey/target-value pairs that collectively define the 1445 * filter for selecting objects for inclusion in a full-text search. In 1446 * general, an object must match all of the given keys in the filter to be 1447 * added to the result set. The only exception to this rule are the 1448 * CqRecordType keys. If more than one CqRecordType key is present, the 1449 * object needs only match one of them to be a candidate for the result 1450 * set--the object would need to match all the other types of keys to 1451 * actually be selected. 1452 */ 1453 public static interface SearchFilter 1454 { 1455 /** 1456 * Adds a SearchKey and its target value to the full text search filter. 1457 * Each SearchKey specifies what attribute of an object is to be 1458 * filtered on and the target value specifies the value against which 1459 * the attribute value will be compared for possible inclusion in the 1460 * result set. 1461 * 1462 * @param <U> The data type used to specify the target value. This type 1463 * must match the type parameter of the key used and so 1464 * currently this must be String, List<String>, Date, or 1465 * Boolean. 1466 * @param key A SearchKey<U> object representing the attribute of 1467 * each candidate object that the search should filter on. 1468 * Currently this may be a SearchLevel enumerator, a 1469 * DateLimit enumerator, a WordMode enumerator, a 1470 * CqRecordType proxy, or a CqFieldDefinition proxy. 1471 * @param targetValue An instance of class U that specifies which values 1472 * of the key attribute will select or reject a record in the 1473 * search. If this value is <b>null</b> (or Boolean.FALSE) 1474 * the corresponding SearchKey will be removed from the 1475 * search specification. 1476 * @return The value previously associated with the SearchKey. 1477 */ 1478 <U> U put(SearchKey<U> key, 1479 U targetValue); 1480 1481 /** 1482 * Extends the target value list associated with a SearchKey by a single 1483 * item. 1484 * 1485 * @param <U> The type of item in a target value list; currently must be 1486 * String. 1487 * @param key The SearchKey whose target value list is to be extended. 1488 * The SeachKey does not need to already be in the 1489 * SearchFilter. Currently the SearchKey must be a WordMode 1490 * enumerator or a CqFieldDefinition proxy. 1491 * @param targetItem The new item to be added to the target value list 1492 * @return The target value list after modification. 1493 */ 1494 <U> List<U> add(SearchKey<List<U>> key, 1495 U targetItem); 1496 1497 /** 1498 * Returns the target value currently associated with a given SearchKey 1499 * 1500 * @param <U> The data type used to specify the value against which the 1501 * key attribute will be compared. This type must match the 1502 * type parameter of the key used and so currently this must 1503 * be String, List<String>, Date, or Boolean. 1504 * @param key A SearchKey<U> object representing the attribute of each 1505 * candidate record that the search should filter on. 1506 * Currently this may be a SearchLevel enumerator, a 1507 * DateLimit enumerator, a WordMode enumerator, a 1508 * CqRecordType proxy, or a CqFieldDefinition proxy. 1509 * @return The value currently associated with the given key in this 1510 * search filter; <b>null</b> if no association is currently 1511 * defined. 1512 */ 1513 <U> U get(SearchKey<U> key); 1514 1515 /** 1516 * @return A List of all the SearchKey/target-values pairs defined by 1517 * this SearchFilter. 1518 */ 1519 List<Map.Entry<SearchKey<Object>, Object>> getAll(); 1520 1521 /** 1522 * Retrieves SearchKey/target-value pairs of a given target-value type 1523 * 1524 * @param <U> The data type used to specify the value against which the 1525 * key attribute will be compared. This type must match the 1526 * type parameter of a defined SearchKey and so currently 1527 * this must be String, List<String>, Date, or Boolean. 1528 * @param type The Class object for the desired target-value data type. 1529 * @return All of the entries in this SearchFilter whose target value 1530 * type matches the given type. The result will never be <b>null</b>, 1531 * but the returned list may be empty. 1532 */ 1533 <U> List<Map.Entry<SearchKey<U>, U>> getEntries(Class<U> type); 1534 1535 /** 1536 * Retrieves SearchKey/target-value pairs by SearchKey type 1537 * 1538 * @param <U> The data type used to specify the value against which the 1539 * key attribute will be compared. This type must match the 1540 * type parameter of a defined SearchKey and so currently 1541 * this must be String, List<String>, Date, or Boolean. 1542 * @param <V> A subclass of SearchKey<U> 1543 * @param keyType The type of keys to retrieve from this search 1544 * specification 1545 * @return All entries of this SearchFilter whose key is of the 1546 * specified type. The result will never be null, but the 1547 * returned list may be empty. 1548 */ 1549 <V extends SearchKey<U>, U> List<Map.Entry<V, U>> getEntriesByKey(Class<V> keyType); 1550 1551 /** 1552 * @return The SearchLevel entry of this SearchFilter; otherwise null 1553 */ 1554 Map.Entry<SearchLevel, String> getStringFilter(); 1555 1556 /** 1557 * @return A list of the CqRecordType entries of this SearchFilter; will 1558 * never be <b>null</b> but the list may be empty. 1559 */ 1560 List<Map.Entry<CqRecordType, Boolean>> getRecordTypeFilters(); 1561 1562 /** 1563 * @return A list of the CqFieldDefinition entries of this SearchFilter; 1564 * will never be <b>null</b> but the list may be empty. 1565 */ 1566 List<Map.Entry<CqFieldDefinition, List<String>>> getFieldFilters(); 1567 1568 /** 1569 * @return A list of the WordMode entries of this SearchFilter; will 1570 * never be <b>null</b> but the list may be empty. 1571 */ 1572 List<Map.Entry<WordMode, List<String>>> getWordFilters(); 1573 1574 /** 1575 * @return A list of the DateLimit entries of this SearchFilter; will 1576 * never be <b>null</b> but the list may be empty. 1577 */ 1578 List<Map.Entry<DateLimit, Date>> getDateFilters(); 1579 1580 /** 1581 * Removes all SearchKey entries from this SearchFilter 1582 */ 1583 void clear(); 1584 } 1585 1586 /** 1587 * Constructs a SearchFilter instance with an initial simple specification 1588 * string. 1589 * 1590 * @param simpleString A search specification using the simple specification 1591 * syntax. If <b>null</b>, an empty SearchFilter will be 1592 * returned. 1593 * @return A SearchFilter instance defining the simple search specification 1594 * derived from the simpleString argument. 1595 */ 1596 SearchFilter buildSearchFilter(String simpleString); 1597 1598 /** 1599 * Searches the indexed content of the database for objects that match a 1600 * given filter. Information about each selected object is returned as a 1601 * packet of data called a <i>hit</i>. The matching process assigns a score 1602 * to the hit between 1 and 100, with 100 designating a near-perfect match. 1603 * The hits are ranked according to this score and are returned in order 1604 * highest rank to lowest. 1605 * <p> 1606 * When this method returns, the highest ranking hits will be available 1607 * immediately for inspection on the client. An argument to this method 1608 * controls the size of this first set of hits. If there were more hits 1609 * found than could be returned immediately, the remaining hits can be 1610 * requested using the CqHitSet.doGetMore() method. 1611 * 1612 * @param searchFilter A SearchFilter specifying which objects of the 1613 * database are to be selected for inclusion in the result set. 1614 * @param setParams 0, 1, or 2 long values specifying how the hits are to be 1615 * returned from the server to the client. 1616 * <ul> 1617 * <li>setParams[0]: The maximum number of hits the client will 1618 * accept from the server in the immediate response to this 1619 * request. Based on the total number of hits found and the load 1620 * on the server, however, the actual number of hits returned may 1621 * be less than this number. If this value is zero (or omitted) 1622 * the number of hits returned will be determined solely by the 1623 * server. In which case, the client should be prepared to accept 1624 * all hits found by the search. 1625 * <li>setParams[1]: The index of the first hit to be returned 1626 * to the client, where 1 is the index of the first hit found by 1627 * the search. If this value is zero (or omitted) the first hit 1628 * found will be the first hit returned. 1629 * </ul> 1630 * @return An iterator over the hits found in the search. 1631 * 1632 * @see CqHitSet#doGetMore(long) 1633 */ 1634 CqHitSet doFullTextSearch(SearchFilter searchFilter, 1635 long... setParams) throws WvcmException; 1636 1637 /** 1638 * The typeahead enabled search, searches the indexed content of the database for objects that match a 1639 * given filter. Information about each selected object is returned as a 1640 * packet of data called a <i>hit</i>. The matching process assigns a score 1641 * to the hit between 1 and 100, with 100 designating a near-perfect match. 1642 * The hits are ranked according to this score and are returned in order 1643 * highest rank to lowest. 1644 * <p> 1645 * When this method returns, the highest ranking hits will be available 1646 * immediately for inspection on the client. Four arguments are setting the scope of the typeahead search, 1647 * controls which filed of a record is typeahead enabled, and which fields will be searched and put in the result set. 1648 * If there were more hits found than could be returned immediately, the remaining hits can be 1649 * requested using the CqHitSet.doGetMore() method. 1650 * 1651 * @param parentRecordTypeLocation A Lcation string specifying which recordType is for the record 1652 * @param parentRecordLocation A String specifying which record is to be selected to do the 1653 * typeahead 1654 * @param parentRecordFieldNameLocation A Location string specifying which field of the record is typeahead 1655 * enabled 1656 * @param displayFieldNameLocation A List of Location strings specifying which fields of a recordtype are 1657 * to be searched and displayed in the result set 1658 * @param searchFilter A SearchFilter specifying which objects of the database are to 1659 * be selected for inclusion in the result set. 1660 * @param setParams 0, 1, or 2 long values specifying how the hits are to be 1661 * returned from the server to the client. 1662 * <ul> 1663 * <li>setParams[0]: The maximum number of hits the client will 1664 * accept from the server in the immediate response to this 1665 * request. Based on the total number of hits found and the load 1666 * on the server, however, the actual number of hits returned may 1667 * be less than this number. If this value is zero (or omitted) 1668 * the number of hits returned will be determined solely by the 1669 * server. In which case, the client should be prepared to accept 1670 * all hits found by the search. 1671 * <li>setParams[1]: The index of the first hit to be returned to 1672 * the client, where 1 is the index of the first hit found by the 1673 * search. If this value is zero (or omitted) the first hit found 1674 * will be the first hit returned. 1675 * </ul> 1676 * @return An iterator over the hits found in the search. 1677 * @throws WvcmException 1678 */ 1679 CqHitSet doFullTextSearch(String parentRecordTypeLocation, 1680 String parentRecordLocation, String parentRecordFieldNameLocation, 1681 List<String> displayFieldNameLocation, SearchFilter searchFilter, 1682 long... setParams) throws WvcmException; 1683}