Package com.blackbuild.klum.ast

Annotation Interface Validate

@Target({FIELD,METHOD,TYPE})
@Retention(RUNTIME)
@Documented
public @interface Validate

Activates validation for the given field or marks the annotated method as validation method.

On a class

If set on a class, the class behaves as if the annotation was set on all fields of the class not already annotated. In this usage, fields can be exempted by annotating them with Validate(Ignore).

On a field

If this annotation is set on a field, this field is validated as part of the object validation, During the validation phase. The actual validation can be one of the following:

Valid options to use Validate annotation on a field

empty	Validates the content of the field according to groovy truth
empty (for Boolean fields)	Validates that the content of the field is not null
Validate.Ignore	Don't validate this field. This only makes sense if the class itself is annotated with Validate to exclude the annotated field from validation.
a closure	The given closure is evaluated called with the field value as parameter. If the result of the call satisfies Groovy Truth, the field is assumed valid.

It is illegal to place the annotation on a primitive boolean field.

 @DSL
 class Foo {
   @Validate
   String notEmpty
   @Validate({ it.length > 3 })
   String minLength
 }
 

message() can be used to provide a custom message for failed validations.

On a method

On a method, this annotation is used to designate a validation method which is called as part of the validation process. If the method returns without throwing an exception / an AssertionError, the method is considered to be passed.

Validation methods are commonly used for interdependent fields (field a must have a value matching field b) or to perform a validation that would be to long to comfortably include in a closure

 given:
 @DSL
 class Foo {
   String value1
   String value2

   @Validate
   private def stringLength() {
     assert value1.length() < value2.length()
   }
 }

 when:
 clazz.Create.With {
   value1 "abc"
   value2 "bl"
 }

 then:
 thrown(IllegalStateException)
 

Validation methods should not change the state of an object, use PostApply or PostCreate for that.

When placing Validate on a method or a class, neither a message() nor a value() must be given.

On a validation class

When placed on a non-static inner class of a model class, all public, non-static, and parameterless methods of that class are considered validation methods. This includes validation classes of super classes of the current class, as long as they are not inherited by a current validation class.

Validation classes offer some distinct advantages over validation methods:

• they do not pollute the interface of the model class
• they can inherit logic from common parent classes
• when working on source code, they can be folded as a whole in modern IDEs
• They can be used to group validations logically and by level

Order of validation

When validating an object, the following order is executed.

• Validation of the superclass, if the superclass is also a model class
• validation of all fields
• validation methods
• validator classes
• validation provided by plugins (like bean validation)

Using the level() member, the validation can be designated as information/warning only.

Validation is usually executed as part of the ValidationPhase, which performs validations on all objects in the hierarchy. Validation results of all objects are collected, and if an Error level problem is found, a KlumValidationException is thrown.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Validate.DefaultImpl
static class	Validate.GroovyTruth	Default value for value().
static class	Validate.Ignore	If used as value for value(), configures validation to ignore this field.
static enum	Validate.Level	Defines the severity of the validation problem.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
Validate.Level	level	Defines the severity of the validation problem.
String	message	A message to be returned when validation fails.
Class<? extends groovy.lang.Closure>	value	A closure to be executed to validate the annotated field.

Element Details

value

Class<? extends groovy.lang.Closure> value

A closure to be executed to validate the annotated field. If empty, Groovy Truth is used to validate the field. Illegal when annotating a method.

Default:

com.blackbuild.klum.ast.Validate.GroovyTruth.class

message

String message

A message to be returned when validation fails. Illegal when annotating a method.

Default:

""

level

Validate.Level level

Defines the severity of the validation problem. Default is Validate.Level.ERROR. This can be used to create Warning or Info messages instead of errors. Cannot be used on top level classes.

Default:

ERROR