Introduction

Hibernate Validator provides powerful validation capabilities beyond the standard Bean Validation API. Custom constraints allow you to define domain-specific validation rules, complex business logic validations, and cross-field validations that aren't possible with built-in constraints.

Key Concepts

Custom Validation Components

• Constraint Annotation - Defines the validation contract
• Constraint Validator - Implements the validation logic
• Constraint Payload - Carries metadata for validation
• Groups - Organize validations by context
• Message Interpolation - Custom error messages

Dependencies

Maven Dependencies

<properties> <hibernate.validator.version>8.0.1.Final</hibernate.validator.version> <validation.api.version>3.0.2</validation.api.version> </properties> <dependencies> <!-- Bean Validation API --> <dependency> <groupId>jakarta.validation</groupId> <artifactId>jakarta.validation-api</artifactId> <version>${validation.api.version}</version> </dependency> <!-- Hibernate Validator --> <dependency> <groupId>org.hibernate.validator</groupId> <artifactId>hibernate-validator</artifactId> <version>${hibernate.validator.version}</version> </dependency> <!-- Expression Language (required for Hibernate Validator) --> <dependency> <groupId>org.glassfish</groupId> <artifactId>jakarta.el</artifactId> <version>4.0.2</version> </dependency> </dependencies>

Basic Custom Constraint

1. Simple Custom Constraint Annotation

