public class Validator
extends java.lang.Object
 This class is not meant to be created and used, it is actually documentation of settings
 allowed in a DataSource descriptor (.ds.xml file), for use with Smart GWT Pro Edition and
 above.
 See com.smartgwt.client.docs.serverds for how to use this documentation.
 
 Validators are specified for DataSource fields via the DataSourceField.validators
 property and are executed in the order in
 which they are defined. Validators that need not be run on the server can also be specified
 for a specific FormItem or ListGridField. 
 Smart GWT supports a powerful library of
 ValidatorTypes which have identical behavior on
 both the client and the server.   
  Beyond this, custom validators can be defined on the
 client and custom validation logic added on the server.  Note that the regexp and
 mask validator types are very flexible and can be used to perform virtually any
 kind of formatting check that doesn't involve some large external dataset. 
 Custom
 validators can be reused on the client by adding them to the global validator list, via the
 addValidator()
 method.
ValidatorType| Modifier and Type | Field and Description | 
|---|---|
| AdvancedCriteria | applyWhenUsed to create a conditional validator based on  criteria. | 
| boolean | caseSensitiveApplies only to the "isUnique" and "hasRelatedRecord" validators and controls whether the
 search for existing records is case sensitive or not. | 
| java.lang.Boolean | clientOnlyIndicates this validator runs on the client only. | 
| StringMethod | conditionFor a validator that is not a built-in  ValidatorType, aCallback, 
  function, or JavaScript expression to evaluate to see if this validator passes or fails. | 
| java.lang.String[] | dependentFieldsUser-defined list of fields on which this validator depends. | 
| java.lang.String | errorMessageText to display if the value does not pass this validation check. | 
| java.lang.Boolean | exclusive | 
| java.lang.Object | maxIndicates the maximum value for range-based validators. | 
| java.lang.Object | minIndicates the minimum value for range-based validators. | 
| java.lang.String | operationIdApplies only to the "isUnique" validator; allows you to name a specific   operationfor the server-side
 uniqueness check. | 
| java.lang.String | serverConditionFor validators of type "serverCustom" only: a scriptlet in any supported JSR223 scripting
  language which is run in order to see if validation passes. | 
| ServerObject | serverObjectFor validators of type "serverCustom" only, a  ServerObjectdeclaration that allows
  the Smart GWT Server to find a Java class via a variety of possible approaches, and call a
  method on it to perform validation. | 
| java.lang.Boolean | serverOnlyIndicates this validator runs on the server only. | 
| java.lang.Boolean | stopIfFalseNormally, all validators defined for a field will be run   in the order in which they are definedeven if
 one of the validators has already failed. | 
| java.lang.Boolean | stopOnErrorIndicates that if this validator is not passed, the user should not be allowed to exit the
 field - focus will be forced back into the field until the error is corrected. | 
| ValidatorType | typeType of the validator. | 
| java.lang.Boolean | validateOnChangeIf true, validator will be validated when each item's "change" handler is fired as well as when
 the entire form is submitted or validated. | 
| Constructor and Description | 
|---|
| Validator() | 
public boolean caseSensitive
Default value is false
public java.lang.String errorMessage
If unspecified, default error messages exist for all built-in validators, and a generic message will be used for a custom validator that is not passed.
Server-side this string evaluates in a Velocity context where the variables $value and $fieldName are available and refer to the supplied value and the field name, respectively. Note that if the validator is intended to run both on the client and server, you shouldn't use these velocity vars as they will not be expanded on the client and the user may then see raw uninterpolated strings.
Default value is null
public java.lang.Boolean validateOnChange
Note that this property can also be set at the form/grid or field level; If true at any level and not explicitly false on the validator, the validator will be fired on change - displaying errors and rejecting the change on validation failure.
Default value is null
public java.lang.String[] dependentFields
applyWhen criteria.  Note that for
 validators run on the server, fields required due to dependentFields but not
 present in the DSRequest.data of an update
 because they haven't changed will be filled in from the server DataSource.
 
