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