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, 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
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 /*
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 }