Default value is null
applyWhenpublic java.lang.Boolean stopOnError
 This
 property defaults to FormItem.stopOnError if unset. 
 Enabling this property also implies FormItem.validateOnExit is
 automatically enabled. If this is a server-based validator, setting this property also implies
 that FormItem.synchronousValidation is forced on.
 
Default value is null
public AdvancedCriteria applyWhen
criteria.
  The criteria defines when the validator applies. The form current values or ListGrid record
  is used as reference for the criteria. If the criteria match, then the validator will be
  processed. Otherwise the validator is skipped and assumed valid.
  
 To use an applyWhen criteria the form or grid must use a DataSource.
  
  NOTE: applyWhen is not supported for "binary" fields.
  
applyWhen element is treated as a Criterion.
  
  <!-- Normal format -->
  <field name="age" type="integer">
    <validators>
      <validator type="integerRange" min="0" max="100">
        <applyWhen operator="or">
          <criteria>
            <criterion fieldName="restrictAge" operator="equals" value="true"/>
            <criterion fieldName="gender" operator="equals" value="female"/>
          </criteria> 
        </applyWhen>
      </validator>
    </validators>
  </field>
 
  <!-- Conditional requirement -->
  <field name="reason" type="text">
    <validators>
      <validator type="required">
        <applyWhen fieldName="willAttend" operator="equals" value="false"/>
      </validator>
    </validators>
  </field>
  
 
  The last example above shows an alternate to the requiredIf validator using a
 shorthand format which is only available
 for client-side
  use. On the client the reason field will change appearance to match other
  required or non-required fields when willAttend changes.  Note that using
  applyWhen for a validator of type required as in the example may
  result in validation request being set to the server where a fetch is made against the
  DataSource.  For more details, see the discussion at the end of the
 DataSourceField.required
 help topic.
  
Component XML
  similarly to provide client-only validations or read-only state management. A common
  use case is conditionally displaying or enabling fields. Use the readOnly
  validator with an applyWhen value to control the read-only appearance of a
  field. The example below shows a field which is hidden when willAttend=true.
  
  <!-- field definition within a Component XML DynamicForm -->
  <field name="reason" type="text">
    <validators>
      <validator type="readOnly" fieldAppearance="hidden">
        <applyWhen fieldName="willAttend" operator="equals" value="true"/>
      </validator>
    </validators>
  </field>
  
  Conditional validators can be applied to DynamicForm or ListGrid fields in Java code as well.
Default value is null
public java.lang.String serverCondition
      <validator type="serverCustom">
          <serverCondition language="groovy"><![CDATA[
              value < dataSources.StockItem.fetchById(record.itemId).quantity
          ]]></serverCondition>
      </validator>
  
  The scriptlet should return a boolean true or false value - failing to return a value will
  be considered a false result (validator failed).  If your expression is syntactically
  invalid, an exception is thrown and the error message is displayed in the client.
  
 See ServerScript for general information on Server Scripting
 and JSR223, and
 VelocitySupport for general information on Velocity support,
 and also see below
  for special rules for Velocity.
  
  Available variables
  The following variables are available in a serverCondition:
  
MapDSField object)
      $dataSource.fetchById($record.primaryKeyField).otherFieldName
  
  Note that, while a DSRequest provides dsRequest.oldValues, these values cannot be relied
  upon for a security check since they could be faked.
  
  Server-side custom validators also have access to the standard set of context variables that
  come from the Servlet API.  However, be aware that if you write conditions that depend upon 
  these variables, you preclude your Validator from being used in the widest possible variety 
  of circumstances; for example, in a command-line process.  Rather, it will be tied to 
  operating in the context of, say, an HttpSession.  
  
Given the above caveat, the following context variables are also available:
HttpServletRequestHttpSessionMap
          of the associated HttpServletRequest; it is an alternate form of 
          $servletRequest.getParameterMap 
          of the associated HttpServletRequest; it is an alternate form of 
          $servletRequest.getAttributeMap 
          of the associated HttpSession; it is an alternate form of 
          $session.getAttributeSpecial considerations for Velocity
