Package com.documentum.fc.client

# Interface IDfValidator

public interface IDfValidator
Interface that provides the data validation functionality. It is returned by IDfPersistentObject.getValidator() or IDfType.getTypeValidator(). If it was obtained using IDfPersistentObject.getValidator() then the IDfValidator is object specific i.e. associated with an object instance. If the IDfValidator was obtained using IDfType.getTypeValidator(), the validator is not associated with an object instance. The getAssociatedObject method can be used to determine if the IDfValidator is object Specific or not. The getAssociatedObject method will return `null` if the interface is not associated with an object instance; otherwise it will return the IDfPersistentObject interface from which the validator was obtained.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `IDfPersistentObject`
  `getAssociatedObject()`
  Returns the IDfPersistentObject interface of the object associated with the IDfValidator.
  `int`
  `getMaxErrorBeforeStop()`
  Returns the upper limit for validation detection.
  `String`
  `getObjectType()`
  Returns the object type associated with this validator.
  `IDfId`
  `getPolicyID()`
  Returns the business policy id associated with this validator.
  `String`
  `getStateName()`
  Returns the name of the current business policy state associated with this validator.
  `String`
  `getTimePattern()`
  Returns the time pattern used for validation.
  `IDfValueAssistance`
  `getValueAssistance(String attrName, IDfProperties depAttrValues)`
  Returns the value assistance associated with the specified attribute.
  `IDfProperties`
  `getValueAssistanceDependencies(String attrName)`
  Return the list of attributes on which the value assistance selection depends on.
  `String`
  `getWidgetType(int environment, String attrName)`
  Find the appropriate widget type given a specific development environment and attribute name.
  `boolean`
  `hasValueAssistance(String attrName)`
  Indicates whether value assistance is setup for the specified attribute or not.
  `void`
  `setMaxErrorBeforeStop(int stopAfterNumOfErrors)`
  Sets the upper limit for validation detection.
  `void`
  `setTimePattern(String timePattern)`
  Sets an alternative time pattern used for validation.
  `void`
  `validateAll(IDfProperties attrValues, boolean modifiedAttrsOnly)`
  Performs both attribute level and object level validation.
  `void`
  `validateAllAttrRules(IDfProperties attrValues, boolean modifiedAttrsOnly)`
  Validate the user input `attrValues` with all the attribute level validation rules specified for this object type, policy and state set in the Data Dictionary.
  `void`
  `validateAllObjRules(IDfProperties attrValues)`
  Validate the user input attrValues with all the object level validation rules specified for this object type, policy and state set in the Data Dictionary.
  `void`
  `validateAttrRules(String attrName, IDfList values, IDfProperties depAttrValues)`
  Validate the specified attribute with the validation rules set in the Data Dictionary given a list of attribute values, and an IDfProperties interface containing dependent attributes.

