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 * (C) Copyright IBM Corporation 2004, 2014.  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
014package com.ibm.rational.wvcm.stp.cq;
015
016import java.util.ArrayList;
017import java.util.List;
018
019import javax.wvcm.Feedback;
020import javax.wvcm.ResourceList;
021import javax.wvcm.WvcmException;
022import javax.wvcm.PropertyNameList.PropertyName;
023
024import com.ibm.rational.wvcm.stp.StpLocation;
025import com.ibm.rational.wvcm.stp.StpProvider;
026import 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 */
033public 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    /*
470     * Keep track of remote address of client/browser making the requests.
471     */
472    
473    /**
474     * Get the remote address that is making this CQ request.
475     * @return a string representing the remote address.
476     */
477    public String getRemoteAddress();
478    
479    /**
480     * Set the remoteAddress for this provider. This is the address
481     * that is making the current request.
482     * @param remoteAddress A string representing the address that is
483     *                          making this request.
484     */
485    public void setRemoteAddress(String remoteAddress);
486 
487}