001 /* 002 * file CqRecord.java 003 * 004 * Licensed Materials - Property of IBM 005 * Restricted Materials of IBM 006 * 007 * com.ibm.rational.wvcm.stp.cq.CqRecord 008 * 009 * (C) 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 import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE; 016 017 import java.util.Date; 018 import java.util.List; 019 020 import javax.wvcm.Feedback; 021 import javax.wvcm.PropertyNameList; 022 import javax.wvcm.ResourceList; 023 import javax.wvcm.WvcmException; 024 import javax.wvcm.PropertyNameList.PropertyName; 025 026 import com.ibm.rational.wvcm.stp.StpActivity; 027 import com.ibm.rational.wvcm.stp.StpErrorMessageException; 028 import com.ibm.rational.wvcm.stp.StpProperty; 029 import com.ibm.rational.wvcm.stp.StpResource; 030 import com.ibm.rational.wvcm.stpex.StpExBase; 031 import com.ibm.rational.wvcm.stpex.StpExEnumeration; 032 import com.ibm.rational.wvcm.stpex.StpExEnumerationBase; 033 034 /** 035 * A CqRecord resource proxy provides access to a record in a database, possibly 036 * through its change context. 037 * 038 * <p> 039 * To ensure the integrity of record field data, the modification of a record is 040 * a multi-step process. 041 * 042 * <ul> 043 * <li>First, a writable copy of the record is added to the database's change 044 * context using the current field values from the database. This writable copy 045 * of the record is visible only in the provider where it was created. While it 046 * exists in the change context, it hides the record in the database as seen 047 * through the provider. 048 * <li>Field values are modified in the CqRecord proxy by the client. 049 * <li>As needed, modified field values are written to the writable copy of the 050 * record on the server. (see 051 * {@link CqContextResource#doWriteProperties(Feedback, List) doWriteProperties}.) 052 * <li>The client modifies a record or a set of records in this fashion until 053 * all have been modified and made consistent to the client's satisfaction. Then 054 * they are written back to the database is a single atomic operation. (See 055 * {@link com.ibm.rational.wvcm.stp.cq.CqUserDb#doDeliver(Feedback, List)} or 056 * {@link com.ibm.rational.wvcm.stp.cq.CqContextResource#doDeliver(Feedback)} or 057 * {@link CqContextResource#doWriteProperties(Feedback, List) doWriteProperties}.) 058 * </ul> 059 * 060 * If these steps succeed, the client can be assured that the data written back 061 * to the record is faithfully derived from the data read from the record. 062 * 063 * <p> 064 * If doWriteProperties is applied to a record that is not yet writable, an 065 * action must be started under which the record will be modified. If an action 066 * is not specified as the value of the ACTION property of this proxy, the 067 * default MODIFY-type action for the record is used. 068 * 069 * <p> 070 * The fields of a record manifest themselves as properties of the record 071 * resource and thus record field values are made available to the client via 072 * the normal property request mechanism. The names, types, and other 073 * characteristics of the fields of a record are available as properties of the 074 * {@link CqFieldDefinition CqFieldDefinition} resources enumerated by the 075 * CqRecordType resource associated with the record. 076 * 077 * <p> 078 * In addition to their value, record fields also have meta-properties such as 079 * their requiredness, their original value, and a list of their legal values. 080 * Each of these can be requested using a MetaPropertyName object in a 081 * nested PropertyRequest of the field PropertyName. 082 * <p> 083 * The user-friendly specification for the location of a record has the form 084 * 085 * <pre> 086 * <b>cq.record:</b><i><record-type></i>/<i><record-id></i>@<i><db-set></i>/<i><user-db></i> 087 * </pre> 088 * 089 * @see CqRecordType 090 * @see CqFieldDefinition 091 * @see CqFieldValue 092 */ 093 public interface CqRecord extends StpActivity, CqContextResource 094 { 095 /** 096 * Defines the value of the specified property for this proxy. The 097 * PropertyName may specify a record field name, in which case the Object 098 * may be a {@link CqFieldValue CqFieldValue} structure or the actual value 099 * of the field. 100 * 101 * @see StpResource#setProperty(PropertyNameList.PropertyName, Object) 102 */ 103 <T> void setProperty(PropertyName<T> name, 104 T value); 105 106 /** 107 * Returns the value defined by this proxy for the property specified by the 108 * given PropertyName. The PropertyName may specify a record field, in which 109 * case the Object returned is <i>not</i> a 110 * {@link CqFieldValue CqFieldValue} structure, but the actual value of the 111 * field. (Clients may use {@link #getField getField} or 112 * {@link StpResource#getMetaProperties(PropertyName)} to obtain a 113 * CqFieldValue structure if the additional information provided by the 114 * CqFieldValue structure is needed.). 115 * 116 * @see javax.wvcm.Resource#getProperty(javax.wvcm.PropertyNameList.PropertyName) 117 */ 118 <T> T getProperty(PropertyName<T> name) throws WvcmException; 119 120 /** 121 * A CqRecordType proxy for the record-type resource that defines what kind 122 * of record this is. 123 */ 124 PropertyName<CqRecordType> RECORD_TYPE = 125 new PropertyName<CqRecordType>(StpExBase.PROPERTY_NAMESPACE, 126 "record-type"); 127 128 /** 129 * A CqRecordType proxy for the record-type resource that defines what kind 130 * of record this is. 131 * 132 * @return A proxy for the record-type of this record is returned. 133 * 134 * @throws WvcmException if this proxy does not define a value for the 135 * {@link #RECORD_TYPE RECORD_TYPE} property. 136 */ 137 CqRecordType getRecordType() throws WvcmException; 138 139 /** 140 * A subclass of PropertyName used for naming the record resource properties 141 * that are schema-defined fields of a ClearQuest record. Note that, as with 142 * PropertyName, the type parameter specifies the field's value type. 143 */ 144 public static class FieldName<T> extends PropertyName<T> 145 { 146 /** 147 * Constructs a PropertyName designating the resource property that 148 * corresponds to a field of a ClearQuest record. 149 * 150 * @param fieldName The schema-defined name of the record field. Must 151 * not be null. 152 */ 153 public FieldName(String fieldName) 154 { 155 super(StpExBase.FIELD_NAMESPACE, fieldName); 156 } 157 } 158 159 /** 160 * Returns the meta-property bundle of a record field defined by this proxy. 161 * Since CqFieldValue is an extension of StpProperty, this method is merely 162 * a type-specialized version of 163 * {@link StpResource#getMetaProperties(javax.wvcm.PropertyNameList.PropertyName)}. 164 * 165 * @param fieldName The name of the desired field expressed as a FieldName 166 * object. Cannot be <code>null</code>. 167 * 168 * @return A CqFieldValue structure is returned containing the field 169 * value(s) and/or attributes defined by this proxy. 170 * 171 * @throws WvcmException If the field value denoted by the given field name 172 * is not defined by this proxy--that is, if no field values or 173 * attributes were requested or could not be retrieved when 174 * requested. 175 */ 176 <T> CqFieldValue<T> getFieldInfo(FieldName<T> fieldName) 177 throws WvcmException; 178 179 /** 180 * Defines a new meta-property bundle for a record field in this proxy. Only 181 * the VALUE meta-property of the CqFieldValue is written to the resource, 182 * but the TYPE meta-property is often useful to the library for 183 * interpreting the VALUE when expressed as a String image. 184 * 185 * @param fieldName The name of the field to be updated expressed as a 186 * FieldName object. Cannot be <code>null</code>. 187 * 188 * @param value A CqFieldValue object containing the new field value. Must 189 * not be <b>null</b> 190 */ 191 <T> void setFieldInfo(FieldName<T> fieldName, 192 CqFieldValue<T> value); 193 194 /** 195 * Defines in this proxy, a new value for a field of this record. The field 196 * will not be updated until this proxy is used to invoke a "do" method. 197 * 198 * @param fieldName The name of the field whose value is to be set 199 * @param value The new value for the field expressed as a native Java 200 * object. The String image of the value may be used. 201 */ 202 void setField(String fieldName, 203 Object value); 204 205 /** 206 * Retrieves the value of a field previously requested by an instance of 207 * FieldName having the same fieldName parameter as this method. To retrieve 208 * other meta-properties requested for the field, use 209 * {@link #getFieldInfo(com.ibm.rational.wvcm.stp.cq.CqRecord.FieldName)}. 210 * 211 * @param fieldName The name of the field for which a value was requested. 212 * @return The value of the requested field returned by the server expressed 213 * as a native Java object (not just its String image). 214 * @throws WvcmException If the field value was not requested or could not 215 * be retrieved. 216 */ 217 Object getField(String fieldName) throws WvcmException; 218 219 /** 220 * Creates a new record at the location specified by this proxy, initialized 221 * with the dirty properties of this proxy. The type of record created is 222 * determined by the parent location of this proxy (which must name an 223 * existing record type resource). 224 * <p> 225 * An action must be started under which the record will be created. If an 226 * action is not specified as the value of the ACTION property of this 227 * proxy, the default SUBMIT-type action for the record is used. 228 * <p> 229 * The server is permitted to modify the location as it deems fit. The proxy 230 * returned by this method is a proxy that addresses the location actually 231 * chosen by the server. 232 * 233 * @param feedback A Feedback object requesting the properties desired from 234 * the record created by this operation. May be <b>null</b> if 235 * no properties are desired. 236 * 237 * @return An CqRecord proxy for the created record. This proxy will define 238 * the properties specified in the feedback argument. 239 * 240 * @throws WvcmException If the record cannot be created with the given 241 * properties. 242 */ 243 CqRecord doCreateRecord(Feedback feedback) throws WvcmException; 244 245 /** 246 * Creates a new record at the location specified by this proxy, initialized 247 * with the dirty properties of this proxy. The type of record created is 248 * determined by the parent location of this proxy (which must name an 249 * existing record type resource). 250 * <p> 251 * An action must be started under which the record will be created. If an 252 * action is not specified as the value of the ACTION property of this 253 * proxy, the default SUBMIT-type action for the record is used. 254 * <p> 255 * The server is permitted to modify the location as it deems fit. The proxy 256 * returned by this method is a proxy that addresses the location actually 257 * chosen by the server. 258 * 259 * @param feedback A Feedback object requesting the properties desired from 260 * the record created by this operation. May be <b>null</b> if 261 * no properties are desired. 262 * 263 * @param deliveryOrder If {@link CqProvider#HOLD} the created record is 264 * left in a writable state in the change context--the new record 265 * in the change context must be delivered before the it becomes 266 * visible to other providers. If not {@link CqProvider#HOLD}, 267 * the modified and moribund resources specified by this 268 * parameter will be delivered to or deleted from the database in 269 * the order indicated. To deliver all modified and moribund 270 * resources in an arbitrary order, use 271 * {@link CqProvider#DELIVER_ALL}. To deliver just this new 272 * record, use {@link CqProvider#DELIVER}. Must not be <b>null</b>. 273 * @return A CqRecord proxy for the created record. This proxy will define 274 * the properties specified in the feedback argument. 275 * 276 * @throws WvcmException If the record cannot be created with the given 277 * properties. 278 */ 279 CqRecord doCreateRecord(Feedback feedback, 280 List<CqContextResource> deliveryOrder) 281 throws WvcmException; 282 283 /** 284 * Executes a hook (record script) named in the NAMED_HOOK_LIST property of 285 * this record's RECORD_TYPE resource. The impact on the change context in 286 * which the hook is executed is essentially the same as executing 287 * {@link com.ibm.rational.wvcm.stp.cq.CqContextResource#doWriteProperties(Feedback, List)} 288 * in that context (where the hook is in control of which properties are 289 * written). 290 * <p> 291 * As with doWriteProperties, the record need not be editable prior to 292 * invoking this method, but, unlike doWriteProperties, if it isn't editable 293 * and the hook wants to modify it, then the hook must be prepared to start 294 * an action itself to do so. An implicit Modify-type action is not 295 * automatically started for the hook (except in the case noted below). 296 * <p> 297 * If this proxy contains updated property values when this method is 298 * invoked, an attempt will be made to write those new property values to 299 * the server <i>before</i> the hook is executed. If such an update is 300 * required and this record isn't editable, it will be made editable using 301 * the default Modify-type action and the hook will be applied to that 302 * editable version of the record before delivering the changes to the 303 * database. If the property update fails, this operation fails immediately 304 * and subsequent execution of the hook will not be attempted. 305 * 306 * @param hook A CqHook proxy for the named hook to be fired. If the client 307 * knows the name of the hook to be fired, it should construct a 308 * CqHook proxy at the computed location <i>record</i><code>.stpLocation().recomposeWithNamespace(Namespace.HOOK).parent().child(</code><i>hook-name</i><code>)</code> 309 * If the client does not know the name of the hook to be fired, 310 * a list of available hooks to choose from can be obtained from 311 * the NAMED_HOOK_LIST property of the parent record type of this 312 * record. 313 * @param parameters A String containing any parameters required by the 314 * hook. The format and content of this parameter string is 315 * prescribed solely by the hook, which is also responsible for 316 * parsing it into a usable value or values. 317 * @param feedback Properties to be retrieved from the target record and/or 318 * those records changed by the execution of the hook (and after 319 * delivery if delivery has been requested). 320 * @param deliveryOrder Delivery of the changes made to the record will be 321 * considered only if the hook succeeds. If this argument is 322 * {@link CqProvider#HOLD} the modified record is left in a 323 * writable state in the change context--the modified record must 324 * be delivered before the changes made by the hook become 325 * visible outside the change context. If not 326 * {@link CqProvider#HOLD}, the modified and moribund resources 327 * specified by this parameter will be delivered to or deleted 328 * from the database in the order indicated. To deliver all 329 * modified and moribund resources in an arbitrary order, use 330 * {@link CqProvider#DELIVER_ALL}. To deliver just this modified 331 * record, use {@link CqProvider#DELIVER}. Must not be <b>null</b>. 332 * @return A CqRecord proxy for the modified record, populated with the 333 * resources requested by the feedback argument. 334 * @throws WvcmException if there are problems finding or executing the 335 * named hook, writing updated properties, or starting the 336 * implied action. 337 * @throws StpErrorMessageException if the hook returns a non-empty result 338 */ 339 CqRecord doFireNamedHook(CqHook hook, 340 String parameters, 341 Feedback feedback, 342 List<CqContextResource> deliveryOrder) 343 throws WvcmException, StpErrorMessageException; 344 345 /** 346 * Causes the execution of an action of type 347 * CqAction.Type.RECORD_SCRIPT_ALIAS. Such actions are defined solely by a 348 * hook script, which is executed when the action is applied to a record. 349 * When this method is called, the action is started on this record and the 350 * action's hook script is executed as the sole content of that action and 351 * then the action is committed. The impact of this operation on the change 352 * context is essentially equivalent to executing in the same context 353 * {@link com.ibm.rational.wvcm.stp.cq.CqContextResource#doWriteProperties(Feedback, List)} 354 * where the deliveryOrder argument forces an immediate delivery of the 355 * change context. 356 * <p> 357 * Because of this prescribed processing 358 * <ul> 359 * <li>This record must not be editable when this method is called so that 360 * the specified RECORD_SCRIPT_ALIAS action can be started on it. 361 * <li> This record must not contain updated property values because only 362 * the record script of the action is allowed to make modifications to the 363 * record once the action has started. 364 * <li>If the action script succeeds, delivery of the targeted record is 365 * immediate and cannot be deferred--i.e., CqProvider.HOLD <i>may not</i> 366 * be used for the delivery order list. Furthermore, the targeted record is 367 * delivered first, regardless of the content of the delivery order list. 368 * <li>If the action script fails, no delivery will be attempted and the 369 * change context will remain as it was before invoking this method. 370 * </ul> 371 * <p> 372 * Typically, schema designers have associated arbitrary executable code 373 * with a record type, represented in a GUI as a button with the display 374 * name of the record type action. 375 * 376 * @param action A CqAction for an action of type RECORD_SCRIPT_ALIAS. This 377 * action must be defined by the record type of this record 378 * instance. 379 * @param feedback A Feedback object requesting the properties desired from 380 * resources involved in this operation. May be <b>null</b> if 381 * no properties are desired. 382 * @param deliveryOrder Upon successful execution of the action script, the 383 * target record will be delivered to its database. Then, any 384 * other resources specified by this argument will be delivered. 385 * Must not be <b>null</b> and must not be CqProvider.HOLD. 386 * @return A String containing the return value computed by the hook script. 387 * @throws WvcmException if there are problems 388 * <ul> 389 * <li>finding the record, 390 * <li>finding a RECORD_SCRIPT_ALIAS as specified 391 * <li>starting the action 392 * <li>executing the script 393 * <li>delivering the changes to the database 394 * </ul> 395 */ 396 String doFireRecordScriptAlias(CqAction action, 397 Feedback feedback, 398 List<CqContextResource> deliveryOrder) 399 throws WvcmException; 400 401 /** 402 * Returns the date of the submit action in the record history field. 403 * 404 * @see javax.wvcm.Resource#getCreationDate() 405 */ 406 Date getCreationDate() throws WvcmException; 407 408 /** 409 * Returns the date of the last action applied to the record from its 410 * history 411 * 412 * @see javax.wvcm.Resource#getLastModified() 413 */ 414 Date getLastModified() throws WvcmException; 415 416 /** 417 * Returns the login name of the user who submitted the record 418 * 419 * @see com.ibm.rational.wvcm.stp.StpResource#getCreatorLoginName() 420 */ 421 String getCreatorLoginName() throws WvcmException; 422 423 /** 424 * The error message generated when the record, in its current state, was 425 * validated against the repository schema for compliance with its rules. 426 * This property will be empty if the record is fully compliant (which is 427 * always the case if the record is not open for edit). 428 * <p> 429 * When this property is requested for a record open for editing, the record 430 * is validated before any other properties are retrieved. Thus, all 431 * properties returned with this property reflect the state of the record 432 * after validation was attempted. 433 * <p> 434 * Before a record being edited can be delivered, it must be validated (even 435 * if no fields have been changed). Normally, validation is performed as the 436 * first phase of a delivery and any validation errors cause the delivery to 437 * be aborted. Requesting this property will force validation of the record 438 * without attempting to deliver it. The time and resources needed to 439 * perform a record validation vary with the schema. Unless you have 440 * specific knowledge of the target database's schema, it is best to assume 441 * that the validation process is an expensive operation and design your 442 * application to request this property only when validation is really 443 * required. 444 * <p> 445 * If you are changing the contents of a record programmatically, you should 446 * make sure that your code provides valid data. 447 * <p> 448 * You should not attempt to parse and interpret the returned String 449 * programmatically, because the error text may change in future releases. 450 * If you want to try to correct the value in an field with incorrect 451 * values, you can use the INVALID_FIELDS property to discover which fields 452 * are invalid. The MESSAGE_TEXT meta-property of those fields will identify 453 * problems specific to the field. 454 */ 455 PropertyName<String> VALIDATION_ERROR = 456 new PropertyName<String>(StpExBase.PROPERTY_NAMESPACE, 457 "validation-error"); 458 459 /** 460 * Returns the value of the {@link #VALIDATION_ERROR VALIDATION_ERROR} 461 * property as defined by this proxy. 462 * 463 * @return Returns a String containing the error message generated when this 464 * record was validated against the repository schema. Will never be 465 * <b>null</b>, but may be empty is the record field values are 466 * fully compliant with the rules of the schema. 467 * 468 * @throws WvcmException if this proxy does not define a value for the 469 * {@link #VALIDATION_ERROR VALIDATION_ERROR } property. 470 */ 471 String getValidationError() throws WvcmException; 472 473 /** 474 * The action under which this record is being modified; null if the record 475 * is not being modified. 476 */ 477 PropertyName<CqAction> ACTION = 478 new PropertyName<CqAction>(StpExBase.PROPERTY_NAMESPACE, "action"); 479 480 /** 481 * Returns the value of the {@link #ACTION ACTION} property as defined by 482 * this proxy. 483 * 484 * @return Returns an Action proxy representing the action associated with 485 * this record. 486 * 487 * @throws WvcmException if this proxy does not define a value for the 488 * {@link #ACTION ACTION} property. 489 */ 490 CqAction getAction() throws WvcmException; 491 492 /** 493 * Defines a new value for the {@link #ACTION ACTION} property of this 494 * proxy. Set this value prior to invoking doWriteProperties, 495 * doCreateRecord, or doUnbindAll to specify an action other than the 496 * default action specified for those operations. If this property is not 497 * set prior to invocation of these methods, an action of the required type 498 * will be used if one is unique defined. 499 * 500 * @param action A CqAction proxy identifying the action under which this 501 * record is to be created, modified, or deleted. Must not be 502 * <b>null</b>. For the update to succeed, the given action must 503 * be on the LEGAL_ACTIONs list for this record. 504 */ 505 CqRecord setAction(CqAction action); 506 507 /** 508 * The type of the action under which this record is being modified, 509 * Type.NIL if the record is not being modified 510 */ 511 PropertyName<CqAction.Type> ACTION_TYPE = 512 new PropertyName<CqAction.Type>(StpExBase.PROPERTY_NAMESPACE, 513 "action-type"); 514 515 /** 516 * Returns the value of the {@link #ACTION ACTION} property as defined by 517 * this proxy. 518 * 519 * @return An Action.Type enumerator indicating the type of action 520 * associated with this record. 521 * 522 * @throws WvcmException if this proxy does not define a value for the 523 * {@link #ACTION_TYPE ACTION_TYPE} property. 524 */ 525 CqAction.Type getActionType() throws WvcmException; 526 527 /** 528 * A list of {@link CqFieldValue CqFieldValue} objects corresponding to all 529 * of the fields of this record. By default, no meta-property of any field 530 * is included in the CqFieldValue's on this list. So, essentially, the 531 * result is just a list of field property names. Using a NestedPropertyName 532 * in the PropertyRequest of this property would allow the client to request 533 * any or all meta-properties of the fields in the list. 534 * <code> 535 * new PropertyRequest(ALL_FIELD_VALUES.nest(VALUE.nest(VALUE))), 536 * </code> 537 * for example, would request the value of each field of the record. 538 */ 539 PropertyName<StpProperty.List<CqFieldValue<?>>> ALL_FIELD_VALUES = 540 new PropertyName<StpProperty.List<CqFieldValue<?>>>(PROPERTY_NAMESPACE, 541 "all-field-values"); 542 543 /** 544 * Returns the value of the {@link #ALL_FIELD_VALUES ALL_FIELD_VALUES} 545 * property as defined by this proxy. 546 * 547 * @return An StpProperty.List containing a CqFieldValue instance for each 548 * field of this record. Each CqFieldValue instance defines all of 549 * the metadata requested from the server for the field. 550 * 551 * @throws WvcmException if this proxy does not define a value for the 552 * {@link #ALL_FIELD_VALUES ALL_FIELD_VALUES} property. 553 */ 554 StpProperty.List<CqFieldValue<?>> getAllFieldValues() throws WvcmException; 555 556 /** The default action associated with the current state of this record. */ 557 PropertyName<CqAction> DEFAULT_ACTION = 558 new PropertyName<CqAction>(StpExBase.PROPERTY_NAMESPACE, 559 "default-action"); 560 561 /** 562 * Returns the value of the {@link #DEFAULT_ACTION DEFAULT_ACTION} property 563 * as defined by this proxy. 564 * 565 * @return A CqAction proxy representing the default action associated with 566 * this record in its current state. Will be null if a default 567 * action is not defined for this record. 568 * 569 * @throws WvcmException if this proxy does not define a value for the 570 * {@link #DEFAULT_ACTION DEFAULT_ACTION} property. 571 */ 572 CqAction getDefaultAction() throws WvcmException; 573 574 /** Whether this record has been marked as a duplicate of another record. */ 575 PropertyName<Boolean> IS_DUPLICATE = 576 new PropertyName<Boolean>(StpExBase.PROPERTY_NAMESPACE, "is-duplicate"); 577 578 /** 579 * Returns the value of the {@link #IS_DUPLICATE IS_DUPLICATE} property as 580 * defined by this proxy. 581 * 582 * @return <b>true</b> if this record has been recorded as a duplicate of 583 * another record. 584 * 585 * @throws WvcmException if this proxy does not define a value for the 586 * {@link #IS_DUPLICATE IS_DUPLICATE} property. 587 * 588 * @see #getAllDuplicates() 589 * @see #getDuplicates() 590 * @see #getHasDuplicates() 591 */ 592 boolean getIsDuplicate() throws WvcmException; 593 594 /** 595 * The CqRecord that is marked as the original of this duplicate record. 596 */ 597 PropertyName<CqRecord> ORIGINAL = 598 new PropertyName<CqRecord>(StpExBase.PROPERTY_NAMESPACE, "original"); 599 600 /** 601 * Returns the value of the {@link #ORIGINAL ORIGINAL} property as defined 602 * by this proxy. 603 * 604 * @return A CqRecord proxy representing the record of which this is a 605 * duplicate. Will be <b>null</b> if this record is not a 606 * duplicate. 607 * 608 * @throws WvcmException if this proxy does not define a value for the 609 * {@link #ORIGINAL ORIGINAL} property. 610 */ 611 CqRecord getOriginal() throws WvcmException; 612 613 /** The visible ID of this object's original record. */ 614 PropertyName<String> ORIGINAL_ID = 615 new PropertyName<String>(StpExBase.PROPERTY_NAMESPACE, "original-id"); 616 617 /** 618 * Returns the value of the {@link #ORIGINAL_ID ORIGINAL_ID} property as 619 * defined by this proxy. 620 * 621 * @return A String containing the record id for the record that this record 622 * is a duplicate of. Will be <b>null</b> if this record is not a 623 * duplicate. 624 * 625 * @throws WvcmException if this proxy does not define a value for the 626 * {@link #ORIGINAL_ID ORIGINAL_ID} property. 627 */ 628 String getOriginalId() throws WvcmException; 629 630 /** 631 * Whether other records have been marked as being duplicates of this record 632 */ 633 PropertyName<Boolean> HAS_DUPLICATES = 634 new PropertyName<Boolean>(StpExBase.PROPERTY_NAMESPACE, 635 "has-duplicates"); 636 637 /** 638 * Returns the value of the {@link #HAS_DUPLICATES HAS_DUPLICATES} property 639 * as defined by this proxy. 640 * 641 * @return <b>true</b> if records have been marked as duplicates of this 642 * record. 643 * 644 * @throws WvcmException if this proxy does not define a value for the 645 * {@link #HAS_DUPLICATES HAS_DUPLICATES} property. 646 * 647 * @see #getDuplicates() 648 * @see #getAllDuplicates() 649 * @see #getIsOriginal() 650 */ 651 boolean getHasDuplicates() throws WvcmException; 652 653 /** 654 * True if this record has duplicates but is not itself a duplicate (i.e. 655 * !IS_DUPLICATE & HAS_DUPLICATES) 656 */ 657 PropertyName<Boolean> IS_ORIGINAL = 658 new PropertyName<Boolean>(StpExBase.PROPERTY_NAMESPACE, "is-original"); 659 660 /** 661 * Returns the value of the {@link #IS_ORIGINAL IS_ORIGINAL} property as 662 * defined by this proxy. 663 * 664 * @return <b>true</b> if this record has duplicates but is not, itself, a 665 * duplicate of another record. 666 * 667 * @throws WvcmException if this proxy does not define a value for the 668 * {@link #IS_ORIGINAL IS_ORIGINAL} property. 669 */ 670 boolean getIsOriginal() throws WvcmException; 671 672 /** The immediate duplicates of this record. */ 673 PropertyName<ResourceList<CqRecord>> DUPLICATES = 674 new PropertyName<ResourceList<CqRecord>>(StpExBase.PROPERTY_NAMESPACE, 675 "duplicates"); 676 677 /** 678 * Returns the value of the {@link #DUPLICATES DUPLICATES} property as 679 * defined by this proxy. 680 * 681 * @return A ResourceList of CqRecord proxies representing all of the 682 * records that have been explicitly marked as a duplicate of this 683 * record. 684 * 685 * @throws WvcmException if this proxy does not define a value for the 686 * {@link #DUPLICATES DUPLICATES} property. 687 * 688 * @see #getAllDuplicates() 689 */ 690 ResourceList<CqRecord> getDuplicates() throws WvcmException; 691 692 /** 693 * All of the duplicates of this record, including duplicates of duplicates, 694 * etc. 695 */ 696 PropertyName<ResourceList<CqRecord>> ALL_DUPLICATES = 697 new PropertyName<ResourceList<CqRecord>>(StpExBase.PROPERTY_NAMESPACE, 698 "all-duplicates"); 699 700 /** 701 * Returns the value of the {@link #ALL_DUPLICATES ALL_DUPLICATES} property 702 * as defined by this proxy. 703 * 704 * @return A ResourceList of CqRecord proxies representing all of the 705 * records marked as duplicates of this record or (recursively) one 706 * of its duplicates. 707 * 708 * @throws WvcmException if this proxy does not define a value for the 709 * {@link #ALL_DUPLICATES ALL_DUPLICATES} property. 710 */ 711 ResourceList<CqRecord> getAllDuplicates() throws WvcmException; 712 713 /** 714 * A list of the fields that were modified by the on-going action applied to 715 * this record. 716 */ 717 PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_ACTION = 718 new PropertyName<StpProperty.List<CqFieldValue<?>>>(StpExBase.PROPERTY_NAMESPACE, 719 "fields-updated-this-action"); 720 721 /** 722 * Returns the value of the {@link #FIELDS_UPDATED_THIS_ACTION 723 * FIELDS_UPDATED_THIS_ACTION} property as defined by this proxy. 724 * 725 * @return An StpProperty.List containing a CqFieldValue for each field 726 * updated since the beginning of the current action on this record. 727 * Each CqFieldValue defines the metadata requested when this 728 * property was retrieved from the server. 729 * 730 * @throws WvcmException if this proxy does not define a value for the 731 * {@link #FIELDS_UPDATED_THIS_ACTION 732 * FIELDS_UPDATED_THIS_ACTION} property. 733 */ 734 StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisAction() 735 throws WvcmException; 736 737 /** 738 * A list of the fields that were modified under the current action since 739 * the last time this property was set. 740 * 741 * @see #setFieldsUpdatedThisGroup() 742 */ 743 PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_GROUP = 744 new PropertyName<StpProperty.List<CqFieldValue<?>>>(StpExBase.PROPERTY_NAMESPACE, 745 "fields-updated-this-group"); 746 747 /** 748 * Returns the value of the {@link #FIELDS_UPDATED_THIS_GROUP 749 * FIELDS_UPDATED_THIS_GROUP} property as defined by this proxy. 750 * 751 * @return An StpProperty.List containing a CqFieldValue instance for each 752 * field updated since the last time the 753 * {@link #FIELDS_UPDATED_THIS_GROUP} property was set. 754 * 755 * @throws WvcmException if this proxy does not define a value for the 756 * {@link #FIELDS_UPDATED_THIS_GROUP FIELDS_UPDATED_THIS_GROUP} 757 * property. 758 */ 759 StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisGroup() 760 throws WvcmException; 761 762 /** 763 * Clears the FIELDS_UPDATED_THIS_GROUP property. Only fields updated after 764 * this value is set will be returned by subsequent requests for the 765 * FIELDS_UPDATED_THIS_GROUP property. 766 */ 767 void setFieldsUpdatedThisGroup(); 768 769 /** 770 * The fields that were modified by the last field update. 771 */ 772 PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_SET_VALUE = 773 new PropertyName<StpProperty.List<CqFieldValue<?>>>(StpExBase.PROPERTY_NAMESPACE, 774 "fields-updated-this-set-value"); 775 776 /** 777 * Returns the value of the {@link #FIELDS_UPDATED_THIS_SET_VALUE 778 * FIELDS_UPDATED_THIS_SET_VALUE} property as defined by this proxy. 779 * 780 * @return An StpProperty.List containing a CqFieldValue instance for each 781 * field modified by the most recent client-initiated field update. 782 * 783 * @throws WvcmException if this proxy does not define a value for the 784 * {@link #FIELDS_UPDATED_THIS_SET_VALUE 785 * FIELDS_UPDATED_THIS_SET_VALUE} property. 786 */ 787 StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisSetValue() 788 throws WvcmException; 789 790 /** 791 * A list of the record's invalid fields. 792 */ 793 PropertyName<StpProperty.List<CqFieldValue<?>>> INVALID_FIELDS = 794 new PropertyName<StpProperty.List<CqFieldValue<?>>>(StpExBase.PROPERTY_NAMESPACE, 795 "invalid-fields"); 796 797 /** 798 * Returns the value of the {@link #INVALID_FIELDS INVALID_FIELDS} property 799 * as defined by this proxy. 800 * 801 * @return An StpProperty.list of CqFieldValue instances identifying the 802 * fields of this record that are currently invalid. 803 * 804 * @throws WvcmException if this proxy does not define a value for the 805 * {@link #INVALID_FIELDS INVALID_FIELDS} property. 806 */ 807 StpProperty.List<CqFieldValue<?>> getInvalidFields() throws WvcmException; 808 809 /** 810 * The actions that can be legally applied to this record in its current 811 * state. 812 */ 813 PropertyName<ResourceList<CqAction>> LEGAL_ACTIONS = 814 new PropertyName<ResourceList<CqAction>>(StpExBase.PROPERTY_NAMESPACE, 815 "legal-actions"); 816 817 /** 818 * Returns the value of the {@link #LEGAL_ACTIONS LEGAL_ACTIONS} property as 819 * defined by this proxy. 820 * 821 * @return A list of CqAction proxies representing the actions that are 822 * currently legal for this record. 823 * 824 * @throws WvcmException if this proxy does not define a value for the 825 * {@link #LEGAL_ACTIONS LEGAL_ACTIONS} property. 826 */ 827 ResourceList<CqAction> getLegalActions() throws WvcmException; 828 829 /** The type (state-based or stateless) of the record. */ 830 PropertyName<CqRecord.Class> RECORD_CLASS = 831 new PropertyName<CqRecord.Class>(StpExBase.PROPERTY_NAMESPACE, 832 "record-class"); 833 834 /** 835 * Returns the value of the {@link #RECORD_CLASS RECORD_CLASS} property as 836 * defined by this proxy. 837 * 838 * @return A CqRecord.Class enumeration identifying the class of this record. 839 * 840 * @throws WvcmException if this proxy does not define a value for the 841 * {@link #RECORD_CLASS RECORD_CLASS} property. 842 */ 843 Class getRecordClass() throws WvcmException; 844 845 /** 846 * The CqAttachmentFolder resources that correspond to the fields of this 847 * record that have or may have attachments. The display name of the 848 * attachment folder is the same as the name of the attachment field. 849 */ 850 PropertyName<ResourceList<CqAttachmentFolder>> ATTACHMENT_FOLDERS = 851 new PropertyName<ResourceList<CqAttachmentFolder>>(StpExBase.PROPERTY_NAMESPACE, 852 "attachment-folders"); 853 854 /** 855 * Returns the value of the {@link #ATTACHMENT_FOLDERS ATTACHMENT_FOLDERS} 856 * property as defined by this proxy. 857 * 858 * @return A ResourceList contain CqAttachmentFolder proxies identifying the 859 * attachment folders of this record. 860 * 861 * @throws WvcmException if this proxy does not define a value for the 862 * {@link #ATTACHMENT_FOLDERS ATTACHMENT_FOLDERS} property. 863 */ 864 ResourceList<CqAttachmentFolder> getAttachmentFolders() 865 throws WvcmException; 866 867 /** 868 * An enumeration of the possible types of records; state-based or 869 * stateless. 870 */ 871 public static enum Class implements StpExEnumeration 872 { 873 /** A record type having no state table. */ 874 STATELESS, 875 876 /** 877 * A record type whose records progress from state to state along 878 * prescribed paths based on the actions applied to them. 879 */ 880 STATE_BASED; 881 } 882 883 /** The name of the record's current state. */ 884 PropertyName<String> STATE_NAME = 885 new PropertyName<String>(StpExBase.PROPERTY_NAMESPACE, "state-name"); 886 887 /** 888 * Returns the value of the {@link #STATE_NAME STATE} property as defined by 889 * this proxy. 890 * 891 * @return A String containing the name of the state the record is currently 892 * in. 893 * 894 * @throws WvcmException if this proxy does not define a value for the 895 * {@link #STATE_NAME STATE} property. 896 */ 897 String getStateName() throws WvcmException; 898 899 /** 900 * The replica that has mastership of this record. 901 */ 902 PropertyName<CqReplica> CQ_MASTER_REPLICA = 903 new PropertyName<CqReplica>(StpExBase.PROPERTY_NAMESPACE, 904 "cq-master-replica"); 905 906 /** 907 * Returns the value of the {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA} 908 * property as defined by this proxy. 909 * 910 * @return A CqReplica proxy for the replica that has mastership of this 911 * record 912 * 913 * @throws WvcmException if this proxy does not define a value for the 914 * {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA} property. 915 */ 916 CqReplica getCqMasterReplica() throws WvcmException; 917 918 /** 919 * Defines a new value for the {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA} 920 * property of this proxy. 921 * 922 * @param master A CqReplica proxy identifying the replica that should 923 * assume mastership of this resource. 924 */ 925 void setCqMasterReplica(CqReplica master); 926 927 /** 928 * A list of all the fields that were modified by the on-going action 929 * applied to this record. Unlike the {@link #FIELDS_UPDATED_THIS_ACTION} 930 * property, this list includes fields modified by the hooks that ran during 931 * start up of the action. 932 */ 933 PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_ENTIRE_ACTION = 934 new PropertyName<StpProperty.List<CqFieldValue<?>>>(StpExBase.PROPERTY_NAMESPACE, 935 "fields-updated-this-entire-action"); 936 937 /** 938 * Returns the value of the 939 * {@link #FIELDS_UPDATED_THIS_ENTIRE_ACTION FIELDS_UPDATED_THIS_ENTIRE_ACTION} 940 * property as defined by this proxy. 941 * 942 * @return An StpProperty.List containing a CqFieldValue for each field 943 * modified during the initialization and execution of the current 944 * action. Will never be <b>null</b>, but may be empty. 945 * 946 * @throws WvcmException if this proxy does not define a value for the 947 * {@link #FIELDS_UPDATED_THIS_ENTIRE_ACTION FIELDS_UPDATED_THIS_ENTIRE_ACTION} 948 * property. 949 */ 950 StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisEntireAction() 951 throws WvcmException; 952 953 /** 954 * A list of the fields of this record of 955 * {@link CqFieldValue.ValueType#JOURNAL} 956 */ 957 PropertyName<StpProperty.List<CqHistoryFieldValue>> HISTORY_FIELDS = 958 new PropertyName<StpProperty.List<CqHistoryFieldValue>>(StpExBase.PROPERTY_NAMESPACE, 959 "history-fields"); 960 961 /** 962 * Returns the value of the {@link #HISTORY_FIELDS HISTORY_FIELDS} property 963 * as defined by this proxy. 964 * 965 * @return An StpProperty.List containing a CqFieldValue instance for each 966 * field of the record whose field value type is JOURNAL. Will never 967 * be <b>null</b>, but may be empty. 968 * 969 * @throws WvcmException if this proxy does not define a value for the 970 * {@link #HISTORY_FIELDS HISTORY_FIELDS} property. 971 */ 972 StpProperty.List<CqHistoryFieldValue> getHistoryFields() 973 throws WvcmException; 974 975 /** 976 * A list of the actions that the current user may apply to this record. 977 */ 978 PropertyName<ResourceList<CqAction>> LEGAL_ACCESSIBLE_ACTIONS = 979 new PropertyName<ResourceList<CqAction>>(StpExBase.PROPERTY_NAMESPACE, 980 "legal-accessible-actions"); 981 982 /** 983 * Returns the value of the 984 * {@link #LEGAL_ACCESSIBLE_ACTIONS LEGAL_ACCESSIBLE_ACTIONS} property as 985 * defined by this proxy. 986 * 987 * @return A ResourceList of CqAction proxies enumerating the actions that 988 * the current user may apply to this record in its current state. 989 * Will never be <b>null</b>, but may be empty. 990 * 991 * @throws WvcmException if this proxy does not define a value for the 992 * {@link #LEGAL_ACCESSIBLE_ACTIONS LEGAL_ACCESSIBLE_ACTIONS} 993 * property. 994 */ 995 ResourceList<CqAction> getLegalAccessibleActions() throws WvcmException; 996 997 /** 998 * The site-extension field for this record. 999 */ 1000 PropertyName<String> SITE_EXTENSION = 1001 new PropertyName<String>(StpExBase.PROPERTY_NAMESPACE, "site-extension"); 1002 1003 /** 1004 * Returns the value of the {@link #SITE_EXTENSION SITE_EXTENSION} property 1005 * as defined by this proxy. 1006 * 1007 * @return A String containing the site-extension field used for this record 1008 * when forming its site-extended name. Will never be <b>null</b>. 1009 * 1010 * @throws WvcmException if this proxy does not define a value for the 1011 * {@link #SITE_EXTENSION SITE_EXTENSION} property. 1012 */ 1013 String getSiteExtension() throws WvcmException; 1014 1015 /** 1016 * A list of all the records of this record type whose names differ from the 1017 * name of this record only in their site extensions. 1018 */ 1019 PropertyName<ResourceList<CqRecord>> SITE_EXTENDED_NAMES = 1020 new PropertyName<ResourceList<CqRecord>>(StpExBase.PROPERTY_NAMESPACE, 1021 "site-extended-names"); 1022 1023 /** 1024 * Returns the value of the {@link #SITE_EXTENDED_NAMES SITE_EXTENDED_NAMES} 1025 * property as defined by this proxy. 1026 * 1027 * @return A ResourceList containing a proxy for each CqRecord resource 1028 * whose name differs from the name of this record only in the 1029 * site extensions used. 1030 * 1031 * @throws WvcmException if this proxy does not define a value for the 1032 * {@link #SITE_EXTENDED_NAMES SITE_EXTENDED_NAMES} property. 1033 */ 1034 public ResourceList<CqRecord> getSiteExtendedNames() throws WvcmException; 1035 1036 /** 1037 * The login name of the user currently holding a lock on this record ("*" 1038 * if the current user is not permitted to see user names). A zero-length 1039 * string indicates that the record is not locked. Setting this property to 1040 * the user's login-name or to a zero-length string locks or unlocks the 1041 * record, respectively. 1042 */ 1043 PropertyName<String> LOCK_OWNER = 1044 new PropertyName<String>(PROPERTY_NAMESPACE, "lock-owner"); 1045 1046 /** 1047 * Returns the value of the {@link #LOCK_OWNER LOCK_OWNER} property as 1048 * defined by this proxy. 1049 * 1050 * @return A String containing the login name of the user that has a lock on 1051 * this record ("*" if the current user is not permitted to see 1052 * other's login names). If no user has a lock on this record, a 1053 * zero-length String is returned. 1054 * 1055 * @throws WvcmException if this proxy does not define a value for the 1056 * {@link #LOCK_OWNER LOCK_OWNER} property. 1057 */ 1058 String getLockOwner() throws WvcmException; 1059 1060 /** 1061 * Defines a new value for the {@link #LOCK_OWNER LOCK_OWNER} property of 1062 * this proxy. 1063 * <p> 1064 * Unlike the other writable properties of a record, updating the LOCK_OWNER 1065 * property <i>does not</i> require that an action be started or be in 1066 * progress. And if an action is started or is in progress, the record is 1067 * locked immediately and will remain locked only until the action is 1068 * delivered or reverted. 1069 * 1070 * @param owner Either a zero-length String or a String containing the login 1071 * name of the current user. Setting the value to a zero-length 1072 * String will unlock the record. Setting a non-zero length value 1073 * will lock the record. 1074 * 1075 * @return This proxy. 1076 */ 1077 CqRecord setLockOwner(String owner); 1078 }