To return a true or false value in Velocity, you script can either be just an expression that returns a boolean value, or the result of evaluating the Velocity template can result in output of "true" or "false". All of the following are valid forms:
    $value < 100(assuming that "someField" contains a boolean
 value)
    $util.contains($value, "some string")
   $record.someField
    $value > $record.otherField
For additional troubleshooting information when Velocity expressions aren't working as expected, set the log category org.apache.Velocity to DEBUG in log4j.isc.config.xml.
Because it's tricky to call arbitrary Java methods in Velocity, the following special objects are passed to Velocity for convenience:
$dataSources.supplyItem refers to the supplyItem DataSource
      object).com.isomorphic.util.DataTools object, giving you access to
                all of that class's useful helper functionsDefault value is null
public java.lang.Boolean stopIfFalse
in the order in which they are defined  even if
 one of the validators has already failed.  However, if stopIfFalse is set,
 validation will not proceed beyond this validator if the check fails. This is useful to prevent expensive validators from being run unnecessarily, or to allow custom validators that don't need to be robust about handling every conceivable type of value.
Default value is false
public java.lang.Boolean exclusive
min or  max values will fail validation.  When setting
 this property, consider also adding a custom message.
 Default value is null
public ValidatorType type
 This can be one of the built-in ValidatorType, the string "custom" to define a custom validator, or
 the string "serverCustom" to define a server-only custom validator.
 
Default value is null
public java.lang.Boolean serverOnly
Default value is null
public java.lang.Boolean clientOnly
Normally, if the server is trying to run validators and finds a validator that it can't execute, for safety reasons validation is considered to have failed. Use this flag to explicitly mark a validator that only needs to run on the client.
Default value is false
public StringMethod condition
ValidatorType, a
 Callback, 
  function, or JavaScript expression to evaluate to see if this validator passes or fails.
  
  Because the validator declaration itself is passed as a parameter to
  condition(), you can effectively parameterize the validator.  For example, to
  create a validator that checks that the value is after a certain date:
 
      { type:"custom", afterDate:new Date(), 
        condition:"value.getTime() > validator.afterDate.getTime()" }
  
  Reusable validators, like the above, can be registered as a standard validatorType by
 calling addValidator().
  
 Note that, if a field is declared with a builtin FieldType,
 the value passed in
  will already have been converted to the specified type, if possible.
  
For the required parameters, see the documentation for ValidatorConditionCallback.
Default value is null
public java.lang.Object min
min value will pass validation.   To
 make a validator-range exclusive, and have equal values fail validation, set  validator.exclusive to true and provide
 a  custom message.
 Default value is null
public ServerObject serverObject
ServerObject declaration that allows
  the Smart GWT Server to find a Java class via a variety of possible approaches, and call a
  method on it to perform validation.
  
  The target object must implement a method whose first 4 arguments are:
  
     Object value, Validator validator, String fieldName, Map record
  
  (com.isomorphic.datasource.Validator is a subclass of Map that 
  represents a validator's configuration, and also provides APIs for implementing templated
  error messages).
  You provide the name of the method to call by specifying 
  methodName
  as part of the serverObject declaration.  If you do not specify a methodName, Smart GWT 
  expects to find a compliant method called "condition".
  
  Additional arguments may be declared and are automatically supplied based on the declared
 argument type, via DMI.  Available objects
 include:
  
Note that "record" will contain only other values submitted at the same time, not the complete DataSource record. For most types of cross-field validation, you should fetch the current saved record. For example:
      final Map existingRecord = dataSource.fetchById(record);
   
 Default value is null
public java.lang.String operationId
operation for the server-side
 uniqueness check. Ignored on the client.
 Default value is null
public java.lang.Object max
max value will pass validation.   To
 make a validator-range exclusive, and have equal values fail validation, set  validator.exclusive to true and provide
 a  custom message.
 Default value is null