Validator

Validator предназначен для проверки значений, введенных в визуальные компоненты.

Валидация и проверка типа входных данных - это разные механизмы. Предположим, что для некоторого компонента (например, textField) установлен тип данных, отличный от строки (это может произойти при привязке к атрибуту сущности или установке datatype). В этом случае без всяких валидаторов компонент не позволит пользователю ввести значение, не соответствующее этому типу данных. Когда компонент теряет фокус или когда пользователь нажимает Enter, отображается уведомление об ошибке.

Фреймворк содержит набор валидаторов, которые можно использовать в проекте.

Обычно валидаторы добавляются компонентам в XML-дескрипторах экранов во вложенном в компонент элементе validators.

Чтобы добавить валидатор для компонента в Jmix Studio, выберите компонент в XML-дескрипторе экрана или на панели иерархии Jmix UI и нажмите кнопку Add на панели инспектора Jmix UI.

Ниже приведен пример добавления валидатора компоненту textField:

add validator

Сообщения об ошибках могут быть указаны при добавлении валидатора компоненту. Если сообщение не задано, используется сообщение по умолчанию. Ниже для каждого валидатора описаны ключи сообщений, используемые фреймворком по умолчанию. Их можно переопределить в своем проекте, определив сообщения с такими же ключами.

Некоторые валидаторы могут иметь параметры в сообщении об ошибке (например, ${value}). Значения таких параметров форматируются в соответствии с локалью текущего пользователя.

Каждый валидатор представляет собой prototype bean, поэтому если необходимо использовать валидаторы в коде Java, их нужно получать с помощью ApplicationContext или ObjectProvider, например:

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

Валидатор можно назначить компоненту программно, передав экземпляр валидатора в метод addValidator() компонента, например:

numberField.addValidator(maxValidator);

DecimalMaxValidator

Данный валидатор проверяет, что значение меньше или равно указанному максимуму. Поддерживаемые типы: BigDecimal, BigInteger, Long, Integer, и String представляющий BigDecimal-значение с текущей локалью.

Он имеет следующие атрибуты:

  • value - максимальное значение (обязательно);

  • inclusive - если установлено значение true, значение должно быть меньше или равно указанному максимальному значению. Если установлено значение false, значение должно быть меньше указанного максимального значения. Значение по умолчанию true;

  • message - сообщение, отображаемое пользователю в случае неудачной проверки. Это сообщение может содержать параметры $value и $max.

Ключи сообщений по умолчанию:

  • validation.constraints.decimalMaxInclusive;

  • validation.constraints.decimalMax.

Использование в XML:

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

Использование в Java:

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

DecimalMinValidator

Данный валидатор проверяет, что значение больше или равно указанному минимуму. Поддерживаемые типы: BigDecimal, BigInteger, Long, Integer, и String представляющий BigDecimal-значение с текущей локалью.

Он имеет следующие атрибуты:

  • value - минимальное значение (обязательно);

  • inclusive - если установлено значение true, значение должно быть больше или равно указанному минимальному значению. Если установлено значение false, значение должно быть больше указанного минимального значения. Значение по умолчанию true;

  • message - сообщение, отображаемое пользователю в случае неудачной проверки. Это сообщение может содержать параметры $value и $max.

Ключи сообщений по умолчанию:

  • validation.constraints.decimalMinInclusive;

  • validation.constraints.decimalMin.

Использование в XML:

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

Использование в Java:

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

DigitsValidator

Данный валидатор проверяет, имеет ли числовое значение указанное число цифр в целой и дробной части. Поддерживаемые типы: BigDecimal, BigInteger, Long, Integer, и String представляющий BigDecimal-значение с текущей локалью.

Он имеет следующие атрибуты:

  • integer - количество цифр в целой части (обязательно);

  • fraction - количество цифр в дробной части (обязательно);

  • message - сообщение, отображаемое пользователю в случае неудачной проверки. Это сообщение может содержать параметры $value, $integer, и $fraction.

Ключ сообщения по умолчанию:

  • validation.constraints.digits.

Использование в 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>

Использование в Java:

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

DoubleMaxValidator

Данный валидатор проверяет, что значение меньше или равно указанному максимуму. Поддерживаемые типы: Double, и представляющий Double значение с текущей локалью.

Он имеет следующие атрибуты:

  • value - максимальное значение (обязательно);

  • inclusive - если установлено значение true, значение должно быть меньше или равно указанному максимальному значению. Если установлено значение false, значение должно быть меньше указанного максимального значения. Значение по умолчанию true;

  • message - сообщение, отображаемое пользователю в случае неудачной проверки. Это сообщение может содержать параметры $value и $max.

