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