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     * © Copyright IBM Corporation 2004, 2008.  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         * Returns the value of the {@link #REPORT_FORMATS REPORT_FORMATS} property
1003         * as defined by this proxy.
1004         * 
1005         * @return A ResourceList containing a CqReportFormat proxy for each report
1006         *         format defined in the public and personal query folders . Will
1007         *         never be <b>null</b>.
1008         * 
1009         * @throws WvcmException if this proxy does not define a value for the
1010         *             {@link #REPORT_FORMATS REPORT_FORMATS} property.
1011         */
1012        ResourceList<CqReportFormat> getReportFormats() throws WvcmException;
1013    
1014        /**
1015         * Returns a CqUserInfo structure containing read-only information about the
1016         * user currently logged into this database.
1017         */
1018        PropertyName<CqUserInfo> USER_INFO = 
1019            new PropertyName<CqUserInfo>(PROPERTY_NAMESPACE, "user-info");
1020        
1021        /**
1022         * Returns the value of the {@link #USER_INFO USER_INFO} property as defined
1023         * by this proxy.
1024         * 
1025         * @return A CqUserInfo instance containing read-only information about the
1026         *         user currently logged into this database. Will never be <b>null</b>.
1027         * 
1028         * @throws WvcmException if this proxy does not define a value for the
1029         *             {@link #USER_INFO USER_INFO} property.
1030         */
1031        CqUserInfo getUserInfo() throws WvcmException;
1032    
1033        /**
1034         * Removes all modified and moribund resources from the change context of
1035         * this database; thereby reverting those resources to their previous,
1036         * unmodified or undeleted state.
1037         * 
1038         * @param feedback A Feedback object requesting properties of this database
1039         *            and/or properties of the reverted resources to be returned
1040         *            from the server after successful completion of the operation.
1041         * 
1042         * @throws WvcmException If the resources cannot be reverted.
1043         */
1044        CqUserDb doClearContext(Feedback feedback) throws WvcmException;
1045    
1046        /**
1047         * Selectively delivers (commits) modified resources to the database and/or
1048         * destroys moribund resources from the database and removes them from the
1049         * change context.
1050         * <p>
1051         * NOTE: A ClearQuest query created and delivered in one CqProvider instance
1052         * may not appear in another already-existing CqProvider instance. To make
1053         * them available, create a new CqProvider instance <b>after</b> the
1054         * delivery is complete.
1055         * <p>
1056         * Known places in the implementation that will have this problem include:<br>
1057         * Creation or deletion of a ClearQuest query (modification is OK).<br>
1058         * Creation or deletion of a ClearQuest CqQueryFolder.<br>
1059         * Modification of a ClearQuest CqDynamicChoiceList (creation is not
1060         * supported anyway).
1061         * 
1062         * @param feedback A request for specific properties from the resources that
1063         *            were directly or indirectly impacted by this operation, which,
1064         *            in this case would be the modified resources that were
1065         *            delivered by this operation. May be <b>null</b>; in which
1066         *            case this information will not be requested from the server.
1067         * @param deliveryOrder The modified and moribund resources currently in
1068         *            this change context that are to be delivered or deleted. They
1069         *            will be delivered or deleted in the order specified by the
1070         *            proxies in the given list. To deliver/delete all
1071         *            modified/moribund resources in an arbitrary order, use
1072         *            {@link CqProvider#DELIVER_ALL}. Must not be <b>null</b> nor
1073         *            any of the other special delivery order constants AUTO, HOLD,
1074         *            or DELIVER.
1075         * 
1076         * @throws WvcmException if any preconditions are not satisfied or if other
1077         *             errors are detected while writing the records to the
1078         *             database.
1079         */
1080    
1081        CqUserDb doDeliver(Feedback feedback,
1082                           List<CqContextResource> deliveryOrder)
1083            throws WvcmException;
1084    
1085        /**
1086         * Selectively reverts modified or moribund resources in this database's
1087         * change context to their previous, unmodified/undeleted state. To revert
1088         * all resources in the change context, in an arbitrary order, use
1089         * {@link #doClearContext(Feedback)}. This operation is semantically
1090         * equivalent to invoking doRevert() on each resource in the given list, but
1091         * will be more efficient because there is only one round-trip to the server
1092         * required.
1093         * <p>
1094         * Note that doRevert removes all changes to the resource from the change
1095         * context. It is not an undo operation, but a revert. If multiple changes
1096         * have been made to a resource (since the last time it was delivered) they
1097         * will all be discarded by doRevert.
1098         * 
1099         * @param feedback A request for specific properties from the resources that
1100         *            were directly or indirectly impacted by this operation, which,
1101         *            in this case would be the modified/moribund resources that
1102         *            were reverted by this operation. May be <b>null</b>; in which
1103         *            case this information will not be requested from the server.
1104         * @param revertOrder The modified/moribund resources currently in this
1105         *            change context to be reverted to their original state. They
1106         *            will be reverted/undeleted in the order specified by the
1107         *            proxies in this argument. Must not be <b>null</b> nor any of
1108         *            the special delivery order constants AUTO, HOLD, DELIVER, or
1109         *            DELIVER_ALL.
1110         * 
1111         * @throws WvcmException if any preconditions are not satisfied or if other
1112         *             errors are detected while writing the records to the
1113         *             database.
1114         */
1115    
1116        CqUserDb doRevert(Feedback feedback,
1117                          List<CqContextResource> revertOrder) throws WvcmException;
1118    
1119        /**
1120         * Searches the database for records having a given display name.
1121         * 
1122         * @param displayName A String containing the display name of the record to
1123         *            be found.
1124         * 
1125         * @param possibleRecordTypes An array of locations containing a
1126         *            CqRecordType location for each type of record to be considered
1127         *            in the search. May not contain record type family names. May
1128         *            be <b>null</b> or empty to force consideration of all record
1129         *            types.
1130         *            <p>
1131         *            The record type array is used to control the search for the
1132         *            record identified by the displayName argument. This list of
1133         *            record types is iterated and processed in the order given
1134         *            until a record is found. If any of the record type locations
1135         *            provided in this argument is invalid (such as referring to a
1136         *            record type family), an exception is thrown that identifies
1137         *            the invalid location. If a null or empty array value is
1138         *            provided, all record types defined in the schema are searched,
1139         *            with the search order being from the most frequently found
1140         *            record type searched first to the least found record type
1141         *            being searched last.
1142         * 
1143         * @param mode A FindMode enumerator identifying the type of record to
1144         *            search for.
1145         * 
1146         * @param feedback A Feedback object in which may be requested search
1147         *            progress reports and additional properties to be included in
1148         *            the result proxy. May be <b>null</b> if no additional
1149         *            feedback is needed.
1150         * 
1151         * @return A CqRecord proxy representing a record of one of the requested
1152         *         types or type categories whose display name matches the given
1153         *         displayName argument; <b>null</b> if no such record can be
1154         *         found. If a record is found, the returned proxy will be populated
1155         *         with the properties requested by the feedback parameter.
1156         * 
1157         * @throws WvcmException If the search as specified could not be completed;
1158         *             for example, if the database or the specified record types
1159         *             are not accessible. If all record types can be searched as
1160         *             specified, failure to find a matching record <i>does not</i>
1161         *             cause an exception but results in a null result.
1162         */
1163        CqRecord doFindRecord(String displayName,
1164                              FindMode mode,
1165                              Feedback feedback,
1166                              Location... possibleRecordTypes) throws WvcmException;
1167    
1168        /**
1169         * Searches the database for records having a given dbid.
1170         * 
1171         * @param dbid The dbid of the record to be found.
1172         * 
1173         * @param mode A FindMode enumerator identifying the type of record to
1174         *            search for.
1175         * 
1176         * @param possibleRecordTypes An array of locations containing a
1177         *            CqRecordType location for each type of record to be considered
1178         *            in the search. May not contain record type family names. May
1179         *            be <b>null</b> or empty to force consideration of all record
1180         *            types.
1181         *            <p>
1182         *            The record type array is used to control the search for the
1183         *            record identified by the displayName argument. This list of
1184         *            record types is iterated and processed in the order given
1185         *            until a record is found. If any of the record type locations
1186         *            provided in this argument is invalid (such as referring to a
1187         *            record type family), an exception is thrown that identifies
1188         *            the invalid location. If a null or empty array value is
1189         *            provided, all record types defined in the schema are searched,
1190         *            with the search order being from the most frequently found
1191         *            record type searched first to the least found record type
1192         *            being searched last.
1193         * 
1194         * @param feedback A Feedback object in which may be requested search
1195         *            progress reports and additional properties to be included in
1196         *            the result proxy. May be <b>null</b> if no additional
1197         *            feedback is needed.
1198         * 
1199         * @return A CqRecord proxy representing a record of one of the requested
1200         *         types or type categories whose dbid name matches the given
1201         *         dbid argument; <b>null</b> if no such record can be
1202         *         found. If a record is found, the returned proxy will be populated
1203         *         with the properties requested by the feedback parameter.
1204         * 
1205         * @throws WvcmException If the search as specified could not be completed;
1206         *             for example, if the database or the specified record types
1207         *             are not accessible. If all record types can be searched as
1208         *             specified, failure to find a matching record <i>does not</i>
1209         *             cause an exception but results in a null result.
1210    
1211         * @see #doFindRecord(long, com.ibm.rational.wvcm.stp.cq.CqUserDb.FindMode,
1212         *      Feedback, Location[])
1213         */
1214        CqRecord doFindRecord(long dbid,
1215                              FindMode mode,
1216                              Feedback feedback,
1217                              Location... possibleRecordTypes) throws WvcmException;
1218    
1219        /**
1220         * Enumerates the options for restricting the finding of records based on
1221         * their record class.
1222         */
1223        enum FindMode implements StpExEnumeration
1224        {
1225            FIND_ANY_RECORD, FIND_STATELESS_RECORD, FIND_STATEFUL_RECORD;
1226        }
1227    
1228        /**
1229         * Returns a list of all the resources in the database whose names differ
1230         * from a given name only in their site extensions. Currently, only query
1231         * folder items and records of a stateless record type could possibly need
1232         * site extensions to disambiguate them, so applying this method to any
1233         * other resource is simply a waste of time and is likely to raise an
1234         * exception.
1235         * <p>
1236         * Applying this method to a stateless record type location has a special
1237         * meaning. In that case <i>all</i> instances of that record type that
1238         * require site extension are returned.
1239         * 
1240         * @param name A (potentially ambiguous) user-friendly location
1241         *            specification for a ClearQuest record, record type, or query
1242         *            folder item, whose repo field, if present, must name this
1243         *            database.
1244         * 
1245         * @param feedback A Feedback object in which may be requested search
1246         *            progress reports and additional properties to be included in
1247         *            the result proxies. May be <b>null</b> if no additional
1248         *            feedback is needed.
1249         * 
1250         * @return A ResourceList containing a proxy for each resource in the
1251         *         database whose site-extended name differs from the given name
1252         *         only in the site extensions used. Will never be <b>null</b> or
1253         *         empty.
1254         * 
1255         * @throws WvcmException If the database is not accessible, if the given
1256         *             name identifies a resource other than a record or query
1257         *             folder item in this database, or if the given name cannot be
1258         *             extended in any way to name any resource.
1259         */
1260        ResourceList<CqResource> doFindSiteExtendedNames(StpLocation name,
1261                                                         Feedback feedback)
1262            throws WvcmException;
1263    
1264        /**
1265         * Upgrades this database's user and group information to match that of its
1266         * db-set. This method copies the changes from the db-set to the user
1267         * database. You should call this function to upgrade a database after
1268         * making changes to the users and groups of the db-set.
1269         * 
1270         * @param feedback Specifies optional feedback to the caller.
1271         * @return A proxy for this user database (after the upgrade is complete),
1272         *         whose properties are specified by feedback.
1273         * @throws WvcmException
1274         */
1275        CqUserDb doUpgradeUsersAndGroups(Feedback feedback) throws WvcmException;
1276    
1277        /**
1278         * Verifies that a CqQueryFolderItem of a given type can be created at a
1279         * given location. The operation checks that the characters used in the
1280         * location are valid for the target database and that no resource currently
1281         * exists at the specified location.
1282         * 
1283         * @param item A proxy for the item whose location is to be tested.
1284         * 
1285         * @param feedback A Feedback object that specifies the properties to be
1286         *            included in the result proxy (if a resource exists at the
1287         *            specified location). If the argument is null, the properties
1288         *            defined by the result proxy are unspecified.
1289         * 
1290         * @return If the location is valid and there is no resource currently at
1291         *         the specified location, the result is <b>null</b>. If the
1292         *         location is valid, but a resource already exists at that
1293         *         location, a proxy for that resource is returned, populated with
1294         *         any properties requested by the feedback argument.
1295         * 
1296         * @throws WvcmException if the location is not valid on the target
1297         *             database.
1298         */
1299        CqQueryFolderItem doValidateLocation(CqQueryFolderItem item,
1300                                             Feedback feedback)
1301            throws WvcmException;
1302    
1303        /**
1304         * The interface for an API object that may be used to define a filter for a
1305         * full-text search of the database. The search key specifies an attribute
1306         * of the database object whose value will be used to select the object for
1307         * inclusion in the result set of the full-text search. In the SearchFilter,
1308         * each SearchKey is associated with a target value that specifies what
1309         * attribute values will cause the object to be selected.
1310         * <p>
1311         * The currently defined SearchKey types are
1312         * <ul>
1313         * <li>{@link SearchLevel}: (SearchKey&lt;String>) selects an object
1314         * having any field matching the specification in the target String. The
1315         * SearchMode enumerator specifies the type of specification to be found in
1316         * the target string. Currently there is only one SearchMode, SIMPLE, which
1317         * represents a full-text search using a simple specification.
1318         * <li>{@link WordMode}: (SearchKey&lt;List&lt;String>>) selects an object
1319         * having any field matching the words in the target list. The WordMode
1320         * enumerator specifies how the target words must match a field to select
1321         * the object.
1322         * <li>{@link DateLimit}: (SearchKey&lt;Date>) selects an object based on
1323         * the relationship between the object's creation or modification date and
1324         * the target date. The DateLimit enumerator specifies which date attribute
1325         * to compare against and the relationship with the target date that will
1326         * select the object.
1327         * <li>{@link CqRecordType}: (SearchKey&lt;Boolean>) selects a record
1328         * based on its record type. If the target value is Boolean.TRUE, a record
1329         * whose record type is the same as the record type denoted by the
1330         * CqRecordType object will be selected. If several CqRecordType keys (with
1331         * TRUE target values) are present in a SearchFilter, a record having anyone
1332         * of those record types is selected.
1333         * <li>{@link CqFieldDefinition}: (SearchKey&lt;List&lt;String>>) selects
1334         * a record having a specific field whose value matches all of the target
1335         * strings. The CqFieldDefinition specifies the record type and the field of
1336         * that record type that must match the target strings. Each target string
1337         * is a simple search specification.
1338         * </ul>
1339         * 
1340         * @param <T> The type of object used to specify the value or values that
1341         *            will select or reject an object based on the value it has for
1342         *            the key attribute.
1343         */
1344        public static interface SearchKey<T>
1345        {}
1346    
1347        /**
1348         * WordMode SearchKeys limit the search results to just those objects that
1349         * contain the targeted words associated with the WordMode key in the
1350         * filter.
1351         */
1352        public static enum WordMode implements SearchKey<List<String>>
1353        {
1354            /** Match all of the words in the target list */
1355            ALL,
1356            /** Match all of the words in the target list in the order given */
1357            EXACT,
1358            /** Match any (at least one) of the words in the target list */
1359            ANY,
1360            /** Match none (do not match any) of the words in the target list */
1361            NONE
1362        }
1363    
1364        /**
1365         * A DateLimit SearchKey limits the search to just those objects whose
1366         * creation or modification time are in a target range.
1367         */
1368        public static enum DateLimit implements SearchKey<Date>
1369        {
1370            /** Matches an object created on or after the target date */
1371            CREATED_AFTER,
1372    
1373            /** Matches an object created on or before the target date */
1374            CREATED_BEFORE,
1375    
1376            /** Matches an object modified on or after the target date */
1377            MODIFIED_AFTER,
1378    
1379            /** Matches an object modified on or before the target date */
1380            MODIFIED_BEFORE
1381        }
1382    
1383        /** Specifies a simple search string */
1384        public static enum SearchLevel implements SearchKey<String>
1385        {
1386            /** Interpret the associated argument as a simple search string and
1387             * match accordingly against that.
1388             */
1389            SIMPLE
1390        }
1391    
1392        /**
1393         * A collection of SearchKey/target-value pairs that collectively define the
1394         * filter for selecting objects for inclusion in a full-text search. In
1395         * general, an object must match all of the given keys in the filter to be
1396         * added to the result set. The only exception to this rule are the
1397         * CqRecordType keys. If more than one CqRecordType key is present, the
1398         * object needs only match one of them to be a candidate for the result
1399         * set--the object would need to match all the other types of keys to
1400         * actually be selected.
1401         */
1402        public static interface SearchFilter
1403        {
1404            /**
1405             * Adds a SearchKey and its target value to the full text search filter.
1406             * Each SearchKey specifies what attribute of an object is to be
1407             * filtered on and the target value specifies the value against which
1408             * the attribute value will be compared for possible inclusion in the
1409             * result set.
1410             * 
1411             * @param <U> The data type used to specify the target value. This type
1412             *            must match the type parameter of the key used and so
1413             *            currently this must be String, List&lt;String>, Date, or
1414             *            Boolean.
1415             * @param key A SearchKey&lt;U> object representing the attribute of
1416             *            each candidate object that the search should filter on.
1417             *            Currently this may be a SearchLevel enumerator, a
1418             *            DateLimit enumerator, a WordMode enumerator, a
1419             *            CqRecordType proxy, or a CqFieldDefinition proxy.
1420             * @param targetValue An instance of class U that specifies which values
1421             *            of the key attribute will select or reject a record in the
1422             *            search. If this value is <b>null</b> (or Boolean.FALSE)
1423             *            the corresponding SearchKey will be removed from the
1424             *            search specification.
1425             * @return The value previously associated with the SearchKey.
1426             */
1427            <U> U put(SearchKey<U> key,
1428                      U targetValue);
1429    
1430            /**
1431             * Extends the target value list associated with a SearchKey by a single
1432             * item.
1433             * 
1434             * @param <U> The type of item in a target value list; currently must be
1435             *            String.
1436             * @param key The SearchKey whose target value list is to be extended.
1437             *            The SeachKey does not need to already be in the
1438             *            SearchFilter. Currently the SearchKey must be a WordMode
1439             *            enumerator or a CqFieldDefinition proxy.
1440             * @param targetItem The new item to be added to the target value list
1441             * @return The target value list after modification.
1442             */
1443            <U> List<U> add(SearchKey<List<U>> key,
1444                            U targetItem);
1445    
1446            /**
1447             * Returns the target value currently associated with a given SearchKey
1448             * 
1449             * @param <U> The data type used to specify the value against which the
1450             *            key attribute will be compared. This type must match the
1451             *            type parameter of the key used and so currently this must
1452             *            be String, List&lt;String>, Date, or Boolean.
1453             * @param key A SearchKey<U> object representing the attribute of each
1454             *            candidate record that the search should filter on.
1455             *            Currently this may be a SearchLevel enumerator, a
1456             *            DateLimit enumerator, a WordMode enumerator, a
1457             *            CqRecordType proxy, or a CqFieldDefinition proxy.
1458             * @return The value currently associated with the given key in this
1459             *         search filter; <b>null</b> if no association is currently
1460             *         defined.
1461             */
1462            <U> U get(SearchKey<U> key);
1463    
1464            /**
1465             * @return A List of all the SearchKey/target-values pairs defined by
1466             *         this SearchFilter.
1467             */
1468            List<Map.Entry<SearchKey<Object>, Object>> getAll();
1469    
1470            /**
1471             * Retrieves SearchKey/target-value pairs of a given target-value type
1472             * 
1473             * @param <U> The data type used to specify the value against which the
1474             *            key attribute will be compared. This type must match the
1475             *            type parameter of a defined SearchKey and so currently
1476             *            this must be String, List&lt;String>, Date, or Boolean.
1477             * @param type The Class object for the desired target-value data type.
1478             * @return All of the entries in this SearchFilter whose target value
1479             *         type matches the given type. The result will never be <b>null</b>,
1480             *         but the returned list may be empty.
1481             */
1482            <U> List<Map.Entry<SearchKey<U>, U>> getEntries(Class<U> type);
1483    
1484            /**
1485             * Retrieves SearchKey/target-value pairs by SearchKey type
1486             * 
1487             * @param <U> The data type used to specify the value against which the
1488             *            key attribute will be compared. This type must match the
1489             *            type parameter of a defined SearchKey and so currently
1490             *            this must be String, List&lt;String>, Date, or Boolean.
1491             * @param <V> A subclass of SearchKey<U>
1492             * @param keyType The type of keys to retrieve from this search
1493             *            specification
1494             * @return All entries of this SearchFilter whose key is of the
1495             *         specified type. The result will never be null, but the
1496             *         returned list may be empty.
1497             */
1498            <V extends SearchKey<U>, U> List<Map.Entry<V, U>> getEntriesByKey(Class<V> keyType);
1499    
1500            /**
1501             * @return The SearchLevel entry of this SearchFilter; otherwise null
1502             */
1503            Map.Entry<SearchLevel, String> getStringFilter();
1504    
1505            /**
1506             * @return A list of the CqRecordType entries of this SearchFilter; will
1507             *         never be <b>null</b> but the list may be empty.
1508             */
1509            List<Map.Entry<CqRecordType, Boolean>> getRecordTypeFilters();
1510    
1511            /**
1512             * @return A list of the CqFieldDefinition entries of this SearchFilter;
1513             *         will never be <b>null</b> but the list may be empty.
1514             */
1515            List<Map.Entry<CqFieldDefinition, List<String>>> getFieldFilters();
1516    
1517            /**
1518             * @return A list of the WordMode entries of this SearchFilter; will
1519             *         never be <b>null</b> but the list may be empty.
1520             */
1521            List<Map.Entry<WordMode, List<String>>> getWordFilters();
1522    
1523            /**
1524             * @return A list of the DateLimit entries of this SearchFilter; will
1525             *         never be <b>null</b> but the list may be empty.
1526             */
1527            List<Map.Entry<DateLimit, Date>> getDateFilters();
1528    
1529            /**
1530             * Removes all SearchKey entries from this SearchFilter
1531             */
1532            void clear();
1533        }
1534    
1535        /**
1536         * Constructs a SearchFilter instance with an initial simple specification
1537         * string.
1538         * 
1539         * @param simpleString A search specification using the simple specification
1540         *            syntax. If <b>null</b>, an empty SearchFilter will be
1541         *            returned.
1542         * @return A SearchFilter instance defining the simple search specification
1543         *         derived from the simpleString argument.
1544         */
1545        SearchFilter buildSearchFilter(String simpleString);
1546    
1547        /**
1548         * Searches the indexed content of the database for objects that match a
1549         * given filter. Information about each selected object is returned as a
1550         * packet of data called a <i>hit</i>. The matching process assigns a score
1551         * to the hit between 1 and 100, with 100 designating a near-perfect match.
1552         * The hits are ranked according to this score and are returned in order
1553         * highest rank to lowest.
1554         * <p>
1555         * When this method returns, the highest ranking hits will be available
1556         * immediately for inspection on the client. An argument to this method
1557         * controls the size of this first set of hits. If there were more hits
1558         * found than could be returned immediately, the remaining hits can be
1559         * requested using the CqHitSet.doGetMore() method.
1560         * 
1561         * @param searchFilter A SearchFilter specifying which objects of the
1562         *            database are to be selected for inclusion in the result set.
1563         * @param setParams 0, 1, or 2 long values specifying how the hits are to be
1564         *            returned from the server to the client.
1565         *            <ul>
1566         *            <li>setParams[0]: The maximum number of hits the client will
1567         *            accept from the server in the immediate response to this
1568         *            request. Based on the total number of hits found and the load
1569         *            on the server, however, the actual number of hits returned may
1570         *            be less than this number. If this value is zero (or omitted)
1571         *            the number of hits returned will be determined solely by the
1572         *            server. In which case, the client should be prepared to accept
1573         *            all hits found by the search.
1574         *            <li>setParams[1]: The index of the first hit to be returned
1575         *            to the client, where 1 is the index of the first hit found by
1576         *            the search. If this value is zero (or omitted) the first hit
1577         *            found will be the first hit returned.
1578         *            </ul>
1579         * @return An iterator over the hits found in the search.
1580         * 
1581         * @see CqHitSet#doGetMore(long)
1582         */
1583        CqHitSet doFullTextSearch(SearchFilter searchFilter,
1584                                  long... setParams) throws WvcmException;
1585    }