Ключи сообщений по умолчанию:

  • validation.constraints.decimalMaxInclusive;

  • validation.constraints.decimalMax.

Использование в XML:

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

Использование в Java:

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

DoubleMinValidator

Данный валидатор проверяет, что значение больше или равно указанному минимуму. Поддерживаемые типы: Double, String представляющие Double значение с текущей локалью.

Он имеет следующие атрибуты:

  • value - минимальное значение (обязательно);

  • inclusive - если установлено значение true, значение должно быть больше или равно указанному минимальному значению. Если установлено значение false, значение должно быть больше указанного минимального значения. Значение по умолчанию true;

  • message - сообщение, отображаемое пользователю в случае неудачной проверки. Это сообщение может содержать параметры $value и $max.

Ключи сообщений по умолчанию:

  • validation.constraints.decimalMinInclusive;

  • validation.constraints.decimalMin.

Использование в XML:

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

Использование в Java:

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

EmailValidator

Валидатор электронной почты проверяет, что строковое значение является адресом электронной почты или содержит несколько адресов электронной почты, разделенных точкой с запятой или запятой. Поддерживаемый тип: String.

Он имеет следующий атрибут:

  • message - сообщение, отображаемое пользователю в случае неудачной проверки.

Ключ сообщения по умолчанию:

  • validation.invalidEmail.

Использование в XML:

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

Использование в Java:

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

FutureOrPresentValidator

Данный валидатор проверяет, что дата и время находятся в будущем или настоящем. Поддерживаемые типы: java.util.Date, LocalDate, LocalDateTime, LocalTime, OffsetDateTime, OffsetTime.

Он имеет следующие атрибуты:

  • checkSeconds - если установлено значение true, валидатор сравнивает дату и время с секундами и миллисекундами. Значение по умолчанию false;

  • message - сообщение, отображаемое пользователю в случае неудачной проверки.

Ключ сообщения по умолчанию:

  • validation.constraints.futureOrPresent.

Использование в XML:

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

Использование в Java:

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

FutureValidator

Данный валидатор проверяет, что дата и время находятся в будущем. Поддерживаемые типы: java.util.Date, LocalDate, LocalDateTime, LocalTime, OffsetDateTime, OffsetTime.

Он имеет следующие атрибуты:

  • checkSeconds - если установлено значение true, валидатор сравнивает дату и время с секундами и миллисекундами. Значение по умолчанию false;

  • message - сообщение, отображаемое пользователю в случае неудачной проверки.

Ключ сообщения по умолчанию:

  • validation.constraints.future.

Использование в XML:

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

Использование в Java:

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

MaxValidator

Данный валидатор проверяет, что значение меньше или равно указанному максимуму. Поддерживаемые типы: BigDecimal, BigInteger, Long, Integer.

Он имеет следующие атрибуты:

  • value - максимальное значение (обязательно);

  • message - сообщение, отображаемое пользователю в случае неудачной проверки. Это сообщение может содержать параметры $value и $max.

Ключ сообщения по умолчанию:

  • validation.constraints.max.

Использование в XML:

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

Использование в Java:

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

MinValidator

Данный валидатор проверяет, что значение больше или равно указанному минимуму. Поддерживаемые типы: BigDecimal, BigInteger, Long, Integer.

Он имеет следующие атрибуты:

  • value - минимальное значение (обязательно);

  • message - сообщение, отображаемое пользователю в случае неудачной проверки. Это сообщение может содержать параметры $value и $min.

Ключ сообщения по умолчанию:

  • validation.constraints.min.

Использование в XML:

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

Использование в Java:

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

NegativeOrZeroValidator

Данный валидатор проверяет, что значение меньше или равно 0. Поддерживаемые типы: BigDecimal, BigInteger, Long, Integer, Double, Float.

Он имеет следующий атрибут:

  • message - сообщение, отображаемое пользователю в случае неудачной проверки. Это сообщение может содержать параметр $value.

Ключ сообщения по умолчанию:

  • validation.constraints.negativeOrZero.

Использование в XML:

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

Использование в Java:

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

NegativeValidator

Данный валидатор проверяет, что значение строго меньше 0. Поддерживаемые типы: BigDecimal, BigInteger, Long, Integer, Double, Float.

Он имеет следующий атрибут:

  • message - сообщение, отображаемое пользователю в случае неудачной проверки. Это сообщение может содержать параметр $value.

Ключ сообщения по умолчанию:

  • validation.constraints.negative.

Использование в XML:

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

Использование в Java:

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

NotBlankValidator

Данный валидатор проверяет, что значение содержит хотя бы один не пробельный символ.Поддерживаемый тип: String.

