Announcing Grails Constraints Custom Domain Constraint Plugin

I’ve released my first public Grails Plugin today.

The Grails Constraint plugin gives you the ability to create custom Constraints that you can apply to your Domain classes to validate them. These are applied and act just like the built in Domain class constraints.

Why would you want this?

Grails provides two generic, catch-all Constraints in the core application:

  • validator – a generic closure mechanism for validation
  • matches – a regular expression mechanism

While those work, I find myself often wanting to use the same Constraints on multiple Domain classes (think Social Security Number, Phone Number, Zipcode, etc.) and I don’t like to repeat those regular expressions or validations all over the place.

What does this plugin do?

With the Grails Constraints plugin, you can write a custom Constraint class, drop it in /grails-app/utils/ and it will automatically be available to all of your domain classes.

Example

I create a new constrain by hand in /grails-app/utils/ComparisonConstraint.groovy. (You can also use the provided create-constraint script like grails create-constraint com.foo.MyConstraint)

class ComparisonConstraint {
 
    static name = "compareTo"
    static expectsParams = true
 
    def validate = { val, target ->
        def compareVal = target."$params"
        if (null == val || null == compareVal)
            return false
 
        return val.compareTo(compareVal) == 0
    }
}

Then you can apply your constraint to your Domain class:

class Login {
    String password
    String confirm
 
    static constraints = {
        password(compareTo: 'confirm')
    }
}

See Grails Custom Constraints Plugin for the full documentation on what all of the above means and the source code.

Password Strength Validation with Regular Expressions

Regular Expressions are both complex and elegant at the same time. They can be made to look like someone was just randomly hammering on their keyboard. They are also an incredibly efficient and elegant solution to describing the structure of text and matching those structures. They are very handy for defining what a string should look like and as such are very good for use in data validation.

To validate a US phone number you might create a simple regular expression \d{3}-\d{3}-\d{4} which will match a phone number like 123-555-1212. Where regular expressions can become difficult though is when the format is not quite as clear cut. What if we need to support (123) 555-1212 and just 555-1212? Well that’s where things can get more complex. But this is not about validating phone numbers. In this post I will look at how to make assertions about the complexity of a string, which is very useful if you want to enforce complexity of a user created password.

The key to making password strength validation easy using Regular Expressions is to understand Zero-width positive lookahead assertions (also know as zero-width positive lookaheads). Now that’s a mouthful isn’t it? Luckily the concept itself is a lot simpler than the name.

Zero-width positive lookahead assertions

Basically a Zero-width positive lookahead assertion is simply an assertion about a match existing or not. Rather than returning a match though, it merely returns true or false to say if that match exists. It is used as a qualification for another match.

The general form of this is:

(?= some_expression)

For example:

  • The regular expression z matches the z in the string zorched.
  • The regular expression z(?=o) also matches the z in the string zorched. It does not match the zo, but only the z.
  • The regular expression z(?=o) does NOT match the z in the string pizza because the assertion of z followed by an o is not true.

Making Assertions About Password Complexity

Now that you know how to make assertions about the contents of a string without actually matching on that string, you can start deciding what you want to actually assert. Remember that on their own these lookaheads do not match anything, but they modify what is matched.

Assert a string is 8 or more characters:
(?=.{8,})

Assert a string contains at least 1 lowercase letter (zero or more characters followed by a lowercase character):
(?=.*[a-z])

Assert a string contains at least 1 uppercase letter (zero or more characters followed by an uppercase character):
(?=.*[A-Z])

Assert a string contains at least 1 digit:
(?=.*[\d])

Assert a string contains at least 1 special character:
(?=.*[\W])

Assert a string contains at least 1 special character or a digit:
(?=.*[\d\W])

These are of course just a few common examples but there are many more that you could create as well.

Applying Assertions to Create a Complexity Validation

Knowing that these make assertions about elements in a string, but not about a match itself, you need to combine this with a matching regular expression to create you match validation.

.* matches zero or more characters.
^ matches the beginning of a string.
$ matches the end of a string.

