Package com.documentum.fc.client

# Interface IDfValueAssistance

public interface IDfValueAssistance
Interface to provide information about the value assistance of an attribute, given the set of attribute name/value pairs of its depending attributes. It is returned by IDfValidator.getValueAssistance().
The value assistance information associated with a specified set of depending attribute name/value pairs includes: the actual possible values that the user can choose from, the display values corresponding to each actual value, and whether the value assistance is complete or not. If the value assistance is complete, any values outside of the value assistance list will be considered invalid.
A value assistance is valid if the values of the depending attributes have not changed since the value assistance was last retrieved.
The actual and display values should be a one-to-one mapping.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `getActualValue(String displayValue)`
  Return the possible actual value mapped to the specified `displayValue`.
  `IDfList`
  `getActualValues()`
  Return the list of possible actual values that the user can choose from.
  `String`
  `getDisplayValue(String actualValue)`
  Return the possible display value mapped to the specified actual value.
  `IDfList`
  `getDisplayValues()`
  Return the list of possbile attribute display values.
  `boolean`
  `isListComplete()`
  Indicate whether value assistance is complete or not.
  `boolean`
  `isValidForDependentValues(IDfProperties depAttrValues)`
  Indicate whether the value assistance is valid or not.
  `boolean`
  `isValidForObject(IDfPersistentObject objectInstance)`
  Indicate whether the value assistance is valid or not.

- ## Method Details

  - ### getActualValues

    IDfList getActualValues()
    Return the list of possible actual values that the user can choose from.
    Returns:
      the list of possible actual values

  - ### getActualValue

    String getActualValue(String displayValue) throws DfException
    Return the possible actual value mapped to the specified `displayValue`. If the specified `displayValue` is not found, `null` will be returned.

    Note: a developer can specify a value mapping table in the data dictionary. It maps a possible "actual value" to a user-friendly display value. For example, there could be a mapping as follows in the data dictionary:

         Actual Value     Display Value
         CA               California
         NY               New York
         FL               Florida

    In a UI, the end-user will see California, New York and Florida in a drop down list. If the end-user chooses California, the application will map California back to its "actual value", CA, and store CA in the Documentum server as the attribute value for that object instance.

    The following code example demonstrates how to obtain an IDfValueAssistance interface for a sysobject and display the actual values for an attribute:

    >      IDfPersistentObject pObj = sess.getObject(new DfId("0900d5bb8001fd49"));
    >      IDfValidator v = pObj.getValidator();
    >      IDfValueAssistance va = v.getValueAssistance("attr_list", null);
    >      String actualVal = va.getActualValue("California");
    >      if (actualVal.equals("CA"))
    >      {
    >           // Do something here..
    >      }

    Parameters:
      `displayValue` - the display value.
    Returns:
      the possible actual value mapped to the specified displayValue, or `null` if the specified displayValue is not found.
    Throws:
      `DfException`

  - ### getDisplayValues

    IDfList getDisplayValues()
    Return the list of possbile attribute display values.

    The following code example demonstrates how to obtain an IDfValueAssistance interface for an IDfPersistentObject and the display values for an attribute:

    >      IDfPersistentObject pObj = sess.getObject(new DfId("0900d5bb8001fd49"));
    >      IDfValidator v = pObj.getValidator();
    >      IDfValueAssistance va = v.getValueAssistance("attr_list", null);
    >      IDfList listVals = va.getDisplayValues();
    >      for (int i = 0; i < listVals.getCount(); i++)
    >      {
    >           System.out.println("Display Value: " + listVals.getString(i));
    >      }

    Returns:
      a list of display values.

  - ### getDisplayValue

    String getDisplayValue(String actualValue) throws DfException
    Return the possible display value mapped to the specified actual value. If the specified actualValue is not found, `null` will be returned.
    Parameters:
      `actualValue` - the actual value
    Returns:
      the display value mapped to the specified actual value `null`, if the specified actualValue is not found.
    Throws:
      `DfException`

  - ### isListComplete

    boolean isListComplete()
    Indicate whether value assistance is complete or not. The value assistance is complete if the only values accepted as valid are those specified in the value assistance list.
    Returns:
      `true` if the value assistance is complete, `false` otherwise.

  - ### isValidForObject

    boolean isValidForObject(IDfPersistentObject objectInstance) throws DfException
    Indicate whether the value assistance is valid or not. Value assistance is valid if the values of the depending attributes have not changed since the value assistance was last retrieved. If the selection of value assistance is dependent on other attributes, the values of the depending attributes will be looked up from the specified `objectInstance`.
    Parameters:
      `objectInstance` - the object instance where the values of the depending attributes will be looked up from
    Returns:
      `true` if the value assistance is valid, `false` otherwise.
    Throws:
      `DfException`

  - ### isValidForDependentValues

    boolean isValidForDependentValues(IDfProperties depAttrValues) throws DfException
    Indicate whether the value assistance is valid or not. Value assistance is valid if the values of the depending attributes have not changed since the value assistance was last retrieved. If the selection of value assistance is dependent on other attributes, the values of the depending attributes will be looked up from the specified attribute name/value pairs.
    Parameters:
      `depAttrValues` - the attribute name/value pairs where the values of the depending attributes will be looked up from
    Returns:
      `true` if the value assistance is valid, `false` otherwise.
    Throws:
      `DfException`