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 * © 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. 439 * <p> 440 * If you are changing the contents of a record programmatically, you should 441 * make sure that your code provides valid data. 442 * <p> 443 * You should not attempt to parse and interpret the returned String 444 * programmatically, because the error text may change in future releases. 445 * If you want to try to correct the value in an field with incorrect 446 * values, you can use the INVALID_FIELDS property to discover which fields 447 * are invalid. The MESSAGE_TEXT meta-property of those fields will identify 448 * problems specific to the field. 449 */ 450 PropertyName<String> VALIDATION_ERROR = 451 new PropertyName<String>(StpExBase.PROPERTY_NAMESPACE, 452 "validation-error"); 453 454 /** 455 * Returns the value of the {@link #VALIDATION_ERROR VALIDATION_ERROR} 456 * property as defined by this proxy. 457 * 458 * @return Returns a String containing the error message generated when this 459 * record was validated against the repository schema. Will never be 460 * <b>null</b>, but may be empty is the record field values are 461 * fully compliant with the rules of the schema. 462 * 463 * @throws WvcmException if this proxy does not define a value for the 464 * {@link #VALIDATION_ERROR VALIDATION_ERROR } property. 465 */ 466 String getValidationError() throws WvcmException; 467 468 /** 469 * The action under which this record is being modified; null if the record 470 * is not being modified. 471 */ 472 PropertyName<CqAction> ACTION = 473 new PropertyName<CqAction>(StpExBase.PROPERTY_NAMESPACE, "action"); 474 475 /** 476 * Returns the value of the {@link #ACTION ACTION} property as defined by 477 * this proxy. 478 * 479 * @return Returns an Action proxy representing the action associated with 480 * this record. 481 * 482 * @throws WvcmException if this proxy does not define a value for the 483 * {@link #ACTION ACTION} property. 484 */ 485 CqAction getAction() throws WvcmException; 486 487 /** 488 * Defines a new value for the {@link #ACTION ACTION} property of this 489 * proxy. Set this value prior to invoking doWriteProperties, 490 * doCreateRecord, or doUnbindAll to specify an action other than the 491 * default action specified for those operations. If this property is not 492 * set prior to invocation of these methods, an action of the required type 493 * will be used if one is unique defined. 494 * 495 * @param action A CqAction proxy identifying the action under which this 496 * record is to be created, modified, or deleted. Must not be 497 * <b>null</b>. For the update to succeed, the given action must 498 * be on the LEGAL_ACTIONs list for this record. 499 */ 500 CqRecord setAction(CqAction action); 501 502 /** 503 * The type of the action under which this record is being modified, 504 * Type.NIL if the record is not being modified 505 */ 506 PropertyName<CqAction.Type> ACTION_TYPE = 507 new PropertyName<CqAction.Type>(StpExBase.PROPERTY_NAMESPACE, 508 "action-type"); 509 510 /** 511 * Returns the value of the {@link #ACTION ACTION} property as defined by 512 * this proxy. 513 * 514 * @return An Action.Type enumerator indicating the type of action 515 * associated with this record. 516 * 517 * @throws WvcmException if this proxy does not define a value for the 518 * {@link #ACTION_TYPE ACTION_TYPE} property. 519 */ 520 CqAction.Type getActionType() throws WvcmException; 521 522 /** 523 * A list of {@link CqFieldValue CqFieldValue} objects corresponding to all 524 * of the fields of this record. By default, no meta-property of any field 525 * is included in the CqFieldValue's on this list. So, essentially, the 526 * result is just a list of field property names. Using a NestedPropertyName 527 * in the PropertyRequest of this property would allow the client to request 528 * any or all meta-properties of the fields in the list. 529 * <code> 530 * new PropertyRequest(ALL_FIELD_VALUES.nest(VALUE.nest(VALUE))), 531 * </code> 532 * for example, would request the value of each field of the record. 533 */ 534 PropertyName<StpProperty.List<CqFieldValue<?>>> ALL_FIELD_VALUES = 535 new PropertyName<StpProperty.List<CqFieldValue<?>>>(PROPERTY_NAMESPACE, 536 "all-field-values"); 537 538 /** 539 * Returns the value of the {@link #ALL_FIELD_VALUES ALL_FIELD_VALUES} 540 * property as defined by this proxy. 541 * 542 * @return An StpProperty.List containing a CqFieldValue instance for each 543 * field of this record. Each CqFieldValue instance defines all of 544 * the metadata requested from the server for the field. 545 * 546 * @throws WvcmException if this proxy does not define a value for the 547 * {@link #ALL_FIELD_VALUES ALL_FIELD_VALUES} property. 548 */ 549 StpProperty.List<CqFieldValue<?>> getAllFieldValues() throws WvcmException; 550 551 /** The default action associated with the current state of this record. */ 552 PropertyName<CqAction> DEFAULT_ACTION = 553 new PropertyName<CqAction>(StpExBase.PROPERTY_NAMESPACE, 554 "default-action"); 555 556 /** 557 * Returns the value of the {@link #DEFAULT_ACTION DEFAULT_ACTION} property 558 * as defined by this proxy. 559 * 560 * @return A CqAction proxy representing the default action associated with 561 * this record in its current state. Will be null if a default 562 * action is not defined for this record. 563 * 564 * @throws WvcmException if this proxy does not define a value for the 565 * {@link #DEFAULT_ACTION DEFAULT_ACTION} property. 566 */ 567 CqAction getDefaultAction() throws WvcmException; 568 569 /** Whether this record has been marked as a duplicate of another record. */ 570 PropertyName<Boolean> IS_DUPLICATE = 571 new PropertyName<Boolean>(StpExBase.PROPERTY_NAMESPACE, "is-duplicate"); 572 573 /** 574 * Returns the value of the {@link #IS_DUPLICATE IS_DUPLICATE} property as 575 * defined by this proxy. 576 * 577 * @return <b>true</b> if this record has been recorded as a duplicate of 578 * another record. 579 * 580 * @throws WvcmException if this proxy does not define a value for the 581 * {@link #IS_DUPLICATE IS_DUPLICATE} property. 582 * 583 * @see #getAllDuplicates() 584 * @see #getDuplicates() 585 * @see #getHasDuplicates() 586 */ 587 boolean getIsDuplicate() throws WvcmException; 588 589 /** 590 * The CqRecord that is marked as the original of this duplicate record. 591 */ 592 PropertyName<CqRecord> ORIGINAL = 593 new PropertyName<CqRecord>(StpExBase.PROPERTY_NAMESPACE, "original"); 594 595 /** 596 * Returns the value of the {@link #ORIGINAL ORIGINAL} property as defined 597 * by this proxy. 598 * 599 * @return A CqRecord proxy representing the record of which this is a 600 * duplicate. Will be <b>null</b> if this record is not a 601 * duplicate. 602 * 603 * @throws WvcmException if this proxy does not define a value for the 604 * {@link #ORIGINAL ORIGINAL} property. 605 */ 606 CqRecord getOriginal() throws WvcmException; 607 608 /** The visible ID of this object's original record. */ 609 PropertyName<String> ORIGINAL_ID = 610 new PropertyName<String>(StpExBase.PROPERTY_NAMESPACE, "original-id"); 611 612 /** 613 * Returns the value of the {@link #ORIGINAL_ID ORIGINAL_ID} property as 614 * defined by this proxy. 615 * 616 * @return A String containing the record id for the record that this record 617 * is a duplicate of. Will be <b>null</b> if this record is not a 618 * duplicate. 619 * 620 * @throws WvcmException if this proxy does not define a value for the 621 * {@link #ORIGINAL_ID ORIGINAL_ID} property. 622 */ 623 String getOriginalId() throws WvcmException; 624 625 /** 626 * Whether other records have been marked as being duplicates of this record 627 */ 628 PropertyName<Boolean> HAS_DUPLICATES = 629 new PropertyName<Boolean>(StpExBase.PROPERTY_NAMESPACE, 630 "has-duplicates"); 631 632 /** 633 * Returns the value of the {@link #HAS_DUPLICATES HAS_DUPLICATES} property 634 * as defined by this proxy. 635 * 636 * @return <b>true</b> if records have been marked as duplicates of this 637 * record. 638 * 639 * @throws WvcmException if this proxy does not define a value for the 640 * {@link #HAS_DUPLICATES HAS_DUPLICATES} property. 641 * 642 * @see #getDuplicates() 643 * @see #getAllDuplicates() 644 * @see #getIsOriginal() 645 */ 646 boolean getHasDuplicates() throws WvcmException; 647 648 /** 649 * True if this record has duplicates but is not itself a duplicate (i.e. 650 * !IS_DUPLICATE & HAS_DUPLICATES) 651 */ 652 PropertyName<Boolean> IS_ORIGINAL = 653 new PropertyName<Boolean>(StpExBase.PROPERTY_NAMESPACE, "is-original"); 654 655 /** 656 * Returns the value of the {@link #IS_ORIGINAL IS_ORIGINAL} property as 657 * defined by this proxy. 658 * 659 * @return <b>true</b> if this record has duplicates but is not, itself, a 660 * duplicate of another record. 661 * 662 * @throws WvcmException if this proxy does not define a value for the 663 * {@link #IS_ORIGINAL IS_ORIGINAL} property. 664 */ 665 boolean getIsOriginal() throws WvcmException; 666 667 /** The immediate duplicates of this record. */ 668 PropertyName<ResourceList<CqRecord>> DUPLICATES = 669 new PropertyName<ResourceList<CqRecord>>(StpExBase.PROPERTY_NAMESPACE, 670 "duplicates"); 671 672 /** 673 * Returns the value of the {@link #DUPLICATES DUPLICATES} property as 674 * defined by this proxy. 675 * 676 * @return A ResourceList of CqRecord proxies representing all of the 677 * records that have been explicitly marked as a duplicate of this 678 * record. 679 * 680 * @throws WvcmException if this proxy does not define a value for the 681 * {@link #DUPLICATES DUPLICATES} property. 682 * 683 * @see #getAllDuplicates() 684 */ 685 ResourceList<CqRecord> getDuplicates() throws WvcmException; 686 687 /** 688 * All of the duplicates of this record, including duplicates of duplicates, 689 * etc. 690 */ 691 PropertyName<ResourceList<CqRecord>> ALL_DUPLICATES = 692 new PropertyName<ResourceList<CqRecord>>(StpExBase.PROPERTY_NAMESPACE, 693 "all-duplicates"); 694 695 /** 696 * Returns the value of the {@link #ALL_DUPLICATES ALL_DUPLICATES} property 697 * as defined by this proxy. 698 * 699 * @return A ResourceList of CqRecord proxies representing all of the 700 * records marked as duplicates of this record or (recursively) one 701 * of its duplicates. 702 * 703 * @throws WvcmException if this proxy does not define a value for the 704 * {@link #ALL_DUPLICATES ALL_DUPLICATES} property. 705 */ 706 ResourceList<CqRecord> getAllDuplicates() throws WvcmException; 707 708 /** 709 * A list of the fields that were modified by the on-going action applied to 710 * this record. 711 */ 712 PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_ACTION = 713 new PropertyName<StpProperty.List<CqFieldValue<?>>>(StpExBase.PROPERTY_NAMESPACE, 714 "fields-updated-this-action"); 715 716 /** 717 * Returns the value of the {@link #FIELDS_UPDATED_THIS_ACTION 718 * FIELDS_UPDATED_THIS_ACTION} property as defined by this proxy. 719 * 720 * @return An StpProperty.List containing a CqFieldValue for each field 721 * updated since the beginning of the current action on this record. 722 * Each CqFieldValue defines the metadata requested when this 723 * property was retrieved from the server. 724 * 725 * @throws WvcmException if this proxy does not define a value for the 726 * {@link #FIELDS_UPDATED_THIS_ACTION 727 * FIELDS_UPDATED_THIS_ACTION} property. 728 */ 729 StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisAction() 730 throws WvcmException; 731 732 /** 733 * A list of the fields that were modified under the current action since 734 * the last time this property was set. 735 * 736 * @see #setFieldsUpdatedThisGroup() 737 */ 738 PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_GROUP = 739 new PropertyName<StpProperty.List<CqFieldValue<?>>>(StpExBase.PROPERTY_NAMESPACE, 740 "fields-updated-this-group"); 741 742 /** 743 * Returns the value of the {@link #FIELDS_UPDATED_THIS_GROUP 744 * FIELDS_UPDATED_THIS_GROUP} property as defined by this proxy. 745 * 746 * @return An StpProperty.List containing a CqFieldValue instance for each 747 * field updated since the last time the 748 * {@link #FIELDS_UPDATED_THIS_GROUP} property was set. 749 * 750 * @throws WvcmException if this proxy does not define a value for the 751 * {@link #FIELDS_UPDATED_THIS_GROUP FIELDS_UPDATED_THIS_GROUP} 752 * property. 753 */ 754 StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisGroup() 755 throws WvcmException; 756 757 /** 758 * Clears the FIELDS_UPDATED_THIS_GROUP property. Only fields updated after 759 * this value is set will be returned by subsequent requests for the 760 * FIELDS_UPDATED_THIS_GROUP property. 761 */ 762 void setFieldsUpdatedThisGroup(); 763 764 /** 765 * The fields that were modified by the last field update. 766 */ 767 PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_SET_VALUE = 768 new PropertyName<StpProperty.List<CqFieldValue<?>>>(StpExBase.PROPERTY_NAMESPACE, 769 "fields-updated-this-set-value"); 770 771 /** 772 * Returns the value of the {@link #FIELDS_UPDATED_THIS_SET_VALUE 773 * FIELDS_UPDATED_THIS_SET_VALUE} property as defined by this proxy. 774 * 775 * @return An StpProperty.List containing a CqFieldValue instance for each 776 * field modified by the most recent client-initiated field update. 777 * 778 * @throws WvcmException if this proxy does not define a value for the 779 * {@link #FIELDS_UPDATED_THIS_SET_VALUE 780 * FIELDS_UPDATED_THIS_SET_VALUE} property. 781 */ 782 StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisSetValue() 783 throws WvcmException; 784 785 /** 786 * A list of the record's invalid fields. 787 */ 788 PropertyName<StpProperty.List<CqFieldValue<?>>> INVALID_FIELDS = 789 new PropertyName<StpProperty.List<CqFieldValue<?>>>(StpExBase.PROPERTY_NAMESPACE, 790 "invalid-fields"); 791 792 /** 793 * Returns the value of the {@link #INVALID_FIELDS INVALID_FIELDS} property 794 * as defined by this proxy. 795 * 796 * @return An StpProperty.list of CqFieldValue instances identifying the 797 * fields of this record that are currently invalid. 798 * 799 * @throws WvcmException if this proxy does not define a value for the 800 * {@link #INVALID_FIELDS INVALID_FIELDS} property. 801 */ 802 StpProperty.List<CqFieldValue<?>> getInvalidFields() throws WvcmException; 803 804 /** 805 * The actions that can be legally applied to this record in its current 806 * state. 807 */ 808 PropertyName<ResourceList<CqAction>> LEGAL_ACTIONS = 809 new PropertyName<ResourceList<CqAction>>(StpExBase.PROPERTY_NAMESPACE, 810 "legal-actions"); 811 812 /** 813 * Returns the value of the {@link #LEGAL_ACTIONS LEGAL_ACTIONS} property as 814 * defined by this proxy. 815 * 816 * @return A list of CqAction proxies representing the actions that are 817 * currently legal for this record. 818 * 819 * @throws WvcmException if this proxy does not define a value for the 820 * {@link #LEGAL_ACTIONS LEGAL_ACTIONS} property. 821 */ 822 ResourceList<CqAction> getLegalActions() throws WvcmException; 823 824 /** The type (state-based or stateless) of the record. */ 825 PropertyName<CqRecord.Class> RECORD_CLASS = 826 new PropertyName<CqRecord.Class>(StpExBase.PROPERTY_NAMESPACE, 827 "record-class"); 828 829 /** 830 * Returns the value of the {@link #RECORD_CLASS RECORD_CLASS} property as 831 * defined by this proxy. 832 * 833 * @return A CqRecord.Class enumeration identifying the class of this record. 834 * 835 * @throws WvcmException if this proxy does not define a value for the 836 * {@link #RECORD_CLASS RECORD_CLASS} property. 837 */ 838 Class getRecordClass() throws WvcmException; 839 840 /** 841 * The CqAttachmentFolder resources that correspond to the fields of this 842 * record that have or may have attachments. The display name of the 843 * attachment folder is the same as the name of the attachment field. 844 */ 845 PropertyName<ResourceList<CqAttachmentFolder>> ATTACHMENT_FOLDERS = 846 new PropertyName<ResourceList<CqAttachmentFolder>>(StpExBase.PROPERTY_NAMESPACE, 847 "attachment-folders"); 848 849 /** 850 * Returns the value of the {@link #ATTACHMENT_FOLDERS ATTACHMENT_FOLDERS} 851 * property as defined by this proxy. 852 * 853 * @return A ResourceList contain CqAttachmentFolder proxies identifying the 854 * attachment folders of this record. 855 * 856 * @throws WvcmException if this proxy does not define a value for the 857 * {@link #ATTACHMENT_FOLDERS ATTACHMENT_FOLDERS} property. 858 */ 859 ResourceList<CqAttachmentFolder> getAttachmentFolders() 860 throws WvcmException; 861 862 /** 863 * An enumeration of the possible types of records; state-based or 864 * stateless. 865 */ 866 public static enum Class implements StpExEnumeration 867 { 868 /** A record type having no state table. */ 869 STATELESS, 870 871 /** 872 * A record type whose records progress from state to state along 873 * prescribed paths based on the actions applied to them. 874 */ 875 STATE_BASED; 876 } 877 878 /** The name of the record's current state. */ 879 PropertyName<String> STATE_NAME = 880 new PropertyName<String>(StpExBase.PROPERTY_NAMESPACE, "state-name"); 881 882 /** 883 * Returns the value of the {@link #STATE_NAME STATE} property as defined by 884 * this proxy. 885 * 886 * @return A String containing the name of the state the record is currently 887 * in. 888 * 889 * @throws WvcmException if this proxy does not define a value for the 890 * {@link #STATE_NAME STATE} property. 891 */ 892 String getStateName() throws WvcmException; 893 894 /** 895 * The replica that has mastership of this record. 896 */ 897 PropertyName<CqReplica> CQ_MASTER_REPLICA = 898 new PropertyName<CqReplica>(StpExBase.PROPERTY_NAMESPACE, 899 "cq-master-replica"); 900 901 /** 902 * Returns the value of the {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA} 903 * property as defined by this proxy. 904 * 905 * @return A CqReplica proxy for the replica that has mastership of this 906 * record 907 * 908 * @throws WvcmException if this proxy does not define a value for the 909 * {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA} property. 910 */ 911 CqReplica getCqMasterReplica() throws WvcmException; 912 913 /** 914 * Defines a new value for the {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA} 915 * property of this proxy. 916 * 917 * @param master A CqReplica proxy identifying the replica that should 918 * assume mastership of this resource. 919 */ 920 void setCqMasterReplica(CqReplica master); 921 922 /** 923 * A list of all the fields that were modified by the on-going action 924 * applied to this record. Unlike the {@link #FIELDS_UPDATED_THIS_ACTION} 925 * property, this list includes fields modified by the hooks that ran during 926 * start up of the action. 927 */ 928 PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_ENTIRE_ACTION = 929 new PropertyName<StpProperty.List<CqFieldValue<?>>>(StpExBase.PROPERTY_NAMESPACE, 930 "fields-updated-this-entire-action"); 931 932 /** 933 * Returns the value of the 934 * {@link #FIELDS_UPDATED_THIS_ENTIRE_ACTION FIELDS_UPDATED_THIS_ENTIRE_ACTION} 935 * property as defined by this proxy. 936 * 937 * @return An StpProperty.List containing a CqFieldValue for each field 938 * modified during the initialization and execution of the current 939 * action. Will never be <b>null</b>, but may be empty. 940 * 941 * @throws WvcmException if this proxy does not define a value for the 942 * {@link #FIELDS_UPDATED_THIS_ENTIRE_ACTION FIELDS_UPDATED_THIS_ENTIRE_ACTION} 943 * property. 944 */ 945 StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisEntireAction() 946 throws WvcmException; 947 948 /** 949 * A list of the fields of this record of 950 * {@link CqFieldValue.ValueType#JOURNAL} 951 */ 952 PropertyName<StpProperty.List<CqHistoryFieldValue>> HISTORY_FIELDS = 953 new PropertyName<StpProperty.List<CqHistoryFieldValue>>(StpExBase.PROPERTY_NAMESPACE, 954 "history-fields"); 955 956 /** 957 * Returns the value of the {@link #HISTORY_FIELDS HISTORY_FIELDS} property 958 * as defined by this proxy. 959 * 960 * @return An StpProperty.List containing a CqFieldValue instance for each 961 * field of the record whose field value type is JOURNAL. Will never 962 * be <b>null</b>, but may be empty. 963 * 964 * @throws WvcmException if this proxy does not define a value for the 965 * {@link #HISTORY_FIELDS HISTORY_FIELDS} property. 966 */ 967 StpProperty.List<CqHistoryFieldValue> getHistoryFields() 968 throws WvcmException; 969 970 /** 971 * A list of the actions that the current user may apply to this record. 972 */ 973 PropertyName<ResourceList<CqAction>> LEGAL_ACCESSIBLE_ACTIONS = 974 new PropertyName<ResourceList<CqAction>>(StpExBase.PROPERTY_NAMESPACE, 975 "legal-accessible-actions"); 976 977 /** 978 * Returns the value of the 979 * {@link #LEGAL_ACCESSIBLE_ACTIONS LEGAL_ACCESSIBLE_ACTIONS} property as 980 * defined by this proxy. 981 * 982 * @return A ResourceList of CqAction proxies enumerating the actions that 983 * the current user may apply to this record in its current state. 984 * Will never be <b>null</b>, but may be empty. 985 * 986 * @throws WvcmException if this proxy does not define a value for the 987 * {@link #LEGAL_ACCESSIBLE_ACTIONS LEGAL_ACCESSIBLE_ACTIONS} 988 * property. 989 */ 990 ResourceList<CqAction> getLegalAccessibleActions() throws WvcmException; 991 992 /** 993 * The site-extension field for this record. 994 */ 995 PropertyName<String> SITE_EXTENSION = 996 new PropertyName<String>(StpExBase.PROPERTY_NAMESPACE, "site-extension"); 997 998 /** 999 * Returns the value of the {@link #SITE_EXTENSION SITE_EXTENSION} property 1000 * as defined by this proxy. 1001 * 1002 * @return A String containing the site-extension field used for this record 1003 * when forming its site-extended name. Will never be <b>null</b>. 1004 * 1005 * @throws WvcmException if this proxy does not define a value for the 1006 * {@link #SITE_EXTENSION SITE_EXTENSION} property. 1007 */ 1008 String getSiteExtension() throws WvcmException; 1009 1010 /** 1011 * A list of all the records of this record type whose names differ from the 1012 * name of this record only in their site extensions. 1013 */ 1014 PropertyName<ResourceList<CqRecord>> SITE_EXTENDED_NAMES = 1015 new PropertyName<ResourceList<CqRecord>>(StpExBase.PROPERTY_NAMESPACE, 1016 "site-extended-names"); 1017 1018 /** 1019 * Returns the value of the {@link #SITE_EXTENDED_NAMES SITE_EXTENDED_NAMES} 1020 * property as defined by this proxy. 1021 * 1022 * @return A ResourceList containing a proxy for each CqRecord resource 1023 * whose name differs from the name of this record only in the 1024 * site extensions used. 1025 * 1026 * @throws WvcmException if this proxy does not define a value for the 1027 * {@link #SITE_EXTENDED_NAMES SITE_EXTENDED_NAMES} property. 1028 */ 1029 public ResourceList<CqRecord> getSiteExtendedNames() throws WvcmException; 1030 1031 /** 1032 * The login name of the user currently holding a lock on this record ("*" 1033 * if the current user is not permitted to see user names). A zero-length 1034 * string indicates that the record is not locked. Setting this property to 1035 * the user's login-name or to a zero-length string locks or unlocks the 1036 * record, respectively. 1037 */ 1038 PropertyName<String> LOCK_OWNER = 1039 new PropertyName<String>(PROPERTY_NAMESPACE, "lock-owner"); 1040 1041 /** 1042 * Returns the value of the {@link #LOCK_OWNER LOCK_OWNER} property as 1043 * defined by this proxy. 1044 * 1045 * @return A String containing the login name of the user that has a lock on 1046 * this record ("*" if the current user is not permitted to see 1047 * other's login names). If no user has a lock on this record, a 1048 * zero-length String is returned. 1049 * 1050 * @throws WvcmException if this proxy does not define a value for the 1051 * {@link #LOCK_OWNER LOCK_OWNER} property. 1052 */ 1053 String getLockOwner() throws WvcmException; 1054 1055 /** 1056 * Defines a new value for the {@link #LOCK_OWNER LOCK_OWNER} property of 1057 * this proxy. 1058 * <p> 1059 * Unlike the other writable properties of a record, updating the LOCK_OWNER 1060 * property <i>does not</i> require that an action be started or be in 1061 * progress. And if an action is started or is in progress, the record is 1062 * locked immediately and will remain locked only until the action is 1063 * delivered or reverted. 1064 * 1065 * @param owner Either a zero-length String or a String containing the login 1066 * name of the current user. Setting the value to a zero-length 1067 * String will unlock the record. Setting a non-zero length value 1068 * will lock the record. 1069 * 1070 * @return This proxy. 1071 */ 1072 CqRecord setLockOwner(String owner); 1073 }