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