Put together ^.*$ matches any single line (including an empty line). With what you know about Zero-width positive lookahead assertions now you can combine a “match everything” with assertions about that line to limit what is matched.

If I want to match a line with at least 1 lowercase character then I can use:
^.(?=.[a-z]).*$
(Which reads something like: start of string, zero or more characters, assert that somewhere in the string is a lowercase character, zero or more trailing characters, the end of the string)

The part that makes this all interesting is that you can combine any number of assertions about the string into one larger expression that will create your rules for complexity. So if you want to match a string at least 6 characters long, with at least one lower case and at least one uppercase letter you could use something like:
^.(?=.{6,})(?=.[a-z])(?=.[A-Z]).$

And if you want to throw in some extra complexity and require at least one digit or one symbol you could make a match like:
^.(?=.{6,})(?=.[a-z])(?=.[A-Z])(?=.[\d\W]).*$

There you go. Now you can create regular expressions to check the complexity of passwords.

For more help with Regular Expressions, you might want to check out:

Grails Validations Based on Related Objects

Grails has a rich set of tools for performing validations of your domain objects. There are quite a few built in validations that you can use. These mainly resolve around validating single properties within a single domain object. It also supports things like validating the sizes of dependent collections.

Sometimes you need to know about the properties of one instance to validate another dependent instance. The property of that dependent instance might be used to determine the valid values of or might provide a limit for a property.

This is more easily explained with an example.

Problem Statement

I’ll use voting for members of the Board of a public company as an example.

A ShareHolder owns N number of shares of stock in a company. When the ShareHolder votes on a Board member of the company, the ShareHolder can assign 1 to N shares to that Candidate. The top 5 Candidates that receive the most Shares (not individual votes) win the election.

We might create a series of Domain classes like this:

class ShareHolder {
    static hasMany = [votes:Vote]
 
    String name
    Double shares
}
 
class Candidate {
    static hasMany = [votes:Vote]
 
    String name
}
 
class Vote {
    static belongsTo = [shareHolder: ShareHolder, candidate: Candidate]
 
    Double voteShares
}

A ShareHolder can vote multiple times, so it has many Votes. A Candidate can be voted for many times, so it has many Votes. A given Vote can be assigned 1 or more shares. But the shares for a given vote must be less than or equal to the number of shares that the voter (the ShareHolder) owns.

Validation

The natural place to perform this validation is on the Vote domain object itself. The problem is that the limit is really the shares value from the ShareHolder domain object. To solve this we can not use a built in validation. Instead we need to create our own.

To do this we can utilize the validator validation. This is no different than any other custom validation that we might need to create. Since we must have the ShareHolder and the Candidate set for this to be a valid object, we can assume that they are available. Because of this we should be able to access their properties to validate our Vote domain object.

Add a custom validator constraint:

class Vote {
    static belongsTo = [shareHolder: ShareHolder, candidate: Candidate]
 
    Double voteShares
 
    static constraints = {
        voteShares(min: 0D,
                validator: {
                    val, obj ->
                    val <= obj.shareHolder?.shares
                })
    }
}

As you can see, the obj that gets passed in is the instance that is being validated. The val is the value of the property being validated, in this case the voteShares property. All that has to be done is to compare the value of the obj.shareHolder?.shares too the voteShares property. The obj.shareHolder?. should protect us against a null reference in case the shareHolder isn’t set. Then the validation will just fail on not having the ShareHolder.

Nothing really tricky here, just something interesting I ran into recently.

Custom Validators in Grails in a Single App

In my previous post I wrote about Building a Custom Validator in Grails using a Plugin. That’s a great way to build a reusable Constraint that will allow you to share your code among multiple projects. But often you only have one application that you are building, or a validator is a very domain specific thing that will only make sense in a single app.

Building the Constraint in a Single App

Please look at the previous post for the details of the Plugin.
As I mentioned in that post a plugin looks almost exactly like a Grails App. Just like in the plugin case, your grails app has a src/groovy and a src/java directory where you can put general code. In this case I wrote the Constraint in the src/groovy directory as I wanted to use the Groovy language and some of the fun dynamic techniques it offers.

