Validator

Validator is designed to check values entered into visual components.

Validation and input type checking are different mechanisms. Suppose a given component (for example, textField) data type is set to something different from string (this can happen when binding to an entity attribute or setting datatype). Then without any validator, the component will not allow the user to enter a value that does not comply with this data type. When the component loses focus or when the user presses Enter, the error notification will be shown.

The framework contains a set of validators that can be used in your project.

Usually, validators are added to components in view XML descriptors using the validators element nested in the component element.

To add a validator to a component in Jmix Studio, select the component in the view XML descriptor or in the Jmix UI hierarchy panel and click on the Add button in the Jmix UI inspector panel.

Below is an example of adding a validator to the textField component:

add validator

Error messages can be specified when adding a validator to a component. If the message is not set, the default message is used. Below for each validator we describe message keys used by the framework to get default messages. You can override them in your project by defining messages with the same keys.

Some validators can have parameters in the error message (for example, ${value}). The parameter values are formatted according to the current user locale.

Standard validators are defined by prototype beans, so if you need to create them in Java, use ApplicationContext or ObjectProvider. For example:

DecimalMaxValidator maxValidator = applicationContext
        .getBean(DecimalMaxValidator.class, new BigDecimal(1000));
numberField.addValidator(maxValidator);

DecimalMaxValidator

Checks that value is less than or equal to the specified maximum. Supported types: BigDecimal, BigInteger, Long, Integer, and String that represents BigDecimal value with the current locale.

It has the following attributes:

  • value - maximum value (required);

  • inclusive - when set to true, the value should be less than or equal to the specified maximum value. When set to false, the value should be less than the specified maximum value. The default value is true;

  • message - a custom message displayed to a user when validation fails. This message can contain $value and $max parameters.

Default message keys:

  • validation.constraints.decimalMaxInclusive;

  • validation.constraints.decimalMax.

Usage in XML:

<textField id="numberField" datatype="decimal">
    <validators>
        <decimalMax value="1000"
                    inclusive="true"
                    message="Value ${value} cannot be greater than ${max}"/>
    </validators>
</textField>

Usage in Java:

DecimalMaxValidator maxValidator = applicationContext
        .getBean(DecimalMaxValidator.class, new BigDecimal(1000));
numberField.addValidator(maxValidator);

DecimalMinValidator

Checks that value is greater than or equal to the specified minimum. Supported types: BigDecimal, BigInteger, Long, Integer, and String that represents BigDecimal value with the current locale.

It has the following attributes:

  • value - minimum value (required);

  • inclusive - when set to true, the value should be greater than or equal to the specified minimum value. When set to false, the value should be greater than the specified minimum value. The default value is true;

  • message - a custom message displayed to a user when validation fails. This message can contain $value and $max parameters.

Default message keys:

  • validation.constraints.decimalMinInclusive;

  • validation.constraints.decimalMin.

Usage in XML:

<textField id="decimalField" datatype="decimal">
    <validators>
        <decimalMin value="100"
                    inclusive="false"
                    message="Value ${value} cannot be less than ${min}"/>
    </validators>
</textField>

Usage in Java:

DecimalMinValidator minValidator = applicationContext
        .getBean(DecimalMinValidator.class, new BigDecimal(100));
decimalField.addValidator(minValidator);

DigitsValidator

Checks that the numeric value has specified number of digits in its integer and fractional parts. Supported types: BigDecimal, BigInteger, Long, Integer, and String that represents BigDecimal value with the current locale.

It has the following attributes:

  • integer - number of digits in the integer part (required);

  • fraction - number of digits in the fraction part (required);

  • message - a custom message displayed to a user when validation fails. This message can contain $value, $integer, and $fraction parameters.

Default message key:

  • validation.constraints.digits.

Usage in XML:

<textField id="digitsField">
    <validators>
        <digits fraction="2"
                integer="3"
                message="Value ${value} is out of bounds (${integer}
                digits are expected in integer part and ${fraction}
                in fractional part)"/>
    </validators>
</textField>

Usage in Java:

DigitsValidator digitsValidator = applicationContext
        .getBean(DigitsValidator.class, 3, 2);
digitsField.addValidator(digitsValidator);

DoubleMaxValidator

Checks that value is less than or equal to the specified maximum. Supported types: Double, and String that represents Double value with the current locale.

