Validator (Smart GWT EE API 4.0p (2021-05-01))

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

```
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). See com.smartgwt.client.docs.serverds for how to use this documentation.
A validator describes a check that should be performed on a value the user is trying to save.
Validators are specified for DataSource fields via the 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 Validator.addValidator method.

See Also:
ValidatorType

Field Summary

Fields
Modifier and Type	Field and Description
`java.lang.Boolean`	`clientOnly` Indicates this validator runs on the client only.
`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()

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
  - 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
  - serverOnly
```
public java.lang.Boolean serverOnly
```
    Indicates this validator runs on the server only.
    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
  - 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 stopOnError if unset.
    Enabling this property also implies validateOnExit is automatically enabled. If this is a server-based validator, setting this property also implies that synchronousValidation is forced on.
    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
  - 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
    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.
    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
  - 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
  - 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
- Constructor Detail
  - Validator
```
public Validator()
```

Class Validator

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

stopIfFalse

serverOnly

errorMessage

stopOnError

clientOnly

serverObject

validateOnChange

serverCondition

type

Constructor Detail

Validator