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, 2010. 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. Additionally a global hook can be 286 * executed if the global hook's name is known in advance. The impact on 287 * the change context in which the hook is executed is essentially 288 * the same as executing 289 * {@link com.ibm.rational.wvcm.stp.cq.CqContextResource#doWriteProperties(Feedback, List)} 290 * in that context (where the hook is in control of which properties are 291 * written). 292 * <p> 293 * As with doWriteProperties, the record need not be editable prior to 294 * invoking this method, but, unlike doWriteProperties, if it isn't editable 295 * and the hook wants to modify it, then the hook must be prepared to start 296 * an action itself to do so. An implicit Modify-type action is not 297 * automatically started for the hook (except in the case noted below). 298 * <p> 299 * If this proxy contains updated property values when this method is 300 * invoked, an attempt will be made to write those new property values to 301 * the server <i>before</i> the hook is executed. If such an update is 302 * required and this record isn't editable, it will be made editable using 303 * the default Modify-type action and the hook will be applied to that 304 * editable version of the record before delivering the changes to the 305 * database. If the property update fails, this operation fails immediately 306 * and subsequent execution of the hook will not be attempted. 307 * 308 * @param hook A CqHook proxy for the named hook to be fired. If the client 309 * knows the name of the hook to be fired, it should construct a 310 * CqHook proxy at the computed location <i>record</i><code>.stpLocation().recomposeWithNamespace(Namespace.HOOK).parent().child(</code><i>hook-name</i><code>)</code> 311 * If the client does not know the name of the hook to be fired, 312 * a list of available hooks to choose from can be obtained from 313 * the NAMED_HOOK_LIST property of the parent record type of this 314 * record. 315 * Additionally, the client can specify a global hook. If using 316 * a global hook, the client must know the name in advance and 317 * should construct a CqHook proxy at the computed location 318 * <i>record</i><code>.stpLocation().recomposeWithMods(Namespace.HOOK,</code><i>hook-name</i><code>,</code><i>null</i><code>,</code><i>null</i><code>)</code> 319 * @param parameters A String containing any parameters required by the 320 * hook. The format and content of this parameter string is 321 * prescribed solely by the hook, which is also responsible for 322 * parsing it into a usable value or values. 323 * @param feedback Properties to be retrieved from the target record and/or 324 * those records changed by the execution of the hook (and after 325 * delivery if delivery has been requested). 326 * @param deliveryOrder Delivery of the changes made to the record will be 327 * considered only if the hook succeeds. If this argument is 328 * {@link CqProvider#HOLD} the modified record is left in a 329 * writable state in the change context--the modified record must 330 * be delivered before the changes made by the hook become 331 * visible outside the change context. If not 332 * {@link CqProvider#HOLD}, the modified and moribund resources 333 * specified by this parameter will be delivered to or deleted 334 * from the database in the order indicated. To deliver all 335 * modified and moribund resources in an arbitrary order, use 336 * {@link CqProvider#DELIVER_ALL}. To deliver just this modified 337 * record, use {@link CqProvider#DELIVER}. Must not be <b>null</b>. 338 * @return A CqRecord proxy for the modified record, populated with the 339 * resources requested by the feedback argument. 340 * @throws WvcmException if there are problems finding or executing the 341 * named hook, writing updated properties, or starting the 342 * implied action. 343 * @throws StpErrorMessageException if the hook returns a non-empty result 344 */ 345 CqRecord doFireNamedHook(CqHook hook, 346 String parameters, 347 Feedback feedback, 348 List<CqContextResource> deliveryOrder) 349 throws WvcmException, StpErrorMessageException; 350 351 /** 352 * Causes the execution of an action of type 353 * CqAction.Type.RECORD_SCRIPT_ALIAS. Such actions are defined solely by a 354 * hook script, which is executed when the action is applied to a record. 355 * When this method is called, the action is started on this record and the 356 * action's hook script is executed as the sole content of that action and 357 * then the action is committed. The impact of this operation on the change 358 * context is essentially equivalent to executing in the same context 359 * {@link com.ibm.rational.wvcm.stp.cq.CqContextResource#doWriteProperties(Feedback, List)} 360 * where the deliveryOrder argument forces an immediate delivery of the 361 * change context. 362 * <p> 363 * Because of this prescribed processing 364 * <ul> 365 * <li>This record must not be editable when this method is called so that 366 * the specified RECORD_SCRIPT_ALIAS action can be started on it. 367 * <li> This record must not contain updated property values because only 368 * the record script of the action is allowed to make modifications to the 369 * record once the action has started. 370 * <li>If the action script succeeds, delivery of the targeted record is 371 * immediate and cannot be deferred--i.e., CqProvider.HOLD <i>may not</i> 372 * be used for the delivery order list. Furthermore, the targeted record is 373 * delivered first, regardless of the content of the delivery order list. 374 * <li>If the action script fails, no delivery will be attempted and the 375 * change context will remain as it was before invoking this method. 376 * </ul> 377 * <p> 378 * Typically, schema designers have associated arbitrary executable code 379 * with a record type, represented in a GUI as a button with the display 380 * name of the record type action. 381 * 382 * @param action A CqAction for an action of type RECORD_SCRIPT_ALIAS. This 383 * action must be defined by the record type of this record 384 * instance. 385 * @param feedback A Feedback object requesting the properties desired from 386 * resources involved in this operation. May be <b>null</b> if 387 * no properties are desired. 388 * @param deliveryOrder Upon successful execution of the action script, the 389 * target record will be delivered to its database. Then, any 390 * other resources specified by this argument will be delivered. 391 * Must not be <b>null</b> and must not be CqProvider.HOLD. 392 * @return A String containing the return value computed by the hook script. 393 * @throws WvcmException if there are problems 394 * <ul> 395 * <li>finding the record, 396 * <li>finding a RECORD_SCRIPT_ALIAS as specified 397 * <li>starting the action 398 * <li>executing the script 399 * <li>delivering the changes to the database 400 * </ul> 401 */ 402 String doFireRecordScriptAlias(CqAction action, 403 Feedback feedback, 404 List<CqContextResource> deliveryOrder) 405 throws WvcmException; 406 407 /** 408 * Returns the date of the submit action in the record history field. 409 * 410 * @see javax.wvcm.Resource#getCreationDate() 411 */ 412 Date getCreationDate() throws WvcmException; 413 414 /** 415 * Returns the date of the last action applied to the record from its 416 * history 417 * 418 * @see javax.wvcm.Resource#getLastModified() 419 */ 420 Date getLastModified() throws WvcmException; 421 422 /** 423 * Returns the login name of the user who submitted the record 424 * 425 * @see com.ibm.rational.wvcm.stp.StpResource#getCreatorLoginName() 426 */ 427 String getCreatorLoginName() throws WvcmException; 428 429 /** 430 * The error message generated when the record, in its current state, was 431 * validated against the repository schema for compliance with its rules. 432 * This property will be empty if the record is fully compliant (which is 433 * always the case if the record is not open for edit). 434 * <p> 435 * When this property is requested for a record open for editing, the record 436 * is validated before any other properties are retrieved. Thus, all 437 * properties returned with this property reflect the state of the record 438 * after validation was attempted. 439 * <p> 440 * Before a record being edited can be delivered, it must be validated (even 441 * if no fields have been changed). Normally, validation is performed as the 442 * first phase of a delivery and any validation errors cause the delivery to 443 * be aborted. Requesting this property will force validation of the record 444 * without attempting to deliver it. The time and resources needed to 445 * perform a record validation vary with the schema. Unless you have 446 * specific knowledge of the target database's schema, it is best to assume 447 * that the validation process is an expensive operation and design your 448 * application to request this property only when validation is really 449 * required. 450 * <p> 451 * If you are changing the contents of a record programmatically, you should 452 * make sure that your code provides valid data. 453 * <p> 454 * You should not attempt to parse and interpret the returned String 455 * programmatically, because the error text may change in future releases. 456 * If you want to try to correct the value in an field with incorrect 457 * values, you can use the INVALID_FIELDS property to discover which fields 458 * are invalid. The MESSAGE_TEXT meta-property of those fields will identify 459 * problems specific to the field. 460 */ 461 PropertyName<String> VALIDATION_ERROR = 462 new PropertyName<String>(StpExBase.PROPERTY_NAMESPACE, 463 "validation-error"); 464 465 /** 466 * Returns the value of the {@link #VALIDATION_ERROR VALIDATION_ERROR} 467 * property as defined by this proxy. 468 * 469 * @return Returns a String containing the error message generated when this 470 * record was validated against the repository schema. Will never be 471 * <b>null</b>, but may be empty is the record field values are 472 * fully compliant with the rules of the schema. 473 * 474 * @throws WvcmException if this proxy does not define a value for the 475 * {@link #VALIDATION_ERROR VALIDATION_ERROR } property. 476 */ 477 String getValidationError() throws WvcmException; 478 479 /** 480 * The action under which this record is being modified; null if the record 481 * is not being modified. 482 */ 483 PropertyName<CqAction> ACTION = 484 new PropertyName<CqAction>(StpExBase.PROPERTY_NAMESPACE, "action"); 485 486 /** 487 * Returns the value of the {@link #ACTION ACTION} property as defined by 488 * this proxy. 489 * 490 * @return Returns an Action proxy representing the action associated with 491 * this record. 492 * 493 * @throws WvcmException if this proxy does not define a value for the 494 * {@link #ACTION ACTION} property. 495 */ 496 CqAction getAction() throws WvcmException; 497 498 /** 499 * Defines a new value for the {@link #ACTION ACTION} property of this 500 * proxy. Set this value prior to invoking doWriteProperties, 501 * doCreateRecord, or doUnbindAll to specify an action other than the 502 * default action specified for those operations. If this property is not 503 * set prior to invocation of these methods, an action of the required type 504 * will be used if one is unique defined. 505 * 506 * @param action A CqAction proxy identifying the action under which this 507 * record is to be created, modified, or deleted. Must not be 508 * <b>null</b>. For the update to succeed, the given action must 509 * be on the LEGAL_ACTIONs list for this record. 510 */ 511 CqRecord setAction(CqAction action); 512 513 /** 514 * The type of the action under which this record is being modified, 515 * Type.NIL if the record is not being modified 516 */ 517 PropertyName<CqAction.Type> ACTION_TYPE = 518 new PropertyName<CqAction.Type>(StpExBase.PROPERTY_NAMESPACE, 519 "action-type"); 520 521 /** 522 * Returns the value of the {@link #ACTION ACTION} property as defined by 523 * this proxy. 524 * 525 * @return An Action.Type enumerator indicating the type of action 526 * associated with this record. 527 * 528 * @throws WvcmException if this proxy does not define a value for the 529 * {@link #ACTION_TYPE ACTION_TYPE} property. 530 */ 531 CqAction.Type getActionType() throws WvcmException; 532 533 /** 534 * A list of {@link CqFieldValue CqFieldValue} objects corresponding to all 535 * of the fields of this record. By default, no meta-property of any field 536 * is included in the CqFieldValue's on this list. So, essentially, the 537 * result is just a list of field property names. Using a NestedPropertyName 538 * in the PropertyRequest of this property would allow the client to request 539 * any or all meta-properties of the fields in the list. 540 * <code> 541 * new PropertyRequest(ALL_FIELD_VALUES.nest(VALUE.nest(VALUE))), 542 * </code> 543 * for example, would request the value of each field of the record. 544 */ 545 PropertyName<StpProperty.List<CqFieldValue<?>>> ALL_FIELD_VALUES = 546 new PropertyName<StpProperty.List<CqFieldValue<?>>>(PROPERTY_NAMESPACE, 547 "all-field-values"); 548 549 /** 550 * Returns the value of the {@link #ALL_FIELD_VALUES ALL_FIELD_VALUES} 551 * property as defined by this proxy. 552 * 553 * @return An StpProperty.List containing a CqFieldValue instance for each 554 * field of this record. Each CqFieldValue instance defines all of 555 * the metadata requested from the server for the field. 556 * 557 * @throws WvcmException if this proxy does not define a value for the 558 * {@link #ALL_FIELD_VALUES ALL_FIELD_VALUES} property. 559 */ 560 StpProperty.List<CqFieldValue<?>> getAllFieldValues() throws WvcmException; 561 562 /** The default action associated with the current state of this record. */ 563 PropertyName<CqAction> DEFAULT_ACTION = 564 new PropertyName<CqAction>(StpExBase.PROPERTY_NAMESPACE, 565 "default-action"); 566 567 /** 568 * Returns the value of the {@link #DEFAULT_ACTION DEFAULT_ACTION} property 569 * as defined by this proxy. 570 * 571 * @return A CqAction proxy representing the default action associated with 572 * this record in its current state. Will be null if a default 573 * action is not defined for this record. 574 * 575 * @throws WvcmException if this proxy does not define a value for the 576 * {@link #DEFAULT_ACTION DEFAULT_ACTION} property. 577 */ 578 CqAction getDefaultAction() throws WvcmException; 579 580 /** Whether this record has been marked as a duplicate of another record. */ 581 PropertyName<Boolean> IS_DUPLICATE = 582 new PropertyName<Boolean>(StpExBase.PROPERTY_NAMESPACE, "is-duplicate"); 583 584 /** 585 * Returns the value of the {@link #IS_DUPLICATE IS_DUPLICATE} property as 586 * defined by this proxy. 587 * 588 * @return <b>true</b> if this record has been recorded as a duplicate of 589 * another record. 590 * 591 * @throws WvcmException if this proxy does not define a value for the 592 * {@link #IS_DUPLICATE IS_DUPLICATE} property. 593 * 594 * @see #getAllDuplicates() 595 * @see #getDuplicates() 596 * @see #getHasDuplicates() 597 */ 598 boolean getIsDuplicate() throws WvcmException; 599 600 /** 601 * The CqRecord that is marked as the original of this duplicate record. 602 */ 603 PropertyName<CqRecord> ORIGINAL = 604 new PropertyName<CqRecord>(StpExBase.PROPERTY_NAMESPACE, "original"); 605 606 /** 607 * Returns the value of the {@link #ORIGINAL ORIGINAL} property as defined 608 * by this proxy. 609 * 610 * @return A CqRecord proxy representing the record of which this is a 611 * duplicate. Will be <b>null</b> if this record is not a 612 * duplicate. 613 * 614 * @throws WvcmException if this proxy does not define a value for the 615 * {@link #ORIGINAL ORIGINAL} property. 616 */ 617 CqRecord getOriginal() throws WvcmException; 618 619 /** The visible ID of this object's original record. */ 620 PropertyName<String> ORIGINAL_ID = 621 new PropertyName<String>(StpExBase.PROPERTY_NAMESPACE, "original-id"); 622 623 /** 624 * Returns the value of the {@link #ORIGINAL_ID ORIGINAL_ID} property as 625 * defined by this proxy. 626 * 627 * @return A String containing the record id for the record that this record 628 * is a duplicate of. Will be <b>null</b> if this record is not a 629 * duplicate. 630 * 631 * @throws WvcmException if this proxy does not define a value for the 632 * {@link #ORIGINAL_ID ORIGINAL_ID} property. 633 */ 634 String getOriginalId() throws WvcmException; 635 636 /** 637 * Whether other records have been marked as being duplicates of this record 638 */ 639 PropertyName<Boolean> HAS_DUPLICATES = 640 new PropertyName<Boolean>(StpExBase.PROPERTY_NAMESPACE, 641 "has-duplicates"); 642 643 /** 644 * Returns the value of the {@link #HAS_DUPLICATES HAS_DUPLICATES} property 645 * as defined by this proxy. 646 * 647 * @return <b>true</b> if records have been marked as duplicates of this 648 * record. 649 * 650 * @throws WvcmException if this proxy does not define a value for the 651 * {@link #HAS_DUPLICATES HAS_DUPLICATES} property. 652 * 653 * @see #getDuplicates() 654 * @see #getAllDuplicates() 655 * @see #getIsOriginal() 656 */ 657 boolean getHasDuplicates() throws WvcmException; 658 659 /** 660 * True if this record has duplicates but is not itself a duplicate (i.e. 661 * !IS_DUPLICATE & HAS_DUPLICATES) 662 */ 663 PropertyName<Boolean> IS_ORIGINAL = 664 new PropertyName<Boolean>(StpExBase.PROPERTY_NAMESPACE, "is-original"); 665 666 /** 667 * Returns the value of the {@link #IS_ORIGINAL IS_ORIGINAL} property as 668 * defined by this proxy. 669 * 670 * @return <b>true</b> if this record has duplicates but is not, itself, a 671 * duplicate of another record. 672 * 673 * @throws WvcmException if this proxy does not define a value for the 674 * {@link #IS_ORIGINAL IS_ORIGINAL} property. 675 */ 676 boolean getIsOriginal() throws WvcmException; 677 678 /** The immediate duplicates of this record. */ 679 PropertyName<ResourceList<CqRecord>> DUPLICATES = 680 new PropertyName<ResourceList<CqRecord>>(StpExBase.PROPERTY_NAMESPACE, 681 "duplicates"); 682 683 /** 684 * Returns the value of the {@link #DUPLICATES DUPLICATES} property as 685 * defined by this proxy. 686 * 687 * @return A ResourceList of CqRecord proxies representing all of the 688 * records that have been explicitly marked as a duplicate of this 689 * record. 690 * 691 * @throws WvcmException if this proxy does not define a value for the 692 * {@link #DUPLICATES DUPLICATES} property. 693 * 694 * @see #getAllDuplicates() 695 */ 696 ResourceList<CqRecord> getDuplicates() throws WvcmException; 697 698 /** 699 * All of the duplicates of this record, including duplicates of duplicates, 700 * etc. 701 */ 702 PropertyName<ResourceList<CqRecord>> ALL_DUPLICATES = 703 new PropertyName<ResourceList<CqRecord>>(StpExBase.PROPERTY_NAMESPACE, 704 "all-duplicates"); 705 706 /** 707 * Returns the value of the {@link #ALL_DUPLICATES ALL_DUPLICATES} property 708 * as defined by this proxy. 709 * 710 * @return A ResourceList of CqRecord proxies representing all of the 711 * records marked as duplicates of this record or (recursively) one 712 * of its duplicates. 713 * 714 * @throws WvcmException if this proxy does not define a value for the 715 * {@link #ALL_DUPLICATES ALL_DUPLICATES} property. 716 */ 717 ResourceList<CqRecord> getAllDuplicates() throws WvcmException; 718 719 /** 720 * A list of the fields that were modified by the on-going action applied to 721 * this record. 722 */ 723 PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_ACTION = 724 new PropertyName<StpProperty.List<CqFieldValue<?>>>(StpExBase.PROPERTY_NAMESPACE, 725 "fields-updated-this-action"); 726 727 /** 728 * Returns the value of the {@link #FIELDS_UPDATED_THIS_ACTION 729 * FIELDS_UPDATED_THIS_ACTION} property as defined by this proxy. 730 * 731 * @return An StpProperty.List containing a CqFieldValue for each field 732 * updated since the beginning of the current action on this record. 733 * Each CqFieldValue defines the metadata requested when this 734 * property was retrieved from the server. 735 * 736 * @throws WvcmException if this proxy does not define a value for the 737 * {@link #FIELDS_UPDATED_THIS_ACTION 738 * FIELDS_UPDATED_THIS_ACTION} property. 739 */ 740 StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisAction() 741 throws WvcmException; 742 743 /** 744 * A list of the fields that were modified under the current action since 745 * the last time this property was set. 746 * 747 * @see #setFieldsUpdatedThisGroup() 748 */ 749 PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_GROUP = 750 new PropertyName<StpProperty.List<CqFieldValue<?>>>(StpExBase.PROPERTY_NAMESPACE, 751 "fields-updated-this-group"); 752 753 /** 754 * Returns the value of the {@link #FIELDS_UPDATED_THIS_GROUP 755 * FIELDS_UPDATED_THIS_GROUP} property as defined by this proxy. 756 * 757 * @return An StpProperty.List containing a CqFieldValue instance for each 758 * field updated since the last time the 759 * {@link #FIELDS_UPDATED_THIS_GROUP} property was set. 760 * 761 * @throws WvcmException if this proxy does not define a value for the 762 * {@link #FIELDS_UPDATED_THIS_GROUP FIELDS_UPDATED_THIS_GROUP} 763 * property. 764 */ 765 StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisGroup() 766 throws WvcmException; 767 768 /** 769 * Clears the FIELDS_UPDATED_THIS_GROUP property. Only fields updated after 770 * this value is set will be returned by subsequent requests for the 771 * FIELDS_UPDATED_THIS_GROUP property. 772 */ 773 void setFieldsUpdatedThisGroup(); 774 775 /** 776 * The fields that were modified by the last field update. 777 */ 778 PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_SET_VALUE = 779 new PropertyName<StpProperty.List<CqFieldValue<?>>>(StpExBase.PROPERTY_NAMESPACE, 780 "fields-updated-this-set-value"); 781 782 /** 783 * Returns the value of the {@link #FIELDS_UPDATED_THIS_SET_VALUE 784 * FIELDS_UPDATED_THIS_SET_VALUE} property as defined by this proxy. 785 * 786 * @return An StpProperty.List containing a CqFieldValue instance for each 787 * field modified by the most recent client-initiated field update. 788 * 789 * @throws WvcmException if this proxy does not define a value for the 790 * {@link #FIELDS_UPDATED_THIS_SET_VALUE 791 * FIELDS_UPDATED_THIS_SET_VALUE} property. 792 */ 793 StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisSetValue() 794 throws WvcmException; 795 796 /** 797 * A list of the record's invalid fields. 798 */ 799 PropertyName<StpProperty.List<CqFieldValue<?>>> INVALID_FIELDS = 800 new PropertyName<StpProperty.List<CqFieldValue<?>>>(StpExBase.PROPERTY_NAMESPACE, 801 "invalid-fields"); 802 803 /** 804 * Returns the value of the {@link #INVALID_FIELDS INVALID_FIELDS} property 805 * as defined by this proxy. 806 * 807 * @return An StpProperty.list of CqFieldValue instances identifying the 808 * fields of this record that are currently invalid. 809 * 810 * @throws WvcmException if this proxy does not define a value for the 811 * {@link #INVALID_FIELDS INVALID_FIELDS} property. 812 */ 813 StpProperty.List<CqFieldValue<?>> getInvalidFields() throws WvcmException; 814 815 /** 816 * The actions that can be legally applied to this record in its current 817 * state. 818 */ 819 PropertyName<ResourceList<CqAction>> LEGAL_ACTIONS = 820 new PropertyName<ResourceList<CqAction>>(StpExBase.PROPERTY_NAMESPACE, 821 "legal-actions"); 822 823 /** 824 * Returns the value of the {@link #LEGAL_ACTIONS LEGAL_ACTIONS} property as 825 * defined by this proxy. 826 * 827 * @return A list of CqAction proxies representing the actions that are 828 * currently legal for this record. 829 * 830 * @throws WvcmException if this proxy does not define a value for the 831 * {@link #LEGAL_ACTIONS LEGAL_ACTIONS} property. 832 */ 833 ResourceList<CqAction> getLegalActions() throws WvcmException; 834 835 /** The type (state-based or stateless) of the record. */ 836 PropertyName<CqRecord.Class> RECORD_CLASS = 837 new PropertyName<CqRecord.Class>(StpExBase.PROPERTY_NAMESPACE, 838 "record-class"); 839 840 /** 841 * Returns the value of the {@link #RECORD_CLASS RECORD_CLASS} property as 842 * defined by this proxy. 843 * 844 * @return A CqRecord.Class enumeration identifying the class of this record. 845 * 846 * @throws WvcmException if this proxy does not define a value for the 847 * {@link #RECORD_CLASS RECORD_CLASS} property. 848 */ 849 Class getRecordClass() throws WvcmException; 850 851 /** 852 * The CqAttachmentFolder resources that correspond to the fields of this 853 * record that have or may have attachments. The display name of the 854 * attachment folder is the same as the name of the attachment field. 855 */ 856 PropertyName<ResourceList<CqAttachmentFolder>> ATTACHMENT_FOLDERS = 857 new PropertyName<ResourceList<CqAttachmentFolder>>(StpExBase.PROPERTY_NAMESPACE, 858 "attachment-folders"); 859 860 /** 861 * Returns the value of the {@link #ATTACHMENT_FOLDERS ATTACHMENT_FOLDERS} 862 * property as defined by this proxy. 863 * 864 * @return A ResourceList contain CqAttachmentFolder proxies identifying the 865 * attachment folders of this record. 866 * 867 * @throws WvcmException if this proxy does not define a value for the 868 * {@link #ATTACHMENT_FOLDERS ATTACHMENT_FOLDERS} property. 869 */ 870 ResourceList<CqAttachmentFolder> getAttachmentFolders() 871 throws WvcmException; 872 873 /** 874 * An enumeration of the possible types of records; state-based or 875 * stateless. 876 */ 877 public static enum Class implements StpExEnumeration 878 { 879 /** A record type having no state table. */ 880 STATELESS, 881 882 /** 883 * A record type whose records progress from state to state along 884 * prescribed paths based on the actions applied to them. 885 */ 886 STATE_BASED; 887 } 888 889 /** The name of the record's current state. */ 890 PropertyName<String> STATE_NAME = 891 new PropertyName<String>(StpExBase.PROPERTY_NAMESPACE, "state-name"); 892 893 /** 894 * Returns the value of the {@link #STATE_NAME STATE} property as defined by 895 * this proxy. 896 * 897 * @return A String containing the name of the state the record is currently 898 * in. 899 * 900 * @throws WvcmException if this proxy does not define a value for the 901 * {@link #STATE_NAME STATE} property. 902 */ 903 String getStateName() throws WvcmException; 904 905 /** 906 * The replica that has mastership of this record. 907 */ 908 PropertyName<CqReplica> CQ_MASTER_REPLICA = 909 new PropertyName<CqReplica>(StpExBase.PROPERTY_NAMESPACE, 910 "cq-master-replica"); 911 912 /** 913 * Returns the value of the {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA} 914 * property as defined by this proxy. 915 * 916 * @return A CqReplica proxy for the replica that has mastership of this 917 * record 918 * 919 * @throws WvcmException if this proxy does not define a value for the 920 * {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA} property. 921 */ 922 CqReplica getCqMasterReplica() throws WvcmException; 923 924 /** 925 * Defines a new value for the {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA} 926 * property of this proxy. 927 * 928 * @param master A CqReplica proxy identifying the replica that should 929 * assume mastership of this resource. 930 */ 931 void setCqMasterReplica(CqReplica master); 932 933 /** 934 * A list of all the fields that were modified by the on-going action 935 * applied to this record. Unlike the {@link #FIELDS_UPDATED_THIS_ACTION} 936 * property, this list includes fields modified by the hooks that ran during 937 * start up of the action. 938 */ 939 PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_ENTIRE_ACTION = 940 new PropertyName<StpProperty.List<CqFieldValue<?>>>(StpExBase.PROPERTY_NAMESPACE, 941 "fields-updated-this-entire-action"); 942 943 /** 944 * Returns the value of the 945 * {@link #FIELDS_UPDATED_THIS_ENTIRE_ACTION FIELDS_UPDATED_THIS_ENTIRE_ACTION} 946 * property as defined by this proxy. 947 * 948 * @return An StpProperty.List containing a CqFieldValue for each field 949 * modified during the initialization and execution of the current 950 * action. Will never be <b>null</b>, but may be empty. 951 * 952 * @throws WvcmException if this proxy does not define a value for the 953 * {@link #FIELDS_UPDATED_THIS_ENTIRE_ACTION FIELDS_UPDATED_THIS_ENTIRE_ACTION} 954 * property. 955 */ 956 StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisEntireAction() 957 throws WvcmException; 958 959 /** 960 * A list of the fields of this record of 961 * {@link CqFieldValue.ValueType#JOURNAL} 962 */ 963 PropertyName<StpProperty.List<CqHistoryFieldValue>> HISTORY_FIELDS = 964 new PropertyName<StpProperty.List<CqHistoryFieldValue>>(StpExBase.PROPERTY_NAMESPACE, 965 "history-fields"); 966 967 /** 968 * Returns the value of the {@link #HISTORY_FIELDS HISTORY_FIELDS} property 969 * as defined by this proxy. 970 * 971 * @return An StpProperty.List containing a CqFieldValue instance for each 972 * field of the record whose field value type is JOURNAL. Will never 973 * be <b>null</b>, but may be empty. 974 * 975 * @throws WvcmException if this proxy does not define a value for the 976 * {@link #HISTORY_FIELDS HISTORY_FIELDS} property. 977 */ 978 StpProperty.List<CqHistoryFieldValue> getHistoryFields() 979 throws WvcmException; 980 981 /** 982 * A list of the actions that the current user may apply to this record. 983 */ 984 PropertyName<ResourceList<CqAction>> LEGAL_ACCESSIBLE_ACTIONS = 985 new PropertyName<ResourceList<CqAction>>(StpExBase.PROPERTY_NAMESPACE, 986 "legal-accessible-actions"); 987 988 /** 989 * Returns the value of the 990 * {@link #LEGAL_ACCESSIBLE_ACTIONS LEGAL_ACCESSIBLE_ACTIONS} property as 991 * defined by this proxy. 992 * 993 * @return A ResourceList of CqAction proxies enumerating the actions that 994 * the current user may apply to this record in its current state. 995 * Will never be <b>null</b>, but may be empty. 996 * 997 * @throws WvcmException if this proxy does not define a value for the 998 * {@link #LEGAL_ACCESSIBLE_ACTIONS LEGAL_ACCESSIBLE_ACTIONS} 999 * property. 1000 */ 1001 ResourceList<CqAction> getLegalAccessibleActions() throws WvcmException; 1002 1003 /** 1004 * The site-extension field for this record. 1005 */ 1006 PropertyName<String> SITE_EXTENSION = 1007 new PropertyName<String>(StpExBase.PROPERTY_NAMESPACE, "site-extension"); 1008 1009 /** 1010 * Returns the value of the {@link #SITE_EXTENSION SITE_EXTENSION} property 1011 * as defined by this proxy. 1012 * 1013 * @return A String containing the site-extension field used for this record 1014 * when forming its site-extended name. Will never be <b>null</b>. 1015 * 1016 * @throws WvcmException if this proxy does not define a value for the 1017 * {@link #SITE_EXTENSION SITE_EXTENSION} property. 1018 */ 1019 String getSiteExtension() throws WvcmException; 1020 1021 /** 1022 * A list of all the records of this record type whose names differ from the 1023 * name of this record only in their site extensions. 1024 */ 1025 PropertyName<ResourceList<CqRecord>> SITE_EXTENDED_NAMES = 1026 new PropertyName<ResourceList<CqRecord>>(StpExBase.PROPERTY_NAMESPACE, 1027 "site-extended-names"); 1028 1029 /** 1030 * Returns the value of the {@link #SITE_EXTENDED_NAMES SITE_EXTENDED_NAMES} 1031 * property as defined by this proxy. 1032 * 1033 * @return A ResourceList containing a proxy for each CqRecord resource 1034 * whose name differs from the name of this record only in the 1035 * site extensions used. 1036 * 1037 * @throws WvcmException if this proxy does not define a value for the 1038 * {@link #SITE_EXTENDED_NAMES SITE_EXTENDED_NAMES} property. 1039 */ 1040 public ResourceList<CqRecord> getSiteExtendedNames() throws WvcmException; 1041 1042 /** 1043 * The login name of the user currently holding a lock on this record ("*" 1044 * if the current user is not permitted to see user names). A zero-length 1045 * string indicates that the record is not locked. Setting this property to 1046 * the user's login-name or to a zero-length string locks or unlocks the 1047 * record, respectively. 1048 */ 1049 PropertyName<String> LOCK_OWNER = 1050 new PropertyName<String>(PROPERTY_NAMESPACE, "lock-owner"); 1051 1052 /** 1053 * Returns the value of the {@link #LOCK_OWNER LOCK_OWNER} property as 1054 * defined by this proxy. 1055 * 1056 * @return A String containing the login name of the user that has a lock on 1057 * this record ("*" if the current user is not permitted to see 1058 * other's login names). If no user has a lock on this record, a 1059 * zero-length String is returned. 1060 * 1061 * @throws WvcmException if this proxy does not define a value for the 1062 * {@link #LOCK_OWNER LOCK_OWNER} property. 1063 */ 1064 String getLockOwner() throws WvcmException; 1065 1066 /** 1067 * Defines a new value for the {@link #LOCK_OWNER LOCK_OWNER} property of 1068 * this proxy. 1069 * <p> 1070 * Unlike the other writable properties of a record, updating the LOCK_OWNER 1071 * property <i>does not</i> require that an action be started or be in 1072 * progress. And if an action is started or is in progress, the record is 1073 * locked immediately and will remain locked only until the action is 1074 * delivered or reverted. 1075 * 1076 * @param owner Either a zero-length String or a String containing the login 1077 * name of the current user. Setting the value to a zero-length 1078 * String will unlock the record. Setting a non-zero length value 1079 * will lock the record. 1080 * 1081 * @return This proxy. 1082 */ 1083 CqRecord setLockOwner(String owner); 1084 }