Validation

Three facts decide whether to use this module in a new project.

The 2.13.0 release added one thing: JAXB and xml-apis became optional for GWT’s javax.validation support, and the gwt.validation.ignoreXml system property avoids needing them. Without the property, the validator generator cannot run on JDK 11 or later (see The gwt.validation.ignoreXml flag).

Prefer the first row for new work and keep the second for applications that already depend on it, as the editors page does for the display side (Editors).

The Bookshelf Book is a shared class. Its constraints are ordinary Bean Validation annotations, a validator factory class tells the GWT compiler which classes to generate validators for, and one replace-with rule in the module connects the standard bootstrap to that factory.

Source: GWT — Developer Guide: Validation

A book with the title ab, an empty author, the year 1200, -1 copies and the ISBN 123 produced this in the browser (HtmlUnit, sorted by property because the set has no defined order):

Five things happened that the rest of the page explains: the annotations were read at compile time, a validator class for Book was generated, the messages were interpolated in the browser from GWT constants, the custom key {book.title.size} was resolved by the application’s own resolver, and the numbers {min}, {max} and {value} came from the annotation attributes.

Nothing is reflected at run time, as with every GWT feature. The ValidatorGenerator of the module com.google.gwt.validation.Validation is registered for every type that is assignable to javax.validation.Validator or to GwtSpecificValidator. When the compiler meets GWT.create(GwtValidator.class) it runs the generator in the compiler’s JVM:

The generated sources are visible in the Super Dev Mode work directory, for the Bookshelf demo module target/gwt/codeserver/com.example.bookshelf.ValidationDemo/compile-2/gen/com/example/bookshelf/.... In the measured run _BookValidatorImpl.java had 695 lines for a bean with six constrained properties, and the factory implementation contained this dispatch:

Source: GWT 2.13.1 source — ValidatorGenerator.java

That generated code references classes such as org.hibernate.validator.constraints.impl.SizeValidatorForString. They are compiled from the sources classifier of Hibernate Validator, which is why a plain jar is not enough. HibernateValidator.gwt.xml (in gwt-user) makes the library usable: it inherits the Validation module, declares the HV constraint packages as source, super-sources GWT-compatible replacements for the validators that use unsupported APIs (EmailValidator, PatternValidator, ScriptAssertValidator and the Calendar ones among them), and registers HibernateValidationMessageResolver for the provider’s own message keys.

Source: GWT 2.13.1 source — AbstractGwtValidatorFactory.java

The published Javadoc of 2.13 does not include the validation packages (the class pages under javadoc/latest/com/google/gwt/validation/client/ answered 404 on 2026-10-09), so the source on GitHub is the reference.

The Developer Guide lists the libraries that must be on the class path: the Validation API with sources (already pulled in by gwt-user), Hibernate Validator 4.1.0.Final with sources, and the SLF4J API that Hibernate Validator logs through. The Maven coordinates that compiled and ran in the Bookshelf client:

Source: Maven Central — org.hibernate:hibernate-validator:4.1.0.Final

What the experiments established about this list:

The generator accepts the constraints of Bean Validation 1.0 whose validators are GWT-compatible. The Bookshelf run put one instance of each on a bean (invalid values everywhere) and the client reported all of them:

Source: GWT 2.13.1 source — HibernateValidator.gwt.xml

Rules that follow from the sources and the runs:

Validation.buildDefaultValidatorFactory().getValidator() returns the generated validator. Build it once and keep it: getValidator() calls createValidator() and initialises a new object each time. The validator offers the three standard methods, all measured:

Source: GWT 2.13.1 source — AbstractGwtValidator.java

validateValue is the one to call from a ValueChangeHandler for as-you-type feedback, since it needs no bean. A null property is a violation of @NotNull: for a book with a null title and author the printed output was:

validate returns a HashSet, so the order of the violations is not stable (the Super Dev Mode run printed isbn, year, author, title, copies). Sort them, or key them by property path, before showing them.

getConstraintsForClass(Book.class).isBeanConstrained() returned true, and Validation.buildDefaultValidatorFactory().getClass().getName() was com.example.bookshelf.client.validation.BookshelfValidatorFactory, which confirms that the module’s replace-with rule is the one in force.

A group is an empty interface. Every constraint belongs to Default unless it names groups, and the validator checks only the groups it was generated for. The @GwtValidation annotation must list every group the client will use:

The Bookshelf @Isbn constraint is in Default and in Draft, so the "save as draft" screen can check only the ISBN:

The three lines are validate(book, Book.Draft.class), validate(book, Default.class, Book.Draft.class).size() and validate(book, Default.class).size(): the book has a too short title and a bad ISBN, so Default alone already finds two (the title and the ISBN, which is also in Default), and adding Draft finds the same two.