It has the following attributes:

  • value - maximum value (required);

  • inclusive - when set to true, the value should be less than or equal to the specified maximum value. When set to false, the value should be less than the specified maximum value. The default value is true;

  • message - a custom message displayed to a user when validation fails. This message can contain $value and $max parameters.

Default message keys:

  • validation.constraints.decimalMaxInclusive;

  • validation.constraints.decimalMax.

Usage in XML:

<textField id="doubleMaxField" datatype="double">
    <validators>
        <doubleMax value="1000"
                   inclusive="false"
                   message="Value ${value} cannot be greater than ${max}"/>
    </validators>
</textField>

Usage in Java:

DoubleMaxValidator maxValidator = applicationContext
        .getBean(DoubleMaxValidator.class, 1000.0);
doubleMaxField.addValidator(maxValidator);

DoubleMinValidator

Checks that value is greater than or equal to the specified minimum. Supported types: Double, and String that represents Double value with the current locale.

It has the following attributes:

  • value - minimum value (required);

  • inclusive - when set to true, the value should be greater than or equal to the specified minimum value. When set to false, the value should be greater than the specified minimum value. The default value is true;

  • message - a custom message displayed to a user when validation fails. This message can contain $value and $min keys for formatted output.

Default message keys:

  • validation.constraints.decimalMinInclusive;

  • validation.constraints.decimalMin.

Usage in XML:

<textField id="doubleMinField" datatype="double">
    <validators>
        <doubleMin value="100"
                   inclusive="false"
                   message="Value ${value} cannot be less than ${min}"/>
    </validators>
</textField>

Usage in Java:

DoubleMinValidator minValidator = applicationContext
        .getBean(DoubleMinValidator.class, 100.0);
doubleMinField.addValidator(minValidator);

EmailValidator

Email validator checks that String value is email or contains multiple emails separated by a semicolon or a comma. Supported type: String.

It has the following attribute:

  • message - a custom message displayed to a user when validation fails.

Default message key:

  • validation.invalidEmail.

Usage in XML:

<textField id="emailField" datatype="string">
    <validators>
        <email message="Invalid email address"/>
    </validators>
</textField>

Usage in Java:

EmailValidator emailValidator = applicationContext
        .getBean(EmailValidator.class);
emailField.addValidator(emailValidator);

FutureOrPresentValidator

Checks that the date and time is in the future or present. Supported types: java.util.Date, LocalDate, LocalDateTime, LocalTime, OffsetDateTime, OffsetTime.

It has the following attributes:

  • checkSeconds - when set to true, the validator compares date and time with seconds and milliseconds. The default value is false;

  • message - a custom message displayed to a user when validation fails.

Default message key:

  • validation.constraints.futureOrPresent.

Usage in XML:

<timePicker datatype="localTime" id="futureField">
    <validators>
        <futureOrPresent checkSeconds="true"/>
    </validators>
</timePicker>

Usage in Java:

FutureOrPresentValidator futureOrPresentValidator = applicationContext
        .getBean(FutureOrPresentValidator.class);
futureField.addValidator(futureOrPresentValidator);

FutureValidator

Checks that the date and time is in the future. Supported types: java.util.Date, LocalDate, LocalDateTime, LocalTime, OffsetDateTime, OffsetTime.

It has the following attributes:

  • checkSeconds - when set to true, the validator compares date and time with seconds and milliseconds. The default value is false;

  • message - a custom message displayed to a user when validation fails.

Default message key:

  • validation.constraints.future.

Usage in XML:

<timePicker datatype="localTime" id="timeField">
    <validators>
        <future checkSeconds="true"/>
    </validators>
</timePicker>

Usage in Java:

FutureValidator futureValidator = applicationContext
        .getBean(FutureValidator.class);
timeField.addValidator(futureValidator);

MaxValidator

Checks that value is less than or equal to the specified maximum. Supported types: BigDecimal, BigInteger, Long, Integer.

It has the following attributes:

  • value - maximum value (required);

  • message - a custom message displayed to a user when validation fails. This message can contain the $value and $max parameters.

Default message key:

  • validation.constraints.max.

Usage in XML:

<textField id="maxField" datatype="int">
    <validators>
        <max value="20500"
             message="Value ${value} must be less than or equal to ${max}"/>
    </validators>
</textField>

Usage in Java:

MaxValidator maxValidator = applicationContext
        .getBean(MaxValidator.class, 20500);
maxField.addValidator(maxValidator);

MinValidator

Checks that value is greater than or equal to the specified minimum. Supported types: BigDecimal, BigInteger, Long, Integer.

