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 }