Project: stp

com.ibm.rational.wvcm.stp.cq
Interface CqFieldValue<T>

All Superinterfaces:
StpProperty<T>
All Known Subinterfaces:
CqHistoryFieldValue

public interface CqFieldValue<T>
extends StpProperty<T>

The representation for the value of a record field as an extended StpProperty object.


Nested Class Summary
static class CqFieldValue.ValidationStatus
          An enumeration indicating the validity of a field value.
static class CqFieldValue.ValueStatus
          An enumeration indicating whether or not a field has a value.
static class CqFieldValue.ValueType
          An enumeration of the possible types of values that can be stored in a record field.
 
Nested classes/interfaces inherited from interface com.ibm.rational.wvcm.stp.StpProperty
StpProperty.List<S extends StpProperty>, StpProperty.MetaPropertyName<V>, StpProperty.Type
 
Field Summary
static StpProperty.MetaPropertyName<List<String>> CHOICE_LIST
          The current list of possible values for this field.
static StpProperty.MetaPropertyName<CqFieldDefinition> FIELD_DEFINITION
          The field definition that defines all static properties of this field.
static StpProperty.MetaPropertyName<CqFieldValue.ValueType> FIELD_TYPE
          The type of this field's VALUE meta-property value.
static StpProperty.MetaPropertyName<String> MESSAGE_TEXT
          A String explaining why the value stored in the field is invalid.
static String NULL_VALUE_IMAGE
          The special string value returned by characterImage for a null field value
static StpProperty.MetaPropertyName<?> ORIGINAL_VALUE
          The field's value as it was retrieved from the database at the start of the action.
static StpProperty.MetaPropertyName<CqFieldValue.ValueStatus> ORIGINAL_VALUE_STATUS
          The field's value status as it was retrieved from the database at the start of the action.
static StpProperty.MetaPropertyName<CqRecord> RECORD
          The record instance of which this field is a part.
static StpProperty.MetaPropertyName<CqFieldDefinition.Requiredness> REQUIREDNESS
          Identifies the requiredness of the specified field.
static StpProperty.MetaPropertyName<CqFieldValue.ValidationStatus> VALIDATION_STATUS
          Identifies whether the field's value is valid.
static StpProperty.MetaPropertyName<Boolean> VALIDITY_CHANGED_THIS_ACTION
          True if the field's validity was changed by the current action.
static StpProperty.MetaPropertyName<Boolean> VALIDITY_CHANGED_THIS_GROUP
          True if the field's validity was changed by the most recent group of SetFieldValue calls.
static StpProperty.MetaPropertyName<Boolean> VALIDITY_CHANGED_THIS_SET_VALUE
          True if the field's validity was changed by the most recent SetFieldValue call.
static StpProperty.MetaPropertyName<Boolean> VALUE_CHANGED_THIS_ACTION
          True if this field's value was modified by the current action.
static StpProperty.MetaPropertyName<Boolean> VALUE_CHANGED_THIS_GROUP
          True if the field's value was modified by the most recent group of SetFieldValue calls.
static StpProperty.MetaPropertyName<Boolean> VALUE_CHANGED_THIS_SET_VALUE
          True if this field's value was modified by the most recent property update interaction with the server.
static StpProperty.MetaPropertyName<CqFieldValue.ValueStatus> VALUE_STATUS
          Identifies whether the field currently has a value.
 
Fields inherited from interface com.ibm.rational.wvcm.stp.StpProperty
IS_EMPTY, META_PROPERTY_NAMES, NAME, NAMESPACE, PROPERTY_NAME, RESOURCE, SIZE, TYPE, VALUE
 
