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