Он имеет следующий атрибут:

  • message - сообщение, отображаемое пользователю в случае неудачной проверки.

Ключ сообщения по умолчанию:

  • validation.constraints.notBlank.

Использование в XML:

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

Использование в Java:

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

NotEmptyValidator

Данный валидатор проверяет, что значение не равно нулю и не пусто. Поддерживаемые типы: Collection и String.

Он имеет следующий атрибут:

  • message - сообщение, отображаемое пользователю в случае неудачной проверки. Это сообщение может содержать параметр $value, если значение типа String.

Ключ сообщения по умолчанию:

  • validation.constraints.notEmpty.

Использование в XML:

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

Использование в Java:

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

NotNullValidator

Данный валидатор проверяет, что значение не равно нулю.

Ключ сообщения по умолчанию:

  • message - сообщение, отображаемое пользователю в случае неудачной проверки.

Ключ сообщения по умолчанию:

  • validation.constraints.notNull.

Использование в XML:

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

Использование в Java:

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

PastOrPresentValidator

Данный валидатор проверяет, что дата и время находятся в прошлом или настоящем. Поддерживаемые типы: java.util.Date, LocalDate, LocalDateTime, LocalTime, OffsetDateTime, OffsetTime.

Он имеет следующие атрибуты:

  • checkSeconds - при установке значения true валидатор сравнивает дату и время с секундами и миллисекундами. Значение по умолчанию false;

  • message - сообщение, отображаемое пользователю в случае неудачной проверки.

Ключ сообщения по умолчанию:

  • validation.constraints.pastOrPresent.

Использование в XML:

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

Использование в Java:

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

PastValidator

Данный валидатор проверяет, что дата и время находятся в прошлом. Поддерживаемые типы: java.util.Date, LocalDate, LocalDateTime, LocalTime, OffsetDateTime, OffsetTime.

Он имеет следующие атрибуты:

  • checkSeconds - если установлено значение true, валидатор сравнивает дату и время с секундами и миллисекундами. Значение по умолчанию false;

  • message - сообщение, отображаемое пользователю в случае неудачной проверки.

Ключ сообщения по умолчанию:

  • validation.constraints.past.

Использование в XML:

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

Использование в Java:

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

PositiveOrZeroValidator

Данный валидатор проверяет, что значение больше или равно 0. Поддерживаемые типы: BigDecimal, BigInteger, Long, Integer, Double, Float.

Он имеет следующий атрибут:

  • message - сообщение, отображаемое пользователю в случае неудачной проверки. Это сообщение может содержать параметр $value.

Ключ сообщения по умолчанию:

  • validation.constraints.positiveOrZero.

Использование в XML:

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

Использование в Java:

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

PositiveValidator

Данный валидатор проверяет, что значение строго больше 0. Поддерживаемые типы: BigDecimal, BigInteger, Long, Integer, Double, Float.

Он имеет следующий атрибут:

  • message - сообщение, отображаемое пользователю в случае неудачной проверки. Это сообщение может содержать параметр $value.

Ключ сообщения по умолчанию:

  • validation.constraints.positive.

Использование в XML:

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

Использование в Java:

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

RegexpValidator

Данный валидатор проверяет, соответствует ли строковое значение указанному регулярному выражению. Поддерживаемый тип: String.

Он имеет следующие атрибуты:

  • regexp - регулярное выражение (обязательно);

  • message - сообщение, отображаемое пользователю в случае неудачной проверки. Это сообщение может содержать параметр $value.

Ключ сообщения по умолчанию:

  • validation.constraints.regexp.

Использование в XML:

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

Использование в Java:

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

SizeValidator

Данный валидатор проверяет, находится ли длина строки или размер коллекции в определенном диапазоне. Поддерживаемые типы: Collection и String.

Он имеет следующие атрибуты:

  • min - минимальное значение (включительно) не может быть меньше 0. Значение по умолчанию 0;

  • max - максимальное значение (включительно), не может быть меньше 0. Значение по умолчанию Integer.MAX_VALUE;

  • message - сообщение, отображаемое пользователю в случае неудачной проверки. Это сообщение может содержать параметры $value (только для типа String), $min, $max.

Ключи сообщений по умолчанию:

  • validation.constraints.collectionSizeRange;

  • validation.constraints.sizeRange.

Использование в 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>

Использование в Java:

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

Создание собственных валидаторов

Собственный валидатор можно определить в бине-прототипе, реализующем интерфейс Validator.

Пример создания валидатора для почтовых индексов:

@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");
    }
}

В XML-дескрипторе экрана пользовательский валидатор используется во вложенном элементе custom:

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

Валидатор может быть также задан лямбдой и добавлен программно, например:

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