Method Summary
 String characterImage()
          Returns the character image of the (first) field value.
 String characterImage(int i)
          Returns the character image of the i-th element of an aggregated value.
 List<String> getChoiceList()
          Returns the value of the CHOICE_LIST metadata component as defined by this Property instance.
 CqFieldDefinition getFieldDefinition()
          Returns the value of the FIELD_DEFINITION metadata component as defined by this Property instance.
 CqRecord.FieldName<T> getFieldName()
           
 CqFieldValue.ValueType getFieldType()
          Returns the value of the FIELD_TYPE meta-property as defined by this CqFieldValue instance.
 String getMessageText()
          Returns the value of the MESSAGE_TEXT metadata component as defined by this Property instance.
 T getOriginalValue()
          Returns the value of the ORIGINAL_VALUE metadata component as defined by this Property instance.
 CqFieldValue.ValueStatus getOriginalValueStatus()
          Returns the value of the ORIGINAL_VALUE_STATUS metadata component as defined by this Property instance.
 CqRecord getRecord()
          Returns the value of the RECORD metadata component as defined by this Property instance.
 CqFieldDefinition.Requiredness getRequiredness()
          Returns the value of the REQUIREDNESS metadata component as defined by this Property instance.
 CqFieldValue.ValidationStatus getValidationStatus()
          Returns the value of the VALIDATION_STATUS metadata component as defined by this Property instance.
 boolean getValidityChangedThisAction()
          Returns the value of the VALIDITY_CHANGED_THIS_ACTION metadata component as defined by this Property instance.
 boolean getValidityChangedThisGroup()
          Returns the value of the VALIDITY_CHANGED_THIS_GROUP metadata component as defined by this Property instance.
 boolean getValidityChangedThisSetValue()
          Returns the value of the VALIDITY_CHANGED_THIS_SET_VALUE metadata component as defined by this Property instance.
 boolean getValueChangedThisAction()
          Returns the value of the VALUE_CHANGED_THIS_ACTION metadata component as defined by this Property instance.
 boolean getValueChangedThisGroup()
          Returns the value of the VALUE_CHANGED_THIS_GROUP metadata component as defined by this Property instance.
 boolean getValueChangedThisSetValue()
          Returns the value of the VALUE_CHANGED_THIS_SET_VALUE metadata component as defined by this Property instance.
 CqFieldValue.ValueStatus getValueStatus()
          Returns the value of the VALUE_STATUS metadata component as defined by this Property instance.
 void initialize(List<String> values)
          Initializes the values of this field value structure.
 void initialize(Object value)
          Initializes the value of this field value structure using the value object rather than its image.
 void initialize(String value)
          Initializes the value of this field value structure.
 long valueCount()
          Returns the number of individual values in an aggregated field value.
 
Methods inherited from interface com.ibm.rational.wvcm.stp.StpProperty
getIsEmpty, getMetaProperty, getMetaPropertyNames, getName, getNamespace, getPropertyName, getResource, getSize, getType, getValue, metaPropertyException, metaPropertyExceptions, metaPropertyNames
 

Field Detail

CHOICE_LIST

static final StpProperty.MetaPropertyName<List<String>> CHOICE_LIST
The current list of possible values for this field. If this list is empty and CqFieldDefinition.HAS_OPEN_CHOICE_LIST is true, it neither implies that all values are permitted nor that no values are permitted; it just means that the schema designer has not provided any hints about the values permitted in the field. On the other hand, if CqFieldDefinition.HAS_OPEN_CHOICE_LIST is false then the choice list contains only the values currently permitted for the field.

In general, the content of a field's choice list is quite volatile and can depend on the state of the record it is in, the value of other fields of that record or related records, the current user's permissions, and other dynamic aspects of the database environment known only to the schema. So, in general, the choice list must be obtained in the context in which it is to be used at the time it is to be used. In this interface, that very dynamic value is expressed as the value of this meta-property.

CHOICE_LIST always returns the choice list for the field whether that list is static or not. If the schema is designed such that the choice list for a field in all records in all contexts is fixed by the schema, then this meta-property will always return the same list for that field. In this static case, the list returned by this meta-property will be the same as the list returned by the CqFieldDefinition.CHOICE_LIST property.

Choice lists can be voluminous and, so, should be read from the server only when needed. Yet, as explained above, they can also be quite volatile and may easily change during the course of a session and not necessarily in direct response to anything the client is doing. To mitigate this problem, a choice-list-id is provided to help the client know when it should request a new copy of the list. Every choice list has a choice-list-id. The value of the choice-list-id changes when and only when the content of the associated choice list changes.

If a client does not know that a given field has a static choice list, it must assume that it is not and monitor the field's CHOICE_LIST_ID to know when to load/reload its content.


FIELD_DEFINITION

static final StpProperty.MetaPropertyName<CqFieldDefinition> FIELD_DEFINITION
The field definition that defines all static properties of this field.


FIELD_TYPE

static final StpProperty.MetaPropertyName<CqFieldValue.ValueType> FIELD_TYPE
The type of this field's VALUE meta-property value.


MESSAGE_TEXT

static final StpProperty.MetaPropertyName<String> MESSAGE_TEXT
A String explaining why the value stored in the field is invalid.


NULL_VALUE_IMAGE

static final String NULL_VALUE_IMAGE
The special string value returned by characterImage for a null field value

See Also:
Constant Field Values

ORIGINAL_VALUE

static final StpProperty.MetaPropertyName<?> ORIGINAL_VALUE
The field's value as it was retrieved from the database at the start of the action.


ORIGINAL_VALUE_STATUS

static final StpProperty.MetaPropertyName<CqFieldValue.ValueStatus> ORIGINAL_VALUE_STATUS
The field's value status as it was retrieved from the database at the start of the action.


RECORD

static final StpProperty.MetaPropertyName<CqRecord> RECORD
The record instance of which this field is a part.


REQUIREDNESS