It has the following attributes:

  • value - minimum value (required);

  • message - a custom message displayed to a user when validation fails. This message can contain the $value, and $min parameters.

Default message key:

  • validation.constraints.min.

Usage in XML:

<textField id="minField" datatype="int">
    <validators>
        <min value="30"
             message="Value ${value} must be greater than or equal to ${min}"/>
    </validators>
</textField>

Usage in Java:

MinValidator minValidator = applicationContext
        .getBean(MinValidator.class, 30);
minField.addValidator(minValidator);

NegativeOrZeroValidator

Checks that value is less than or equal 0. Supported types: BigDecimal, BigInteger, Long, Integer, Double, Float.

It has the following attribute:

  • message - a custom message displayed to a user when validation fails. The message can contain the $value parameter.

Default message key:

  • validation.constraints.negativeOrZero.

Usage in XML:

<textField id="negativeOrZeroField" datatype="int">
    <validators>
        <negativeOrZero message="Value ${value} must be less than or equal to 0"/>
    </validators>
</textField>

Usage in Java:

NegativeOrZeroValidator negativeOrZeroValidator = applicationContext
        .getBean(NegativeOrZeroValidator.class);
negativeOrZeroField.addValidator(negativeOrZeroValidator);

NegativeValidator

Checks that value is strictly less than 0. Supported types: BigDecimal, BigInteger, Long, Integer, Double, Float.

It has the following attribute:

  • message - a custom message displayed to a user when validation fails. The message can contain the $value parameter.

Default message key:

  • validation.constraints.negative.

Usage in XML:

<textField id="negativeField" datatype="int">
    <validators>
        <negative message="Value ${value} must be less than 0"/>
    </validators>
</textField>

Usage in Java:

NegativeValidator negativeValidator = applicationContext
        .getBean(NegativeValidator.class);
negativeField.addValidator(negativeValidator);

NotBlankValidator

Checks that value contains at least one non-whitespace character. Supported type: String.

It has the following attribute:

  • message - a custom message displayed to a user when validation fails.

Default message key:

  • validation.constraints.notBlank.

Usage in XML:

<textField id="notBlankField">
    <validators>
        <notBlank message="Value must contain at least one non-whitespace character"/>
    </validators>
</textField>

Usage in Java:

NotBlankValidator notBlankValidator = applicationContext
        .getBean(NotBlankValidator.class);
notBlankField.addValidator(notBlankValidator);

NotEmptyValidator

Checks that value is not null and not empty. Supported types: Collection and String.

It has the following attribute:

  • message - a custom message displayed to a user when validation fails. This message can contain the $value parameter if the value is of String type.

Default message key:

  • validation.constraints.notEmpty.

Usage in XML:

<textField id="notEmptyField">
    <validators>
        <notEmpty/>
    </validators>
</textField>

Usage in Java:

NotEmptyValidator notEmptyValidator = applicationContext
        .getBean(NotEmptyValidator.class);
notEmptyField.addValidator(notEmptyValidator);

NotNullValidator

Checks that value is not null.

It has the following attribute:

  • message - a custom message displayed to a user when validation fails.

Default message key:

  • validation.constraints.notNull.

Usage in XML:

<textField id="notNullField">
    <validators>
        <notNull/>
    </validators>
</textField>

Usage in Java:

NotNullValidator notNullValidator = applicationContext
        .getBean(NotNullValidator.class);
notNullField.addValidator(notNullValidator);

PastOrPresentValidator

Checks that the date and time is in the past or present. Supported types: java.util.Date, LocalDate, LocalDateTime, LocalTime, OffsetDateTime, OffsetTime.

It has the following attributes:

  • checkSeconds - when setting to true, the validator compares date and time with seconds and milliseconds. The default value is false;

  • message - a custom message displayed to a user when validation fails.

Default message key:

  • validation.constraints.pastOrPresent.

Usage in XML:

<datePicker id="pastOrPresentField">
    <validators>
        <pastOrPresent checkSeconds="true"/>
    </validators>
</datePicker>

Usage in Java:

PastOrPresentValidator pastOrPresentValidator = applicationContext
        .getBean(PastOrPresentValidator.class);
pastOrPresentField.addValidator(pastOrPresentValidator);

PastValidator

Checks that the date and time is in the past. Supported types: java.util.Date, LocalDate, LocalDateTime, LocalTime, OffsetDateTime, OffsetTime.