Hook it into the App

Here’s the simple part. The goal, as we saw in the plugin example, is to register your custom Constraint with the Grails ConstrainedProperty class. I just took a guess on this one and it worked. Grails provides the
Config.groovy class to setup a bunch of things in your application. So all you need to do is add the ConstraintProperty configuration to your Config.groovy script and your application will have a new constraint:

Config.groovy

org.codehaus.groovy.grails.validation.ConstrainedProperty.registerNewConstraint(
PostalCodeConstraint.POSTAL_CODE_CONSTRAINT, PostalCodeConstraint.class)

Have fun building your own Constraints!

Build a Custom Validator in Grails with a Plugin

Grails is a really nice MVC framework inspired by Ruby on Rails. The difference is that Grails is built using Groovy and Java and leverages existing, well known frameworks as it’s foundation. It is essentially a fairly thin convention-over-configuration and integration layer on top of Spring and Hibernate. The documentation for common scenarios is pretty good, but once you get outside of the common cases it deteriorates pretty quickly. This is part of my contribution I guess.

Constraints and Validation

Grails has a fairly good set of built in constraints to use to validate your domain objects. This allows you to decorate your Domain with constraints which are validated prior to persisting the objects.

class Address {
    String street
    String city
    String state
 
    static constraints = {
        street(nullable:true)
        city(blank:false)
        state(size:2..2)
    }
}

You can find a comprehensive list of the built in validations on the Grails website. It includes the ability to create a custom validator for a domain class if the built in ones do not suffice. So you can write a validator inline to your domain object.

class Student {
    String name
    Calendar dateOfBirth
    Calendar enrollmentDate
 
    static constraints = {
        name(blank:false)
        dateOfBirth(blank:false, validator: { val, obj ->
            // Ensure that the date of birth is before the enrollment date
            return ! val.after(obj.enrollmentDate)
        }))
    }
}

This validator is just a closure, so you could write it external to the class and reuse it among many different domain classes. I was interested to know how to create a “first-class” validator though that looked and acted just like the built in ones.

Create a Plugin

Grails is essentially built as a series of plugins. Everything from Hibernate support to Service Injection is implemented as a Plugin. Because of this it obviously must have a strong plugin system that allows you to do almost anything. So I decided to look at using a plugin to create a shared validation.

So, first: Generate a plugin.
On the command line issue the command grails create-plugin MyApp. This will create a directory containing everything you need to construct a new plugin. The directory really looks like a mini Grails application. In fact you can run it exactly as a grails app which is great for testing.

This will create a src/ directory in the plugin as well. We can create our validator in there. You can create some directories under src/groovy or src/java to create a package. Use groovy or java depending on which language you want to use to implement your validator.

Create your Validator

Grails provides org.codehaus.groovy.grails.validation.AbstractConstraint as a simple base class to inherit from to get the basic functionality. Of course if you want to implement the whole thing yourself you just need to implement the interface
org.codehaus.groovy.grails.validation.Constraint. That would be a lot of work, so just inherit from the AbstractConstraint.

Here’s an example of a constraint used to validate a Postal Code (or zip code). This is a simple implementation that supports validating Canadian and US postal codes.

package net.zorched.validation
 
import org.codehaus.groovy.grails.validation.AbstractConstraint
import org.springframework.validation.Errors
 
class PostalCodeConstraint extends AbstractConstraint {
 
    private static final String DEFAULT_NOT_POSTAL_CODE_MESSAGE_CODE = "default.not.postalCode.message";
    public static final String POSTAL_CODE_CONSTRAINT = "postalCode";
 
    private boolean postalCode;
 
    private US = { postalCode->
        postalCode ==~ /\d{5}/
    }
 
    private CA = { postalCode->
        postalCode ==~ /[A-Z]\d[A-Z] \d[A-Z]\d/
    }
 
