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();
}
}
}