It has the following attributes:

  • checkSeconds - when set to true, the validator compares date and time with seconds and milliseconds. The default value is false;

  • message - a custom message displayed to a user when validation fails.

Default message key:

  • validation.constraints.past.

Usage in XML:

<datePicker id="pastField">
    <validators>
        <past/>
    </validators>
</datePicker>

Usage in Java:

PastValidator pastValidator = applicationContext
        .getBean(PastValidator.class);
pastField.addValidator(pastValidator);

PositiveOrZeroValidator

Checks that value is greater than or equal to 0. Supported types: BigDecimal, BigInteger, Long, Integer, Double, Float.

It has the following attribute:

  • message - a custom message displayed to a user when validation fails. The message can contain the $value parameter.

Default message key:

  • validation.constraints.positiveOrZero.

Usage in XML:

<textField id="positiveOrZeroField" datatype="int">
    <validators>
        <positiveOrZero message="Value ${value} should be greater than or equal to '0'"/>
    </validators>
</textField>

Usage in Java:

PositiveOrZeroValidator positiveOrZeroValidator = applicationContext
        .getBean(PositiveOrZeroValidator.class);
positiveOrZeroField.addValidator(positiveOrZeroValidator);

PositiveValidator

Checks that value is strictly greater than 0. Supported types: BigDecimal, BigInteger, Long, Integer, Double, Float.

It has the following attribute:

  • message - a custom message displayed to a user when validation fails. This message can contain the $value parameter.

Default message key:

  • validation.constraints.positive.

Usage in XML:

<textField id="positiveField" datatype="int">
    <validators>
        <positive message="Value ${value} should be greater than '0'"/>
    </validators>
</textField>

Usage in Java:

PositiveValidator positiveValidator = applicationContext
        .getBean(PositiveValidator.class);
positiveField.addValidator(positiveValidator);

RegexpValidator

Checks that the String value matches the specified regular expression. Supported type: String.

It has the following attributes:

  • regexp - a regular expression to match (required);

  • message - a custom message displayed to a user when validation fails. This message can contain the $value parameter.

Default message key:

  • validation.constraints.regexp.

Usage in XML:

<textField id="regexpField">
    <validators>
        <regexp regexp="[a-z]*"/>
    </validators>
</textField>

Usage in Java:

RegexpValidator regexpValidator = applicationContext
        .getBean(RegexpValidator.class,"[a-z]*");
regexpField.addValidator(regexpValidator);

SizeValidator

Checks that string length or collection size is in the specified range. Supported types: Collection and String.

It has the following attributes:

  • min - a minimum value (with inclusive), cannot be less than 0. The default value is 0;

  • max - a maximum value (with inclusive), cannot be less than 0. The default value is Integer.MAX_VALUE;

  • message - a custom message displayed to a user when validation fails. This message can contain the $value (only for the String type), $min, $max parameters.

Default message keys:

  • validation.constraints.collectionSizeRange;

  • validation.constraints.sizeRange.

Usage in XML:

<textField id="sizeField">
    <validators>
        <size max="10"
              min="2"
              message="Value ${value} should be between ${min} and ${max}"/>
    </validators>
</textField>
<multiSelectComboBox id="sizeComboBox"
                     itemsEnum="com.company.onboarding.entity.OnboardingStatus">
    <validators>
        <size max="4"
              min="2"
              message="Collection size must be between ${min} and ${max}"/>
    </validators>
</multiSelectComboBox>

Usage in Java:

SizeValidator sizeValidator = applicationContext
        .getBean(SizeValidator.class);
sizeField.addValidator(sizeValidator);

Creating Custom Validators

A custom validator can be defined by a prototype bean implementing the Validator interface.

Example of creating a validator for zip codes:

@Component
@Scope(BeanDefinition.SCOPE_PROTOTYPE)
public class ZipValidator implements Validator<String> {
    @Override
    public void accept(String value) throws ValidationException {
        if (value != null && value.length() != 6)
            throw new ValidationException("Zip must be of 6 characters length");
    }
}

In a view XML descriptor, the custom validator should be defined in the nested custom element. For example:

<textField id="zipField" datatype="string">
    <validators>
        <custom bean="zipValidator"/>
    </validators>
</textField>

A validator can also be defined by a lambda and added programmatically, for example:

zipField.addValidator(value -> {
    if (value != null && value.length() != 6)
        throw new ValidationException("Zip must be of 6 characters length");
});