SeamFramework.orgCommunity Documentation
Seam Remoting provides integrated support for JSR-303 Bean Validation, which defines a standard approach for validating Java Beans no matter where they are used; web tier or persistence tier, server or client. Bean validation for remoting delivers JSR-303's vision by making all of the validation constraints declared by the server-side beans available on the client side, and allows developers to perform client-side bean validation in an easy to use, consistent fashion.
Client-side validation by its very nature is an asynchronous operation, as it is possible that the client may encounter a custom validation constraint for which it has no knowledge of the corresponding validation logic. Under these circumstances, the client will make a request to the server for the validation to be performed server-side, after which it receives the result will forward it to the client-side callback method. All built-in validation types defined by the JSR-303 specification are executed client-side without requiring a round-trip to the server. It is also possible to provide the client-side validation API with custom JavaScript to allow client-side execution of custom validations.
The Seam.validateBean() method may be used to validate a single object. It accepts
the following parameter values:
Seam.validateBean(bean, callback, groups);
The bean parameter is the object to validate.
The callback parameter should contain a reference to the callback method to
invoke once validation is complete.
The groups parameter is optional, however may be specified if only certain validation groups
should be validated. The groups parameter may be a String or an array
of String values for when multiple groups are to be validated.
Here's an example showing how a bean called customer is validated:
function test() {
var customer = Seam.createBean("com.acme.model.Customer");
customer.setFirstName("John");
customer.setLastName("Smith");
Seam.validateBean(customer, validationCallback);
}
function validationCallback(violations) {
if (violations.length == 0) alert("All validations passed!");
}By default, when Seam Remoting performs validation for a single bean it will traverse the entire object graph for that bean and validate each unique object that it finds. If you don't wish to validate the entire object graph, then please refer to the section on validating multiple objects later in this chapter for an alternative.
Sometimes it might not be desirable to perform validation for all properties of a bean. For example, you might
have a dynamic form which displays validation errors as the user tabs between fields. In this situation, you may use
the Seam.validateProperty() method to validate a single bean property.
Seam.validateProperty(bean, property, callback, groups)
The bean parameter is the object containing the property that is to be validated.
The property parameter is the name of the property to validate.
The callback parameter is a reference to the callback function to invoke once the property has
been validated.
The groups parameter is optional, however may be specified if validating the property against
a certain validation group. The groups parameter may be a String or an array
of String values for multiple groups.
Here's an example showing how to validate the firstName property of a bean called
customer:
function test() {
var customer = Seam.createBean("com.acme.model.Customer");
customer.setFirstName("John");
Seam.validateProperty(customer, "firstName", validationCallback);
}
function validationCallback(violations) {
if (violations.length == 0) alert("All validations passed!");
}
It is also possible to perform multiple validations for beans and bean properties in one go. This might be useful
for example to perform validation of forms that present data from more than one bean.
The Seam.validate() method takes the following parameters:
Seam.validate(validations, callback, groups);
The validations parameter should contain a list of the validations to perform. It may either
be an associative array (for a single validation), or an array of associative arrays (for multiple validations)
which define the validations that should be performed. We'll look at this parameter more closely in just a moment.
The callback parameter should contain a reference to the callback function to invoke once
validation is complete. The optional groups parameter should contain the group name/s
for which to perform validation.
The groups parameter allows one or more validation groups (specified by providing a
String or array of String values) to be validated. The validation groups
specified here will be applied to all bean values contained in the validations parameter.
The simplest example, in which we wish to validate a single object would look like this:
Seam.validate({bean:customer}, callback);
In the above example, validation will be performed for the customer object, after which
the function named validationCallback will be invoked.
Validate multiple beans is done by passing in an array of validations:
Seam.validate([{bean:customer}, {bean:order}], callback);
Single properties can be validated by specifying a property name:
Seam.validate({bean:customer, property: "firstName"}, callback);
To prevent the entire object graph from being validated, the traverse property may be set to false:
Seam.validate({bean:customer, traverse: false}, callback);
Validation groups may also be set for each individual validation, by setting the groups property to a
String or array of Strings value:
Seam.validate({bean:customer, groups: "default"}, callback);
Validation group names should be the unqualified class name of the group class. For example, for the class
com.acme.InternalRegistration, the client-side group name should be specified as
InternalRegistration:
Seam.validateBean(user, callback, "InternalRegistration"
It is also possible to set the default validation groups against which all validations will be performed,
by setting the Seam.ValidationGroups property:
Seam.ValidationGroups = ["Default", "ExternalRegistration"];
If no explicit group is set for the default, and no group is specified when performing validation, then the validation process will be executed against the 'Default' group.
If any validations fail during the validation process, then the callback method specified in the validation function will be invoked with an array of constraint violations. If all validations pass, this array will be empty. Each object in the array represents a single constraint violation, and contains the following property values:
bean - the bean object for which the validation failed.
property - the name of the property that failed validation
value - the value of the property that failed validation
message - a message string describing the nature of the validation failure
The callback method should contain business logic that will process the constraint violations and update the user interface accordingly to inform the user that validation has failed. The following minimalistic example demonstrates how the validation errors can be displayed to the user as popup alerts:
function validationCallback(violations) {
for (var i = 0; i < violations.length; i++) {
alert(violations[i].property + "=" + violations[i].value + " [violation] -> " + violations[i].message);