001/*
002 * IBM and/or HCL Confidential
003 * OCO Source Materials
004 * (C) Copyright IBM Corp. 2004, 2014.  All Rights Reserved.
005 * (C) Copyright HCL Technologies Ltd. 2016, 2018  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
012package com.ibm.rational.wvcm.stp.cq;
013
014import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
015
016import java.util.Date;
017import java.util.List;
018import java.util.Map;
019
020import javax.wvcm.Feedback;
021import javax.wvcm.Location;
022import javax.wvcm.PropertyNameList.PropertyName;
023import javax.wvcm.ResourceList;
024import javax.wvcm.WvcmException;
025
026import com.ibm.rational.wvcm.stp.StpLocation;
027import com.ibm.rational.wvcm.stp.StpProperty;
028import com.ibm.rational.wvcm.stp.StpRepository;
029import com.ibm.rational.wvcm.stpex.StpExBase;
030import 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>&lt;db-set&gt;</i>/<i>&lt;user-db&gt;</i>
075 * </pre>
076 * 
077 * @see CqContextResource
078 */
079public 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&lt;String&gt; 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    /**
908     * Answers whether or not this database, using the CqProvider of this proxy,
909     * provides support for privileged queries.
910     */
911    static PropertyName<Boolean> IS_PRIVILEGED_QUERY_ENABLED =
912            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-privileged-query-enabled");
913
914    /**
915     * Returns the value of the
916     * {@link #IS_PRIVILEGED_QUERY_ENABLED IS_PRIVILEGED_QUERY_ENABLED} property
917     * as defined by this proxy.
918     * 
919     * @return <b>true</b> if full-text search has been enabled on this
920     *         database; <b>false</b> otherwise.
921     * 
922     * @throws WvcmException if this proxy does not define a value for the
923     *             {@link #IS_PRIVILEGED_QUERY_ENABLED IS_PRIVILEGED_QUERY_ENABLED}
924     *             property.
925     */
926    boolean getIsPrivilegedQueryEnabled() throws WvcmException;
927
928    /**
929     * Answers whether or not this database, using the CqProvider of this proxy,
930     * provides support for reports, including access to CqReport and
931     * CqReportFormat resources and the generation of reports via
932     * CqReport.doMakeReport().
933     */
934    static PropertyName<Boolean> IS_REPORTING_ENABLED =
935        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-reporting-enabled");
936
937    /**
938     * Returns the value of the
939     * {@link #IS_REPORTING_ENABLED IS_REPORTING_ENABLED} property as defined by
940     * this proxy.
941     * 
942     * @return <b>true</b> if CqReport and CqReportFormat resources are
943     *         supported by this database through this proxy's CqProvider;
944     *         <b>false</b> otherwise.
945     * 
946     * @throws WvcmException
947     *             if this proxy does not define a value for the
948     *             {@link #IS_REPORTING_ENABLED IS_REPORTING_ENABLED} property.
949     */
950    boolean getIsReportingEnabled() throws WvcmException;
951
952    /**
953     * Answers whether or not this database, using the CqProvider of this proxy,
954     * provides support for the generation of charts via CqQuery.doMakeChart().
955     */
956    static PropertyName<Boolean> IS_CHARTING_ENABLED =
957        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-charting-enabled");
958
959    /**
960     * Returns the value of the {@link #IS_CHARTING_ENABLED IS_CHARTING_ENABLED}
961     * property as defined by this proxy.
962     * 
963     * @return <b>true</b> if charting is supported by this database through
964     *         this proxy's CqProvider; <b>false</b> otherwise.
965     * 
966     * @throws WvcmException
967     *             if this proxy does not define a value for the
968     *             {@link #IS_CHARTING_ENABLED IS_CHARTING_ENABLED} property.
969     */
970    boolean getIsChartingEnabled() throws WvcmException;
971
972    /**
973     * Answers whether or not this is a test database
974     */
975    static PropertyName<Boolean> IS_TEST_DATABASE =
976        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-test-database");
977
978    /**
979     * Returns the value of the {@link #IS_TEST_DATABASE IS_TEST_DATABASE}
980     * property as defined by this proxy.
981     * 
982     * @return <b>true</b> if this user database has been designated a test
983     *         database; <b>false</b> otherwise.
984     * 
985     * @throws WvcmException if this proxy does not define a value for the
986     *             {@link #IS_TEST_DATABASE IS_TEST_DATABASE}
987     *             property.
988     */
989    boolean getIsTestDatabase() throws WvcmException;
990
991    /**
992     * A list of the record types that are being indexed for full-text searches.
993     */
994    static PropertyName<ResourceList<CqRecordType>> INDEXED_RECORD_TYPES =
995        new PropertyName<ResourceList<CqRecordType>>(PROPERTY_NAMESPACE,
996                                                     "indexed-record-types");
997
998    /**
999     * Returns the value of the
1000     * {@link #INDEXED_RECORD_TYPES INDEXED_RECORD_TYPES} property as defined by
1001     * this proxy.
1002     * 
1003     * @return A ResourceList containing a CqRecordType proxy for any record
1004     *         type that is being indexed for use in full-text searches.
1005     * 
1006     * @throws WvcmException if this proxy does not define a value for the
1007     *             {@link #INDEXED_RECORD_TYPES INDEXED_RECORD_TYPES} property.
1008     */
1009    ResourceList<CqRecordType> getIndexedRecordTypes() throws WvcmException;
1010
1011    /**
1012     * A list of all report formats defined in this database and accessible to
1013     * the current user.
1014     */
1015    PropertyName<ResourceList<CqReportFormat>> REPORT_FORMATS =
1016        new PropertyName<ResourceList<CqReportFormat>>(PROPERTY_NAMESPACE,
1017                                                       "report-formats");
1018
1019    /**
1020     * A list of the record types that are OSLCLinks package enabled.
1021     */
1022    static PropertyName<ResourceList<CqRecordType>> OSLCLINKS_ENABLED_RECORD_TYPES =
1023        new PropertyName<ResourceList<CqRecordType>>(PROPERTY_NAMESPACE,
1024                                                     "oslclinks-enabled-record-types");
1025
1026    /**
1027     * Returns the value of the
1028     * {@link #OSLCLINKS_ENABLED_RECORD_TYPES OSLCLINKS_ENABLED_RECORD_TYPES} property as 
1029     * defined by this proxy.
1030     * 
1031     * @return A ResourceList containing a CqRecordType proxy for any record
1032     *         type that is OSLCLinks package enabled
1033     * 
1034     * @throws WvcmException if this proxy does not define a value for the
1035     *             {@link #OSLCLINKS_ENABLED_RECORD_TYPES OSLCLINKS_ENABLED_RECORD_TYPES} 
1036     *             property.
1037     */
1038    ResourceList<CqRecordType> getOslclinksEnabledRecordTypes() throws WvcmException;
1039
1040    /**
1041     * Returns the value of the {@link #REPORT_FORMATS REPORT_FORMATS} property
1042     * as defined by this proxy.
1043     * 
1044     * @return A ResourceList containing a CqReportFormat proxy for each report
1045     *         format defined in the public and personal query folders . Will
1046     *         never be <b>null</b>.
1047     * 
1048     * @throws WvcmException if this proxy does not define a value for the
1049     *             {@link #REPORT_FORMATS REPORT_FORMATS} property.
1050     */
1051    ResourceList<CqReportFormat> getReportFormats() throws WvcmException;
1052
1053    /**
1054     * Returns a CqUserInfo structure containing read-only information about the
1055     * user currently logged into this database.
1056     */
1057    PropertyName<CqUserInfo> USER_INFO = 
1058        new PropertyName<CqUserInfo>(PROPERTY_NAMESPACE, "user-info");
1059    
1060    /**
1061     * Returns the value of the {@link #USER_INFO USER_INFO} property as defined
1062     * by this proxy.
1063     * 
1064     * @return A CqUserInfo instance containing read-only information about the
1065     *         user currently logged into this database. Will never be <b>null</b>.
1066     * 
1067     * @throws WvcmException if this proxy does not define a value for the
1068     *             {@link #USER_INFO USER_INFO} property.
1069     */
1070    CqUserInfo getUserInfo() throws WvcmException;
1071
1072    /**
1073     * Returns the value of the {@link #USER_INFO USER_INFO} property as defined
1074     * by this proxy.
1075     * 
1076     * @return A CqDb instance (which is a CqUserInfo) containing information about the
1077     *         user currently logged into this database. Will never be <b>null</b>.
1078     * 
1079     * @throws WvcmException if this proxy does not define a value for the
1080     *             {@link #USER_INFO USER_INFO} property.
1081     */
1082    CqDb getCqDb() throws WvcmException;
1083
1084    /**
1085     * Removes all modified and moribund resources from the change context of
1086     * this database; thereby reverting those resources to their previous,
1087     * unmodified or undeleted state.
1088     * 
1089     * @param feedback A Feedback object requesting properties of this database
1090     *            and/or properties of the reverted resources to be returned
1091     *            from the server after successful completion of the operation.
1092     * 
1093     * @throws WvcmException If the resources cannot be reverted.
1094     */
1095    CqUserDb doClearContext(Feedback feedback) throws WvcmException;
1096
1097    /**
1098     * Selectively delivers (commits) modified resources to the database and/or
1099     * destroys moribund resources from the database and removes them from the
1100     * change context.
1101     * <p>
1102     * NOTE: A ClearQuest query created and delivered in one CqProvider instance
1103     * may not appear in another already-existing CqProvider instance. To make
1104     * them available, create a new CqProvider instance <b>after</b> the
1105     * delivery is complete.
1106     * <p>
1107     * Known places in the implementation that will have this problem include:<br>
1108     * Creation or deletion of a ClearQuest query (modification is OK).<br>
1109     * Creation or deletion of a ClearQuest CqQueryFolder.<br>
1110     * Modification of a ClearQuest CqDynamicChoiceList (creation is not
1111     * supported anyway).
1112     * 
1113     * @param feedback A request for specific properties from the resources that
1114     *            were directly or indirectly impacted by this operation, which,
1115     *            in this case would be the modified resources that were
1116     *            delivered by this operation. May be <b>null</b>; in which
1117     *            case this information will not be requested from the server.
1118     * @param deliveryOrder The modified and moribund resources currently in
1119     *            this change context that are to be delivered or deleted. They
1120     *            will be delivered or deleted in the order specified by the
1121     *            proxies in the given list. To deliver/delete all
1122     *            modified/moribund resources in an arbitrary order, use
1123     *            {@link CqProvider#DELIVER_ALL}. Must not be <b>null</b> nor
1124     *            any of the other special delivery order constants AUTO, HOLD,
1125     *            or DELIVER.
1126     * 
1127     * @throws WvcmException if any preconditions are not satisfied or if other
1128     *             errors are detected while writing the records to the
1129     *             database.
1130     */
1131
1132    CqUserDb doDeliver(Feedback feedback,
1133                       List<CqContextResource> deliveryOrder)
1134        throws WvcmException;
1135
1136    /**
1137     * Selectively reverts modified or moribund resources in this database's
1138     * change context to their previous, unmodified/undeleted state. To revert
1139     * all resources in the change context, in an arbitrary order, use
1140     * {@link #doClearContext(Feedback)}. This operation is semantically
1141     * equivalent to invoking doRevert() on each resource in the given list, but
1142     * will be more efficient because there is only one round-trip to the server
1143     * required.
1144     * <p>
1145     * Note that doRevert removes all changes to the resource from the change
1146     * context. It is not an undo operation, but a revert. If multiple changes
1147     * have been made to a resource (since the last time it was delivered) they
1148     * will all be discarded by doRevert.
1149     * 
1150     * @param feedback A request for specific properties from the resources that
1151     *            were directly or indirectly impacted by this operation, which,
1152     *            in this case would be the modified/moribund resources that
1153     *            were reverted by this operation. May be <b>null</b>; in which
1154     *            case this information will not be requested from the server.
1155     * @param revertOrder The modified/moribund resources currently in this
1156     *            change context to be reverted to their original state. They
1157     *            will be reverted/undeleted in the order specified by the
1158     *            proxies in this argument. Must not be <b>null</b> nor any of
1159     *            the special delivery order constants AUTO, HOLD, DELIVER, or
1160     *            DELIVER_ALL.
1161     * 
1162     * @throws WvcmException if any preconditions are not satisfied or if other
1163     *             errors are detected while writing the records to the
1164     *             database.
1165     */
1166
1167    CqUserDb doRevert(Feedback feedback,
1168                      List<CqContextResource> revertOrder) throws WvcmException;
1169
1170    /**
1171     * Searches the database for records having a given display name.
1172     * 
1173     * @param displayName A String containing the display name of the record to
1174     *            be found.
1175     * 
1176     * @param possibleRecordTypes An array of locations containing a
1177     *            CqRecordType location for each type of record to be considered
1178     *            in the search. May not contain record type family names. May
1179     *            be <b>null</b> or empty to force consideration of all record
1180     *            types.
1181     *            <p>
1182     *            The record type array is used to control the search for the
1183     *            record identified by the displayName argument. This list of
1184     *            record types is iterated and processed in the order given
1185     *            until a record is found. If any of the record type locations
1186     *            provided in this argument is invalid (such as referring to a
1187     *            record type family), an exception is thrown that identifies
1188     *            the invalid location. If a null or empty array value is
1189     *            provided, all record types defined in the schema are searched,
1190     *            with the search order being from the most frequently found
1191     *            record type searched first to the least found record type
1192     *            being searched last.
1193     * 
1194     * @param mode A FindMode enumerator identifying the type of record to
1195     *            search for.
1196     * 
1197     * @param feedback A Feedback object in which may be requested search
1198     *            progress reports and additional properties to be included in
1199     *            the result proxy. May be <b>null</b> if no additional
1200     *            feedback is needed.
1201     * 
1202     * @return A CqRecord proxy representing a record of one of the requested
1203     *         types or type categories whose display name matches the given
1204     *         displayName argument; <b>null</b> if no such record can be
1205     *         found. If a record is found, the returned proxy will be populated
1206     *         with the properties requested by the feedback parameter.
1207     * 
1208     * @throws WvcmException If the search as specified could not be completed;
1209     *             for example, if the database or the specified record types
1210     *             are not accessible. If all record types can be searched as
1211     *             specified, failure to find a matching record <i>does not</i>
1212     *             cause an exception but results in a null result.
1213     */
1214    CqRecord doFindRecord(String displayName,
1215                          FindMode mode,
1216                          Feedback feedback,
1217                          Location... possibleRecordTypes) throws WvcmException;
1218
1219    /**
1220     * Searches the database for records having a given dbid.
1221     * 
1222     * @param dbid The dbid of the record to be found.
1223     * 
1224     * @param mode A FindMode enumerator identifying the type of record to
1225     *            search for.
1226     * 
1227     * @param possibleRecordTypes An array of locations containing a
1228     *            CqRecordType location for each type of record to be considered
1229     *            in the search. May not contain record type family names. May
1230     *            be <b>null</b> or empty to force consideration of all record
1231     *            types.
1232     *            <p>
1233     *            The record type array is used to control the search for the
1234     *            record identified by the displayName argument. This list of
1235     *            record types is iterated and processed in the order given
1236     *            until a record is found. If any of the record type locations
1237     *            provided in this argument is invalid (such as referring to a
1238     *            record type family), an exception is thrown that identifies
1239     *            the invalid location. If a null or empty array value is
1240     *            provided, all record types defined in the schema are searched,
1241     *            with the search order being from the most frequently found
1242     *            record type searched first to the least found record type
1243     *            being searched last.
1244     * 
1245     * @param feedback A Feedback object in which may be requested search
1246     *            progress reports and additional properties to be included in
1247     *            the result proxy. May be <b>null</b> if no additional
1248     *            feedback is needed.
1249     * 
1250     * @return A CqRecord proxy representing a record of one of the requested
1251     *         types or type categories whose dbid name matches the given
1252     *         dbid argument; <b>null</b> if no such record can be
1253     *         found. If a record is found, the returned proxy will be populated
1254     *         with the properties requested by the feedback parameter.
1255     * 
1256     * @throws WvcmException If the search as specified could not be completed;
1257     *             for example, if the database or the specified record types
1258     *             are not accessible. If all record types can be searched as
1259     *             specified, failure to find a matching record <i>does not</i>
1260     *             cause an exception but results in a null result.
1261
1262     * @see #doFindRecord(long, com.ibm.rational.wvcm.stp.cq.CqUserDb.FindMode,
1263     *      Feedback, Location[])
1264     */
1265    CqRecord doFindRecord(long dbid,
1266                          FindMode mode,
1267                          Feedback feedback,
1268                          Location... possibleRecordTypes) throws WvcmException;
1269
1270    /**
1271     * Enumerates the options for restricting the finding of records based on
1272     * their record class.
1273     */
1274    enum FindMode implements StpExEnumeration
1275    {
1276        FIND_ANY_RECORD, FIND_STATELESS_RECORD, FIND_STATEFUL_RECORD;
1277    }
1278
1279    /**
1280     * Returns a list of all the resources in the database whose names differ
1281     * from a given name only in their site extensions. Currently, only query
1282     * folder items and records of a stateless record type could possibly need
1283     * site extensions to disambiguate them, so applying this method to any
1284     * other resource is simply a waste of time and is likely to raise an
1285     * exception.
1286     * <p>
1287     * Applying this method to a stateless record type location has a special
1288     * meaning. In that case <i>all</i> instances of that record type that
1289     * require site extension are returned.
1290     * 
1291     * @param name A (potentially ambiguous) user-friendly location
1292     *            specification for a ClearQuest record, record type, or query
1293     *            folder item, whose repo field, if present, must name this
1294     *            database.
1295     * 
1296     * @param feedback A Feedback object in which may be requested search
1297     *            progress reports and additional properties to be included in
1298     *            the result proxies. May be <b>null</b> if no additional
1299     *            feedback is needed.
1300     * 
1301     * @return A ResourceList containing a proxy for each resource in the
1302     *         database whose site-extended name differs from the given name
1303     *         only in the site extensions used. Will never be <b>null</b> or
1304     *         empty.
1305     * 
1306     * @throws WvcmException If the database is not accessible, if the given
1307     *             name identifies a resource other than a record or query
1308     *             folder item in this database, or if the given name cannot be
1309     *             extended in any way to name any resource.
1310     */
1311    ResourceList<CqResource> doFindSiteExtendedNames(StpLocation name,
1312                                                     Feedback feedback)
1313        throws WvcmException;
1314
1315    /**
1316     * Upgrades this database's user and group information to match that of its
1317     * db-set. This method copies the changes from the db-set to the user
1318     * database. You should call this function to upgrade a database after
1319     * making changes to the users and groups of the db-set.
1320     * 
1321     * @param feedback Specifies optional feedback to the caller.
1322     * @return A proxy for this user database (after the upgrade is complete),
1323     *         whose properties are specified by feedback.
1324     * @throws WvcmException
1325     */
1326    CqUserDb doUpgradeUsersAndGroups(Feedback feedback) throws WvcmException;
1327
1328    /**
1329     * Verifies that a CqQueryFolderItem of a given type can be created at a
1330     * given location. The operation checks that the characters used in the
1331     * location are valid for the target database and that no resource currently
1332     * exists at the specified location.
1333     * 
1334     * @param item A proxy for the item whose location is to be tested.
1335     * 
1336     * @param feedback A Feedback object that specifies the properties to be
1337     *            included in the result proxy (if a resource exists at the
1338     *            specified location). If the argument is null, the properties
1339     *            defined by the result proxy are unspecified.
1340     * 
1341     * @return If the location is valid and there is no resource currently at
1342     *         the specified location, the result is <b>null</b>. If the
1343     *         location is valid, but a resource already exists at that
1344     *         location, a proxy for that resource is returned, populated with
1345     *         any properties requested by the feedback argument.
1346     * 
1347     * @throws WvcmException if the location is not valid on the target
1348     *             database.
1349     */
1350    CqQueryFolderItem doValidateLocation(CqQueryFolderItem item,
1351                                         Feedback feedback)
1352        throws WvcmException;
1353
1354    /**
1355     * The interface for an API object that may be used to define a filter for a
1356     * full-text search of the database. The search key specifies an attribute
1357     * of the database object whose value will be used to select the object for
1358     * inclusion in the result set of the full-text search. In the SearchFilter,
1359     * each SearchKey is associated with a target value that specifies what
1360     * attribute values will cause the object to be selected.
1361     * <p>
1362     * The currently defined SearchKey types are
1363     * <ul>
1364     * <li>{@link SearchLevel}: (SearchKey&lt;String>) selects an object
1365     * having any field matching the specification in the target String. The
1366     * SearchMode enumerator specifies the type of specification to be found in
1367     * the target string. Currently there is only one SearchMode, SIMPLE, which
1368     * represents a full-text search using a simple specification.
1369     * <li>{@link WordMode}: (SearchKey&lt;List&lt;String>>) selects an object
1370     * having any field matching the words in the target list. The WordMode
1371     * enumerator specifies how the target words must match a field to select
1372     * the object.
1373     * <li>{@link DateLimit}: (SearchKey&lt;Date>) selects an object based on
1374     * the relationship between the object's creation or modification date and
1375     * the target date. The DateLimit enumerator specifies which date attribute
1376     * to compare against and the relationship with the target date that will
1377     * select the object.
1378     * <li>{@link CqRecordType}: (SearchKey&lt;Boolean>) selects a record
1379     * based on its record type. If the target value is Boolean.TRUE, a record
1380     * whose record type is the same as the record type denoted by the
1381     * CqRecordType object will be selected. If several CqRecordType keys (with
1382     * TRUE target values) are present in a SearchFilter, a record having anyone
1383     * of those record types is selected.
1384     * <li>{@link CqFieldDefinition}: (SearchKey&lt;List&lt;String>>) selects
1385     * a record having a specific field whose value matches all of the target
1386     * strings. The CqFieldDefinition specifies the record type and the field of
1387     * that record type that must match the target strings. Each target string
1388     * is a simple search specification.
1389     * </ul>
1390     * 
1391     * @param <T> The type of object used to specify the value or values that
1392     *            will select or reject an object based on the value it has for
1393     *            the key attribute.
1394     */
1395    public static interface SearchKey<T>
1396    {}
1397
1398    /**
1399     * WordMode SearchKeys limit the search results to just those objects that
1400     * contain the targeted words associated with the WordMode key in the
1401     * filter.
1402     */
1403    public static enum WordMode implements SearchKey<List<String>>
1404    {
1405        /** Match all of the words in the target list */
1406        ALL,
1407        /** Match all of the words in the target list in the order given */
1408        EXACT,
1409        /** Match any (at least one) of the words in the target list */
1410        ANY,
1411        /** Match none (do not match any) of the words in the target list */
1412        NONE
1413    }
1414
1415    /**
1416     * A DateLimit SearchKey limits the search to just those objects whose
1417     * creation or modification time are in a target range.
1418     */
1419    public static enum DateLimit implements SearchKey<Date>
1420    {
1421        /** Matches an object created on or after the target date */
1422        CREATED_AFTER,
1423
1424        /** Matches an object created on or before the target date */
1425        CREATED_BEFORE,
1426
1427        /** Matches an object modified on or after the target date */
1428        MODIFIED_AFTER,
1429
1430        /** Matches an object modified on or before the target date */
1431        MODIFIED_BEFORE
1432    }
1433
1434    /** Specifies a simple search string */
1435    public static enum SearchLevel implements SearchKey<String>
1436    {
1437        /** Interpret the associated argument as a simple search string and
1438         * match accordingly against that.
1439         */
1440        SIMPLE
1441    }
1442
1443    /**
1444     * A collection of SearchKey/target-value pairs that collectively define the
1445     * filter for selecting objects for inclusion in a full-text search. In
1446     * general, an object must match all of the given keys in the filter to be
1447     * added to the result set. The only exception to this rule are the
1448     * CqRecordType keys. If more than one CqRecordType key is present, the
1449     * object needs only match one of them to be a candidate for the result
1450     * set--the object would need to match all the other types of keys to
1451     * actually be selected.
1452     */
1453    public static interface SearchFilter
1454    {
1455        /**
1456         * Adds a SearchKey and its target value to the full text search filter.
1457         * Each SearchKey specifies what attribute of an object is to be
1458         * filtered on and the target value specifies the value against which
1459         * the attribute value will be compared for possible inclusion in the
1460         * result set.
1461         * 
1462         * @param <U> The data type used to specify the target value. This type
1463         *            must match the type parameter of the key used and so
1464         *            currently this must be String, List&lt;String>, Date, or
1465         *            Boolean.
1466         * @param key A SearchKey&lt;U> object representing the attribute of
1467         *            each candidate object that the search should filter on.
1468         *            Currently this may be a SearchLevel enumerator, a
1469         *            DateLimit enumerator, a WordMode enumerator, a
1470         *            CqRecordType proxy, or a CqFieldDefinition proxy.
1471         * @param targetValue An instance of class U that specifies which values
1472         *            of the key attribute will select or reject a record in the
1473         *            search. If this value is <b>null</b> (or Boolean.FALSE)
1474         *            the corresponding SearchKey will be removed from the
1475         *            search specification.
1476         * @return The value previously associated with the SearchKey.
1477         */
1478        <U> U put(SearchKey<U> key,
1479                  U targetValue);
1480
1481        /**
1482         * Extends the target value list associated with a SearchKey by a single
1483         * item.
1484         * 
1485         * @param <U> The type of item in a target value list; currently must be
1486         *            String.
1487         * @param key The SearchKey whose target value list is to be extended.
1488         *            The SeachKey does not need to already be in the
1489         *            SearchFilter. Currently the SearchKey must be a WordMode
1490         *            enumerator or a CqFieldDefinition proxy.
1491         * @param targetItem The new item to be added to the target value list
1492         * @return The target value list after modification.
1493         */
1494        <U> List<U> add(SearchKey<List<U>> key,
1495                        U targetItem);
1496
1497        /**
1498         * Returns the target value currently associated with a given SearchKey
1499         * 
1500         * @param <U> The data type used to specify the value against which the
1501         *            key attribute will be compared. This type must match the
1502         *            type parameter of the key used and so currently this must
1503         *            be String, List&lt;String>, Date, or Boolean.
1504         * @param key A SearchKey<U> object representing the attribute of each
1505         *            candidate record that the search should filter on.
1506         *            Currently this may be a SearchLevel enumerator, a
1507         *            DateLimit enumerator, a WordMode enumerator, a
1508         *            CqRecordType proxy, or a CqFieldDefinition proxy.
1509         * @return The value currently associated with the given key in this
1510         *         search filter; <b>null</b> if no association is currently
1511         *         defined.
1512         */
1513        <U> U get(SearchKey<U> key);
1514
1515        /**
1516         * @return A List of all the SearchKey/target-values pairs defined by
1517         *         this SearchFilter.
1518         */
1519        List<Map.Entry<SearchKey<Object>, Object>> getAll();
1520
1521        /**
1522         * Retrieves SearchKey/target-value pairs of a given target-value type
1523         * 
1524         * @param <U> The data type used to specify the value against which the
1525         *            key attribute will be compared. This type must match the
1526         *            type parameter of a defined SearchKey and so currently
1527         *            this must be String, List&lt;String>, Date, or Boolean.
1528         * @param type The Class object for the desired target-value data type.
1529         * @return All of the entries in this SearchFilter whose target value
1530         *         type matches the given type. The result will never be <b>null</b>,
1531         *         but the returned list may be empty.
1532         */
1533        <U> List<Map.Entry<SearchKey<U>, U>> getEntries(Class<U> type);
1534
1535        /**
1536         * Retrieves SearchKey/target-value pairs by SearchKey type
1537         * 
1538         * @param <U> The data type used to specify the value against which the
1539         *            key attribute will be compared. This type must match the
1540         *            type parameter of a defined SearchKey and so currently
1541         *            this must be String, List&lt;String>, Date, or Boolean.
1542         * @param <V> A subclass of SearchKey<U>
1543         * @param keyType The type of keys to retrieve from this search
1544         *            specification
1545         * @return All entries of this SearchFilter whose key is of the
1546         *         specified type. The result will never be null, but the
1547         *         returned list may be empty.
1548         */
1549        <V extends SearchKey<U>, U> List<Map.Entry<V, U>> getEntriesByKey(Class<V> keyType);
1550
1551        /**
1552         * @return The SearchLevel entry of this SearchFilter; otherwise null
1553         */
1554        Map.Entry<SearchLevel, String> getStringFilter();
1555
1556        /**
1557         * @return A list of the CqRecordType entries of this SearchFilter; will
1558         *         never be <b>null</b> but the list may be empty.
1559         */
1560        List<Map.Entry<CqRecordType, Boolean>> getRecordTypeFilters();
1561
1562        /**
1563         * @return A list of the CqFieldDefinition entries of this SearchFilter;
1564         *         will never be <b>null</b> but the list may be empty.
1565         */
1566        List<Map.Entry<CqFieldDefinition, List<String>>> getFieldFilters();
1567
1568        /**
1569         * @return A list of the WordMode entries of this SearchFilter; will
1570         *         never be <b>null</b> but the list may be empty.
1571         */
1572        List<Map.Entry<WordMode, List<String>>> getWordFilters();
1573
1574        /**
1575         * @return A list of the DateLimit entries of this SearchFilter; will
1576         *         never be <b>null</b> but the list may be empty.
1577         */
1578        List<Map.Entry<DateLimit, Date>> getDateFilters();
1579
1580        /**
1581         * Removes all SearchKey entries from this SearchFilter
1582         */
1583        void clear();
1584    }
1585
1586    /**
1587     * Constructs a SearchFilter instance with an initial simple specification
1588     * string.
1589     * 
1590     * @param simpleString A search specification using the simple specification
1591     *            syntax. If <b>null</b>, an empty SearchFilter will be
1592     *            returned.
1593     * @return A SearchFilter instance defining the simple search specification
1594     *         derived from the simpleString argument.
1595     */
1596    SearchFilter buildSearchFilter(String simpleString);
1597
1598    /**
1599     * Searches the indexed content of the database for objects that match a
1600     * given filter. Information about each selected object is returned as a
1601     * packet of data called a <i>hit</i>. The matching process assigns a score
1602     * to the hit between 1 and 100, with 100 designating a near-perfect match.
1603     * The hits are ranked according to this score and are returned in order
1604     * highest rank to lowest.
1605     * <p>
1606     * When this method returns, the highest ranking hits will be available
1607     * immediately for inspection on the client. An argument to this method
1608     * controls the size of this first set of hits. If there were more hits
1609     * found than could be returned immediately, the remaining hits can be
1610     * requested using the CqHitSet.doGetMore() method.
1611     * 
1612     * @param searchFilter A SearchFilter specifying which objects of the
1613     *            database are to be selected for inclusion in the result set.
1614     * @param setParams 0, 1, or 2 long values specifying how the hits are to be
1615     *            returned from the server to the client.
1616     *            <ul>
1617     *            <li>setParams[0]: The maximum number of hits the client will
1618     *            accept from the server in the immediate response to this
1619     *            request. Based on the total number of hits found and the load
1620     *            on the server, however, the actual number of hits returned may
1621     *            be less than this number. If this value is zero (or omitted)
1622     *            the number of hits returned will be determined solely by the
1623     *            server. In which case, the client should be prepared to accept
1624     *            all hits found by the search.
1625     *            <li>setParams[1]: The index of the first hit to be returned
1626     *            to the client, where 1 is the index of the first hit found by
1627     *            the search. If this value is zero (or omitted) the first hit
1628     *            found will be the first hit returned.
1629     *            </ul>
1630     * @return An iterator over the hits found in the search.
1631     * 
1632     * @see CqHitSet#doGetMore(long)
1633     */
1634    CqHitSet doFullTextSearch(SearchFilter searchFilter,
1635                              long... setParams) throws WvcmException;
1636    
1637        /**
1638     * The typeahead enabled search, searches the indexed content of the database for objects that match a
1639     * given filter. Information about each selected object is returned as a
1640     * packet of data called a <i>hit</i>. The matching process assigns a score
1641     * to the hit between 1 and 100, with 100 designating a near-perfect match.
1642     * The hits are ranked according to this score and are returned in order
1643     * highest rank to lowest.
1644     * <p>
1645     * When this method returns, the highest ranking hits will be available
1646     * immediately for inspection on the client. Four arguments are setting the scope of the typeahead search,
1647     * controls which filed of a record is typeahead enabled, and which fields will be searched and put in the result set. 
1648     * If there were more hits found than could be returned immediately, the remaining hits can be
1649     * requested using the CqHitSet.doGetMore() method.
1650     * 
1651         * @param parentRecordTypeLocation A Lcation string specifying which recordType is for the record
1652         * @param parentRecordLocation A String specifying which record is to be selected to do the
1653         *            typeahead
1654         * @param parentRecordFieldNameLocation A Location string specifying which field of the record is typeahead
1655         *            enabled
1656         * @param displayFieldNameLocation A List of Location strings specifying which fields of a recordtype are
1657         *            to be searched and displayed in the result set
1658         * @param searchFilter A SearchFilter specifying which objects of the database are to
1659         *            be selected for inclusion in the result set.
1660         * @param setParams 0, 1, or 2 long values specifying how the hits are to be
1661         *            returned from the server to the client.
1662         *            <ul>
1663         *            <li>setParams[0]: The maximum number of hits the client will
1664         *            accept from the server in the immediate response to this
1665         *            request. Based on the total number of hits found and the load
1666         *            on the server, however, the actual number of hits returned may
1667         *            be less than this number. If this value is zero (or omitted)
1668         *            the number of hits returned will be determined solely by the
1669         *            server. In which case, the client should be prepared to accept
1670         *            all hits found by the search.
1671         *            <li>setParams[1]: The index of the first hit to be returned to
1672         *            the client, where 1 is the index of the first hit found by the
1673         *            search. If this value is zero (or omitted) the first hit found
1674         *            will be the first hit returned.
1675         *            </ul>
1676         * @return An iterator over the hits found in the search.
1677         * @throws WvcmException
1678         */
1679        CqHitSet doFullTextSearch(String parentRecordTypeLocation,
1680                        String parentRecordLocation, String parentRecordFieldNameLocation,
1681                        List<String> displayFieldNameLocation, SearchFilter searchFilter,
1682                        long... setParams) throws WvcmException;
1683}