Asking for a group that was not listed fails at run time, not at compile time:

Validating an object whose class is not in value fails the same way:

Source: GWT 2.13.1 source — AbstractGwtValidator.checkGroups

The upstream sample lists only Person in value although Person has @Valid associations to Address objects, so a bean reached through @Valid is validated as part of its owner and does not need its own entry.

A violation message is a template, interpolated in the browser by GwtMessageInterpolator. The algorithm of the Bean Validation specification runs in this order: replace {key} parameters using the user resolver until nothing changes, then using the provider resolver, repeat while the second step changed something, then replace the annotation’s attributes ({min}, {max}, {value}), and finally remove the escapes. The provider resolver is HibernateValidationMessageResolver, which serves the keys of org.hibernate.validator.ValidationMessages (such as javax.validation.constraints.NotNull.message); the module ships English, German, French, Turkish and Mongolian files, and the GWT locale property selects among them. That is why the violations of the test module, which is fixed to the en locale, are English.

Your own keys need a resolver. A ConstantsWithLookup interface holds the messages, a class that extends AbstractValidationMessageResolver and implements UserValidationMessagesResolver wraps it, and the module replaces the default (NullUserValidationMessageResolver, which returns nothing):

Source: GWT 2.13.1 sample — validation client (CustomValidationMessagesResolver)

AbstractValidationMessageResolver.get replaces each . in the key by _ before the lookup, so book.title.size is read as the method book_title_size. Locale variants are the usual GWT ones: ValidationMessages_es.properties next to the interface, and a compiled es locale (see Internationalization). The constraint says message = "{book.title.size}", and the browser printed Title needs between 3 and 200 characters, with {min} and {max} taken from the annotation.

The server needs the same key or it prints the key itself. Hibernate Validator on the server resolves {book.title.size} from a ValidationMessages.properties at the root of its class path (the Bookshelf server has one with the identical line), and it chooses the language from the JVM default locale, not from the browser:

The first line was printed with the JVM default locale en, the second on the same machine without any code change when the default locale was Spanish.

Pass the user’s locale explicitly (a custom MessageInterpolator or a locale-aware LocaleResolver) if the server’s messages must match the language of the page.

This is the part that changed most since the Developer Guide was written. The guide says that the same constraints can be reused for server-side validation. That is true when the server speaks javax.validation, as Hibernate Validator 4.x, 5.x and 6.2 do. The Bookshelf server runs on Jakarta Servlet 6, and the maintained Bean Validation providers for that platform (Hibernate Validator 7.0 and later; 8.0 for Jakarta EE 10, 9.x for Jakarta EE 11) use the namespace jakarta.validation. Their annotation types are different classes with the same simple names.

The experiment used the Bookshelf Book with javax.validation annotations only, compiled once and validated by Hibernate Validator 9.1.4.Final (Jakarta Validation 3.1.1, Expressly 6.0.0 as the expression language):

The same invalid book that produced five violations in the browser produced none on the server. Hibernate Validator 9 does not read javax.validation.constraints annotations and does not report that it ignored them. This is the most dangerous failure mode of the whole page, because everything compiles, the client works, and the server silently accepts what the browser rejected.

Source: Hibernate Validator — Releases

The Editor framework does not validate; it displays errors that something else computed. EditorDriver.setConstraintViolations(Iterable<ConstraintViolation<?>>) converts each violation into an EditorError at the editor whose path equals the violation’s property path and whose root bean is the instance the driver edited. The workflow of the Bookshelf BookEditor:

Source: GWT — Developer Guide: Editors

A book with the title ab, an empty author field and the year 1200 gave:

trySave() returned false with the invalid book (nothing was passed to the listener) and true after the fields were corrected and the book was edited again.

Two details:

The same page covers ValueBoxEditorDecorator, which shows an error label next to the field, and the RequestFactory driver, whose server side runs a JSR-303 validator of its own: ReflectiveServiceLayer builds Validation.byDefaultProvider().configure() and honours gwt.validation.ignoreXml too.

The scratch application is the three-module Bookshelf (bookshelf-shared, bookshelf-client, bookshelf-server) from the project structure page (Project structure and modules). The pieces added for this page:

The commands that were run (JDK 21, offline Maven after the first resolution):

Results:

Source: GWT 2.13.1 sample — validation

The upstream samples/validation project of the GWT repository (client, shared and server modules generated from the modular-webapp archetype) is the closest official reference: it uses a ServerConstraint in a server group, a custom messages resolver, Validation.byDefaultProvider().configure().ignoreXmlConfiguration() on the server, and throws ConstraintViolationException from an RPC method (all with the javax namespace).