This Grails plugin allows you to create custom domain Constraints for validating Domain objects.
Without this plugin, if you have a custom validation that you want to perform on a Domain object, you have to use a generic validator constraint and define it inline. With this plugin, you can create reusable, shareable constraints that you can use on multiple Domain objects. You can then package Constraints in plugins of their own and reuse them across projects as well.
Plugins are not loaded during Unit Tests, so you cannot test constraints in your unit tests. They should work during integration tests though, so you can test them there.
- Create a groovy file in /grails-app/utils/ called *Constraint.groovy
- Implement a validate closure
- Add appropriate messages to /grails-app/i18n/messages.properties
- Apply the validation to a Domain class
Under /grails-app/utils/:
class UsPhoneConstraint {
def validate = { val ->
return val ==~ /^[01]?[- .]?(\([2-9]\d{2}\)|[2-9]\d{2})[- .]?\d{3}[- .]?\d{4}$/
}
}
Unless you set the defaultMessage static property, then it is a good idea to add an entry to messages.properties with a default format string to show the user if validation fails.
The default format is: default.invalid.constraintName.message
class Person {
String phone
static constraints = {
phone(usPhone: true)
}
}
Any parameters passed to the constraint will be available in your Constraint object via the params property.
e.g. class FooDomain { String prop static constraints = { prop(someConstraint: ['a':1, 'b':2]) } }
def validate = { val ->
def a = params.a
def b = params.b
return val == a + b
}
The validate closure is the main part of the algorithm where validation is performed. It should return a value to indicate if the validation was successful.
Successful validation is indicated by the return of:
- true
- null
An unsuccessful validation is indicated by the return of:
- false
- A String which is used as the error message to show the user
- A Collection with first element being message code, and following elements being message parameters
- An Array with first element being message code, and following elements being message parameters
The validate closure takes up to 3 parameters:
- The value to be validated
- The target object being validated
- The validation errors collection
e.g. def validate = { thePropertyValue, theTargetObject, errorsListYouProbablyWontEverNeed -> return null != thePropertyValue && theTargetObject.rocks() }
Your Constraint can optionally implement a supports closure that will allow you to restrict the types of the properties that the Constraint can be applied to. This closure will be passed a single argument, a Class that represents the type of the property that the constraint was applied to.
e.g.:
class Foo {
Integer bar
static constraints = {
bar(custom: true)
}
}
The CustomConstraint will get an Integer class passed to its supports closure to check.
The default name of the Constraint to use in your Domain object is the name of the class, camelCased, without the tailing Constraint.
e.g.:
- MyConstraint -> my
- UsPhoneConstraint -> usPhone
You can override this by providing a static name variable in your constraint definition:
static name = "customName"
The defaultMessageCode property defines the default key that will be used to look up the error message in the grails-app/i18n/messages.properties files.
The default value is default.$name.invalid.message You can override this by providing a static variable:
static defaultMessageCode = "default.something.unset.message"
The failureCode property defines a key that can be used to lookup error messages in the grails-app/i18n/messages.properties files. The value of this property is appended to the end of the Class.property name that the Constraint is applied to.
The default value is invalid.$name e.g.: With a CustomConstraint defined the default entry in messages.properties will be something like: Person.firstName.custom.invalid
You can override this by providing a static variable:
static failureCode = "unset.constraint"
If no value is found in messages.properties for the defaultMessageCode or the failureCode then this message will be used if it is supplied.
The expectsParams static property allows you to define the required parameters for the Constraint. The expectsParams can be one of:
- Boolean true, saying a parameter is expected
- A List of the named parameters that are expected in a map
- A Closure allowing you to validate the parameters yourself
e.g.:
static expectsParams = ['start', 'end']
static expectsParams = true
static expectsParams = { parameters -> // ... do something }
If you need access to the database to perform your validation, you can make your Constraint a persistent constraint by setting the static property persist = true in your Constraint class.
This will make a hibernateTemplate property available to your Constraint that you can use to access the database. Generally these will be more complicated to write because they require knowledge of the details of the Domain
Set this property in your Constraint class with:
static persistent = true
Persistent constraints are only supported when using the Hibernate plugin.
class SsnConstraint {
static name = "social"
static defaultMessageCode = "default.not.social.message"
def supports = { type ->
return type!= null && String.class.isAssignableFrom(type);
}
def validate = { propertyValue ->
return propertyValue ==~ /\d{3}(-)?\d{2}(-)?\d{4}/
}
}
class Person {
String ssn
static constraints = {
ssn(social: true)
}
}
class StartsAndEndsWithConstraint {
static expectsParams = ['start', 'end']
def validate = { propertyValue, target ->
return propertyValue[0] == params.start && propertyValue[-1] == params.end
}
}
class MyDomain {
String foo
static constraints = {
foo(startsAndEndsWith: [start: 'G', end: 'f'])
}
}
import org.codehaus.groovy.grails.commons.DomainClassArtefactHandler;
import org.hibernate.Criteria;
import org.hibernate.FlushMode;
import org.hibernate.HibernateException;
import org.hibernate.Session;
import org.hibernate.criterion.Restrictions;
import org.springframework.orm.hibernate3.HibernateCallback;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Iterator;
import java.util.List;
class UniqueEgConstraint {
static persistent = true
def dbCall = { propertyValue, Session session ->
session.setFlushMode(FlushMode.MANUAL);
try {
boolean shouldValidate = true;
if(propertyValue != null && DomainClassArtefactHandler.isDomainClass(propertyValue.getClass())) {
shouldValidate = session.contains(propertyValue)
}
if(shouldValidate) {
Criteria criteria = session.createCriteria( constraintOwningClass )
.add(Restrictions.eq( constraintPropertyName, propertyValue ))
return criteria.list()
} else {
return null
}
} finally {
session.setFlushMode(FlushMode.AUTO)
}
}
def validate = { propertyValue ->
dbCall.delegate = delegate
def _v = dbCall.curry(propertyValue) as HibernateCallback
def result = hibernateTemplate.executeFind(_v)
return result ? false : true // If we find a result, then non-unique
}
}
Constraints are standard Grails Artefacts which means that standard things like dependency injection are supported. You can inject a service or other Spring managed beans into your Constraint class if you need to use it.
e.g.
class MyCustomConstraint {
def someService
def validate = { val ->
return someService.someMethod(val)
}
}
Like dependency injection, your constraints classes will have access to the log property if you want to do logging in them.
e.g.
class MyCustomConstraint {
def validate = { val ->
log.debug "Calling MyCustomConstraint with value [${val}]"
// ...
}
}
@TestMixin support has been added to make Constraints easy to test using Unit tests.
e.g.
@TestMixin(ConstraintUnitTestMixin)
class UsPhoneConstraintTest {
@Test
void testUsPhoneValidation() {
def constraint = testFor(UsPhoneConstraint)
// Params are automatically mixed in to the test class and exposed
// to the constraint with the call above.
params = true
assertTrue constraint.validate("5135551212")
assertFalse constraint.validate("bad")
}
}