static final StpProperty.MetaPropertyName<CqFieldDefinition.Requiredness> REQUIREDNESS
Identifies the requiredness of the specified field.


VALIDATION_STATUS

static final StpProperty.MetaPropertyName<CqFieldValue.ValidationStatus> VALIDATION_STATUS
Identifies whether the field's value is valid.


VALIDITY_CHANGED_THIS_ACTION

static final StpProperty.MetaPropertyName<Boolean> VALIDITY_CHANGED_THIS_ACTION
True if the field's validity was changed by the current action.


VALIDITY_CHANGED_THIS_GROUP

static final StpProperty.MetaPropertyName<Boolean> VALIDITY_CHANGED_THIS_GROUP
True if the field's validity was changed by the most recent group of SetFieldValue calls.


VALIDITY_CHANGED_THIS_SET_VALUE

static final StpProperty.MetaPropertyName<Boolean> VALIDITY_CHANGED_THIS_SET_VALUE
True if the field's validity was changed by the most recent SetFieldValue call.


VALUE_CHANGED_THIS_ACTION

static final StpProperty.MetaPropertyName<Boolean> VALUE_CHANGED_THIS_ACTION
True if this field's value was modified by the current action.


VALUE_CHANGED_THIS_GROUP

static final StpProperty.MetaPropertyName<Boolean> VALUE_CHANGED_THIS_GROUP
True if the field's value was modified by the most recent group of SetFieldValue calls.


VALUE_CHANGED_THIS_SET_VALUE

static final StpProperty.MetaPropertyName<Boolean> VALUE_CHANGED_THIS_SET_VALUE
True if this field's value was modified by the most recent property update interaction with the server.


VALUE_STATUS

static final StpProperty.MetaPropertyName<CqFieldValue.ValueStatus> VALUE_STATUS
Identifies whether the field currently has a value.

Method Detail

characterImage

String characterImage()
                      throws WvcmException
Returns the character image of the (first) field value.

Returns:
Returns characterImage(0).
Throws:
WvcmException - If the value is null (valueCount == 0).

characterImage

String characterImage(int i)
                      throws WvcmException
Returns the character image of the i-th element of an aggregated value.

Parameters:
i - The (zero-origin) index of the value whose character image is desired. Must be zero or less than valueCount.
Returns:
The character image of the i-th element of the field value. If the field value is null, NULL_VALUE_IMAGE is returned for index 0.
Throws:
WvcmException - If an i-th value exists in this fields value list.

getChoiceList

List<String> getChoiceList()
                           throws WvcmException
Returns the value of the CHOICE_LIST metadata component as defined by this Property instance.

Returns:
A List of Strings, each containing a possible value for this field.
Throws:
WvcmException - if this Property instance does not define a value for the CHOICE_LIST metadata component.

getFieldDefinition

CqFieldDefinition getFieldDefinition()
                                     throws WvcmException
Returns the value of the FIELD_DEFINITION metadata component as defined by this Property instance.

Returns:
A CqFieldDefinition proxy specifying the static properties of this field.
Throws:
WvcmException - if this Property instance does not define a value for the FIELD_DEFINITION metadata component.

getFieldName

CqRecord.FieldName<T> getFieldName()
Returns:
the PropertyName of this CqFieldValue property as a CqRecord.FieldName

getFieldType

CqFieldValue.ValueType getFieldType()
                                    throws WvcmException
Returns the value of the FIELD_TYPE meta-property as defined by this CqFieldValue instance.

Returns:
A VAlueType enumeration representing the type of this property's VALUE meta-property.
Throws:
WvcmException - if this Property instance does not define a value for the FIELD_TYPE meta-property.

getMessageText

String getMessageText()
                      throws WvcmException
Returns the value of the MESSAGE_TEXT metadata component as defined by this Property instance.

Returns:
A String containing any message currently associated with this field.
Throws:
WvcmException - if this Property instance does not define a value for the MESSAGE_TEXT metadata component.

getOriginalValue

T getOriginalValue()
                   throws WvcmException
Returns the value of the ORIGINAL_VALUE metadata component as defined by this Property instance.

Returns:
An Object representing the value of this field just prior to being made editable in this workspace.
Throws:
WvcmException - if this Property instance does not define a value for the ORIGINAL_VALUE metadata component.

getOriginalValueStatus

CqFieldValue.ValueStatus getOriginalValueStatus()
                                                throws WvcmException
Returns the value of the ORIGINAL_VALUE_STATUS metadata component as defined by this Property instance.

Returns:
A ValueStatus enumerator representing the status of this field's value just prior to being made editable in this workspace.
Throws:
WvcmException - if this Property instance does not define a value for the ORIGINAL_VALUE_STATUS metadata component.

getRecord

CqRecord getRecord()
                   throws WvcmException
Returns the value of the RECORD metadata component as defined by this Property instance.

