JPA –Custom Validation Contraints

The Java Validation API contains numerous annotations used for validation as I have written before about it. Provided annotations can never cover all the cases  developer might need so in this tutorial I will cover the concept of creating custom annotations and validation constraints using JPA Entities.

I will create an example  that will validate entity property userName and insure that username holds only letters.

@UserName Validation Constraint

Creating validation constraint has two steps, first you must create annotation and then constrain validator.

Annotation must bi annotated with several other annotations.

@Target specifies what elements can be annotated, if missing then all elements can be annotated with in this case @UserName annotation. Possible values are from docs

  • ElementType.TYPE, Class, interface (including annotation type), or enum declaration
  • ElementType.FIELD, Field declaration (includes enum constants)
  • ElementType.METHOD, Method declaration
  • ElementType.PARAMETER, Formal parameter declaration
  • ElementType.CONSTRUCTOR, Constructor declaration
  • ElementType.LOCAL_VARIABLE, Local variable declaration
  • ElementType.ANNOTATION_TYPE, Annotation type declaration
  • ElementType.PACKAGE, Package declaration
  • ElementType.TYPE_PARAMETER, Type parameter declaration (@since 1.8)
  • ElementType.TYPE_USE, Use of a type @since 1.8

@Retention, defines how long annotations are supposed to be retained. There ares several retention policies

  • SOURCE, annotations are used only in source and are discarded after compilation
  • CLASS, annotations are discarted on class load and are usefull for bytecode-level post processing . This is default option.
  • RUNTIME, annotations survive compilations and class loading and of course are available for reflection at runtime. Of course I pick this value because validation is done in runtime when validation is being invoked.

@Constraint, belongs to Java Validation API and helps specify class that is used to validate the value( like userName).

Groups and payload are required by validation api and message is mandatory.


ConstrainValidator implementsConstraintValidator that has two methods initialize and isValid and also two type parameters annotation and value that is to be validated. It does not do much it just checks if username consists of all letters :).

How to use custom validation constraint for your Entity?

Here is the part of Entity called User

What happens when someone tries to create entity with wrong value?

Exception ConstraintViolationException is thrown with specified message


Is it easy to create your own constraint that will be applied on type User

  1. Create annotation with @Target=ElementType.TYPE
  2. @Constraint(validatedBy = YourOwnValidator.class)
  3. YourOwnValidator implements ConstraintValidator<YourOwnAnnotation,User>

Happy coding.

JPA – Validation Contraints

JPA comes with few default constraints that help validate entity properties.

@Null and @NotNull

Force property to be null or !null.

Accepts any type.

@AssertFalse and @AssertTrue

Force value of the property to false or true.

Accepts Boolean type.

@DecimalMax, @DecimalMin and @Digits

Decimal min and max force the property to be in the specified range. Digits forces the property to be of the specified format.

Accepts BigDecimal, BigInteger, CharSequence, byte, short, int, long with their respective wrappers

@Past and @Future

Force property to be in the correct time frame.

Accepts  java.util.Date and java.util.Calendar types.

note: null is considered valid

@Min, @Max

Force the property value to be in the correct number range.

Accepts BigDecimal, BigInteger, byte, short, int, long, with their respective wrappers


Forces the property value to be of specified pattern.

Accepts CharSequence type.


Forces the property value to be in the specified length range.

Accepts types of

  • CharSequence (length of character sequence is evaluated)
  • Collection (collection size is evaluated)
  • Map (map size is evaluated)
  • Array (array length is evaluated)