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