javax.validation.ConstraintValidatorContext Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.liveSense.misc.gwt.jsr303 Show documentation
liveSense JSR 303 GWT client Bean Validation
The newest version!
// $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();
		}
	}
}