Project: stp

com.ibm.rational.wvcm.stp.cq
Interface CqRecord

All Superinterfaces:
CqContextResource, CqResource, CqUserDbMember, Resource, StpActivity, StpResource

public interface CqRecord
extends StpActivity, CqContextResource

A CqRecord resource proxy provides access to a record in a database, possibly through its change context.

To ensure the integrity of record field data, the modification of a record is a multi-step process.

If these steps succeed, the client can be assured that the data written back to the record is faithfully derived from the data read from the record.

If doWriteProperties is applied to a record that is not yet writable, an action must be started under which the record will be modified. If an action is not specified as the value of the ACTION property of this proxy, the default MODIFY-type action for the record is used.

The fields of a record manifest themselves as properties of the record resource and thus record field values are made available to the client via the normal property request mechanism. The names, types, and other characteristics of the fields of a record are available as properties of the CqFieldDefinition resources enumerated by the CqRecordType resource associated with the record.

In addition to their value, record fields also have meta-properties such as their requiredness, their original value, and a list of their legal values. Each of these can be requested using a MetaPropertyName object in a nested PropertyRequest of the field PropertyName.

The user-friendly specification for the location of a record has the form

  cq.record:<record-type>/<record-id>@<db-set>/<user-db>
 

See Also:
CqRecordType, CqFieldDefinition, CqFieldValue

Nested Class Summary
static class CqRecord.Class
          An enumeration of the possible types of records; state-based or stateless.
static class CqRecord.FieldName<T>
          A subclass of PropertyName used for naming the record resource properties that are schema-defined fields of a ClearQuest record.
 
Nested classes/interfaces inherited from interface com.ibm.rational.wvcm.stp.StpActivity
StpActivity.CqUcmIntegrationState
 
Nested classes/interfaces inherited from interface com.ibm.rational.wvcm.stp.StpResource
StpResource.UnsupportedProperty
 
Nested classes/interfaces inherited from interface javax.wvcm.Resource
Resource.CopyFlag
 
Field Summary
static PropertyNameList.PropertyName<CqAction> ACTION
          The action under which this record is being modified; null if the record is not being modified.
static PropertyNameList.PropertyName<CqAction.Type> ACTION_TYPE
          The type of the action under which this record is being modified, Type.NIL if the record is not being modified
static PropertyNameList.PropertyName<ResourceList<CqRecord>> ALL_DUPLICATES
          All of the duplicates of this record, including duplicates of duplicates, etc.
static PropertyNameList.PropertyName<StpProperty.List<CqFieldValue<?>>> ALL_FIELD_VALUES
          A list of CqFieldValue objects corresponding to all of the fields of this record.
static PropertyNameList.PropertyName<ResourceList<CqAttachmentFolder>> ATTACHMENT_FOLDERS
          The CqAttachmentFolder resources that correspond to the fields of this record that have or may have attachments.
static PropertyNameList.PropertyName<CqReplica> CQ_MASTER_REPLICA
          The replica that has mastership of this record.
static PropertyNameList.PropertyName<CqAction> DEFAULT_ACTION
          The default action associated with the current state of this record.
static PropertyNameList.PropertyName<ResourceList<CqRecord>> DUPLICATES
          The immediate duplicates of this record.
static PropertyNameList.PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_ACTION
          A list of the fields that were modified by the on-going action applied to this record.
static PropertyNameList.PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_ENTIRE_ACTION
          A list of all the fields that were modified by the on-going action applied to this record.
static PropertyNameList.PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_GROUP
          A list of the fields that were modified under the current action since the last time this property was set.
static PropertyNameList.PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_SET_VALUE
          The fields that were modified by the last field update.
static PropertyNameList.PropertyName<Boolean> HAS_DUPLICATES
          Whether other records have been marked as being duplicates of this record
static PropertyNameList.PropertyName<StpProperty.List<CqHistoryFieldValue>> HISTORY_FIELDS
          A list of the fields of this record of CqFieldValue.ValueType.JOURNAL
static PropertyNameList.PropertyName<StpProperty.List<CqFieldValue<?>>> INVALID_FIELDS
          A list of the record's invalid fields.
static PropertyNameList.PropertyName<Boolean> IS_DUPLICATE
          Whether this record has been marked as a duplicate of another record.