    public void setParameter(Object constraintParameter) {
        if(!(constraintParameter instanceof Boolean))
        throw new IllegalArgumentException("Parameter for constraint ["
               +POSTAL_CODE_CONSTRAINT+"] of property ["
               +constraintPropertyName+"] of class ["
               +constraintOwningClass+"] must be a boolean value");
 
        this.postalCode = ((Boolean)constraintParameter).booleanValue();
        super.setParameter(constraintParameter);
    }
 
    protected void processValidate(Object target, Object propertyValue, Errors errors) {
        if (! validPostalCode(target, propertyValue)) {
            def args = (Object[]) [constraintPropertyName, constraintOwningClass, 
            propertyValue]
            super.rejectValue(target, errors, DEFAULT_NOT_POSTAL_CODE_MESSAGE_CODE, 
                "not." + POSTAL_CODE_CONSTRAINT, args);
        }
    }
 
    boolean supports(Class type) {
        return type != null && String.class.isAssignableFrom(type);
    }
 
    String getName() {
        return POSTAL_CODE_CONSTRAINT;
    }
 
    boolean validPostalCode(target, propertyValue) {
        def country = "US"
        if (target.metaClass.hasMetaProperty("country")) {
            country = target.country
        }
        println country
        this."$country"(propertyValue)
    }
}

The name property is the key used to match your validator in your domain class to this Constraint instance.

class Address {
    String street
    String city
    String state
    String postalCode
    String country = "US"
 
    static constraints = {
        street(nullable:true)
        city(blank:false)
        state(size:2..2)
        postalCode(blank:false,postalCode:true)
    }
}

Unit Test It

You’ll notice that I wrote the main algorithm for doing the validation as its own method. That will make it easy for me to write Unit Tests to confirm the functionality of my validator before I implement it in a domain class. So, now when someone comes back and wants to support Zip+4 in the US, I’ll can write a test, see that it fails and then fix my Constraint to support that case as well.

class PostalCodeConstraintTests extends GroovyTestCase {
 
	void test_us_postal_code_succeeds_for_valid() {
		def postalCodeConstraint = new PostalCodeConstraint()
		def address = new Address(country:"US", postalCode:"53212")
 
		assert postalCodeConstraint.validPostalCode(address, address.postalCode)
	}
 
	void test_us_postal_code_fails_for_canada() {
		def postalCodeConstraint = new PostalCodeConstraint()
		def address = new Address(country:"US", postalCode:"A1A 3E3")
 
		assert ! postalCodeConstraint.validPostalCode(address, address.postalCode)
	}
 
	void test_ca_postal_code_succeeds_for_valid() {
		def postalCodeConstraint = new PostalCodeConstraint()
		def address = new Address(country:"CA", postalCode:"A1A 1D3")
 
		assert postalCodeConstraint.validPostalCode(address, address.postalCode)
	}
}
 
class Address {
	String country
	String postalCode
}

Wire It Into Grails

The only thing left to do is to register your Constraint so that Grails knows about it. When you created the plugin, grails generated a plugin “bootstrap” class for you. You can do that by registering your class with the ConstrainedProperty class provided by the Grails framework.

import net.zorched.validation.PostalCodeConstraint
 
import org.codehaus.groovy.grails.validation.ConstrainedProperty
 
class MyAppPlugin {
    def version = 0.1
    def author = "Geoff Lane"
    def description = '''
This plugin adds specific functionality to the application for my app.
'''
    def dependsOn = [:]
	def loadAfter = ['controllers']
 
    def doWithSpring = {
        ConstrainedProperty.registerNewConstraint(
            PostalCodeConstraint.POSTAL_CODE_CONSTRAINT, 
            PostalCodeConstraint.class);
    }
}

ConstrainedProperty basically keeps a map of the constraint keys to the class type that implements the constraint.

Conclusion

Grails Plugins basically allow you to do anything that you might want to create an easily packaged piece of reusable functionality. I didn’t find a anything in the documentation about how to build validators like the built in ones, so I read a bunch of source code. Now you don’t have to, except for fun.


UPDATE: Please check out the Grails Custom Constraints plugin that automates all of this at http://grails.org/plugin/constraints