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