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 }