- ## Method Details

  - ### validateAll

    void validateAll(IDfProperties attrValues, boolean modifiedAttrsOnly) throws DfException
    Performs both attribute level and object level validation.

    If `attrValues` passed in is `null`, the value in the object instance associated with this IDfValidator is used. (If there is no object instance associated, an exception will be thrown) If `modifiedAttrsOnly` is set to `true`, attribute level validation will be performed on attributes that are modified but not yet validated (e.g. by an explicit call to `validateAttr`). Attributes can be modified via calls to append*, insert*, set[Repeating]*, remove* or removeAll. If `modifiedAttrsOnly` is set to `false`, attribute level validation will be performed on all the attributes within this object type.

    The following code example demonstrates how to validate all attributes for an object type, specifically those attributes that have been modified:

    >      IDfPersistentObject pObj = null;
    >      IDfValidator v = null;
    >      try
    >      {
    >           pObj = sess.getObject(new DfId("0900d5bb8001fd49"));
    >           pObj.setInt("int_attr", 6);       // Modifying the attr here...
    >           v = pObj.getValidator();
    >           v.validateAll(null,true);
    >      }
    >      catch(DfValidationException ve)
    >      {
    >           // Validation rules violated...
    >      }

    Parameters:
      `attrValues` - specifies the attribute name/attribute values pair related to the validation. If `attrValues` is `null`, the values will be looked up from the object instance itself, provided the validator is object specific.
      `modifiedAttrsOnly` - specifies whether to perform attribute level validation on all the attributes within this object type, or on the modified attributes only.
    Throws:
      `DfException` - if validation rules are violated.
    See Also:
      - `validateAllAttrRules(com.documentum.fc.common.IDfProperties, boolean)`
      - `validateAllObjRules(com.documentum.fc.common.IDfProperties)`
      - `validateAttrRules(java.lang.String, com.documentum.fc.common.IDfList, com.documentum.fc.common.IDfProperties)`

  - ### validateAllAttrRules

    void validateAllAttrRules(IDfProperties attrValues, boolean modifiedAttrsOnly) throws DfException
    Validate the user input `attrValues` with all the attribute level validation rules specified for this object type, policy and state set in the Data Dictionary. If `attrValues` is `null`, the value in the object instance associated with this IDfValidator is used. (If there is no object instance associated, an exception will be thrown)

    If `modifiedAttrsOnly` is set to `true`, attribute level validation will be performed on attributes that are modified but not yet validated (e.g. by an explicit call to `validateAttr`). Attributes can be modified via calls to append*, insert*, set[Repeating]*, remove* or removeAll. If `modifiedAttrsOnly` is set to `false`, attribute level validation will be performed on all the attributes within this object type.

    The following code example demonstrates how to validate the attribute assigned to the IDfProperties interface list:

    >      IDfPersistentObject pObj = null;
    >      IDfValidator v = null;
    >      IDfProperties props = new DfProperties();
    >      IDfList values = new DfList(IDfList.DF_STRING);
    >      try
    >      {
    >           pObj = sess.getObject(new DfId("0900d5bb8001fd49"));
    >           v = pObj.getValidator();
    >           values.appendString("6");
    >           props.putString("str_attr", values);
    >           v.validateAllAttrRules(props, false);
    >      }
    >      catch(DfValidationException ve)
    >      {
    >           // Validation rules violated...
    >      }

    Parameters:
      `attrValues` - specifies the attribute name/attribute values pair related to the validation. If attrValues is `null`, the values will be looked up from the object instance itself, provided the validator is object specific.
      `modifiedAttrsOnly` - specifies whether to perform attribute level validation on all the attributes within this object type, or on the modified attributes only.
    Throws:
      `DfException` - if validation rules are violated.
    See Also:
      - `validateAll(com.documentum.fc.common.IDfProperties, boolean)`
      - `validateAllObjRules(com.documentum.fc.common.IDfProperties)`
      - `validateAttrRules(java.lang.String, com.documentum.fc.common.IDfList, com.documentum.fc.common.IDfProperties)`

  - ### validateAllObjRules

    void validateAllObjRules(IDfProperties attrValues) throws DfException
    Validate the user input attrValues with all the object level validation rules specified for this object type, policy and state set in the Data Dictionary. If `attrValues` is `null`, the value in the object instance associated with this IDfValidator is used. (If there is no object instance associated, an exception will be thrown)

    The following code example demonstrates how to validate the attribute added to the IDfProperties interface list based on object rules defined when the object type was created:

    >      IDfPersistentObject pObj = null;
    >      IDfValidator v = null;
    >      IDfProperties props = new DfProperties();
    >      IDfList values = new DfList(IDfList.DF_STRING);
    >      try
    >      {
    >           pObj = sess.getObject(new DfId("0900d5bb8001fd49"));
    >           v = pObj.getValidator();
    >           values.appendString("6");
    >           props.putString("str_attr", values);
    >           v.validateAllObjRules(props);
    >      }
    >      catch(DfValidationException ve)
    >      {
    >           // Validation rules violated...
    >      }

    Parameters:
      `attrValues` - the attribute name/values pairs used for this validation. If values are `null`, the value will be looked up from the object instance itself, provided that the validator is object specific.
    Throws:
      `DfException` - - if validation rules are violated.
    See Also:
      - `validateAll(com.documentum.fc.common.IDfProperties, boolean)`
      - `validateAllAttrRules(com.documentum.fc.common.IDfProperties, boolean)`
      - `validateAttrRules(java.lang.String, com.documentum.fc.common.IDfList, com.documentum.fc.common.IDfProperties)`

  - ### validateAttrRules

    void validateAttrRules(String attrName, IDfList values, IDfProperties depAttrValues) throws DfException
    Validate the specified attribute with the validation rules set in the Data Dictionary given a list of attribute values, and an IDfProperties interface containing dependent attributes.

    If values passed in is null, the values in the object instance associated with this IDfValidator is used. (If there is no object instance associated, an exception will be thrown)

    The following code example demonstrates how to validate an attribute given a list of values where there are no dependencies:

    >      IDfPersistentObject pObj = null;
    >      IDfValidator v = null;
    >      IDfList values = new IDfList();
    >      try
    >      {
    >           pObj = sess.getObject(new DfId("0900d5bb8001fd49"));
    >           v = pObj.getValidator();
    >           values.insertString("6");
    >           v.validateAttrRules("str_attr", valList, null);
    >      }
    >      catch(DfException dfe)
    >      {
    >           // Validation rules violated...
    >      }

    Parameters:
      `attrName` - the name of the attribute.
      `values` - the list of values to be validated. If values are `null`, the value will be looked up from the object instance itself, provided that the validator is object specific.
      `depAttrValues` - the list of attribute name/values pairs that the evaluation of value assistance is dependent on. If depAttrValues is `null`, but the value assistance selection does depend on other attribute values, the attribute values will be looked up from the object instance itself, provided that the validator is object specific.
    Throws:
      `DfException` - if validation rules are violated.
    See Also:
      - `validateAll(com.documentum.fc.common.IDfProperties, boolean)`
      - `validateAllAttrRules(com.documentum.fc.common.IDfProperties, boolean)`
      - `validateAllObjRules(com.documentum.fc.common.IDfProperties)`

  - ### getValueAssistance

    IDfValueAssistance getValueAssistance(String attrName, IDfProperties depAttrValues) throws DfException
    Returns the value assistance associated with the specified attribute. Value assistance is a list of legal values associated with an attribute that a user can choose from (typically from an application with a UI). Depending on the attribute and object rules setup during object type creation, the value assistance could vary depending on the values of other attributes within the same object type.

    The following code example demonstrates how to obtain an IDfValueAssistance interface for one of a sysobject's attributes:

    >      IDfPersistentObject pObj = sess.getObject(new DfId("0900d5bb8001fd49"));
    >      IDfValidator v = pObj.getValidator();
    >      IDfValueAssistance va = v.getValueAssistance("attr_list", null);

    Parameters:
      `attrName` - the name of the attribute.
      `depAttrValues` - the list of attribute name/values pairs that the evaluation of value assistance is dependent on. If depAttrValues is `null`, but the value assistance selection does depend on other attribute values, the attribute values will be looked up from the object instance itself, provided that the validator is object specific.
    Returns:
      an IDfValueAssistance interface associated with the attribute with the specified depending attributes values.
    Throws:
      `DfException` - if the server returns an error.
    See Also:
      - `hasValueAssistance(java.lang.String)`
      - `getValueAssistanceDependencies(java.lang.String)`

  - ### getWidgetType

    String getWidgetType(int environment, String attrName) throws DfException
    Find the appropriate widget type given a specific development environment and attribute name. If in a Java development environment, a class name will be returned; if in the Visual Basic/Visual C++ environment (Microsoft), a CLSID for an ActiveX component will be returned.

    The following code example demonstrates how to obtain the CLSID of an ActiveX component given the Microsoft development environment:

    >      IDfPersistentObject pObj = sess.getObject(new DfId("0900d5bb8001fd49"));
    >      IDfValidator v = pObj.getValidator();
    >      String retVal = v.getWidgetType(1, "str_attr");

    Parameters:
      `environment` - specifies the development environment for the validation widgets. Available choices are:

           0    Java - obtain the full Java ClassPath
           1    Microsoft - obtain the CLSID of the ActiveX control

      `attrName` - specifies the name of the attribute associated with the widget.
    Returns:
      a String representing the suggested widget (Java class or a CLSID depending on whether `environent` is set to 0 or 1, respectively).
    Throws:
      `DfException` - if unable to obtain a widget type.

  - ### getValueAssistanceDependencies

    IDfProperties getValueAssistanceDependencies(String attrName) throws DfException
    Return the list of attributes on which the value assistance selection depends on. During object type creation, you can define rules for an attribute where the attribute depends on the settings (or assignments) of other attributes.

    The following code example demonstrates how to obtain an IDfProperties interface containing a list of dependent attribute names:

    >      IDfPersistentObject pObj = sess.getObject(new DfId("0900d5bb8001fd49"));
    >      IDfValidator v = pObj.getValidator();
    >      IDfProperties props = v.getValueAssistanceDependencies("str_list_dep");
    >      if (props != null)
    >      {
    >           IDfList depAttrsName = props.getProperties();
    >           for (int i = 0; i < props.getCount(); i++)
    >           {
    >               System.out.println(depAttrsName.getString(i));
    >           }
    >      }

    Parameters:
      `attrName` - the attribute to get the dependencies for.
    Returns:
      a list of attribute names the selection depends on, in the form of a IDfProperties interface with the corresponding attribute values set to blank. If there is no value assistance dependencies for the specified attrName, `null` will be returned.
    Throws:
      `DfException` - if the server returns an error.
    See Also:
      - `hasValueAssistance(java.lang.String)`
      - `getValueAssistance(java.lang.String, com.documentum.fc.common.IDfProperties)`

  - ### setMaxErrorBeforeStop

    void setMaxErrorBeforeStop(int stopAfterNumOfErrors)
    Sets the upper limit for validation detection.
    Parameters:
      `stopAfterNumOfErrors` - specifies the maximum number of violated validation rules validation calls will detect. If "stopAfterNumOfErrors" is set to zero (the default), validation will not stop until it completes all the validation rules.

  - ### setTimePattern

    void setTimePattern(String timePattern)
    Sets an alternative time pattern used for validation. Validation will recognize both the specified time pattern and the time pattern in the client desktop setting. The default is the format specified by client desktop settings. The user can specified one of the 42 patterns defined in IDfTime. If the pattern specified is not recognized, the default client desktop setting will be used for validation.
    Parameters:
      `timePattern` - specifies a date time pattern the user would like to use in addition to the client desktop setting for validation. It should be a Documentum date/time pattern string. See the comments for the constructor DfTime(String, String) for a listing of the legal patterns.

  - ### getAssociatedObject

    IDfPersistentObject getAssociatedObject()
    Returns the IDfPersistentObject interface of the object associated with the IDfValidator.
    Returns:
      IDfPersistentObject if the IDfValidator is object specific, `null` otherwise.

  - ### hasValueAssistance

    boolean hasValueAssistance(String attrName) throws DfException
    Indicates whether value assistance is setup for the specified attribute or not. Value Assistance is a list of possible values for a specified attribute.
    Parameters:
      `attrName` - specifies the name of the attribute
    Returns:
      `true` if there is value assistance for the specified attribute, `false` otherwise.
    Throws:
      `DfException` - if the server returns an error.
    See Also:
      - `getValueAssistance(java.lang.String, com.documentum.fc.common.IDfProperties)`
      - `getValueAssistanceDependencies(java.lang.String)`

  - ### getObjectType

    String getObjectType()
    Returns the object type associated with this validator. A Validator can be identified by looking at the object type, business policy id and the current state name the validator is associated with.
    Returns:
      the object type associated with this validator.
    See Also:
      - `getPolicyID()`
      - `getStateName()`

  - ### getPolicyID

    IDfId getPolicyID()
    Returns the business policy id associated with this validator. A Validator can be identified by looking at the object type, business policy id and the current state name the validator is associated with.
    Returns:
      the business policy id associated with this validator.
    See Also:
      - `getObjectType()`
      - `getStateName()`

  - ### getStateName

    String getStateName()
    Returns the name of the current business policy state associated with this validator. A Validator can be identified by looking at the object type, business policy id and the current state name the validator is associated with.
    Returns:
      the current policy state associated with this validator.
    See Also:
      - `getObjectType()`
      - `getPolicyID()`

  - ### getMaxErrorBeforeStop

    int getMaxErrorBeforeStop()
    Returns the upper limit for validation detection.
    Returns:
      specifies the maximum number of violated validation rules validation calls will detect. If "stopAfterNumOfErrors" is set to zero (the default), validation will not stop until it completes all the validation rules.

  - ### getTimePattern

    String getTimePattern()
    Returns the time pattern used for validation. The default is the format specified by client desktop settings. The user can specify one of the 42 patterns defined in IDfTime. If the pattern specified is not recognized, the default client desktop setting will be used for validation.
    Returns:
      specifies a date time pattern the user would like to use in place of the client desktop settings for validation. It should be a Documentum date/time pattern string. See the comments for the constructor DfTime(String, String) for a listing of the legal patterns.