All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.validation.ConstraintValidatorContext Maven / Gradle / Ivy

// $Id: ConstraintValidatorContext.java 17620 2009-10-04 19:19:28Z hardy.ferentschik $
/*
* JBoss, Home of Professional Open Source
* Copyright 2009, Red Hat, Inc. and/or its affiliates, and individual contributors
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package javax.validation;

/**
 * Provide 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
 */
public interface ConstraintValidatorContext {
	/**
	 * Disable 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.
	 */
	void disableDefaultConstraintViolation();

	/**
	 * @return the current uninterpolated default message.
	 */
	String getDefaultConstraintMessageTemplate();

	/**
	 * Return an constraint violation builder building an 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 isValid returns false, a ConstraintViolation * object will be built per ConstraintViolation report including the default one (unless * {@link #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 overriden. *

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

	 * {@code
	 * // create new violation report with the default path the constraint is located on
	 * context.buildConstraintViolationWithTemplate( "way too long" )
	 *             .addConstraintViolation();
	 *
	 * // create new violation report in the "street" subnode of the default path
	 * //the constraint is located on
	 * context.buildConstraintViolationWithTemplate( "way too long" )
	 *              .addNode( "street" )
	 *              .addConstraintViolation();
	 *
	 * //create new violation report in the "addresses["home"].city.name" subnode
	 * //of the default path the constraint is located on
	 * context.buildConstraintViolationWithTemplate( "this detail is wrong" )
	 *              .addNode( "addresses" )
	 *              .addNode( "country" )
	 *                  .inIterable().atKey( "home" )
	 *              .addNode( "name" )
	 *              .addConstraintViolation();
	 * }
	 * 
* * @param messageTemplate new uninterpolated constraint message. * @return Returns an constraint violation builder */ ConstraintViolationBuilder buildConstraintViolationWithTemplate(String messageTemplate); /** * ConstraintViolation builder allowing to optionally associate * the violation report to a sub path. * * 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 objects * an IllegalStateException is raised. * */ interface ConstraintViolationBuilder { /** * Add a node to the path the ConstraintViolation will be associated to. * * name describes a single property. In particular, * dot (.) is not allowed. * * @param name property name * @return a builder representing node name */ NodeBuilderDefinedContext addNode(String name); /** * Add the new ConstraintViolation to be generated if the * constraint validator marks the value as invalid. * Methods of this ConstraintViolationBuilder instance and its nested * objects return IllegalStateException from now on. * * @return the ConstraintValidatorContext instance the * ConstraintViolationBuilder comes from */ ConstraintValidatorContext addConstraintViolation(); /** * Represent a node whose context is known * (ie index, key and isInIterable) */ interface NodeBuilderDefinedContext { /** * Add a node to the path the ConstraintViolation will be associated to. * * name describes a single property. In particular, * dot (.) are not allowed. * * @param name property name * @return a builder representing this node */ NodeBuilderCustomizableContext addNode(String name); /** * Add the new ConstraintViolation to be generated if the * constraint validator marks the value as invalid. * Methods of the ConstraintViolationBuilder instance this object * comes from and the constraint violation builder nested * objects return IllegalStateException after this call. * * @return ConstraintValidatorContext instance the * ConstraintViolationBuilder comes from */ ConstraintValidatorContext addConstraintViolation(); } /** * Represent a node whose context is * configurable (ie index, key and isInIterable) */ interface NodeBuilderCustomizableContext { /** * Mark the node as being in an Iterable or a Map * * @return a builder representing iterable details */ NodeContextBuilder inIterable(); /** * Add a node to the path the ConstraintViolation will be associated to. * * name describes a single property. In particular, * dot (.) are not allowed. * * @param name property name * @return a builder representing this node */ NodeBuilderCustomizableContext addNode(String name); /** * Add the new ConstraintViolation to be generated if the * constraint validator mark the value as invalid. * Methods of the ConstraintViolationBuilder instance this object * comes from and the constraint violation builder nested * objects return IllegalStateException after this call. * * @return ConstraintValidatorContext instance the * ConstraintViolationBuilder comes from */ ConstraintValidatorContext addConstraintViolation(); } /** * Represent refinement choices for a node which is * in an Iterator or Map. * If the iterator is an indexed collection or a map, * the index or the key should be set. */ interface NodeContextBuilder { /** * Define the key the object is into the Map * * @param key map key * @return a builder representing the current node */ NodeBuilderDefinedContext atKey(Object key); /** * Define the index the object is into the List or array * * @param index index * @return a builder representing the current node */ NodeBuilderDefinedContext atIndex(Integer index); /** * Add a node to the path the ConstraintViolation will be associated to. * * name describes a single property. In particular, * dot (.) is not allowed. * * @param name property name * @return a builder representing this node */ NodeBuilderCustomizableContext addNode(String name); /** * Add the new ConstraintViolation to be generated if the * constraint validator mark the value as invalid. * Methods of the ConstraintViolationBuilder instance this object * comes from and the constraint violation builder nested * objects return IllegalStateException after this call. * * @return ConstraintValidatorContext instance the * ConstraintViolationBuilder comes from */ ConstraintValidatorContext addConstraintViolation(); } } }