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