package com.example.validation.constraints; import com.example.validation.validators.StrongPasswordValidator; import jakarta.validation.Constraint; import jakarta.validation.Payload; import java.lang.annotation.*; @Documented @Constraint(validatedBy = StrongPasswordValidator.class) @Target({ ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE }) @Retention(RetentionPolicy.RUNTIME) public @interface StrongPassword { String message() default "Password must be strong"; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; // Custom parameters int minLength() default 8; boolean requireUppercase() default true; boolean requireLowercase() default true; boolean requireDigits() default true; boolean requireSpecialChars() default true; // For multiple constraints of the same type @Target({ ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE }) @Retention(RetentionPolicy.RUNTIME) @Documented @interface List { StrongPassword[] value(); } }

2. Constraint Validator Implementation

package com.example.validation.validators; import com.example.validation.constraints.StrongPassword; import jakarta.validation.ConstraintValidator; import jakarta.validation.ConstraintValidatorContext; public class StrongPasswordValidator implements ConstraintValidator<StrongPassword, String> { private int minLength; private boolean requireUppercase; private boolean requireLowercase; private boolean requireDigits; private boolean requireSpecialChars; @Override public void initialize(StrongPassword constraintAnnotation) { this.minLength = constraintAnnotation.minLength(); this.requireUppercase = constraintAnnotation.requireUppercase(); this.requireLowercase = constraintAnnotation.requireLowercase(); this.requireDigits = constraintAnnotation.requireDigits(); this.requireSpecialChars = constraintAnnotation.requireSpecialChars(); } @Override public boolean isValid(String password, ConstraintValidatorContext context) { if (password == null || password.trim().isEmpty()) { return true; // Use @NotNull for null validation } // Build validation messages StringBuilder message = new StringBuilder(); boolean isValid = true; if (password.length() < minLength) { message.append("Password must be at least ").append(minLength).append(" characters long. "); isValid = false; } if (requireUppercase && !password.matches(".*[A-Z].*")) { message.append("Password must contain at least one uppercase letter. "); isValid = false; } if (requireLowercase && !password.matches(".*[a-z].*")) { message.append("Password must contain at least one lowercase letter. "); isValid = false; } if (requireDigits && !password.matches(".*\\d.*")) { message.append("Password must contain at least one digit. "); isValid = false; } if (requireSpecialChars && !password.matches(".*[!@#$%^&*()_+\\-=\\[\\]{};':\"\\\\|,.<>\\/?].*")) { message.append("Password must contain at least one special character. "); isValid = false; } if (!isValid) { context.disableDefaultConstraintViolation(); context.buildConstraintViolationWithTemplate(message.toString().trim()) .addConstraintViolation(); } return isValid; } }

Advanced Custom Constraints

1. Cross-Field Validation

package com.example.validation.constraints; import com.example.validation.validators.FieldsValueMatchValidator; import jakarta.validation.Constraint; import jakarta.validation.Payload; import java.lang.annotation.*; @Documented @Constraint(validatedBy = FieldsValueMatchValidator.class) @Target({ ElementType.TYPE }) @Retention(RetentionPolicy.RUNTIME) public @interface FieldsValueMatch { String message() default "Fields values don't match"; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; String field(); String fieldMatch(); // Custom message for each field String fieldMessage() default ""; String fieldMatchMessage() default ""; @Target({ ElementType.TYPE }) @Retention(RetentionPolicy.RUNTIME) @interface List { FieldsValueMatch[] value(); } }

2. Cross-Field Validator

package com.example.validation.validators; import com.example.validation.constraints.FieldsValueMatch; import jakarta.validation.ConstraintValidator; import jakarta.validation.ConstraintValidatorContext; import org.springframework.beans.BeanWrapperImpl; public class FieldsValueMatchValidator implements ConstraintValidator<FieldsValueMatch, Object> { private String field; private String fieldMatch; private String fieldMessage; private String fieldMatchMessage; @Override public void initialize(FieldsValueMatch constraintAnnotation) { this.field = constraintAnnotation.field(); this.fieldMatch = constraintAnnotation.fieldMatch(); this.fieldMessage = constraintAnnotation.fieldMessage(); this.fieldMatchMessage = constraintAnnotation.fieldMatchMessage(); } @Override public boolean isValid(Object value, ConstraintValidatorContext context) { if (value == null) { return true; } Object fieldValue = new BeanWrapperImpl(value).getPropertyValue(field); Object fieldMatchValue = new BeanWrapperImpl(value).getPropertyValue(fieldMatch); boolean isValid = fieldValue != null && fieldValue.equals(fieldMatchValue); if (!isValid) { context.disableDefaultConstraintViolation(); // Build custom constraint violations for specific fields if (!fieldMessage.isEmpty()) { context.buildConstraintViolationWithTemplate(fieldMessage) .addPropertyNode(field) .addConstraintViolation(); } if (!fieldMatchMessage.isEmpty()) { context.buildConstraintViolationWithTemplate(fieldMatchMessage) .addPropertyNode(fieldMatch) .addConstraintViolation(); } // Default message if (fieldMessage.isEmpty() && fieldMatchMessage.isEmpty()) { context.buildConstraintViolationWithTemplate(context.getDefaultConstraintMessageTemplate()) .addPropertyNode(fieldMatch) .addConstraintViolation(); } } return isValid; } }

3. Date/Time Validation

package com.example.validation.constraints; import com.example.validation.validators.FutureAfterValidator; import jakarta.validation.Constraint; import jakarta.validation.Payload; import java.lang.annotation.*; import java.time.temporal.ChronoUnit; @Documented @Constraint(validatedBy = FutureAfterValidator.class) @Target({ ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE }) @Retention(RetentionPolicy.RUNTIME) public @interface FutureAfter { String message() default "Date must be in the future after the specified duration"; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; int amount() default 0; ChronoUnit unit() default ChronoUnit.DAYS; boolean inclusive() default false; @Target({ ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE }) @Retention(RetentionPolicy.RUNTIME) @Documented @interface List { FutureAfter[] value(); } }

4. Date/Time Validator

package com.example.validation.validators; import com.example.validation.constraints.FutureAfter; import jakarta.validation.ConstraintValidator; import jakarta.validation.ConstraintValidatorContext; import java.time.LocalDate; import java.time.LocalDateTime; import java.time.temporal.ChronoUnit; import java.util.Date; public class FutureAfterValidator implements ConstraintValidator<FutureAfter, Object> { private int amount; private ChronoUnit unit; private boolean inclusive; @Override public void initialize(FutureAfter constraintAnnotation) { this.amount = constraintAnnotation.amount(); this.unit = constraintAnnotation.unit(); this.inclusive = constraintAnnotation.inclusive(); } @Override public boolean isValid(Object value, ConstraintValidatorContext context) { if (value == null) { return true; // Use @NotNull for null validation } java.time.temporal.Temporal now = getNow(); java.time.temporal.Temporal targetDate = getTargetDate(value); java.time.temporal.Temporal minimumDate = now.plus(amount, unit); if (inclusive) { return !targetDate.isBefore(minimumDate); } else { return targetDate.isAfter(minimumDate); } } private java.time.temporal.Temporal getNow() { return LocalDateTime.now(); } private java.time.temporal.Temporal getTargetDate(Object value) { if (value instanceof LocalDate) { return ((LocalDate) value).atStartOfDay(); } else if (value instanceof LocalDateTime) { return (LocalDateTime) value; } else if (value instanceof Date) { return ((Date) value).toInstant().atZone(java.time.ZoneId.systemDefault()).toLocalDateTime(); } else { throw new IllegalArgumentException("Unsupported date type: " + value.getClass()); } } }

Business Logic Validations

1. Unique Email Constraint

package com.example.validation.constraints; import com.example.validation.validators.UniqueEmailValidator; import jakarta.validation.Constraint; import jakarta.validation.Payload; import java.lang.annotation.*; @Documented @Constraint(validatedBy = UniqueEmailValidator.class) @Target({ ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE }) @Retention(RetentionPolicy.RUNTIME) public @interface UniqueEmail { String message() default "Email already exists"; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; String excludeId() default ""; @Target({ ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE }) @Retention(RetentionPolicy.RUNTIME) @Documented @interface List { UniqueEmail[] value(); } }

2. Unique Email Validator with Service Integration

package com.example.validation.validators; import com.example.service.UserService; import com.example.validation.constraints.UniqueEmail; import jakarta.validation.ConstraintValidator; import jakarta.validation.ConstraintValidatorContext; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Component; @Component public class UniqueEmailValidator implements ConstraintValidator<UniqueEmail, String> { @Autowired private UserService userService; private String excludeId; @Override public void initialize(UniqueEmail constraintAnnotation) { this.excludeId = constraintAnnotation.excludeId(); } @Override public boolean isValid(String email, ConstraintValidatorContext context) { if (email == null || email.trim().isEmpty()) { return true; // Use @NotNull for null validation } boolean emailExists = userService.emailExists(email); if (excludeId != null && !excludeId.trim().isEmpty()) { // For update operations, exclude current entity Long currentId = Long.parseLong(excludeId); boolean isOwnEmail = userService.isEmailOwnedByUser(email, currentId); return !emailExists || isOwnEmail; } return !emailExists; } }

3. Valid Phone Number Constraint

package com.example.validation.constraints; import com.example.validation.validators.ValidPhoneNumberValidator; import jakarta.validation.Constraint; import jakarta.validation.Payload; import java.lang.annotation.*; @Documented @Constraint(validatedBy = ValidPhoneNumberValidator.class) @Target({ ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE }) @Retention(RetentionPolicy.RUNTIME) public @interface ValidPhoneNumber { String message() default "Invalid phone number"; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; String[] supportedCountries() default {"US", "CA", "GB"}; boolean requireCountryCode() default true; @Target({ ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE }) @Retention(RetentionPolicy.RUNTIME) @Documented @interface List { ValidPhoneNumber[] value(); } }

4. Phone Number Validator

package com.example.validation.validators; import com.example.validation.constraints.ValidPhoneNumber; import com.google.i18n.phonenumbers.PhoneNumberUtil; import com.google.i18n.phonenumbers.Phonenumber; import jakarta.validation.ConstraintValidator; import jakarta.validation.ConstraintValidatorContext; public class ValidPhoneNumberValidator implements ConstraintValidator<ValidPhoneNumber, String> { private PhoneNumberUtil phoneUtil = PhoneNumberUtil.getInstance(); private String[] supportedCountries; private boolean requireCountryCode; @Override public void initialize(ValidPhoneNumber constraintAnnotation) { this.supportedCountries = constraintAnnotation.supportedCountries(); this.requireCountryCode = constraintAnnotation.requireCountryCode(); } @Override public boolean isValid(String phoneNumber, ConstraintValidatorContext context) { if (phoneNumber == null || phoneNumber.trim().isEmpty()) { return true; // Use @NotNull for null validation } try { // Try to parse the phone number Phonenumber.PhoneNumber parsedNumber = phoneUtil.parse(phoneNumber, null); // Check if the number is valid if (!phoneUtil.isValidNumber(parsedNumber)) { return false; } // Check country support String countryCode = phoneUtil.getRegionCodeForNumber(parsedNumber); if (supportedCountries.length > 0) { boolean countrySupported = false; for (String supportedCountry : supportedCountries) { if (supportedCountry.equalsIgnoreCase(countryCode)) { countrySupported = true; break; } } if (!countrySupported) { return false; } } // Check country code requirement if (requireCountryCode && parsedNumber.getCountryCode() == 0) { return false; } return true; } catch (Exception e) { return false; } } }

Complex Object Validation

1. Valid Address Constraint

package com.example.validation.constraints; import com.example.validation.validators.ValidAddressValidator; import jakarta.validation.Constraint; import jakarta.validation.Payload; import java.lang.annotation.*; @Documented @Constraint(validatedBy = ValidAddressValidator.class) @Target({ ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE }) @Retention(RetentionPolicy.RUNTIME) public @interface ValidAddress { String message() default "Invalid address"; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; boolean validateGeolocation() default false; String[] supportedCountries() default {}; @Target({ ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE }) @Retention(RetentionPolicy.RUNTIME) @Documented @interface List { ValidAddress[] value(); } }

2. Address Validator

package com.example.validation.validators; import com.example.validation.constraints.ValidAddress; import jakarta.validation.ConstraintValidator; import jakarta.validation.ConstraintValidatorContext; import java.util.Arrays; import java.util.HashSet; import java.util.Set; public class ValidAddressValidator implements ConstraintValidator<ValidAddress, Object> { private boolean validateGeolocation; private Set<String> supportedCountries; @Override public void initialize(ValidAddress constraintAnnotation) { this.validateGeolocation = constraintAnnotation.validateGeolocation(); this.supportedCountries = new HashSet<>(Arrays.asList(constraintAnnotation.supportedCountries())); } @Override public boolean isValid(Object value, ConstraintValidatorContext context) { if (value == null) { return true; // Use @NotNull for null validation } try { // Use reflection to access address properties java.lang.reflect.Field streetField = value.getClass().getDeclaredField("street"); java.lang.reflect.Field cityField = value.getClass().getDeclaredField("city"); java.lang.reflect.Field stateField = value.getClass().getDeclaredField("state"); java.lang.reflect.Field zipCodeField = value.getClass().getDeclaredField("zipCode"); java.lang.reflect.Field countryField = value.getClass().getDeclaredField("country"); streetField.setAccessible(true); cityField.setAccessible(true); stateField.setAccessible(true); zipCodeField.setAccessible(true); countryField.setAccessible(true); String street = (String) streetField.get(value); String city = (String) cityField.get(value); String state = (String) stateField.get(value); String zipCode = (String) zipCodeField.get(value); String country = (String) countryField.get(value); // Basic validation if (isEmpty(street) || isEmpty(city) || isEmpty(state) || isEmpty(zipCode) || isEmpty(country)) { return false; } // Country validation if (!supportedCountries.isEmpty() && !supportedCountries.contains(country.toUpperCase())) { context.disableDefaultConstraintViolation(); context.buildConstraintViolationWithTemplate("Country not supported: " + country) .addConstraintViolation(); return false; } // Zip code format validation based on country if (!isValidZipCode(zipCode, country)) { context.disableDefaultConstraintViolation(); context.buildConstraintViolationWithTemplate("Invalid zip code format for country: " + country) .addConstraintViolation(); return false; } // Optional geolocation validation if (validateGeolocation && !isValidGeolocation(street, city, state, country)) { context.disableDefaultConstraintViolation(); context.buildConstraintViolationWithTemplate("Address could not be geolocated") .addConstraintViolation(); return false; } return true; } catch (Exception e) { return false; } } private boolean isEmpty(String value) { return value == null || value.trim().isEmpty(); } private boolean isValidZipCode(String zipCode, String country) { // Implement country-specific zip code validation switch (country.toUpperCase()) { case "US": return zipCode.matches("\\d{5}(-\\d{4})?"); case "CA": return zipCode.matches("[A-Z]\\d[A-Z] \\d[A-Z]\\d"); default: return zipCode.length() >= 3; // Basic validation for other countries } } private boolean isValidGeolocation(String street, String city, String state, String country) { // Implement geolocation validation using external service // This is a simplified example try { // Mock geolocation validation return !street.toLowerCase().contains("invalid"); } catch (Exception e) { return false; } } }

Validation Groups

1. Validation Group Definitions

package com.example.validation.groups; public interface ValidationGroups { interface Create {} interface Update {} interface PartialUpdate {} interface AdminOperation {} interface UserOperation {} }

2. Group-Based Constraints

package com.example.validation.constraints; import com.example.validation.validators.AdminAccessValidator; import com.example.validation.groups.ValidationGroups; import jakarta.validation.Constraint; import jakarta.validation.Payload; import java.lang.annotation.*; @Documented @Constraint(validatedBy = AdminAccessValidator.class) @Target({ ElementType.TYPE }) @Retention(RetentionPolicy.RUNTIME) public @interface AdminAccess { String message() default "Admin access required for this operation"; Class<?>[] groups() default { ValidationGroups.AdminOperation.class }; Class<? extends Payload>[] payload() default {}; String requiredRole() default "ADMIN"; @Target({ ElementType.TYPE }) @Retention(RetentionPolicy.RUNTIME) @Documented @interface List { AdminAccess[] value(); } }

Custom Payloads

1. Severity Payload

package com.example.validation.payload; import jakarta.validation.Payload; public class Severity { public static class Info implements Payload {} public static class Warning implements Payload {} public static class Error implements Payload {} public static class Critical implements Payload {} }

2. Business Payload

package com.example.validation.payload; import jakarta.validation.Payload; public class Business { public static class HighPriority implements Payload {} public static class RequiresApproval implements Payload {} public static class AuditRequired implements Payload {} public static class LegalCompliance implements Payload {} }

Domain Models with Custom Constraints

1. User Entity with Custom Validations

package com.example.model; import com.example.validation.constraints.*; import com.example.validation.groups.ValidationGroups; import com.example.validation.payload.Severity; import jakarta.persistence.*; import jakarta.validation.constraints.*; import java.time.LocalDate; import java.time.LocalDateTime; @Entity @Table(name = "users") @FieldsValueMatch( field = "password", fieldMatch = "confirmPassword", fieldMessage = "Password must match", fieldMatchMessage = "Confirm password must match", groups = ValidationGroups.Create.class ) @AdminAccess(requiredRole = "SUPER_ADMIN", groups = ValidationGroups.AdminOperation.class) public class User { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; @NotBlank(message = "Username is required") @Size(min = 3, max = 50, message = "Username must be between 3 and 50 characters") @Pattern(regexp = "^[a-zA-Z0-9_]+$", message = "Username can only contain letters, numbers, and underscores") @Column(unique = true, nullable = false) private String username; @NotBlank(message = "Email is required", groups = {ValidationGroups.Create.class, ValidationGroups.Update.class}) @Email(message = "Invalid email format") @UniqueEmail( message = "Email already exists", excludeId = "#{this.id}", groups = {ValidationGroups.Create.class, ValidationGroups.Update.class}, payload = {Severity.Error.class} ) @Column(unique = true, nullable = false) private String email; @NotBlank(message = "Password is required", groups = ValidationGroups.Create.class) @StrongPassword( minLength = 10, requireUppercase = true, requireLowercase = true, requireDigits = true, requireSpecialChars = true, groups = ValidationGroups.Create.class, payload = {Severity.Critical.class} ) @Transient // Not persisted private String password; @NotBlank(message = "Confirm password is required", groups = ValidationGroups.Create.class) @Transient // Not persisted private String confirmPassword; @Size(max = 255, message = "First name cannot exceed 255 characters") @Pattern(regexp = "^[a-zA-Z\\s-']+$", message = "First name can only contain letters, spaces, hyphens, and apostrophes") @Column(name = "first_name") private String firstName; @Size(max = 255, message = "Last name cannot exceed 255 characters") @Pattern(regexp = "^[a-zA-Z\\s-']+$", message = "Last name can only contain letters, spaces, hyphens, and apostrophes") @Column(name = "last_name") private String lastName; @ValidPhoneNumber( supportedCountries = {"US", "CA", "GB"}, requireCountryCode = false, payload = {Severity.Warning.class} ) @Column(name = "phone_number") private String phoneNumber; @Past(message = "Birth date must be in the past") @Column(name = "birth_date") private LocalDate birthDate; @FutureAfter( amount = 1, unit = java.time.temporal.ChronoUnit.DAYS, message = "Account expiration must be at least 1 day in the future" ) @Column(name = "account_expires_at") private LocalDateTime accountExpiresAt; @NotNull(message = "Address is required") @ValidAddress( supportedCountries = {"US", "CA"}, validateGeolocation = true, payload = {Business.RequiresApproval.class} ) @Embedded private Address address; @AssertTrue(message = "Must accept terms and conditions", groups = ValidationGroups.Create.class) @Column(name = "terms_accepted") private Boolean termsAccepted; // Constructors public User() {} public User(String username, String email, String password) { this.username = username; this.email = email; this.password = password; this.termsAccepted = false; } // Getters and setters public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getUsername() { return username; } public void setUsername(String username) { this.username = username; } public String getEmail() { return email; } public void setEmail(String email) { this.email = email; } public String getPassword() { return password; } public void setPassword(String password) { this.password = password; } public String getConfirmPassword() { return confirmPassword; } public void setConfirmPassword(String confirmPassword) { this.confirmPassword = confirmPassword; } public String getFirstName() { return firstName; } public void setFirstName(String firstName) { this.firstName = firstName; } public String getLastName() { return lastName; } public void setLastName(String lastName) { this.lastName = lastName; } public String getPhoneNumber() { return phoneNumber; } public void setPhoneNumber(String phoneNumber) { this.phoneNumber = phoneNumber; } public LocalDate getBirthDate() { return birthDate; } public void setBirthDate(LocalDate birthDate) { this.birthDate = birthDate; } public LocalDateTime getAccountExpiresAt() { return accountExpiresAt; } public void setAccountExpiresAt(LocalDateTime accountExpiresAt) { this.accountExpiresAt = accountExpiresAt; } public Address getAddress() { return address; } public void setAddress(Address address) { this.address = address; } public Boolean getTermsAccepted() { return termsAccepted; } public void setTermsAccepted(Boolean termsAccepted) { this.termsAccepted = termsAccepted; } }

2. Address Value Object

package com.example.model; import jakarta.persistence.Embeddable; import jakarta.validation.constraints.NotBlank; import jakarta.validation.constraints.Size; @Embeddable public class Address { @NotBlank(message = "Street is required") @Size(max = 255, message = "Street cannot exceed 255 characters") private String street; @NotBlank(message = "City is required") @Size(max = 100, message = "City cannot exceed 100 characters") private String city; @NotBlank(message = "State is required") @Size(max = 100, message = "State cannot exceed 100 characters") private String state; @NotBlank(message = "Zip code is required") @Size(max = 20, message = "Zip code cannot exceed 20 characters") private String zipCode; @NotBlank(message = "Country is required") @Size(max = 100, message = "Country cannot exceed 100 characters") private String country; // Constructors public Address() {} public Address(String street, String city, String state, String zipCode, String country) { this.street = street; this.city = city; this.state = state; this.zipCode = zipCode; this.country = country; } // Getters and setters public String getStreet() { return street; } public void setStreet(String street) { this.street = street; } public String getCity() { return city; } public void setCity(String city) { this.city = city; } public String getState() { return state; } public void setState(String state) { this.state = state; } public String getZipCode() { return zipCode; } public void setZipCode(String zipCode) { this.zipCode = zipCode; } public String getCountry() { return country; } public void setCountry(String country) { this.country = country; } }

Validation Service

1. Custom Validation Service

package com.example.service; import com.example.validation.groups.ValidationGroups; import jakarta.validation.ConstraintViolation; import jakarta.validation.Validator; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Service; import java.util.Set; import java.util.stream.Collectors; @Service public class ValidationService { @Autowired private Validator validator; public <T> ValidationResult validate(T object) { return validate(object, new Class[0]); } public <T> ValidationResult validate(T object, Class<?>... groups) { Set<ConstraintViolation<T>> violations = validator.validate(object, groups); return new ValidationResult(violations); } public <T> ValidationResult validateProperty(T object, String propertyName) { Set<ConstraintViolation<T>> violations = validator.validateProperty(object, propertyName); return new ValidationResult(violations); } public <T> ValidationResult validateValue(Class<T> beanType, String propertyName, Object value) { Set<ConstraintViolation<T>> violations = validator.validateValue(beanType, propertyName, value); return new ValidationResult(violations); } public static class ValidationResult { private final Set<? extends ConstraintViolation<?>> violations; private final boolean valid; public ValidationResult(Set<? extends ConstraintViolation<?>> violations) { this.violations = violations; this.valid = violations.isEmpty(); } public boolean isValid() { return valid; } public Set<String> getErrorMessages() { return violations.stream() .map(ConstraintViolation::getMessage) .collect(Collectors.toSet()); } public Set<ConstraintViolation<?>> getViolations() { return Set.copyOf(violations); } public void throwIfInvalid() { if (!valid) { throw new ValidationException("Validation failed", violations); } } } public static class ValidationException extends RuntimeException { private final Set<? extends ConstraintViolation<?>> violations; public ValidationException(String message, Set<? extends ConstraintViolation<?>> violations) { super(message); this.violations = violations; } public Set<? extends ConstraintViolation<?>> getViolations() { return violations; } public Set<String> getErrorMessages() { return violations.stream() .map(ConstraintViolation::getMessage) .collect(Collectors.toSet()); } } }

Spring Configuration

1. Validation Configuration

package com.example.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.validation.beanvalidation.MethodValidationPostProcessor; @Configuration public class ValidationConfig { @Bean public MethodValidationPostProcessor methodValidationPostProcessor() { return new MethodValidationPostProcessor(); } @Bean public jakarta.validation.Validator validator() { return jakarta.validation.Validation.buildDefaultValidatorFactory().getValidator(); } }

2. Application Properties

# application.yml spring: jackson: deserialization: fail-on-unknown-properties: true default-property-inclusion: NON_NULL app: validation: fail-fast: true show-details: true logging: level: org.hibernate.validator: DEBUG

Testing Custom Constraints

1. Constraint Validator Test

package com.example.validation; import com.example.validation.constraints.StrongPassword; import com.example.validation.validators.StrongPasswordValidator; import jakarta.validation.ConstraintValidatorContext; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.extension.ExtendWith; import org.mockito.Mock; import org.mockito.junit.jupiter.MockitoExtension; import static org.junit.jupiter.api.Assertions.*; import static org.mockito.ArgumentMatchers.anyString; import static org.mockito.Mockito.*; @ExtendWith(MockitoExtension.class) class StrongPasswordValidatorTest { @Mock private StrongPassword constraintAnnotation; @Mock private ConstraintValidatorContext context; @Mock private ConstraintValidatorContext.ConstraintViolationBuilder builder; private StrongPasswordValidator validator; @BeforeEach void setUp() { validator = new StrongPasswordValidator(); when(constraintAnnotation.minLength()).thenReturn(8); when(constraintAnnotation.requireUppercase()).thenReturn(true); when(constraintAnnotation.requireLowercase()).thenReturn(true); when(constraintAnnotation.requireDigits()).thenReturn(true); when(constraintAnnotation.requireSpecialChars()).thenReturn(true); validator.initialize(constraintAnnotation); when(context.buildConstraintViolationWithTemplate(anyString())).thenReturn(builder); when(builder.addConstraintViolation()).thenReturn(context); } @Test void testValidPassword() { assertTrue(validator.isValid("StrongPass123!", context)); verify(context, never()).buildConstraintViolationWithTemplate(anyString()); } @Test void testTooShortPassword() { assertFalse(validator.isValid("Short1!", context)); verify(context).buildConstraintViolationWithTemplate(anyString()); } @Test void testNoUppercasePassword() { assertFalse(validator.isValid("lowercase123!", context)); verify(context).buildConstraintViolationWithTemplate(anyString()); } @Test void testNoDigitsPassword() { assertFalse(validator.isValid("NoDigitsHere!", context)); verify(context).buildConstraintViolationWithTemplate(anyString()); } @Test void testNullPassword() { assertTrue(validator.isValid(null, context)); } @Test void testEmptyPassword() { assertTrue(validator.isValid("", context)); } }

2. Integration Test

package com.example.validation; import com.example.model.User; import com.example.validation.groups.ValidationGroups; import jakarta.validation.Validator; import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.context.SpringBootTest; import java.time.LocalDate; import java.time.LocalDateTime; import java.util.Set; import static org.junit.jupiter.api.Assertions.*; @SpringBootTest class UserValidationTest { @Autowired private Validator validator; @Test void testValidUser() { User user = createValidUser(); Set violations = validator.validate(user, ValidationGroups.Create.class); assertTrue(violations.isEmpty()); } @Test void testInvalidEmail() { User user = createValidUser(); user.setEmail("invalid-email"); Set violations = validator.validate(user, ValidationGroups.Create.class); assertFalse(violations.isEmpty()); assertEquals(1, violations.size()); } @Test void testPasswordMismatch() { User user = createValidUser(); user.setConfirmPassword("differentPassword"); Set violations = validator.validate(user, ValidationGroups.Create.class); assertFalse(violations.isEmpty()); } @Test void testWeakPassword() { User user = createValidUser(); user.setPassword("weak"); user.setConfirmPassword("weak"); Set violations = validator.validate(user, ValidationGroups.Create.class); assertFalse(violations.isEmpty()); } private User createValidUser() { User user = new User(); user.setUsername("testuser"); user.setEmail("[email protected]"); user.setPassword("StrongPassword123!"); user.setConfirmPassword("StrongPassword123!"); user.setFirstName("John"); user.setLastName("Doe"); user.setPhoneNumber("+1-555-123-4567"); user.setBirthDate(LocalDate.of(1990, 1, 1)); user.setAccountExpiresAt(LocalDateTime.now().plusDays(30)); user.setTermsAccepted(true); return user; } }

Best Practices

1. Performance Optimization

package com.example.validation.optimization; import org.hibernate.validator.HibernateValidator; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import jakarta.validation.Validation; import jakarta.validation.Validator; import jakarta.validation.ValidatorFactory; @Configuration public class OptimizedValidationConfig { @Bean public Validator validator() { ValidatorFactory validatorFactory = Validation.byProvider(HibernateValidator.class) .configure() .failFast(true) // Stop on first validation error .buildValidatorFactory(); return validatorFactory.getValidator(); } }

2. Custom Message Interpolation

package com.example.validation.messages; import org.hibernate.validator.messageinterpolation.AbstractMessageInterpolator; import org.hibernate.validator.resourceloading.PlatformResourceBundleLocator; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import jakarta.validation.MessageInterpolator; @Configuration public class CustomMessageInterpolationConfig { @Bean public MessageInterpolator messageInterpolator() { return new AbstractMessageInterpolator( new PlatformResourceBundleLocator("ValidationMessages") ) { @Override public String interpolate(String message, Context context) { // Custom message interpolation logic String interpolated = super.interpolate(message, context); return customizeMessage(interpolated, context); } private String customizeMessage(String message, Context context) { // Add custom logic for message customization return message; } }; } }

Conclusion

Hibernate Validator custom constraints provide:

Key Benefits

• Domain-specific validation rules tailored to your business needs
• Complex business logic validation beyond basic constraints
• Cross-field validation for validating relationships between fields
• Reusable validation logic across multiple entities
• Integration with Spring and other frameworks

Best Practices

1. Keep validators stateless for thread safety
2. Use dependency injection carefully in validators
3. Implement proper null handling in validators
4. Use validation groups for context-specific validation
5. Provide meaningful error messages with custom templates
6. Test validators thoroughly with various scenarios

Common Use Cases

• Password strength validation
• Email uniqueness checks
• Cross-field matching (password confirmation)
• Business rule validation (age restrictions, date ranges)
• External service integration (address validation, phone verification)

Custom constraints empower you to create robust, maintainable validation logic that accurately reflects your domain model and business requirements.