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

- - ### 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

    Methods
    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).
    `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

    - #### 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 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()
                           .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" )
                           .inIterable().atKey( "home" )
                       .addPropertyNode( "name" )
                       .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 addresses, Map 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()
                           .inIterable().atKey("home")
                       .addConstraintViolation();

           //Cross-parameter constraint on a method
           //mergeAddresses(Map addresses, Map 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")
                           .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.
      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

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.