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 }