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