com.smartgwt.client.docs.serverds

## Class Validator

- java.lang.Object
- - com.smartgwt.client.docs.serverds.Validator

-     public class Validator
      extends java.lang.Object

  A validator describes a check that should be performed on a value the user is trying to save.

  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. 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.

  See Also:
    `ValidatorType`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `boolean` | `caseSensitive` Applies only to the "isUnique" validator and controls whether the search for existing records is case sensitive or not.
    `java.lang.Boolean` | `clientOnly` Indicates this validator runs on the client only.
    `java.lang.String[]` | `dependentFields` User-defined list of fields on which this validator depends.
    `java.lang.String` | `errorMessage` Text to display if the value does not pass this validation check.
    `java.lang.String` | `serverCondition` For validators of type "serverCustom" only: a scriptlet in any supported JSR223 scripting language which is run in order to see if validation passes.
    `ServerObject` | `serverObject` For validators of type "serverCustom" only, a `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.
    `java.lang.Boolean` | `serverOnly` Indicates this validator runs on the server only.
    `java.lang.Boolean` | `stopIfFalse` Normally, all validators defined for a field will be run even if one of the validators has already failed.
    `java.lang.Boolean` | `stopOnError` Indicates 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` | `type` Type of the validator.
    `java.lang.Boolean` | `validateOnChange` If 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 Summary

    Constructors
    Constructor and Description
    `Validator()`

  - ### Method Summary

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### caseSensitive

          public boolean caseSensitive

      Applies only to the "isUnique" validator and controls whether the search for existing records is case sensitive or not.

      Default value is false

    - #### serverObject

          public ServerObject serverObject

      For validators of type "serverCustom" only, a `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:

      - DataSource - the DataSource where this validator is declared, an instance of com.isomorphic.datasource.DataSource or a subclass
      - HttpServletRequest - from standard Java servlets API
      - HttpServletResponse - from standard Java servlets API
      - ServletContext - from standard Java servlets API
      - HttpSession - from standard Java servlets API
      - RequestContext - an instance of com.isomorphic.servlet.RequestContext
      - RPCManager - the RPCManager associated with the transaction this validation is part of; an instance of com.isomorphic.rpc.RPCManager
      - DSRequest - the DSRequest this validation is part of; an instance of com.isomorphic.datasource.DSRequest
      - DSField - the datasource field which value is validated; an instance of com.isomorphic.datasource.DSField
      - ValidationContext - the context where value is validated; an instance of com.isomorphic.datasource.ValidationContext
      Note that any servlet-related objects will not be available if your validator is run outside of the scope of an HTTP servlet request, such as a command-line process.

      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

    - #### errorMessage

          public java.lang.String errorMessage

      Text to display if the value does not pass this validation check.

      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.

      Default value is null

    - #### validateOnChange

          public java.lang.Boolean validateOnChange

      If true, validator will be validated when each item's "change" handler is fired as well as when the entire form is submitted or validated. If false, this validator will not fire on the item's "change" handler.

      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

    - #### dependentFields

          public java.lang.String[] dependentFields

      User-defined list of fields on which this validator depends. Primarily used for validators of type "custom" but can also be used to supplement `applyWhen` criteria.

      Default value is null

      See Also:
        `com.smartgwt.client.docs.serverds.Validator#applyWhen`

    - #### stopOnError

          public java.lang.Boolean stopOnError

      Indicates 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.

      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

    - #### serverCondition

          public java.lang.String serverCondition

      For validators of type "serverCustom" only: a scriptlet in any supported JSR223 scripting language which is run in order to see if validation passes. For example:

                <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`:

      - dataSource - The current DataSource
      - record - Other submitted values part of the same update
      - value - The value of the field
      - validator - The config of this validator, including all attributes declared on the <validator> tag, presented as a `Map`
      - field - The field (as a `DSField` object)
      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 using the server-side API DataSource.fetchById(). For example, in Velocity:

                $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:

      - servletRequest - The associated `HttpServletRequest`
      - session - The associated `HttpSession`
      - httpParameters - This variable gives you access to the parameters `Map` of the associated `HttpServletRequest`; it is an alternate form of `$servletRequest.getParameter`
      - requestAttributes - This variable gives you access to the attributes `Map` of the associated `HttpServletRequest`; it is an alternate form of `$servletRequest.getAttribute`
      - sessionAttributes - This variable gives you access to the attributes `Map` of the associated `HttpSession`; it is an alternate form of `$session.getAttribute`

      Special 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
      $util.contains($value, "some string")
      $record.someField`(assuming that "someField" contains a boolean value)`
      $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 - The list of all DataSources, accessible by name (so, for example, `$dataSources.supplyItem` refers to the `supplyItem` DataSource object).
      - util - A `com.isomorphic.util.DataTools` object, giving you access to all of that class's useful helper functions

      Default value is null

    - #### stopIfFalse

          public java.lang.Boolean stopIfFalse

      Normally, all validators defined for a field will be run 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

    - #### type

          public ValidatorType type

      Type of the validator.

      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

    - #### serverOnly

          public java.lang.Boolean serverOnly

      Indicates this validator runs on the server only.

      Default value is null

    - #### clientOnly

          public java.lang.Boolean clientOnly

      Indicates this validator runs on the client only.

      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

  - ### Constructor Detail

    - #### Validator

          public Validator()