Play framework 1.0 built-in validations
The Play framework (version 1.0) provides flexible and easy-to-use functionality for HTTP request data validation, for validating form data. This article provides an overview of the framework’s built-in validation rules.
Validation overview
The Play validation guide describes three ways to validate form (HTTP request) data in a Play web application.
-
In the controller method, call methods on the controller’s
validation
field directly. -
Add validation annotations to the controller method’s parameter declarations.
-
Add the
@Valid
annotation to the controller method’s POJO parameters, and add validation annotations to the POJO properties.
In all three cases, the usual pattern is to then check the controller’s
validation
field for validation failures, save the request parameters
and validation errors in flash scope, and then redirect back to the edit
page to display validation error messages. Retrieving and displaying
these messages is outside the scope of this article.
For example, this controller method validates that a required value is not empty using the first approach - calling a play.data.validation.Validation method.
public static void save(String value) {
validation.required(value);
if (validation.hasErrors()) {
params.flash();
validation.keep();
}
details();
}
The second approach - adding a play.data.validation annotation:
public static void save(@Required String value) {
if (validation.hasErrors()) {
params.flash();
validation.keep();
}
details();
}
The third approach - putting on the annotations on a JavaBean’s properties, and annotating the parameter with the @Valid annotation:
public static void save(@Valid Data data) {
if (validation.hasErrors()) {
params.flash();
validation.keep();
}
details();
}
public class Data extends Model {
@Required public String value;
}
Built-in validations
Play defines several built-in validations, in addition to the 'required' validation used in the above examples.
Each validation has an associated error message, defined in
$PLAY_HOME/resources/messages
, whose key is validation.
followed by
the validation name. You can override this message by using the same key
in your application’s conf/messages
file, and localise it using
message files for other languages.
Checks that the value is a valid e-mail address.
validation.email(address);
Annotation syntax:
@Email String address
Message key: validation.email
equals
Checks that the value is equal to another parameter’s value, using the
value’s equals
method, e.g. for checking for a password confirmation
field.
validation.equals(password, passwordConfirmation);
Annotation syntax:
@Equals("passwordConfirmation") String password
Message key: validation.equals
future
Checks that the value is a date in the future. If a second date is specified as a reference, then the value must be in the future with respect to the reference date - i.e. after it.
validation.future(dueDate);
validation.future(dueDate, shipmentDate);
Annotation syntax:
@InFuture String dueDate
@InFuture("1979-12-31") String birthDate
Message key: validation.future
isTrue
Checks that the value is a String
or Boolean
that evaluates to
true
, e.g. for an 'I agree to the terms' checkbox that must be
checked, or a non-zero Number
. Null values are considered
false/invalid.
validation.isTrue(agree);
Annotation syntax:
@IsTrue String agree
Message key: validation.isTrue
match
Checks that the value is a string that matches the given regular expression. Empty strings are considered valid.
validation.match(abbreviation, "[A-Z]{3}"); // TLA
Annotation syntax:
@Match("[A-Z]{3}") String abbreviation
Message key: validation.match
max
Checks that the value is a String
or Number
that is no greater than
the given number. Null values are considered valid.
validation.max(wordCount, 7500); // Short story
Annotation syntax:
@Max(7500) String wordCount
Message key: validation.max
maxSize
Checks that the value is a String
whose length is no greater than the
given length. Empty strings are considered valid.
validation.maxSize(url, 2083); // IE 4.0 - 8
Annotation syntax:
@MaxSize(2083) String value
Message key: validation.maxSize
min
Checks that the value is a String
or Number
that is no less than the
given number. Null values are considered valid.
validation.min(age, 18); // Adult
Annotation syntax:
@Min(18) Long age
Message key: validation.min
minSize
Checks that the value is a String
whose length is no less than the
given length. Empty strings are considered valid.
validation.minSize(value, 42);
Annotation syntax:
@MinSize(42) String value
Message key: validation.minSize
past
Checks that the value is a date in the future. If a second date is specified as a reference, then the value must be in the past with respect to the reference date - i.e. before it.
validation.past(actualDepartureDate);
validation.past(expectedDepartureDate, expectedArrivalDate);
Annotation syntax:
@Past String actualDepartureDate
@Past("1980-01-01") String birthDate
Message key: validation.past
range
Checks that the value is a number within the range (inclusive) specified by the two given numbers.
validation.range(wordCount, 17500, 40000); // Novella
Annotation syntax:
@Range(min = 17500, max = 40000) String wordCount
Message key: validation.past
required
Checks that the value is a non-empty String
, Collection
, File
or
array.
validation.required(value);
Annotation syntax:
@Required String value
Message key: validation.required
url
Checks that the value is a valid URL; empty strings are considered valid. There is no play.data.validation.Validation method for this validation.
@URL String address
Message key: validation.url