javax.validation

Interface ConstraintValidatorContext

public interface ConstraintValidatorContext

Provides contextual data and operation when applying a given constraint validator. At least one ConstraintViolation must be defined (either the default one, of if the default ConstraintViolation is disabled, a custom one).

Author:

Emmanuel Bernard, Guillaume Smet

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ConstraintValidatorContext.ConstraintViolationBuilder ConstraintViolation builder allowing to optionally associate the violation report to a sub path.

Method Summary

Modifier and Type	Method and Description
ConstraintValidatorContext.ConstraintViolationBuilder	buildConstraintViolationWithTemplate(String messageTemplate) Returns a constraint violation builder building a violation report allowing to optionally associate it to a sub path.
void	disableDefaultConstraintViolation() Disables the default ConstraintViolation object generation (which is using the message template declared on the constraint).
ClockProvider	getClockProvider() Returns the provider for obtaining the current time in the form of a Clock, e.g.
String	getDefaultConstraintMessageTemplate()
<T> T	unwrap(Class<T> type) Returns an instance of the specified type allowing access to provider-specific APIs.

Method Detail

disableDefaultConstraintViolation

void disableDefaultConstraintViolation()

Disables the default ConstraintViolation object generation (which is using the message template declared on the constraint).

Useful to set a different violation message or generate a ConstraintViolation based on a different property.

getDefaultConstraintMessageTemplate

String getDefaultConstraintMessageTemplate()

Returns:

the current un-interpolated default message

getClockProvider

ClockProvider getClockProvider()

Returns the provider for obtaining the current time in the form of a Clock, e.g. when validating the Future and Past constraints.

Returns:

the provider for obtaining the current time, never null. If no specific provider has been configured during bootstrap, a default implementation using the current system time and the current default time zone as returned by Clock.systemDefaultZone() will be returned.

Since:

2.0

buildConstraintViolationWithTemplate

ConstraintValidatorContext.ConstraintViolationBuilder buildConstraintViolationWithTemplate(String messageTemplate)

Returns a constraint violation builder building a violation report allowing to optionally associate it to a sub path. The violation message will be interpolated.

To create the ConstraintViolation, one must call either one of the addConstraintViolation() methods available in one of the interfaces of the fluent API. If another method is called after addConstraintViolation() on ConstraintViolationBuilder or any of its associated nested interfaces an IllegalStateException is raised.

If ConstraintValidator.isValid(Object, ConstraintValidatorContext) returns false, a ConstraintViolation object will be built per constraint violation report including the default one (unless disableDefaultConstraintViolation() has been called).

ConstraintViolation objects generated from such a call contain the same contextual information (root bean, path and so on) unless the path has been overridden.

To create a different ConstraintViolation, a new constraint violation builder has to be retrieved from ConstraintValidatorContext Here are a few usage examples:

 //assuming the following domain model
 public class User {
     public Map<String,Address> getAddresses() { ... }
 }

 public class Address {
     public String getStreet() { ... }
     public Country getCountry() { ... }
 }

 public class Country {
     public String getName() { ... }
 }

 //From a property-level constraint on User.addresses
 //Build a constraint violation on the default path - i.e. the "addresses" property
 context.buildConstraintViolationWithTemplate( "this detail is wrong" )
             .addConstraintViolation();

 //From a class level constraint on Address
 //Build a constraint violation on the default path + "street"
 //i.e. the street property of Address
 context.buildConstraintViolationWithTemplate( "this detail is wrong" )
             .addPropertyNode( "street" )
             .addConstraintViolation();

 //From a property-level constraint on  User.addresses
 //Build a constraint violation on the default path + the bean stored
 //under the "home" key in the map
 context.buildConstraintViolationWithTemplate( "Incorrect home address" )
             .addBeanNode()
                 .inContainer( Map.class, 1 )
                 .inIterable().atKey( "home" )
             .addConstraintViolation();

 //From a class level constraint on User
 //Build a constraint violation on the default path + addresses["home"].country.name
 //i.e. property "country.name" on the object stored under "home" in the map
 context.buildConstraintViolationWithTemplate( "this detail is wrong" )
             .addPropertyNode( "addresses" )
             .addPropertyNode( "country" )
                 .inContainer( Map.class, 1 )
                 .inIterable().atKey( "home" )
             .addPropertyNode( "name" )
             .addConstraintViolation();

 //From a class level constraint on User
 //Build a constraint violation on the default path + addresses["home"].<map key>
 //i.e. a container element constraint violation for the map key
 context.buildConstraintViolationWithTemplate( "the map key is invalid" )
             .addPropertyNode( "addresses" )
             .addContainerElementNode( "<map key>", Map.class, 0 )
                 .inIterable().atKey( "invalid" )
             .addConstraintViolation();
 

Cross-parameter constraints on a method can create a node specific to a particular parameter if required. Let's explore a few examples:

 //Cross-parameter constraint on method
 //createUser(String password, String passwordRepeat)
 //Build a constraint violation on the default path + "passwordRepeat"
 context.buildConstraintViolationWithTemplate("Passwords do not match")
             .addParameterNode(1)
             .addConstraintViolation();

 //Cross-parameter constraint on a method
 //mergeAddresses(Map<String,Address> addresses,
 //        Map<String,Address> otherAddresses)
 //Build a constraint violation on the default path + "otherAddresses["home"]
 //i.e. the Address bean hosted in the "home" key of the "otherAddresses" map parameter
 context.buildConstraintViolationWithTemplate(
         "Map entry home present in both and does not match")
             .addParameterNode(1)
             .addBeanNode()
                 .inContainer( Map.class, 1 )
                 .inIterable().atKey("home")
             .addConstraintViolation();

 //Cross-parameter constraint on a method
 //mergeAddresses(Map<String,Address> addresses,
 //        Map<String,Address> otherAddresses)
 //Build a constraint violation on the default path + "otherAddresses["home"].city
 //i.e. on the "city" property of the Address bean hosted in
 //the "home" key of the "otherAddresses" map
 context.buildConstraintViolationWithTemplate(
         "Map entry home present in both but city does not match")
             .addParameterNode(1)
             .addPropertyNode("city")
                 .inContainer( Map.class, 1 )
                 .inIterable().atKey("home")
             .addConstraintViolation();
 

Parameters:

messageTemplate - new un-interpolated constraint message

Returns:

returns a constraint violation builder

unwrap

<T> T unwrap(Class<T> type)

Returns an instance of the specified type allowing access to provider-specific APIs. If the Bean Validation provider implementation does not support the specified class, ValidationException is thrown.

Type Parameters:

T - the type of the object to be returned

Parameters:

type - the class of the object to be returned

Returns:

an instance of the specified class

Throws:

ValidationException - if the provider does not support the call

Since:

1.1