Returns:
A Record proxy for the record of which this field is a member.
Throws:
WvcmException - if this Property instance does not define a value for the RECORD metadata component.

getRequiredness

CqFieldDefinition.Requiredness getRequiredness()
                                               throws WvcmException
Returns the value of the REQUIREDNESS metadata component as defined by this Property instance.

Returns:
A Requiredness enumerator specifying whether this field cannot, may, or must have a value in the current state.
Throws:
WvcmException - if this Property instance does not define a value for the REQUIREDNESS metadata component.

getValidationStatus

CqFieldValue.ValidationStatus getValidationStatus()
                                                  throws WvcmException
Returns the value of the VALIDATION_STATUS metadata component as defined by this Property instance.

Returns:
A ValidationStatus enumerator identifying the validation status of this field.
Throws:
WvcmException - if this Property instance does not define a value for the VALIDATION_STATUS metadata component.

getValidityChangedThisAction

boolean getValidityChangedThisAction()
                                     throws WvcmException
Returns the value of the VALIDITY_CHANGED_THIS_ACTION metadata component as defined by this Property instance.

Returns:
true if the field validity changed during the current action
Throws:
WvcmException - if this Property instance does not define a value for the VALIDITY_CHANGED_THIS_ACTION metadata component.

getValidityChangedThisGroup

boolean getValidityChangedThisGroup()
                                    throws WvcmException
Returns the value of the VALIDITY_CHANGED_THIS_GROUP metadata component as defined by this Property instance.

Returns:
true if this field's validity has changed since the last setting of CqRecord.FIELDS_UPDATED_THIS_GROUP in this field's record.
Throws:
WvcmException - if this Property instance does not define a value for the VALIDITY_CHANGED_THIS_GROUP metadata component.

getValidityChangedThisSetValue

boolean getValidityChangedThisSetValue()
                                       throws WvcmException
Returns the value of the VALIDITY_CHANGED_THIS_SET_VALUE metadata component as defined by this Property instance.

Returns:
true if the field validity was changed by the most recent property update.
Throws:
WvcmException - if this Property instance does not define a value for the VALIDITY_CHANGED_THIS_SET_VALUE metadata component.

getValueChangedThisAction

boolean getValueChangedThisAction()
                                  throws WvcmException
Returns the value of the VALUE_CHANGED_THIS_ACTION metadata component as defined by this Property instance.

Returns:
true if this field's value has changed during the current action.
Throws:
WvcmException - if this Property instance does not define a value for the VALUE_CHANGED_THIS_ACTION metadata component.

getValueChangedThisGroup

boolean getValueChangedThisGroup()
                                 throws WvcmException
Returns the value of the VALUE_CHANGED_THIS_GROUP metadata component as defined by this Property instance.

Returns:
true if this field's value has changed since the last setting of CqRecord.FIELDS_UPDATED_THIS_GROUP in this field's record.
Throws:
WvcmException - if this Property instance does not define a value for the VALUE_CHANGED_THIS_GROUP metadata component.

getValueChangedThisSetValue

boolean getValueChangedThisSetValue()
                                    throws WvcmException
Returns the value of the VALUE_CHANGED_THIS_SET_VALUE metadata component as defined by this Property instance.

Returns:
true if this fields value changed during the latest property-update interaction with the server
Throws:
WvcmException - if this Property instance does not define a value for the VALUE_CHANGED_THIS_SET_VALUE metadata component.

getValueStatus

CqFieldValue.ValueStatus getValueStatus()
                                        throws WvcmException
Returns the value of the VALUE_STATUS metadata component as defined by this Property instance.

Returns:
A ValueStatus enumeration indicating whether or not this field has a value.
Throws:
WvcmException - if this Property instance does not define a value for the VALUE_STATUS metadata component.

initialize

void initialize(List<String> values)
Initializes the values of this field value structure.

Parameters:
values - A list of value images that are to be the new field value images. May be null to indicate a null field value.

initialize

void initialize(Object value)
                throws WvcmException
Initializes the value of this field value structure using the value object rather than its image.

Parameters:
value - The value of the field. Must be a native representation of one of the supported field types.
Throws:
WvcmException

initialize

void initialize(String value)
                throws WvcmException
Initializes the value of this field value structure.

Parameters:
value - The string value that is to be the new field value image. May be null to indicate a null field value.
Throws:
WvcmException - if the field value is a record or list of records and the specified String is not a valid StpLocation image.

valueCount

long valueCount()
Returns the number of individual values in an aggregated field value.

Returns:
Returns 0 for a null value, 1 for a scalar value, and the count of the number of individual values in a aggregated value.
Throws:
WvcmException - if the field value is a record or list of records and the value specified as a String is not a valid StpLocation image.

Generated Mon 24-Aug-2015 12:11 PM

Copyright © IBM 2015. All rights reserved.