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 }