001/* 002 * IBM and/or HCL Confidential 003 * OCO Source Materials 004 * Rational ClearQuest 005 * (C) Copyright IBM Corporation 2004, 2008. All Rights Reserved. 006 * (C) Copyright HCL Technologies Ltd. 2016, 2018. All Rights Reserved. 007 * 008 * Note to U.S. Government Users Restricted Rights: Use, duplication or 009 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp. 010 */ 011 012package com.ibm.rational.wvcm.stp.cq; 013 014 015import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE; 016 017import java.io.File; 018import java.util.List; 019 020import javax.wvcm.Feedback; 021import javax.wvcm.ResourceList; 022import javax.wvcm.WvcmException; 023import javax.wvcm.PropertyNameList.PropertyName; 024 025import com.ibm.rational.wvcm.stp.cqex.CqExForm; 026 027 028/** 029 * A proxy for the specification of a record type in a database. 030 * 031 * The user-friendly specification for the location of a record type has the form 032 * <pre> 033 * <b>cq.record:</b><i><record-type-name></i>@<i><db-set></i>/<i><user-db></i> 034 * </pre> 035 */ 036public interface CqRecordType 037 extends CqUserDbMember, CqUserDb.SearchKey<Boolean> 038{ 039 /** A list of the field definitions of this record type */ 040 PropertyName<ResourceList<CqFieldDefinition>> FIELD_DEFINITIONS = 041 new PropertyName<ResourceList<CqFieldDefinition>>(PROPERTY_NAMESPACE, 042 "field-definitions"); 043 044 /** 045 * Returns the value of the {@link #FIELD_DEFINITIONS FIELD_DEFINITIONS} 046 * property as defined by this proxy. 047 * 048 * @return A ResourceList of CqFieldDefinition record proxies; one proxy 049 * per field of this record type. Will never by <b>null</b>. 050 * 051 * @throws WvcmException if this proxy does not define a value for the 052 * {@link #FIELD_DEFINITIONS FIELD_DEFINITIONS} property. 053 */ 054 public ResourceList<CqFieldDefinition> getFieldDefinitions() 055 throws WvcmException; 056 057 /** All of the actions defined on this record type. */ 058 PropertyName<ResourceList<CqAction>> ACTION_LIST = 059 new PropertyName<ResourceList<CqAction>>(PROPERTY_NAMESPACE, 060 "action-list"); 061 062 /** 063 * Returns the value of the {@link #ACTION_LIST ACTION_LIST} property as 064 * defined by this proxy. 065 * 066 * @return A ResourceList of CqAction proxies containing all of the actions 067 * defined for this record type. 068 * 069 * @throws WvcmException if this proxy does not define a value for the 070 * {@link #ACTION_LIST ACTION_LIST} property. 071 */ 072 public ResourceList<CqAction> getActionList() 073 throws WvcmException; 074 075 /** 076 * The names of all the states defined for this record type. Will be an 077 * empty list if this is a stateless record type. 078 */ 079 PropertyName<List<String>> STATE_NAME_LIST = 080 new PropertyName<List<String>>(PROPERTY_NAMESPACE, 081 "state-name-list"); 082 083 /** 084 * Returns the value of the {@link #STATE_NAME_LIST STATE_NAME_LIST} 085 * property as defined by this proxy. 086 * 087 * @return A list of Strings, each containing the name of a state of this 088 * record type. Will be an empty list if this is a stateless 089 * record type. 090 * 091 * @throws WvcmException if this proxy does not define a value for the 092 * {@link #STATE_NAME_LIST STATE_NAME_LIST} 093 * property. 094 */ 095 public List<String> getStateNameList() 096 throws WvcmException; 097 098 /** 099 * The names of all the forms defined for this record type. Will be an 100 * empty list if the record type has no forms, such as "history". 101 */ 102 PropertyName<ResourceList<CqExForm>> FORM_LIST = 103 new PropertyName<ResourceList<CqExForm>>(PROPERTY_NAMESPACE, 104 "form-list"); 105 106 /** 107 * Returns the value of the {@link #FORM_LIST} 108 * property as defined by this proxy. 109 * 110 * @return A list of Strings, each containing the name of a form and 111 * stable location of this 112 * record type. Will be an empty list if the record type has no 113 * forms, such as "history". 114 * 115 * @throws WvcmException if this proxy does not define a value for the 116 * {@link #FORM_LIST FORM_LIST} 117 * property. 118 */ 119 public ResourceList<CqExForm> getFormList() 120 throws WvcmException; 121 122 /** Answers whether or not this record type is a stateless record type. */ 123 PropertyName<Boolean> IS_STATELESS = 124 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-stateless"); 125 126 /** 127 * Returns the value of the {@link #IS_STATELESS IS_STATELESS} property as 128 * defined by this proxy. 129 * 130 * @return <b>true</b> if this is a stateless record type. 131 * 132 * @throws WvcmException if this proxy does not define a value for the 133 * {@link #IS_STATELESS IS_STATELESS} property. 134 */ 135 public boolean getIsStateless() 136 throws WvcmException; 137 138 /** Answers whether or not records of this type may be submitted by clients. */ 139 PropertyName<Boolean> IS_SUBMITTABLE = 140 new PropertyName<Boolean>(PROPERTY_NAMESPACE, 141 "is-submittable"); 142 143 /** 144 * Returns the value of the {@link #IS_SUBMITTABLE IS_SUBMITTABLE} property 145 * as defined by this proxy. 146 * 147 * @return <b>true</b> if records of this type may be submitted by clients. 148 * 149 * @throws WvcmException if this proxy does not define a value for the 150 * {@link #IS_SUBMITTABLE IS_SUBMITTABLE} property. 151 */ 152 public boolean getIsSubmittable() 153 throws WvcmException; 154 155 /** All of the named hooks associated with this record type. */ 156 PropertyName<ResourceList<CqHook>> NAMED_HOOK_LIST = 157 new PropertyName<ResourceList<CqHook>>(PROPERTY_NAMESPACE, 158 "named-hook-list"); 159 160 /** 161 * Returns the value of the {@link #NAMED_HOOK_LIST NAMED_HOOK_LIST} 162 * property as defined by this proxy. 163 * 164 * @return A ResourceList of CqHook proxies containing all the named hooks 165 * of this record type. 166 * 167 * @throws WvcmException if this proxy does not define a value for the 168 * {@link #NAMED_HOOK_LIST NAMED_HOOK_LIST} property. 169 */ 170 public ResourceList<CqHook> getNamedHookList() 171 throws WvcmException; 172 173 /** Answers whether or not records of this type can be security contexts. */ 174 PropertyName<Boolean> CAN_BE_SECURITY_CONTEXT = 175 new PropertyName<Boolean>(PROPERTY_NAMESPACE, 176 "can-be-security-context"); 177 178 /** 179 * Returns the value of the {@link #CAN_BE_SECURITY_CONTEXT 180 * CAN_BE_SECURITY_CONTEXT} property as defined by this proxy. 181 * 182 * @return <b>true</b> if records of this type can be security contexts 183 * 184 * @throws WvcmException if this proxy does not define a value for the 185 * {@link #CAN_BE_SECURITY_CONTEXT CAN_BE_SECURITY_CONTEXT} 186 * property. 187 */ 188 public boolean getCanBeSecurityContext() 189 throws WvcmException; 190 191 /** 192 * Answers whether or a record of this record type is used as a security 193 * context 194 */ 195 PropertyName<Boolean> IS_SECURITY_CONTEXT = 196 new PropertyName<Boolean>(PROPERTY_NAMESPACE, 197 "is-security-context"); 198 199 /** 200 * Returns the value of the {@link #IS_SECURITY_CONTEXT IS_SECURITY_CONTEXT} 201 * property as defined by this proxy. 202 * 203 * @return <b>true</b> if records of this type are used as security 204 * contexts. 205 * 206 * @throws WvcmException if this proxy does not define a value for the 207 * {@link #IS_SECURITY_CONTEXT IS_SECURITY_CONTEXT} 208 * property. 209 */ 210 public boolean getIsSecurityContext() 211 throws WvcmException; 212 213 /** 214 * Answers whether or not this is the definition of a record type family. 215 */ 216 PropertyName<Boolean> IS_FAMILY = 217 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-family"); 218 219 /** 220 * Returns the value of the {@link #IS_FAMILY IS_FAMILY} property as defined 221 * by this proxy. 222 * 223 * @return <b>true</b> if this is a record type family specification. 224 * 225 * @throws WvcmException if this proxy does not define a value for the 226 * {@link #IS_FAMILY IS_FAMILY} property. 227 */ 228 public boolean getIsFamily() 229 throws WvcmException; 230 231 /** 232 * Answers whether or not this record type is a built-in record type, not 233 * added by a schema developer or package. 234 */ 235 PropertyName<Boolean> IS_BUILT_IN_SYSTEM_OWNED = 236 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-built-in-system-owned"); 237 238 /** 239 * Returns the value of the 240 * {@link #IS_BUILT_IN_SYSTEM_OWNED IS_BUILD_IN_SYSTEM_OWNED} property as 241 * defined by this proxy. 242 * 243 * @return <b>true</b> if this record type is defined for all ClearQuest 244 * schemas as part of the base implementation. 245 * 246 * @throws WvcmException if this proxy does not define a value for the 247 * {@link #IS_BUILT_IN_SYSTEM_OWNED IS_BUILT_IN_SYSTEM_OWNED} 248 * property. 249 */ 250 public boolean getIsBuiltInSystemOwned() 251 throws WvcmException; 252 253 /** 254 * The record types that are members of this record type family. The list 255 * is empty is this is not a record type family. 256 */ 257 PropertyName<ResourceList<CqRecordType>> FAMILY_MEMBERS = 258 new PropertyName<ResourceList<CqRecordType>>(PROPERTY_NAMESPACE, 259 "family-members"); 260 261 /** 262 * Returns the value of the {@link #FAMILY_MEMBERS} property as defined by 263 * this proxy 264 * 265 * @return A ResourceList containing a CqRecordType proxy for each record 266 * type that is a member of this record type family; Will never be 267 * <b>null</b> but may be empty if this is not a record type family 268 * or if no members are defined. 269 * 270 * @throws WvcmException if this proxy does not define a value for the 271 * {@link #FAMILY_MEMBERS} property. 272 */ 273 public ResourceList<CqRecordType> getFamilyMembers() 274 throws WvcmException; 275 276 /** 277 * A list of the record type families this record is a member of. 278 */ 279 PropertyName<ResourceList<CqRecordType>> PARENT_FAMILIES = 280 new PropertyName<ResourceList<CqRecordType>>(PROPERTY_NAMESPACE, 281 "parent-families"); 282 283 /** 284 * Returns the value of the {@link #PARENT_FAMILIES} property as defined by 285 * this proxy 286 * 287 * @return A ResourceList containing a CqRecordType proxy for each record 288 * type family that this record type is a member of; Will never be 289 * <b>null</b> but may be empty if this record type is not a member 290 * of a record type family. 291 * 292 * @throws WvcmException if this proxy does not define a value for the 293 * {@link #PARENT_FAMILIES} property. 294 */ 295 public ResourceList<CqRecordType> getParentFamilies() 296 throws WvcmException; 297 298 /** 299 * A list of the schema-defined fields that constitute the unique key for 300 * records of this type, presented in sort-key order starting from the 301 * primary sort key. (Note: In this release computation of this property 302 * requires the IS_RAW_SQL_WRITER permission.) 303 */ 304 PropertyName<ResourceList<CqFieldDefinition>> KEY_FIELDS = 305 new PropertyName<ResourceList<CqFieldDefinition>>(PROPERTY_NAMESPACE, 306 "key-fields"); 307 308 /** 309 * Returns the value of the {@link CqRecordType#KEY_FIELDS KEY_FIELDS} property as 310 * defined by this proxy. 311 * 312 * @return A ResourceList of CqFieldDefinition proxies each representing a 313 * key field of this record type presented in sort-key order.. 314 * 315 * @throws WvcmException if this proxy does not define a value for the 316 * {@link CqRecordType#KEY_FIELDS KEY_FIELDS} property. 317 */ 318 public ResourceList<CqFieldDefinition> getKeyFields() throws WvcmException; 319 320 /** 321 * Answers whether or not records of this type may be used as a UCM 322 * activity. 323 */ 324 PropertyName<Boolean> IS_UCM_ENABLED = 325 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-ucm-enabled"); 326 327 /** 328 * Returns the value of the {@link #IS_UCM_ENABLED IS_UCM_ENABLED} property 329 * as defined by this proxy. 330 * 331 * @return <b>true</b> if records of this type may be used as a UCM 332 * activity. 333 * 334 * @throws WvcmException if this proxy does not define a value for the 335 * {@link #IS_UCM_ENABLED IS_UCM_ENABLED} property. 336 */ 337 public boolean getIsUcmEnabled() 338 throws WvcmException; 339 340 /** 341 * Returns specified fields from records that are of this record type and 342 * match a specified filtering expression. This proxy does not need to 343 * define any properties as only its location is needed to establish the 344 * record type to be selected and the database from which to select them. 345 * 346 * @param displayFields An array of {@link CqQuery.DisplayField} objects, 347 * each specifying a value to be returned from each selected 348 * record and collectively specifying the order in which the 349 * matched records are to be included in the response. Must not 350 * be <b>null</b>. 351 * @param filtering A {@link CqQuery.Filter} object specifying how the 352 * records of this type are to be selected for inclusion in the 353 * response. May be <b>null</b>, in which case all records of 354 * this record type will be included (up to the limits imposed by 355 * the targetRow and maxRows parameters). 356 * @param targetRow Specifies the first record that is to be included in the 357 * response among the records that match the filter, where a 358 * value of 1 specifies the first matching record. The ordering 359 * of matched records is defined by the display fields array. 360 * @param maxRows The maximum number of records that should be included in 361 * the response to this request. A value of Long.MAX_VALUE will 362 * request that the targeted record and all records after it in 363 * the prescribed ordering should be included in the response; If 364 * this parameter is 0, no records will be included. If the 365 * filter matches fewer than the maximum records requested, it is 366 * not an error. 367 * @param options An instance of {@link CqQuery.ListOptions} that specifies 368 * optional attributes for controlling the performance of the 369 * query or its response. May be <b>null</b>, in which case 370 * server-specified values will be used for each attribute. 371 * 372 * @return A CqResultSet of CqRowData objects each representing a record 373 * selected by the filter and containing the values specified by the 374 * display fields array. The values in each CqRowData object are 375 * ordered according to the display fields array. The total row 376 * count, if requested, is available as a field of the returned 377 * CqResultSet. 378 * 379 * @throws WvcmException if any errors occur during the execution of the 380 * query or the formation of the response. 381 * 382 * @see CqQuery#doExecute(long, long, com.ibm.rational.wvcm.stp.cq.CqQuery.ListOptions, com.ibm.rational.wvcm.stp.cq.CqQuery.FilterLeaf[]) 383 */ 384 CqResultSet doQuery(CqQuery.DisplayField[] displayFields, 385 CqQuery.Filter filtering, 386 long targetRow, 387 long maxRows, 388 CqQuery.ListOptions options) 389 throws WvcmException; 390 391 /** 392 * Returns specified fields from records that are of the type defined by 393 * this record type and match a specified filtering expression. This proxy 394 * does not need to define any properties as only its location is needed to 395 * establish the type of records to be selected and the database from which 396 * to select them. 397 * 398 * @param displayFields An array of {@link CqQuery.DisplayField} objects, 399 * each specifying a value to be returned from each selected 400 * record and collectively specifying the order in which the 401 * matched records are to be included in the response. Must not 402 * be <b>null</b>. 403 * @param filtering A {@link CqQuery.Filter} node specifying how the records 404 * of this type are to be selected for inclusion in the response. 405 * May be <b>null</b>, in which case all records of this record 406 * type will be included (up to the limits imposed by the 407 * targetRow and maxRows parameters). 408 * @param options An instance of {@link CqQuery.FileOptions} that specifies 409 * optional attributes for controlling the format of the response 410 * response. May be <b>null</b>, in which case server-specified 411 * values will be used for each attribute. 412 * @param feedback A Feedback instance specifying properties to be returned 413 * from the operation in the CqRecordType proxy. May be <b>null</b>. 414 * 415 * @param result The File into which the result set is to be written. Must 416 * not be <b>null</b>. 417 * 418 * @return A proxy for this record type, populated with the properties 419 * requested by the Feedback argument. 420 * 421 * @throws WvcmException if any errors occur during the execution of the 422 * query or the formation of the response. 423 */ 424 CqRecordType doQuery(CqQuery.DisplayField[] displayFields, 425 CqQuery.Filter filtering, 426 File result, 427 Feedback feedback, 428 CqQuery.FileOptions options) 429 throws WvcmException; 430 431 /** 432 * Returns specified fields from records that are of the type defined by 433 * this record type and match a specified filtering expression. To launch 434 * this method this proxy does not need to define any properties as only its 435 * location is needed to establish the type of records to be selected and 436 * the database from which to select them. 437 * 438 * @param sql A String containing an SQL select statement specifying the 439 * fields to be returned by the query and the filter to be used 440 * to select the records. 441 * 442 * @param targetRow Specifies the first record that is to be included in the 443 * response among the records that match the filter, where a 444 * value of 1 specifies the first matching record. The ordering 445 * of matched records is defined by the display fields array. 446 * 447 * @param maxRows The maximum number of records that should be included in 448 * the response to this request. A value of Long.MAX_VALUE will 449 * request that the targeted record and all records after it in 450 * the prescribed ordering should be included in the response; If 451 * this parameter is 0, no records will be included. If the 452 * filter matches fewer than the maximum records requested, it is 453 * not an error. 454 * 455 * @param options An instance of {@link CqQuery.ListOptions} that specifies 456 * optional attributes for controlling the performance of the 457 * query or its response. May be <b>null</b>, in which case 458 * server-specified values will be used for each attribute. 459 * 460 * @return A CqResultSet containing a list of CqRowData objects, each 461 * representing a record selected by the filter and containing the 462 * values specified by the SQL string. The values in each CqRowData 463 * object are ordered according to the SQL select statement. 464 * 465 * @throws WvcmException if any errors occur during the execution of the 466 * query or the formation of the response. 467 */ 468 CqResultSet doQuery(String sql, 469 long targetRow, 470 long maxRows, 471 CqQuery.ListOptions options) 472 throws WvcmException; 473 474 /** 475 * Returns specified fields from records that are of the type defined by 476 * this record type and match a specified filtering expression. To launch 477 * this method this proxy does not need to define any properties as only its 478 * location is needed to establish the type of records to be selected and 479 * the database from which to select them. 480 * 481 * @param sql A String containing an SQL specification for the fields to be 482 * returned by the query and the filter to be used to select the 483 * records. 484 * 485 * @param result The File into which the result set is to be written. Must 486 * not be <b>null</b>. 487 * 488 * @param feedback A Feedback instance specifying properties to be returned 489 * from the operation in the CqRecordType proxy. May be <b>null</b>. 490 * 491 * @param options An instance of FileOptions that specifies optional 492 * attributes for controlling the format of the response 493 * response. May be <b>null</b>, in which case server-specified 494 * values will be used for each attribute. 495 * 496 * @return A proxy for this record type, populated with the properties 497 * requested by the Feedback argument. 498 * 499 * @throws WvcmException if any errors occur during the execution of the 500 * query or the formation of the response. 501 */ 502 CqRecordType doQuery(String sql, 503 File result, 504 Feedback feedback, 505 CqQuery.FileOptions options) 506 throws WvcmException; 507}