001    /*
002     * file CqProvider.java
003     *
004     * Licensed Materials - Property of IBM
005     * Restricted Materials of IBM 
006     *
007     * com.ibm.rational.wvcm.stp.cq.CqProvider
008     *
009     * � Copyright IBM Corporation 2004, 2009.  All Rights Reserved.
010     * Note to U.S. Government Users Restricted Rights:  Use, duplication or 
011     * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp.
012     */
013    
014    package com.ibm.rational.wvcm.stp.cq;
015    
016    import java.util.ArrayList;
017    import java.util.List;
018    
019    import javax.wvcm.Feedback;
020    import javax.wvcm.ResourceList;
021    import javax.wvcm.WvcmException;
022    import javax.wvcm.PropertyNameList.PropertyName;
023    
024    import com.ibm.rational.wvcm.stp.StpLocation;
025    import com.ibm.rational.wvcm.stp.StpProvider;
026    import com.ibm.rational.wvcm.stp.cq.CqQuery.DisplayField;
027    
028    /**
029     * An extension of the StpProvider interface with additions specific to
030     * ClearQuest databases.
031     * <p>
032     */
033    public interface CqProvider extends StpProvider
034    {
035        /**
036         * The name of a CqProvider class whose instances provide access only to
037         * ClearQuest objects via a local installation of ClearQuest. Pass this name
038         * to ProviderFactory.createProvider to obtain an object that implements
039         * this interface.
040         */
041        String CQ_ONLY_PROVIDER_CLASS =
042            "com.ibm.rational.stp.client.internal.cq.CqJniOnlyProvider";
043    
044        /**
045         * A distinguished instance of List for use in the various CqContextResource
046         * operations that take a delivery order parameter. It indicates that
047         * resources modified by the operation are to be delivered in an unspecified
048         * order. But the delivery is to be attempted only if the change context did
049         * not contain the resource targeted by the operation. If the change context
050         * already contained the targeted resource when the operation started, no
051         * delivery is attempted. Thus AUTO behaves like {@link #DELIVER_ALL} or
052         * {@link #HOLD} depending on the content of the change context at the start
053         * of the operation.
054         * <p>
055         * Where an interface defines a second method that adds only a delivery
056         * order List parameter to the first, the first method's behavior is defined
057         * as if the second method had been passed this special instance. For
058         * example, under this convention,
059         * {@link CqContextResource#doWriteProperties(Feedback)} is defined as
060         * 
061         * <pre>
062         * return doWriteProperties(feedback, CqProvider.AUTO);
063         * </pre>
064         */
065        List<CqContextResource> AUTO = new ArrayList<CqContextResource>();
066    
067        /**
068         * A distinguished instance of List for use in the various CqContextResource
069         * operations that take a delivery order parameter. It indicates that all
070         * modified resources in the change context are to be delivered in an
071         * unspecified order.
072         */
073        List<CqContextResource> DELIVER_ALL = new ArrayList<CqContextResource>();
074    
075        /**
076         * A distinguished instance of List for use in the various CqContextResource
077         * operations that take a delivery order parameter. It indicates that
078         * modified resources in the change context are not to be delivered, but are
079         * to be held in the change context until the next explicit delivery
080         * request.
081         */
082        List<CqContextResource> HOLD = new ArrayList<CqContextResource>();
083    
084        /**
085         * A distinguished instance of List for use in the various CqContextResource
086         * operations that take a delivery order parameter. It indicates that any
087         * resource targeted by the current operation is to be delivered at the
088         * successful termination of the operation.
089         */
090        List<CqContextResource> DELIVER = new ArrayList<CqContextResource>();
091    
092        /**
093         * Returns a list of database sets accessible from this provider.
094         * 
095         * @param feedback The CqDbSet properties to be included on each returned
096         *            CqDbSet proxy. If not <b>null</b>, an attempt will be made to
097         *            log into each database set (using credentials provided by the
098         *            provider's Callback for the database set). If login to a
099         *            database set is not successful, the resource error field of
100         *            the corresponding CqDbSet proxy will be non-null and contain
101         *            the exception thrown by the provider's Callback object.
102         *            <p>
103         *            To construct a list of accessible user databases, request the
104         *            {@link CqDbSet#ACCESSIBLE_DATABASES} property from each
105         *            database set.
106         * @return A list of CqDbSet proxies for the potentially accessible database
107         *         sets.
108         * @throws WvcmException If an error other than a failed login are detected.
109         *             If login to a master database is required (because properties
110         *             have been requested) and the login fails, a proxy for the
111         *             database set is included in the result list, but the value of
112         *             CqDbSet.getResourceError() will be non-null and that proxy
113         *             will contain none of the requested properties.
114         */
115        ResourceList<CqDbSet> doGetDbSetList(Feedback feedback)
116            throws WvcmException;
117    
118        /**
119         * Creates a proxy for a ClearQuest action resource.
120         * 
121         * @param location StpLocation for a ClearQuest action.
122         * 
123         * @return The new CqAction proxy.
124         * 
125         * @throws WvcmException if StpLocation is not a ClearQuest resource
126         *             location.
127         */
128        CqAction cqAction(StpLocation location);
129    
130        /**
131         * Creates a proxy for a ClearQuest attachment resource.
132         * 
133         * @param location StpLocation for a ClearQuest attachment.
134         * 
135         * @return The new CqAttachment proxy.
136         * 
137         * @throws WvcmException if StpLocation is not a ClearQuest resource
138         *             location.
139         */
140        CqAttachment cqAttachment(StpLocation location);
141    
142        /**
143         * Creates a proxy for a ClearQuest attachment folder resource.
144         * 
145         * @param location StpLocation for a ClearQuest attachment folder.
146         * 
147         * @return The new CqAttachmentFolder proxy.
148         * 
149         * @throws WvcmException if StpLocation is not a ClearQuest resource
150         *             location.
151         */
152        CqAttachmentFolder cqAttachmentFolder(StpLocation location);
153    
154        /**
155         * Creates a proxy for a ClearQuest database set resource.
156         * 
157         * @param location StpLocation for a ClearQuest db-set.
158         * 
159         * @return The new CqDbSet proxy.
160         * 
161         * @throws WvcmException if StpLocation is not a ClearQuest resource
162         *             location.
163         */
164        CqDbSet cqDbSet(StpLocation location);
165    
166        /**
167         * Creates a proxy for a ClearQuest dynamic choice list resource.
168         * 
169         * @param location StpLocation for a ClearQuest dynamic choice list.
170         * 
171         * @return The new CqDynamicChoiceList proxy.
172         * 
173         * @throws WvcmException if StpLocation is not a ClearQuest resource
174         *             location.
175         */
176        CqDynamicChoiceList cqDynamicChoiceList(StpLocation location);
177    
178        /**
179         * Creates a proxy for a ClearQuest field definition resource.
180         * 
181         * @param location StpLocation for a ClearQuest field definition.
182         * 
183         * @return The new CqFieldDefinition proxy.
184         * 
185         * @throws WvcmException if StpLocation is not a ClearQuest resource
186         *             location.
187         */
188        CqFieldDefinition cqFieldDefinition(StpLocation location);
189    
190        /**
191         * Creates a proxy for a ClearQuest group resource.
192         * 
193         * @param location StpLocation for a ClearQuest group.
194         * 
195         * @return The new CgGroup proxy.
196         * 
197         * @throws WvcmException if StpLocation is not a ClearQuest resource
198         *             location.
199         */
200        CqGroup cqGroup(StpLocation location);
201    
202        /**
203         * Creates a proxy for a ClearQuest hook resource.
204         * 
205         * @param location StpLocation for a ClearQuest hook.
206         * 
207         * @return The new CgHook proxy.
208         * 
209         * @throws WvcmException if StpLocation is not a ClearQuest resource
210         *             location.
211         */
212        CqHook cqHook(StpLocation location);
213    
214        /**
215         * Creates a proxy for a ClearQuest query resource.
216         * 
217         * @param location StpLocation for a ClearQuest query.
218         * 
219         * @return The new Query proxy.
220         * 
221         * @throws WvcmException if StpLocation is not a ClearQuest resource
222         *             location.
223         */
224        CqQuery cqQuery(StpLocation location);
225    
226        /**
227         * Creates a proxy for a ClearQuest query folder resource.
228         * 
229         * @param location StpLocation for a ClearQuest query folder.
230         * 
231         * @return The new CqQueryFolder proxy.
232         * 
233         * @throws WvcmException if StpLocation is not a ClearQuest resource
234         *             location.
235         */
236        CqQueryFolder cqQueryFolder(StpLocation location);
237    
238        /**
239         * Creates a proxy for a resource in a ClearQuest query folder.
240         * 
241         * @param location StpLocation for a ClearQuest query folder item.
242         * 
243         * @return The new CqQueryFolderItem proxy.
244         * 
245         * @throws WvcmException if StpLocation is not a ClearQuest resource
246         *             location.
247         */
248        CqQueryFolderItem cqQueryFolderItem(StpLocation location);
249    
250        /**
251         * Creates a proxy for a ClearQuest record resource.
252         * 
253         * @param location StpLocation for a ClearQuest record.
254         * 
255         * @return The new CqRecord proxy.
256         * 
257         * @throws WvcmException if StpLocation is not a ClearQuest resource
258         *             location.
259         */
260        CqRecord cqRecord(StpLocation location);
261    
262        /**
263         * Creates a proxy for a ClearQuest record-type resource.
264         * 
265         * @param location StpLocation for a ClearQuest record-type.
266         * 
267         * @return The new CqRecordType proxy.
268         * 
269         * @throws WvcmException if StpLocation is not a ClearQuest resource
270         *             location.
271         */
272        CqRecordType cqRecordType(StpLocation location);
273    
274        /**
275         * Creates a proxy for a ClearQuest replica resource.
276         * 
277         * @param location StpLocation for a ClearQuest replica.
278         * 
279         * @return The new CqReplica proxy.
280         * 
281         * @throws WvcmException if StpLocation is not a ClearQuest resource
282         *             location.
283         */
284        CqReplica cqReplica(StpLocation location);
285    
286        /**
287         * Creates a proxy for a ClearQuest report resource.
288         * 
289         * @param location StpLocation for a ClearQuest report.
290         * 
291         * @return The new CqReport proxy.
292         * 
293         * @throws WvcmException if StpLocation is not a ClearQuest resource
294         *             location.
295         */
296        CqReport cqReport(StpLocation location);
297    
298        /**
299         * Creates a proxy for a ClearQuest report format resource.
300         * 
301         * @param location StpLocation for a ClearQuest report format.
302         * 
303         * @return The new CqReportFormat proxy.
304         * 
305         * @throws WvcmException if StpLocation is not a ClearQuest resource
306         *             location.
307         */
308        CqReportFormat cqReportFormat(StpLocation location);
309    
310        /**
311         * Creates a proxy for a ClearQuest user resource.
312         * 
313         * @param location StpLocation for a ClearQuest user.
314         * 
315         * @return The new CqUser proxy.
316         * 
317         * @throws WvcmException if StpLocation is not a ClearQuest resource
318         *             location.
319         */
320        CqUser cqUser(StpLocation location);
321    
322        /**
323         * Creates a proxy for a ClearQuest user database resource.
324         * 
325         * @param location StpLocation for a ClearQuest user database.
326         * 
327         * @return The new CqUserDb proxy.
328         * 
329         * @throws WvcmException if StpLocation is not a ClearQuest resource
330         *             location.
331         */
332        CqUserDb cqUserDb(StpLocation location);
333    
334        /**
335         * Create a new CqFieldValue structure for a field of a given name and type.
336         * 
337         * @param name The PropertyName for the field.
338         * @param type The type of the field.
339         * @return A CqFieldValue structure.
340         */
341        <U> CqFieldValue<U> cqFieldValue(PropertyName<U> name,
342                                         CqFieldValue.ValueType type);
343    
344        /**
345         * An extension of the
346         * {@link com.ibm.rational.wvcm.stp.StpProvider.StpProductInfo} interface
347         * specifying the additional information available from a ClearQuest
348         * repository.
349         */
350        static public interface CqProductInfo extends StpProductInfo
351        {
352            /**
353             * @return The name of the default database set on the server
354             */
355            String getDefaultDbSetName();
356    
357            /**
358             * @return The major version number of the object model supported by
359             * the server.
360             */
361            long getObjectModelVersionMajor();
362    
363            /**
364             * @return The minor version number of the object model supported by
365             * the server.
366             */
367            long getObjectModelVersionMinor();
368        }
369    
370        /**
371         * Constructs a visible DisplayField object for defining Query display
372         * fields
373         * 
374         * @param path A CqFieldDefinition[] specifying the field path for the
375         *            display field. The first entry of the array must be a
376         *            CqFieldDefinition for a field of the query's primary record
377         *            type. Entry N is allowed only if entry N-1 is a field of type
378         *            {@link CqFieldValue.ValueType#RESOURCE} or
379         *            {@link CqFieldValue.ValueType#RESOURCE_LIST} and entry N is a
380         *            field of the record type named by the
381         *            {@link CqFieldDefinition#REFERENCED_RECORD_TYPE}
382         * 
383         * @return A DisplayField object for specifying a column of the result set
384         *         of a query.
385         */
386        public DisplayField buildDisplayField(CqFieldDefinition... path);
387    
388        /**
389         * Constructs a new DisplayField object for this Query proxy
390         * 
391         * @param path The field path for the display field (see
392         *            {@link #buildDisplayField(CqFieldDefinition[])})
393         * @param isVisible Whether or not the display field is to be visible
394         * 
395         * @return A DisplayField object for specifying a column of the result set
396         *         of a query initialized to the given path a visibility.
397         */
398        public DisplayField buildDisplayField(CqFieldDefinition[] path,
399                                              boolean isVisible);
400    
401        /**
402         * Constructs a new {@link CqQuery.FilterLeaf} object to be used in the
403         * creation or modification of a query's filtering expression.
404         * 
405         * @param operation The comparison Operation code for this filter node. Must
406         *            not be <b>null</b>.
407         * @param source The field path representing the left operand of the
408         *            operation. See {@link CqQuery.FilterLeaf#getSource}
409         *            documentation for more discussion of field paths. Must not be
410         *            <b>null</b>.
411         * @param targets An array of righthand side target types/values suitable as
412         *            an argument to {@link CqQuery.FilterLeaf#setTargets(Object[])}
413         * 
414         * @return A CqQuery.FilterLeaf object specifying the comparison of a field
415         *         value against a target value
416         */
417        public CqQuery.FilterLeaf buildFilterLeaf(CqFieldDefinition[] source,
418                                                  CqQuery.Filter.Operation operation,
419                                                  Object... targets);
420    
421        /**
422         * Constructs a new CqQuery.FilterNode object for the purpose of creating or
423         * modifying the filtering expression of a query.
424         * 
425         * @param operation Either {@link CqQuery.Filter.Operation#CONJUNCTION} or
426         *            {@link CqQuery.Filter.Operation#DISJUNCTION}. Must not be
427         *            <b>null</b>.
428         * @param operands The filter subexpressions to be combined to form a new
429         *            filter expression. Must not be <b>null</b>.
430         * 
431         * @return A CqQuery.FilterNode object for specifying the logical
432         *         combination of filtering subexpressions
433         */
434        public CqQuery.FilterNode buildFilterNode(CqQuery.Filter.Operation operation,
435                                                  CqQuery.Filter... operands);
436    
437        /**
438         * Constructs a new CqQuery.FilterNode object for the purpose of creating or
439         * modifying the filtering expression of a query.
440         * 
441         * @param operation Either {@link CqQuery.Filter.Operation#CONJUNCTION} or
442         *            {@link CqQuery.Filter.Operation#DISJUNCTION}. Must not be
443         *            <b>null</b>.
444         * @param operands The filter subexpressions to be combined to form a new
445         *            filter expression. Must not be <b>null</b>.
446         * 
447         * @return A CqQuery.FilterNode object for specifying the logical
448         *         combination of filtering subexpressions
449         */
450        public CqQuery.FilterNode buildFilterNode(CqQuery.Filter.Operation operation,
451                                                  CqQuery.FilterLeaf... operands);
452    
453        /**
454         * Constructs a new CqQuery.FilterNode object for the purpose of creating or
455         * modifying the filtering expression of a query.
456         * 
457         * @param operation Either {@link CqQuery.Filter.Operation#CONJUNCTION} or
458         *            {@link CqQuery.Filter.Operation#DISJUNCTION}. Must not be
459         *            <b>null</b>.
460         * @param operands The filter subexpressions to be combined to form a new
461         *            filter expression. Must not be <b>null</b>.
462         * 
463         * @return A CqQuery.FilterNode object for specifying the logical
464         *         combination of filtering subexpressions
465         */
466        public CqQuery.FilterNode buildFilterNode(CqQuery.Filter.Operation operation,
467                                                  CqQuery.FilterNode... operands);
468     
469    }