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