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