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