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