static PropertyNameList.PropertyName<Boolean> IS_ORIGINAL
          True if this record has duplicates but is not itself a duplicate (i.e. !
static PropertyNameList.PropertyName<ResourceList<CqAction>> LEGAL_ACCESSIBLE_ACTIONS
          A list of the actions that the current user may apply to this record.
static PropertyNameList.PropertyName<ResourceList<CqAction>> LEGAL_ACTIONS
          The actions that can be legally applied to this record in its current state.
static PropertyNameList.PropertyName<String> LOCK_OWNER
          The login name of the user currently holding a lock on this record ("*" if the current user is not permitted to see user names).
static PropertyNameList.PropertyName<CqRecord> ORIGINAL
          The CqRecord that is marked as the original of this duplicate record.
static PropertyNameList.PropertyName<String> ORIGINAL_ID
          The visible ID of this object's original record.
static PropertyNameList.PropertyName<CqRecord.Class> RECORD_CLASS
          The type (state-based or stateless) of the record.
static PropertyNameList.PropertyName<CqRecordType> RECORD_TYPE
          A CqRecordType proxy for the record-type resource that defines what kind of record this is.
static PropertyNameList.PropertyName<ResourceList<CqRecord>> SITE_EXTENDED_NAMES
          A list of all the records of this record type whose names differ from the name of this record only in their site extensions.
static PropertyNameList.PropertyName<String> SITE_EXTENSION
          The site-extension field for this record.
static PropertyNameList.PropertyName<String> STATE_NAME
          The name of the record's current state.
static PropertyNameList.PropertyName<String> VALIDATION_ERROR
          The error message generated when the record, in its current state, was validated against the repository schema for compliance with its rules.
 
Fields inherited from interface com.ibm.rational.wvcm.stp.StpActivity
BOUND_CC_ACTIVITY, BOUND_CC_ACTIVITY_LOCATION, BOUND_CQ_RECORD, CQ_UCM_INTEGRATION_STATE, HEADLINE, ID_SELECTOR
 
Fields inherited from interface CqContextResource
IS_MODIFIED
 
Fields inherited from interface CqUserDbMember
DB_SET, USER_DB
 
Fields inherited from interface com.ibm.rational.wvcm.stp.StpResource
ALL_PROPERTIES, AUTHENTICATION_REALM, CREATOR_GROUP_NAME, CREATOR_LOGIN_NAME, EFFICIENT_LOCATION, INVALID_PROPERTIES, REPOSITORY, STABLE_LOCATION, USER_FRIENDLY_LOCATION
 
Fields inherited from interface javax.wvcm.Resource
ALL_CUSTOM_PROPERTIES, COMMENT, CONTENT_CHARACTER_SET, CONTENT_IDENTIFIER, CONTENT_LANGUAGE, CONTENT_LENGTH, CONTENT_TYPE, CREATION_DATE, CREATOR_DISPLAY_NAME, DISPLAY_NAME, IS_EXECUTABLE, LAST_MODIFIED, PARENT_LIST, PATHNAME_LOCATION, PROVIDER_LIST, RESOURCE_IDENTIFIER, WORKSPACE_FOLDER_LIST
 
Method Summary
 CqRecord doCreateRecord(Feedback feedback)
          Creates a new record at the location specified by this proxy, initialized with the dirty properties of this proxy.
 CqRecord doCreateRecord(Feedback feedback, List<CqContextResource> deliveryOrder)
          Creates a new record at the location specified by this proxy, initialized with the dirty properties of this proxy.
 CqRecord doFireNamedHook(CqHook hook, String parameters, Feedback feedback, List<CqContextResource> deliveryOrder)
          Executes a hook (record script) named in the NAMED_HOOK_LIST property of this record's RECORD_TYPE resource.
 String doFireRecordScriptAlias(CqAction action, Feedback feedback, List<CqContextResource> deliveryOrder)
          Causes the execution of an action of type CqAction.Type.RECORD_SCRIPT_ALIAS.
 CqAction getAction()
          Returns the value of the ACTION property as defined by this proxy.
 CqAction.Type getActionType()
          Returns the value of the ACTION property as defined by this proxy.
 ResourceList<CqRecord> getAllDuplicates()
          Returns the value of the ALL_DUPLICATES property as defined by this proxy.
 StpProperty.List<CqFieldValue<?>> getAllFieldValues()
          Returns the value of the ALL_FIELD_VALUES property as defined by this proxy.
 ResourceList<CqAttachmentFolder> getAttachmentFolders()
          Returns the value of the ATTACHMENT_FOLDERS property as defined by this proxy.
 CqReplica getCqMasterReplica()
          Returns the value of the CQ_MASTER_REPLICA property as defined by this proxy.
 Date getCreationDate()
          Returns the date of the submit action in the record history field.
 String getCreatorLoginName()
          Returns the login name of the user who submitted the record
 CqAction getDefaultAction()
          Returns the value of the DEFAULT_ACTION property as defined by this proxy.
 ResourceList<CqRecord> getDuplicates()
          Returns the value of the DUPLICATES property as defined by this proxy.
 Object getField(String fieldName)
          Retrieves the value of a field previously requested by an instance of FieldName having the same fieldName parameter as this method.
<T> CqFieldValue<T>
getFieldInfo(CqRecord.FieldName<T> fieldName)
          Returns the meta-property bundle of a record field defined by this proxy.
 StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisAction()
          Returns the value of the FIELDS_UPDATED_THIS_ACTION property as defined by this proxy.
 StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisEntireAction()
          Returns the value of the FIELDS_UPDATED_THIS_ENTIRE_ACTION property as defined by this proxy.
 StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisGroup()
          Returns the value of the FIELDS_UPDATED_THIS_GROUP property as defined by this proxy.
 StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisSetValue()
          Returns the value of the FIELDS_UPDATED_THIS_SET_VALUE property as defined by this proxy.
 boolean getHasDuplicates()
          Returns the value of the HAS_DUPLICATES property as defined by this proxy.
 StpProperty.List<CqHistoryFieldValue> getHistoryFields()
          Returns the value of the HISTORY_FIELDS property as defined by this proxy.
 StpProperty.List<CqFieldValue<?>> getInvalidFields()
          Returns the value of the INVALID_FIELDS property as defined by this proxy.
 boolean getIsDuplicate()
          Returns the value of the IS_DUPLICATE property as defined by this proxy.
 boolean getIsOriginal()
          Returns the value of the IS_ORIGINAL property as defined by this proxy.
 Date getLastModified()
          Returns the date of the last action applied to the record from its history
 ResourceList<CqAction> getLegalAccessibleActions()
          Returns the value of the LEGAL_ACCESSIBLE_ACTIONS property as defined by this proxy.
 ResourceList<CqAction> getLegalActions()
          Returns the value of the LEGAL_ACTIONS property as defined by this proxy.
 String getLockOwner()
          Returns the value of the LOCK_OWNER property as defined by this proxy.
 CqRecord getOriginal()
          Returns the value of the ORIGINAL property as defined by this proxy.
 String getOriginalId()
          Returns the value of the ORIGINAL_ID property as defined by this proxy.
<T> T
getProperty(PropertyNameList.PropertyName<T> name)
          Returns the value defined by this proxy for the property specified by the given PropertyName.
 CqRecord.Class getRecordClass()
          Returns the value of the RECORD_CLASS property as defined by this proxy.
 CqRecordType getRecordType()
          A CqRecordType proxy for the record-type resource that defines what kind of record this is.
 ResourceList<CqRecord> getSiteExtendedNames()
          Returns the value of the SITE_EXTENDED_NAMES property as defined by this proxy.
 String getSiteExtension()
          Returns the value of the SITE_EXTENSION property as defined by this proxy.
 String getStateName()
          Returns the value of the STATE property as defined by this proxy.
 String getValidationError()
          Returns the value of the VALIDATION_ERROR property as defined by this proxy.
 CqRecord setAction(CqAction action)
          Defines a new value for the ACTION property of this proxy.
 void setCqMasterReplica(CqReplica master)
          Defines a new value for the CQ_MASTER_REPLICA property of this proxy.
 void setField(String fieldName, Object value)
          Defines in this proxy, a new value for a field of this record.
<T> void
setFieldInfo(CqRecord.FieldName<T> fieldName, CqFieldValue<T> value)
          Defines a new meta-property bundle for a record field in this proxy.
 void setFieldsUpdatedThisGroup()
          Clears the FIELDS_UPDATED_THIS_GROUP property.
 CqRecord setLockOwner(String owner)
          Defines a new value for the LOCK_OWNER property of this proxy.
<T> void
setProperty(PropertyNameList.PropertyName<T> name, T value)
          Defines the value of the specified property for this proxy.
 
Methods inherited from interface com.ibm.rational.wvcm.stp.StpActivity
getBoundCcActivity, getBoundCcActivityLocation, getBoundCqRecord, getCqUcmIntegrationState, getHeadline, getIdSelector, setHeadline
 
Methods inherited from interface CqContextResource
doDeliver, doRevert, doUnbindAll, doUnbindAll, doWriteProperties, doWriteProperties, getIsModified
 
Methods inherited from interface CqUserDbMember
getDbSet, getUserDb
 
Methods inherited from interface CqResource
cqProvider, getComment, getContentCharacterSet, getContentIdentifier, getContentLanguage, getContentLength, getContentType, getCreatorDisplayName, getIsExecutable, getProviderList, getWorkspaceFolderList, setComment, setContentCharacterSet, setContentLanguage, setContentType, setCreatorDisplayName, setIsExecutable
 
Methods inherited from interface com.ibm.rational.wvcm.stp.StpResource
doReadProperties, equals, getAllProperties, getAuthenticationRealm, getCustomProperties, getEfficientLocation, getInvalidProperties, getMetaProperties, getPropertyException, getRepository, getResourceError, getStableLocation, getUserFriendlyLocation, hashCode, hasProperties, initMetaProperty, proxyType, setPropertyClean, stpLocation, stpProvider
 
Methods inherited from interface javax.wvcm.Resource
doCopy, doFind, doFindAll, doGetPropertyNameList, doGetPropertyNameList, doReadContent, doReadProperties, doWriteContent, forgetProperty, getDisplayName, getParentList, getPathnameLocation, initProperty, location, lookupProperty, modifyLocation, propertyNameList, provider, removeProperty, setDisplayName, setProperty, updatedPropertyNameList
 

Field Detail

ACTION

static final PropertyNameList.PropertyName<CqAction> ACTION
The action under which this record is being modified; null if the record is not being modified.


ACTION_TYPE

static final PropertyNameList.PropertyName<CqAction.Type> ACTION_TYPE
The type of the action under which this record is being modified, Type.NIL if the record is not being modified


ALL_DUPLICATES

static final PropertyNameList.PropertyName<ResourceList<CqRecord>> ALL_DUPLICATES
All of the duplicates of this record, including duplicates of duplicates, etc.


ALL_FIELD_VALUES

static final PropertyNameList.PropertyName<StpProperty.List<CqFieldValue<?>>> ALL_FIELD_VALUES
A list of CqFieldValue objects corresponding to all of the fields of this record. By default, no meta-property of any field is included in the CqFieldValue's on this list. So, essentially, the result is just a list of field property names. Using a NestedPropertyName in the PropertyRequest of this property would allow the client to request any or all meta-properties of the fields in the list. new PropertyRequest(ALL_FIELD_VALUES.nest(VALUE.nest(VALUE))), for example, would request the value of each field of the record.


ATTACHMENT_FOLDERS

static final PropertyNameList.PropertyName<ResourceList<CqAttachmentFolder>> ATTACHMENT_FOLDERS
The CqAttachmentFolder resources that correspond to the fields of this record that have or may have attachments. The display name of the attachment folder is the same as the name of the attachment field.


CQ_MASTER_REPLICA

static final PropertyNameList.PropertyName<CqReplica> CQ_MASTER_REPLICA
The replica that has mastership of this record.


DEFAULT_ACTION

static final PropertyNameList.PropertyName<CqAction> DEFAULT_ACTION
The default action associated with the current state of this record.


DUPLICATES

static final PropertyNameList.PropertyName<ResourceList<CqRecord>> DUPLICATES
The immediate duplicates of this record.


FIELDS_UPDATED_THIS_ACTION

static final PropertyNameList.PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_ACTION
A list of the fields that were modified by the on-going action applied to this record.


FIELDS_UPDATED_THIS_ENTIRE_ACTION

static final PropertyNameList.PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_ENTIRE_ACTION
A list of all the fields that were modified by the on-going action applied to this record. Unlike the FIELDS_UPDATED_THIS_ACTION property, this list includes fields modified by the hooks that ran during start up of the action.


FIELDS_UPDATED_THIS_GROUP

static final PropertyNameList.PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_GROUP
A list of the fields that were modified under the current action since the last time this property was set.

See Also:
setFieldsUpdatedThisGroup()

FIELDS_UPDATED_THIS_SET_VALUE

static final PropertyNameList.PropertyName<StpProperty.List<CqFieldValue<?>>> FIELDS_UPDATED_THIS_SET_VALUE
The fields that were modified by the last field update.


HAS_DUPLICATES

static final PropertyNameList.PropertyName<Boolean> HAS_DUPLICATES
Whether other records have been marked as being duplicates of this record


HISTORY_FIELDS

static final PropertyNameList.PropertyName<StpProperty.List<CqHistoryFieldValue>> HISTORY_FIELDS
A list of the fields of this record of CqFieldValue.ValueType.JOURNAL


INVALID_FIELDS

static final PropertyNameList.PropertyName<StpProperty.List<CqFieldValue<?>>> INVALID_FIELDS
A list of the record's invalid fields.


IS_DUPLICATE

static final PropertyNameList.PropertyName<Boolean> IS_DUPLICATE
Whether this record has been marked as a duplicate of another record.


IS_ORIGINAL

static final PropertyNameList.PropertyName<Boolean> IS_ORIGINAL
True if this record has duplicates but is not itself a duplicate (i.e. !IS_DUPLICATE & HAS_DUPLICATES)


LEGAL_ACCESSIBLE_ACTIONS

static final PropertyNameList.PropertyName<ResourceList<CqAction>> LEGAL_ACCESSIBLE_ACTIONS
A list of the actions that the current user may apply to this record.


LEGAL_ACTIONS

static final PropertyNameList.PropertyName<ResourceList<CqAction>> LEGAL_ACTIONS
The actions that can be legally applied to this record in its current state.


LOCK_OWNER

static final PropertyNameList.PropertyName<String> LOCK_OWNER
The login name of the user currently holding a lock on this record ("*" if the current user is not permitted to see user names). A zero-length string indicates that the record is not locked. Setting this property to the user's login-name or to a zero-length string locks or unlocks the record, respectively.


ORIGINAL

static final PropertyNameList.PropertyName<CqRecord> ORIGINAL
The CqRecord that is marked as the original of this duplicate record.


ORIGINAL_ID

static final PropertyNameList.PropertyName<String> ORIGINAL_ID
The visible ID of this object's original record.


RECORD_CLASS

static final PropertyNameList.PropertyName<CqRecord.Class> RECORD_CLASS
The type (state-based or stateless) of the record.


RECORD_TYPE

static final PropertyNameList.PropertyName<CqRecordType> RECORD_TYPE
A CqRecordType proxy for the record-type resource that defines what kind of record this is.


SITE_EXTENDED_NAMES

static final PropertyNameList.PropertyName<ResourceList<CqRecord>> SITE_EXTENDED_NAMES
A list of all the records of this record type whose names differ from the name of this record only in their site extensions.


SITE_EXTENSION

static final PropertyNameList.PropertyName<String> SITE_EXTENSION
The site-extension field for this record.


STATE_NAME

static final PropertyNameList.PropertyName<String> STATE_NAME
The name of the record's current state.


VALIDATION_ERROR

static final PropertyNameList.PropertyName<String> VALIDATION_ERROR
The error message generated when the record, in its current state, was validated against the repository schema for compliance with its rules. This property will be empty if the record is fully compliant (which is always the case if the record is not open for edit).

When this property is requested for a record open for editing, the record is validated before any other properties are retrieved. Thus, all properties returned with this property reflect the state of the record after validation was attempted.

Before a record being edited can be delivered, it must be validated (even if no fields have been changed). Normally, validation is performed as the first phase of a delivery and any validation errors cause the delivery to be aborted. Requesting this property will force validation of the record without attempting to deliver it. The time and resources needed to perform a record validation vary with the schema. Unless you have specific knowledge of the target database's schema, it is best to assume that the validation process is an expensive operation and design your application to request this property only when validation is really required.

If you are changing the contents of a record programmatically, you should make sure that your code provides valid data.

You should not attempt to parse and interpret the returned String programmatically, because the error text may change in future releases. If you want to try to correct the value in an field with incorrect values, you can use the INVALID_FIELDS property to discover which fields are invalid. The MESSAGE_TEXT meta-property of those fields will identify problems specific to the field.

Method Detail

doCreateRecord

CqRecord doCreateRecord(Feedback feedback)
                        throws WvcmException
Creates a new record at the location specified by this proxy, initialized with the dirty properties of this proxy. The type of record created is determined by the parent location of this proxy (which must name an existing record type resource).

An action must be started under which the record will be created. If an action is not specified as the value of the ACTION property of this proxy, the default SUBMIT-type action for the record is used.

The server is permitted to modify the location as it deems fit. The proxy returned by this method is a proxy that addresses the location actually chosen by the server.

Parameters:
feedback - A Feedback object requesting the properties desired from the record created by this operation. May be null if no properties are desired.
Returns:
An CqRecord proxy for the created record. This proxy will define the properties specified in the feedback argument.
Throws:
WvcmException - If the record cannot be created with the given properties.

doCreateRecord

CqRecord doCreateRecord(Feedback feedback,
                        List<CqContextResource> deliveryOrder)
                        throws WvcmException
Creates a new record at the location specified by this proxy, initialized with the dirty properties of this proxy. The type of record created is determined by the parent location of this proxy (which must name an existing record type resource).

An action must be started under which the record will be created. If an action is not specified as the value of the ACTION property of this proxy, the default SUBMIT-type action for the record is used.

The server is permitted to modify the location as it deems fit. The proxy returned by this method is a proxy that addresses the location actually chosen by the server.

Parameters:
feedback - A Feedback object requesting the properties desired from the record created by this operation. May be null if no properties are desired.
deliveryOrder - If CqProvider.HOLD the created record is left in a writable state in the change context--the new record in the change context must be delivered before the it becomes visible to other providers. If not CqProvider.HOLD, the modified and moribund resources specified by this parameter will be delivered to or deleted from the database in the order indicated. To deliver all modified and moribund resources in an arbitrary order, use CqProvider.DELIVER_ALL. To deliver just this new record, use CqProvider.DELIVER. Must not be null.
Returns:
A CqRecord proxy for the created record. This proxy will define the properties specified in the feedback argument.
Throws:
WvcmException - If the record cannot be created with the given properties.

doFireNamedHook

CqRecord doFireNamedHook(CqHook hook,
                         String parameters,
                         Feedback feedback,
                         List<CqContextResource> deliveryOrder)
                         throws WvcmException,
                                StpErrorMessageException
Executes a hook (record script) named in the NAMED_HOOK_LIST property of this record's RECORD_TYPE resource. Additionally a global hook can be executed if the global hook's name is known in advance. The impact on the change context in which the hook is executed is essentially the same as executing CqContextResource.doWriteProperties(Feedback, List) in that context (where the hook is in control of which properties are written).

As with doWriteProperties, the record need not be editable prior to invoking this method, but, unlike doWriteProperties, if it isn't editable and the hook wants to modify it, then the hook must be prepared to start an action itself to do so. An implicit Modify-type action is not automatically started for the hook (except in the case noted below).

If this proxy contains updated property values when this method is invoked, an attempt will be made to write those new property values to the server before the hook is executed. If such an update is required and this record isn't editable, it will be made editable using the default Modify-type action and the hook will be applied to that editable version of the record before delivering the changes to the database. If the property update fails, this operation fails immediately and subsequent execution of the hook will not be attempted.

Parameters:
hook - A CqHook proxy for the named hook to be fired. If the client knows the name of the hook to be fired, it should construct a CqHook proxy at the computed location record.stpLocation().recomposeWithNamespace(Namespace.HOOK).parent().child(hook-name) If the client does not know the name of the hook to be fired, a list of available hooks to choose from can be obtained from the NAMED_HOOK_LIST property of the parent record type of this record. Additionally, the client can specify a global hook. If using a global hook, the client must know the name in advance and should construct a CqHook proxy at the computed location record.stpLocation().recomposeWithMods(Namespace.HOOK,hook-name,null,null)
parameters - A String containing any parameters required by the hook. The format and content of this parameter string is prescribed solely by the hook, which is also responsible for parsing it into a usable value or values.
feedback - Properties to be retrieved from the target record and/or those records changed by the execution of the hook (and after delivery if delivery has been requested).
deliveryOrder - Delivery of the changes made to the record will be considered only if the hook succeeds. If this argument is CqProvider.HOLD the modified record is left in a writable state in the change context--the modified record must be delivered before the changes made by the hook become visible outside the change context. If not CqProvider.HOLD, the modified and moribund resources specified by this parameter will be delivered to or deleted from the database in the order indicated. To deliver all modified and moribund resources in an arbitrary order, use CqProvider.DELIVER_ALL. To deliver just this modified record, use CqProvider.DELIVER. Must not be null.
Returns:
A CqRecord proxy for the modified record, populated with the resources requested by the feedback argument.
Throws:
WvcmException - if there are problems finding or executing the named hook, writing updated properties, or starting the implied action.
StpErrorMessageException - if the hook returns a non-empty result

doFireRecordScriptAlias

String doFireRecordScriptAlias(CqAction action,
                               Feedback feedback,
                               List<CqContextResource> deliveryOrder)
                               throws WvcmException
Causes the execution of an action of type CqAction.Type.RECORD_SCRIPT_ALIAS. Such actions are defined solely by a hook script, which is executed when the action is applied to a record. When this method is called, the action is started on this record and the action's hook script is executed as the sole content of that action and then the action is committed. The impact of this operation on the change context is essentially equivalent to executing in the same context CqContextResource.doWriteProperties(Feedback, List) where the deliveryOrder argument forces an immediate delivery of the change context.

Because of this prescribed processing

Typically, schema designers have associated arbitrary executable code with a record type, represented in a GUI as a button with the display name of the record type action.

Parameters:
action - A CqAction for an action of type RECORD_SCRIPT_ALIAS. This action must be defined by the record type of this record instance.
feedback - A Feedback object requesting the properties desired from resources involved in this operation. May be null if no properties are desired.
deliveryOrder - Upon successful execution of the action script, the target record will be delivered to its database. Then, any other resources specified by this argument will be delivered. Must not be null and must not be CqProvider.HOLD.
Returns:
A String containing the return value computed by the hook script.
Throws:
WvcmException - if there are problems
  • finding the record,
  • finding a RECORD_SCRIPT_ALIAS as specified
  • starting the action
  • executing the script
  • delivering the changes to the database

getAction

CqAction getAction()
                   throws WvcmException
Returns the value of the ACTION property as defined by this proxy.

Returns:
Returns an Action proxy representing the action associated with this record.
Throws:
WvcmException - if this proxy does not define a value for the ACTION property.

getActionType

CqAction.Type getActionType()
                            throws WvcmException
Returns the value of the ACTION property as defined by this proxy.

Returns:
An Action.Type enumerator indicating the type of action associated with this record.
Throws:
WvcmException - if this proxy does not define a value for the ACTION_TYPE property.

getAllDuplicates

ResourceList<CqRecord> getAllDuplicates()
                                        throws WvcmException
Returns the value of the ALL_DUPLICATES property as defined by this proxy.

Returns:
A ResourceList of CqRecord proxies representing all of the records marked as duplicates of this record or (recursively) one of its duplicates.
Throws:
WvcmException - if this proxy does not define a value for the ALL_DUPLICATES property.

getAllFieldValues

StpProperty.List<CqFieldValue<?>> getAllFieldValues()
                                                    throws WvcmException
Returns the value of the ALL_FIELD_VALUES property as defined by this proxy.

Returns:
An StpProperty.List containing a CqFieldValue instance for each field of this record. Each CqFieldValue instance defines all of the metadata requested from the server for the field.
Throws:
WvcmException - if this proxy does not define a value for the ALL_FIELD_VALUES property.

getAttachmentFolders

ResourceList<CqAttachmentFolder> getAttachmentFolders()
                                                      throws WvcmException
Returns the value of the ATTACHMENT_FOLDERS property as defined by this proxy.

Returns:
A ResourceList contain CqAttachmentFolder proxies identifying the attachment folders of this record.
Throws:
WvcmException - if this proxy does not define a value for the ATTACHMENT_FOLDERS property.

getCqMasterReplica

CqReplica getCqMasterReplica()
                             throws WvcmException
Returns the value of the CQ_MASTER_REPLICA property as defined by this proxy.

Returns:
A CqReplica proxy for the replica that has mastership of this record
Throws:
WvcmException - if this proxy does not define a value for the CQ_MASTER_REPLICA property.

getCreationDate

Date getCreationDate()
                     throws WvcmException
Returns the date of the submit action in the record history field.

Specified by:
getCreationDate in interface CqResource
Specified by:
getCreationDate in interface Resource
Returns:
the Resource.CREATION_DATE property.
Throws:
WvcmException - if this Resource was not created with Resource.CREATION_DATE as a wanted property
See Also:
Resource.getCreationDate()

getCreatorLoginName

String getCreatorLoginName()
                           throws WvcmException
Returns the login name of the user who submitted the record

Specified by:
getCreatorLoginName in interface CqResource
Specified by:
getCreatorLoginName in interface StpResource
Throws:
WvcmException - Thrown if the property was never requested, or otherwise unavailable (e.g. requested in a client-context only).
See Also:
StpResource.getCreatorLoginName()

getDefaultAction

CqAction getDefaultAction()
                          throws WvcmException
Returns the value of the DEFAULT_ACTION property as defined by this proxy.

Returns:
A CqAction proxy representing the default action associated with this record in its current state. Will be null if a default action is not defined for this record.
Throws:
WvcmException - if this proxy does not define a value for the DEFAULT_ACTION property.

getDuplicates

ResourceList<CqRecord> getDuplicates()
                                     throws WvcmException
Returns the value of the DUPLICATES property as defined by this proxy.

Returns:
A ResourceList of CqRecord proxies representing all of the records that have been explicitly marked as a duplicate of this record.
Throws:
WvcmException - if this proxy does not define a value for the DUPLICATES property.
See Also:
getAllDuplicates()

getField

Object getField(String fieldName)
                throws WvcmException
Retrieves the value of a field previously requested by an instance of FieldName having the same fieldName parameter as this method. To retrieve other meta-properties requested for the field, use getFieldInfo(com.ibm.rational.wvcm.stp.cq.CqRecord.FieldName).

Parameters:
fieldName - The name of the field for which a value was requested.
Returns:
The value of the requested field returned by the server expressed as a native Java object (not just its String image).
Throws:
WvcmException - If the field value was not requested or could not be retrieved.

getFieldInfo

<T> CqFieldValue<T> getFieldInfo(CqRecord.FieldName<T> fieldName)
                             throws WvcmException
Returns the meta-property bundle of a record field defined by this proxy. Since CqFieldValue is an extension of StpProperty, this method is merely a type-specialized version of StpResource.getMetaProperties(javax.wvcm.PropertyNameList.PropertyName).

Parameters:
fieldName - The name of the desired field expressed as a FieldName object. Cannot be null.
Returns:
A CqFieldValue structure is returned containing the field value(s) and/or attributes defined by this proxy.
Throws:
WvcmException - If the field value denoted by the given field name is not defined by this proxy--that is, if no field values or attributes were requested or could not be retrieved when requested.

getFieldsUpdatedThisAction

StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisAction()
                                                             throws WvcmException
Returns the value of the FIELDS_UPDATED_THIS_ACTION property as defined by this proxy.

Returns:
An StpProperty.List containing a CqFieldValue for each field updated since the beginning of the current action on this record. Each CqFieldValue defines the metadata requested when this property was retrieved from the server.
Throws:
WvcmException - if this proxy does not define a value for the FIELDS_UPDATED_THIS_ACTION property.

getFieldsUpdatedThisEntireAction

StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisEntireAction()
                                                                   throws WvcmException
Returns the value of the FIELDS_UPDATED_THIS_ENTIRE_ACTION property as defined by this proxy.

Returns:
An StpProperty.List containing a CqFieldValue for each field modified during the initialization and execution of the current action. Will never be null, but may be empty.
Throws:
WvcmException - if this proxy does not define a value for the FIELDS_UPDATED_THIS_ENTIRE_ACTION property.

getFieldsUpdatedThisGroup

StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisGroup()
                                                            throws WvcmException
Returns the value of the FIELDS_UPDATED_THIS_GROUP property as defined by this proxy.

Returns:
An StpProperty.List containing a CqFieldValue instance for each field updated since the last time the FIELDS_UPDATED_THIS_GROUP property was set.
Throws:
WvcmException - if this proxy does not define a value for the FIELDS_UPDATED_THIS_GROUP property.

getFieldsUpdatedThisSetValue

StpProperty.List<CqFieldValue<?>> getFieldsUpdatedThisSetValue()
                                                               throws WvcmException
Returns the value of the FIELDS_UPDATED_THIS_SET_VALUE property as defined by this proxy.

Returns:
An StpProperty.List containing a CqFieldValue instance for each field modified by the most recent client-initiated field update.
Throws:
WvcmException - if this proxy does not define a value for the FIELDS_UPDATED_THIS_SET_VALUE property.

getHasDuplicates

boolean getHasDuplicates()
                         throws WvcmException
Returns the value of the HAS_DUPLICATES property as defined by this proxy.

Returns:
true if records have been marked as duplicates of this record.
Throws:
WvcmException - if this proxy does not define a value for the HAS_DUPLICATES property.
See Also:
getDuplicates(), getAllDuplicates(), getIsOriginal()

getHistoryFields

StpProperty.List<CqHistoryFieldValue> getHistoryFields()
                                                       throws WvcmException
Returns the value of the HISTORY_FIELDS property as defined by this proxy.

Returns:
An StpProperty.List containing a CqFieldValue instance for each field of the record whose field value type is JOURNAL. Will never be null, but may be empty.
Throws:
WvcmException - if this proxy does not define a value for the HISTORY_FIELDS property.

getInvalidFields

StpProperty.List<CqFieldValue<?>> getInvalidFields()
                                                   throws WvcmException
Returns the value of the INVALID_FIELDS property as defined by this proxy.

Returns:
An StpProperty.list of CqFieldValue instances identifying the fields of this record that are currently invalid.
Throws:
WvcmException - if this proxy does not define a value for the INVALID_FIELDS property.

getIsDuplicate

boolean getIsDuplicate()
                       throws WvcmException
Returns the value of the IS_DUPLICATE property as defined by this proxy.

Returns:
true if this record has been recorded as a duplicate of another record.
Throws:
WvcmException - if this proxy does not define a value for the IS_DUPLICATE property.
See Also:
getAllDuplicates(), getDuplicates(), getHasDuplicates()

getIsOriginal

boolean getIsOriginal()
                      throws WvcmException
Returns the value of the IS_ORIGINAL property as defined by this proxy.

Returns:
true if this record has duplicates but is not, itself, a duplicate of another record.
Throws:
WvcmException - if this proxy does not define a value for the IS_ORIGINAL property.

getLastModified

Date getLastModified()
                     throws WvcmException
Returns the date of the last action applied to the record from its history

Specified by:
getLastModified in interface CqResource
Specified by:
getLastModified in interface Resource
Returns:
the Resource.LAST_MODIFIED property.
Throws:
WvcmException - if this Resource was not created with Resource.LAST_MODIFIED as a wanted property.
See Also:
Resource.getLastModified()

getLegalAccessibleActions

ResourceList<CqAction> getLegalAccessibleActions()
                                                 throws WvcmException
Returns the value of the LEGAL_ACCESSIBLE_ACTIONS property as defined by this proxy.

Returns:
A ResourceList of CqAction proxies enumerating the actions that the current user may apply to this record in its current state. Will never be null, but may be empty.
Throws:
WvcmException - if this proxy does not define a value for the LEGAL_ACCESSIBLE_ACTIONS property.

getLegalActions

ResourceList<CqAction> getLegalActions()
                                       throws WvcmException
Returns the value of the LEGAL_ACTIONS property as defined by this proxy.

Returns:
A list of CqAction proxies representing the actions that are currently legal for this record.
Throws:
WvcmException - if this proxy does not define a value for the LEGAL_ACTIONS property.

getLockOwner

String getLockOwner()
                    throws WvcmException
Returns the value of the LOCK_OWNER property as defined by this proxy.

Returns:
A String containing the login name of the user that has a lock on this record ("*" if the current user is not permitted to see other's login names). If no user has a lock on this record, a zero-length String is returned.
Throws:
WvcmException - if this proxy does not define a value for the LOCK_OWNER property.

getOriginal

CqRecord getOriginal()
                     throws WvcmException
Returns the value of the ORIGINAL property as defined by this proxy.

Returns:
A CqRecord proxy representing the record of which this is a duplicate. Will be null if this record is not a duplicate.
Throws:
WvcmException - if this proxy does not define a value for the ORIGINAL property.

getOriginalId

String getOriginalId()
                     throws WvcmException
Returns the value of the ORIGINAL_ID property as defined by this proxy.

Returns:
A String containing the record id for the record that this record is a duplicate of. Will be null if this record is not a duplicate.
Throws:
WvcmException - if this proxy does not define a value for the ORIGINAL_ID property.

getProperty

<T> T getProperty(PropertyNameList.PropertyName<T> name)
              throws WvcmException
Returns the value defined by this proxy for the property specified by the given PropertyName. The PropertyName may specify a record field, in which case the Object returned is not a CqFieldValue structure, but the actual value of the field. (Clients may use getField or StpResource.getMetaProperties(javax.wvcm.PropertyNameList.PropertyName) to obtain a CqFieldValue structure if the additional information provided by the CqFieldValue structure is needed.).

Specified by:
getProperty in interface Resource
Parameters:
name - the name of the property.
Returns:
the value of the specified property of this Resource.
Throws:
WvcmException - if this property was not set and this Resource was not created with the specified property as a wanted property.
See Also:
Resource.getProperty(javax.wvcm.PropertyNameList.PropertyName)

getRecordClass

CqRecord.Class getRecordClass()
                              throws WvcmException
Returns the value of the RECORD_CLASS property as defined by this proxy.

Returns:
A CqRecord.Class enumeration identifying the class of this record.
Throws:
WvcmException - if this proxy does not define a value for the RECORD_CLASS property.

getRecordType

CqRecordType getRecordType()
                           throws WvcmException
A CqRecordType proxy for the record-type resource that defines what kind of record this is.

Returns:
A proxy for the record-type of this record is returned.
Throws:
WvcmException - if this proxy does not define a value for the RECORD_TYPE property.

getSiteExtendedNames

ResourceList<CqRecord> getSiteExtendedNames()
                                            throws WvcmException
Returns the value of the SITE_EXTENDED_NAMES property as defined by this proxy.

Returns:
A ResourceList containing a proxy for each CqRecord resource whose name differs from the name of this record only in the site extensions used.
Throws:
WvcmException - if this proxy does not define a value for the SITE_EXTENDED_NAMES property.

getSiteExtension

String getSiteExtension()
                        throws WvcmException
Returns the value of the SITE_EXTENSION property as defined by this proxy.

Returns:
A String containing the site-extension field used for this record when forming its site-extended name. Will never be null.
Throws:
WvcmException - if this proxy does not define a value for the SITE_EXTENSION property.

getStateName

String getStateName()
                    throws WvcmException
Returns the value of the STATE property as defined by this proxy.

Returns:
A String containing the name of the state the record is currently in.
Throws:
WvcmException - if this proxy does not define a value for the STATE property.

getValidationError

String getValidationError()
                          throws WvcmException
Returns the value of the VALIDATION_ERROR property as defined by this proxy.

Returns:
Returns a String containing the error message generated when this record was validated against the repository schema. Will never be null, but may be empty is the record field values are fully compliant with the rules of the schema.
Throws:
WvcmException - if this proxy does not define a value for the VALIDATION_ERROR property.

setAction

CqRecord setAction(CqAction action)
Defines a new value for the ACTION property of this proxy. Set this value prior to invoking doWriteProperties, doCreateRecord, or doUnbindAll to specify an action other than the default action specified for those operations. If this property is not set prior to invocation of these methods, an action of the required type will be used if one is unique defined.

Parameters:
action - A CqAction proxy identifying the action under which this record is to be created, modified, or deleted. Must not be null. For the update to succeed, the given action must be on the LEGAL_ACTIONs list for this record.

setCqMasterReplica

void setCqMasterReplica(CqReplica master)
Defines a new value for the CQ_MASTER_REPLICA property of this proxy.

Parameters:
master - A CqReplica proxy identifying the replica that should assume mastership of this resource.

setField

void setField(String fieldName,
              Object value)
Defines in this proxy, a new value for a field of this record. The field will not be updated until this proxy is used to invoke a "do" method.

Parameters:
fieldName - The name of the field whose value is to be set
value - The new value for the field expressed as a native Java object. The String image of the value may be used.

setFieldInfo

<T> void setFieldInfo(CqRecord.FieldName<T> fieldName,
                      CqFieldValue<T> value)
Defines a new meta-property bundle for a record field in this proxy. Only the VALUE meta-property of the CqFieldValue is written to the resource, but the TYPE meta-property is often useful to the library for interpreting the VALUE when expressed as a String image.

Parameters:
fieldName - The name of the field to be updated expressed as a FieldName object. Cannot be null.
value - A CqFieldValue object containing the new field value. Must not be null

setFieldsUpdatedThisGroup

void setFieldsUpdatedThisGroup()
Clears the FIELDS_UPDATED_THIS_GROUP property. Only fields updated after this value is set will be returned by subsequent requests for the FIELDS_UPDATED_THIS_GROUP property.


setLockOwner

CqRecord setLockOwner(String owner)
Defines a new value for the LOCK_OWNER property of this proxy.

Unlike the other writable properties of a record, updating the LOCK_OWNER property does not require that an action be started or be in progress. And if an action is started or is in progress, the record is locked immediately and will remain locked only until the action is delivered or reverted.

Parameters:
owner - Either a zero-length String or a String containing the login name of the current user. Setting the value to a zero-length String will unlock the record. Setting a non-zero length value will lock the record.
Returns:
This proxy.

setProperty

<T> void setProperty(PropertyNameList.PropertyName<T> name,
                     T value)
Defines the value of the specified property for this proxy. The PropertyName may specify a record field name, in which case the Object may be a CqFieldValue structure or the actual value of the field.

Specified by:
setProperty in interface Resource
Parameters:
name - the name of the property.
value - the new value of the specified property.
See Also:
Resource.setProperty(PropertyNameList.PropertyName, Object)

Generated Fri 15-Nov-2013 12:48 AM

Copyright © IBM 2013. All rights reserved.