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