net.sourceforge.stripes.validation
Annotation Type ValidationMethod


@Retention(value=RUNTIME)
@Target(value=METHOD)
@Documented
public @interface ValidationMethod

Annotation that marks a method in an ActionBean as a validation method. Validation methods are invoked after required field checks, type conversion and validations specified in @Validate annotations, but before event handler methods.

Validation methods must be public, may return any type (though any return will be ignored by Stripes) and may throw any exceptions. They make take either zero parameters, or a single parameter of type ValidationErrors. When validation methods are invoked all binding will have taken place and the ActionBean will have access to the ActionBeanContext, therefore methods that do not take ValidationErrors as a parameter may retrieve it by calling ActionBeanContext.getValidationErrors().

The attributes of this annotation confer significant control over when a validation method will be run. When a single ActionBean class has multiple validation methods the ordering of them can be specified using the priority attribute. Methods with lower values (i.e. nearer zero) are executed before those with higher values.

The on attribute controls which events the validation method should be invoked for. It should be noted that the 'on' attribute is completely optional. If omitted then the validation method will be invoked for all events not annotated with @DontValidate. The on attribute can take one of two forms. It can specify a list of events to apply the validation method to, for example 'on={"save", "update"}', in which case it will be invoked only for those events. It can alternatively specify a list of events not to apply the validation to, for example 'on="!delete"', in which case the validation will be run for all events except those listed.

The when attribute controls whether or not the validation method is executed when one or more validation errors exist. It has no affect when there are no validation errors. A value of ValidationState.ALWAYS will cause the method to be invoked even if errors exist. This is useful when you wish to perform additional validations that do not depend on having a well-validated ActionBean since it allows the user to see more validation errors at the same time. A value of ValidationState.NO_ERRORS causes the method to be invoked only when there are no pre-existing validation errors. This is useful if the method relies on a valid ActionBean and might throw exceptions otherwise. The value ValidationState.DEFAULT causes Stripes to apply the system level default for this attribute.

The default behaviour is such that if validation errors arise from the annotated validations (or type conversion), validation methods will not be called (nor will the handler method). This behaviour is configurable though. Please see the Stripes documentation on Configuration if you would prefer the default behaviour to be to invoke validation methods when validation errors have been generated by type conversion and annotation based validation.

Since:
Stripes 1.3
Author:
Tim Fennell

Optional Element Summary
 String[] on
          Allows the validation method to be restricted to one or more events.
 int priority
          If there are multiple validation methods in an ActionBean, what is the priority of this one? Lower values == higher priorities and will get run before methods with higher values.
 ValidationState when
          Controls whether or not the validation method will be executed when earlier phases of validation generated validation errors.
 

priority

public abstract int priority
If there are multiple validation methods in an ActionBean, what is the priority of this one? Lower values == higher priorities and will get run before methods with higher values. If methods have the same priority they are executed in alphabetical order.

Default:
0

on

public abstract String[] on
Allows the validation method to be restricted to one or more events. By default the validation method will execute on all events not marked with @DontValidate. Can be used to specify one or more events to apply the method to (e.g. on={"save", "update"}) or to specify one or more events not to apply the method to (e.g. on="!delete").

Default:
{}

when

public abstract ValidationState when
Controls whether or not the validation method will be executed when earlier phases of validation generated validation errors. Valid values are ValidationState.ALWAYS, ValidationState.NO_ERRORS and ValidationState.DEFAULT. By specifying ALWAYS you can ensure that all error messages are presented to the user at once. By specifying NO_ERRORS you can be sure of the state of the ActionBean has been validated successfully prior to execution.

Default:
net.sourceforge.stripes.validation.ValidationState.DEFAULT


? Copyright 2005-2006, Stripes Development Team.