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