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