Изучаем Java EE 7

• @Target({METHOD, FIELD…}) — указывает цель, для которой может использоваться аннотация (подробнее об этом — ниже);

• @Retention(RUNTIME) — определяет, как мы будем обращаться с аннотацией. Необходимо использовать как минимум RUNTIME, чтобы поставщик мог проверять ваш объект во время выполнения;

• @Constraint(validatedBy = NotNullValidator.class) — указывает класс (в случае агрегации ограничений — нуль либо список классов), в котором инкапсулирован валидационный алгоритм;

• @Documented — определяет, будет эта аннотация включена в Javadoc или нет. Опциональная метааннотация.

Поверх этих общих метааннотаций спецификация Bean Validation требует задавать для каждой ограничивающей аннотации три дополнительных атрибута:

• message — обеспечивает для аннотации возможность возвращения интернационализированного сообщения об ошибке, выдаваемого в том случае, если ограничение недопустимо. По умолчанию данный атрибут равен ключу;

• groups — используется для контроля за порядком, в котором интерпретируются ограничения, либо для выполнения частичной валидации;

• payload — применяется для ассоциирования метаинформации с ограничением.

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

Реализация ограничений

Ограничение определяется комбинацией самой аннотации и нуля или более классов реализации. Классы реализации указываются элементом validatedBy в @Constraint (как показано в листинге 3.2). Листинг 3.3 демонстрирует класс реализации для аннотации @NotNull. Как видите, он реализует интерфейс ConstraintValidator и использует дженерики для передачи имени аннотации (NotNull) и типа, к которому применяется аннотация (в данном случае это Object).

Листинг 3.3. Реализация ограничения NotNull

public class NotNullValidator implements ConstraintValidator {

··public void initialize(NotNull parameters) {

··}

··public boolean isValid(Object object, ConstraintValidatorContext context) {

····return object!= null;

··}

}

Интерфейс ConstraintValidator определяет два метода, которые обязательны для реализации конкретными классами.

• initialize — вызывается поставщиком валидации компонентов еще до применения какого-либо ограничения. Именно здесь мы обычно инициализируем любые параметры ограничения, если они имеются.

• isValid — здесь реализуется валидационный алгоритм. Метод интерпретируется поставщиком валидации компонентов всякий раз, когда проверяется конкретное значение. Метод возвращает false, если значение является недопустимым, в противном случае — true. Объект ConstraintValidatorContext несет информацию и операции, доступные в том контексте, к которому применяется ограничение.

Реализация ограничения выполняет валидацию заданной аннотации для указанного типа. В листинге 3.3 ограничение @NotNull типизируется к Object (это означает, что данное ограничение может использоваться с любым типом данных). Но у вас может быть и такая ограничивающая аннотация, которая применяет различные алгоритмы валидации в зависимости от того, об обработке какого типа данных идет речь. Например, вы можете проверять максимальное количество символов для String, максимальное количество знаков для BigDecimal или максимальное количество элементов для Collection. Обратите внимание: в следующей аннотации у нас несколько реализаций одной и той же аннотации (@Size), но она используется с разными типами данных (String, BigDecimal и Collection):

public class SizeValidatorForString·····implements·····{…}

public class SizeValidatorForBigDecimal implements {…}

public class SizeValidatorForCollection implements> {…}

Применение ограничения

Когда у вас есть аннотация и ее реализация, вы можете применять ограничение с элементом заданного типа (атрибут, конструктор, параметр, возвращаемое значение, компонент, интерфейс или аннотация). Это решение, которое разработчик принимает на этапе проектирования и реализует с помощью метааннотации @Target(ElementType.*) (см. листинг 3.2). Существуют следующие типы:

• FIELD — для ограниченных атрибутов;

• METHOD — для ограниченных геттеров и возвращаемых значений ограниченных методов;

• CONSTRUCTOR — для возвращаемых значений ограниченных конструкторов;

• PARAMETER — для параметров ограниченных методов и конструкторов;

• TYPE — для ограниченных компонентов, интерфейсов и суперклассов;

• ANNOTATION_TYPE — для ограничений, состоящих из других ограничений.