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