As a new developer to Grails you’re probably in awe over the vast number of very powerful plugins which are available to you. Without writing a single line of your own code you can do all sorts of cool things like interact with Twitter, Facebook, Amazon’s S3 storage system, Apple Push notifications, Spring Security, and the list goes on and on. As of this writing there are 447 plugins available in the official Grails plugin repository.

It is understandably tempting to leverage all of this code to simply bolt together an integrated solution which solves the problem you’re facing. But there is a downside to consuming someone else’s code, particularly when you’re doing test driven development. Here are some things to consider before you pull the trigger and grails install-plugin.

Using a cannon to kill a mosquito

When you adopt someone else’s code by installing their plugin, you don’t always know about all of it’s capabilities. You very likely did a quick google search, or a keyword search in the grails plugins and found something which appeared to solve the particular problem you were facing. It is very likely though that the plugin you just installed can do what you need, and much MUCH more.

Worse still, it may end up bloating your code with a bunch of functionality that you don’t need, while still not fully solving your problem!

I see a black box and I want to paint it white

If you’re working on a sizable project and collaborating with a team, you’re probably doing TDD, and you probably have a code coverage requirement for your tests. When you install a plugin a lot of the appeal is that it will create a TON of functionality and Grails artifacts for you (controllers, domain classes, services, taglibs etc). If you do have a code coverage requirement, that means that you have to address those new artifacts with tests.

This is a double edged sword. On the bright side, you are forced to really understand what the plugin is doing with the artifacts it provides, and you might discover that you need to rewrite them or refactor them for your application. The negative of course is that you have to expend the mental energy to understand what the author is doing, and how they’re doing it. Very quickly the functionality that you got “for free” isn’t looking so appealing, and you might end up spending as much (or more) time understanding the plugins implementation as you would have to build your own functionality and tests.

The bad that comes with the good

You might have noticed that all but the most mainstream plugins for Grails are not always documented particularly well. This can be a serious barrier to including a plugin in your project as well. If you can’t figure out how to make it work, or get a clear understanding of the inner workings, you may spend more time fiddling with it than leveraging it.

Another consequence of adopting the plugins code is that you inherit the plugins technical debt. The plugin author had a specific problem domain in mind when she wrote the code. If your problem domain is slightly different the compromises built into the plugin may be ones which you’re not willing (or able) to accept.

Looking to the future

If you’ve considered all of these things, and decided that it’s worth the effort to write the tests and accept the technical debt of a plugin, there is one last thing to consider. What happens in the future? What if six months go by and your requirements change, requiring more functionality than your current plugin choice supplies? You could try to find another plugin which covers the new requirement, or you may have to extend the functionality of your chosen plugin. If the plugin you’ve chosen is poorly documented or poorly coded this could be difficult, or impossible, forcing you to pay the price by rewriting all of the functionality provided by the plugin.

Consider too what happens if the plugin author stops maintaining the codebase. When new versions of grails are released, the functionality of the plugin could break and you’re once again forced to maintain code you didn’t write.

Sometimes it’s worth the risk

Of course, I would hardly discourage you from using the plugins that are available, they can be hugely beneficial and save you immense amounts of time. The warning is just to consider the cost of “buying” another developers code and folding it into your solution.

Once you’ve considered all of these things and still decide that a plugin is right for your project you’ll be much better prepared for the effort that comes with using it, and you might just appreciate the functionality that the plugin provides a teeny bit more.

So, I just threw out most of this morning trying to figure out why something which clearly should work was blowing up my unit test on a grails app. To spare you the same pain I’m documenting it here.

The scenario is that I have Roles and Privileges as domain classes. A role has many privileges, and any privilege may belong to one or more roles. This is represented in domain classes pretty succinctly as;

/grails-app/domain/com/nslms/mockdomainlimtations/Role.groovy

package com.nslms.mockdomainlimitations
class Role {
  static hasMany = [privileges: Privilege]
  static constraints = {
  }
  String name
}

/grails-app/domain/com/nslms/mockdomainlimtations/Privilege.groovy

package com.nslms.mockdomainlimitations
class Privilege {
  static constraints = {
  }
  String name
}

So I can access all the privileges which belong to a role pretty easily, but what if I want to know all roles which a particular privilege belongs to? Easy enough, we can look that up in a variety of ways. Below I show adding a new closure to the privilege domain class which uses the withCriteria functionality of GORM to return all roles which have this privilege in the privileges map. The new closure is in the highlighted lines.

/grails-app/domain/com/nslms/mockdomainlimtations/Privilege.groovy (with new closure)

package com.nslms.mockdomainlimitations
class Privilege {
  static constraints = {
  }
  String name
  def getRolesWithThisPrivilege = {
    Role.withCriteria() {
      privileges {
        eq('id', this.id)
      }
    }
  }
}

Now, if you’re doing proper test driven development (you are doing TDD, right?!), you’d probably already have a test written for this new closure that would look something like the highlighted lines of the test fixture below. Notice lines 8 and 9 which are also highlighted to show that we’re asking the framework to mock out the GORM methods on the role and privilege classes.

/test/unit/com/nslms/mockdomainlimitaions/PrivilegeTests.groovy

package com.nslms.mockdomainlimitations
import grails.test.*
class PrivilegeTests extends GrailsUnitTestCase {
  protected void setUp() {
    super.setUp()
    MockUtils.mockDomain(Role.class)
    MockUtils.mockDomain(Privilege.class)
  }
  protected void tearDown() {
    super.tearDown()
  }
  void testAbilityToGetAListOfRolesAPrivilegeBelongsTo() {
    def role1 = new Role(name: 'Administrator')
    def role2 = new Role(name: 'User')
    def priv1 = new Privilege(name: 'ReadAll').save(flush: true)
    role1.addToPrivileges(priv1)
    role2.addToPrivileges(priv1)
    role1.save(flush: true)
    role2.save(flush: true)
    def roleList = priv1.getRolesWithThisPrivilege()
    assert roleList.size() == 2
    assert roleList == [role1, role2]
  }
}

Even after you’ve implemented getRolesWithThisPrivilege on the Privileges domain class though, you’ll find your test still fails with an error that looks like the following.

No signature of method: com.nslms.mockdomainlimitations.Role.withCriteria() is applicable for argument types: (com.nslms.mockdomainlimitations.Privilege$_closure1_closure3) values: [com.nslms.mockdomainlimitations.Privilege$_closure1_closure3@8327473]

In short, it’s telling us that the withCriteria method of GORM isn’t implemented in the context of our test. Of course if you put the exact same code in an integration test you’re golden.

/test/integration/com/nslms/mockdomainlimitations/PrivilegeTest.groovy

package com.nslms.mockdomainlimitations
class PrivilegeTest extends GroovyTestCase {
  void testAbilityToGetAListOfRolesAPrivilegeBelongsTo() {
    def role1 = new Role(name: 'Administrator')
    def role2 = new Role(name: 'User')
    def priv1 = new Privilege(name: 'ReadAll').save(flush: true)
    role1.addToPrivileges(priv1)
    role2.addToPrivileges(priv1)
    role1.save(flush: true)
    role2.save(flush: true)
    def roleList = priv1.getRolesWithThisPrivilege()
    assert roleList.size() == 2
    assert roleList == [role1, role2]
  }
}

With this in place, you can run a “grails test-app -integration” and the exact same test which failed during unit testing will succeed. This is of course because the entire grails bootstrapping occurs, and all of the artifacts (like domain classes) are wired up fully by the framework.

So the moral of the story? If you’re planning to test anything more than simple saves with GORM in your testing phase, consider putting the more complex stuff into an integration test. Either that, or keep your eyes peeled for problems like this and be prepared to refactor.

Feel free to grab a copy of the test grails app I created for this example.

svn export https://linode.nslms.com/svn_ro/MockDomainLimitations

* UPDATE: This example app has a new home..

Grab the project

git clone git://ec2.nslms.com/grails/blog_example_mock_limitations

This is the second installment of my What Grooves You? series of posts, this time discussing how to modularize your Grails application. While Grails does an awesome job of enforcing MVC once your application reaches a certain size, or you have multiple applications which may have shared components, you’re going to have to start thinking about how your going to modularize the reusable parts of your code.

I encountered this pretty quickly because the application I am working on is broken out into two distinct parts, a public facing web form for submitting data (the “Front End”) and a private back office application for managing those user submissions (the “Back End”). These two parts of the application (for compliance reasons) cannot run on the same internet facing system, and the “Back End” must only be available on the internal network. Of course, both of these applications are going to work with the same database and therefore the same Domain classes. It would be dangerous and tedious to try to keep the separate domain classes in each project synchronized with one another.

What won’t work

The RESTful JSON Service

My first thought was to deploy a 3rd application which would be internet visible and act as a proxy for all the database requests. I could then query that application with REST and handle a JSON payload which would be my domain object. This actually seemed pretty elegant since I wouldn’t have to actually share any code between the Front End and Back End applications and I still got a well defined object on either end. The problem of course is that all I get is the data for my domain class, and I don’t have access to any of the functionality that GORM gives me “for free”. I’d have to duplicate search functionality, limits, grouping, sorting, and all sorts of other querying tools in my service. That seemed like an awful lot of work for functionality that is offered by GORM and works very well!

Just JAR it man

The next obvious conclusion is to just toss my domain classes into a library JAR file and reference that library in both of my other applications. This way I actually have the whole domain class and access to the dynamic find methods and all that other good stuff. But, how do you package these? Do you compile the Groovy classes then package the .class files? Will the data source information have to be set for the domain class(es) in the JAR, or will the data source of the application referencing the library be used?

Now some more seasoned Java and Hibernate developers might simply laugh at that barrage of questions, but for me it presented a serious barrier to entry. Fortunately there is a better way.

Just plug it in!

It didn’t take me long to discover that putting my reusable code into a Grails Plugin was the best and most scalable approach. For the sake of demonstration I’m going to take you through an example comment submission and administration application, kinda like blog comments.

The plugin project

First, let’s go ahead and create our plugin project.

grails create-plugin Modular-DAL

Once you’ve got your shiny new plugin created, open it up with your favorite IDE (I use Spring Source Tool Suite) and add a new domain class that you’re going to be sharing.

grails create-domain-class com.nslms.modular.domain.Comment

Now we specify some properties for our new shared domain class.

Comment.groovy

package com.nslms.modular.domain
class Comment {
	static constraints = {
		name(blank:false)
		email(blank:false)
		comment(blank:false)
	}
	String name
	String email
	String website
	String comment
	Boolean isApproved = false
}

With our new shared domain class created, we want to package up our plugin so we can load it into the other projects which we’ll be creating in a moment.

grails package-plugin

That’s it, you’ve just created a (very small) module of your application which contains a shared domain class. This could, of course, contain any number of domain classes, controllers, or services, views, javascript, css, etc. that would be used by other parts of your application, or by other applications.

The Front End

Now, lets create an application which will serve as the “front end” or externally facing form for collecting data.

grails create-app Modular-FrontEnd

Then the very important part of installing the plugin we just created

grails install-plugin ../Modular-DAL/grails-modular-dal-0.1.zip

Because you can download the project I created, I’m not going to go into excruciating detail about the controller and view(s) I setup in my front end, but sufficed to say I am accessing the “Comment” domain class that is supplied by the Modular-DAL plugin project!

CommentsController.groovy (snippet)

import com.nslms.modular.domain.*
class CommentsController {
    def index = { [comments: Comment.findAllByisApproved(true)] }
}

The result of the front end app should be a list of comments which are approved (by the backend) and a submission form to allow you to submit new comments. Kinda like this.

The Back End

Now we need to create the system which will allow you as the administrator to approve the comments submitted by the unwashed masses.

grails create-app Modular-BackEnd

And install the plugin with the shared domain class.

grails install-plugin ../Modular-DAL/grails-modular-dal-0.1.zip

Again because you can download the project I created, here’s just a snippet of the admin controller showing the juicy bits where we use the shared domain class

AdminController.groovy (snippet)

import com.nslms.modular.domain.*;
class AdminController {
    def comments = { [comments: Comment.findAllByisApproved(false)] }
}

The back end app should have a list of all unapproved comments, and a method to approve them. Kinda like this.

Trying it out

Now if you’ve followed along and created your own controllers and views, or downloaded my basic project, you’re going to want to try running both the front end and back end at the same time, persisting data to a common datasource so that you can see the whole thing in action. If you just use the grails run-app command, you’ll find very quickly that you can only run one or the other project, but not both at the same time. This is because they’ll both be trying to run on the common Tomcat port (8080). To overcome this, and run both apps at the same time, try the following starting from the Modular-FrontEnd directory.

grails -Dserver.port=8081 run-app
cd ../Modular-BackEnd
grails -Dserver.port=8082 run-app

Now you should be able to access both applications at http://localhost:8081/FrontEnd and http://localhost:8082/BackEnd respectively.

Download The Project(s)

If you want to download the project(s) and follow along, fire up your favorite subversion client and export everything at svn://linode.nslms.com/blog/grails/Modular or download it here. A couple things to note if you’re grabbing my project, it’s currently setup to use a MySQL database named “modular” running on the same system as the application. If you don’t already have MySQL setup, give XAMPP a look to get you started quickly. Also, I didn’t include the JDBC driver, go fetch it here and drop it into the “lib” directory of both the FrontEnd and BackEnd applications. Lastly, these projects are all written with Grails 1.2.1 so you’ll have to be using 1.2.1 or newer.

* UPDATE: The example apps have a new home..

Grab the projects at

git clone git://ec2.nslms.com/grails/blog_example_modular

This is my first installment in the What Grooves You? series of posts, and it deals with the first thing you’re going to need to consider if you are deploying your Grails/Groovy applications in the average corporate IT infrastructure, Single Sign On with Active Directory and NTLM. Like it or not, because all of our existing applications are based on Microsoft technologies our users have gotten used to just going to the URL for the application they intend to use and being instantly recognized and authenticated. Forcing them to sign in again, or worse still forcing them to setup a new username and password for your system would be completely unacceptable! Below, I’ll take you through the steps I took to solve this problem, including the detours that cost me time!

Throughout this post I’ll be referring to domain objects, controllers, and views which would have been created by running the Acegi LDAP tutorial. So if you want to follow along, go walk through the tutorial, then come back here to see how we tweak it. Be sure to take the “optional” step of creating the views and controllers for the auth domains, you’ll need it not only in the tutorial, but also for some customization we’ll be doing later.

grails generate-manager

You can also download a copy of the Spring Source STS project I used for this application here.

LDAP Single Identity but not Single Sign On

As I started searching to figure out how to authenticate my users, everything seemed to point to using the Acegi Plugin for Grails, and using it with LDAP, tweaked to talk to Active Directory. So, I started down this path and followed the LDAP tutorial for the Acegi plugin. Without a lot of trouble I got this working by following the steps in the tutorial, though I did make a couple significant changes to the SecurityConfig.groovy file to make it play nice with Active Directory

SecurityConfig.groovy

security {
	// see DefaultSecurityConfig.groovy for all settable/overridable properties
	active = true
	useLdap = false
	ldapRetrieveDatabaseRoles = false
	ldapRetrieveGroupRoles = true
	ldapServer = 'ldap://<your-domain-controller>'
	ldapManagerDn = '<your-service-account-dn>'
	ldapManagerPassword = '<your-service-account-password>'
	ldapSearchBase = 'OU=People,DC=yourdomain,DC=com'
	ldapSearchFilter = '(sAMAccountName={0})'
	ldapSearchSubtree = true
	ldapGroupSearchBase = 'CN=Users,DC=yourdomain,DC=com'
	ldapGroupSearchFilter = 'member={0}'
	ldapUsePassword = false
	loginUserDomainClass = "User"
	authorityDomainClass = "Role"
	requestMapClass = "Requestmap"
}

By setting ldapSearchFilter to ‘(sAMAccountName={0})’, we’re telling the Acegi plugin to look for the field in Active Directory that stores the username, this means that users can login just like they’re used to by using their Active Directory user name and password.

The ldapGroupSearchBase and ldapGroupSearchFilter are set such that any domain user groups that a user is a member of become Acegi “Roles” which can be used to determine if a user has authority to do stuff in the application.

Setting ldapUsePassword to false is important too. What we’re telling the Acegi plugin is not to extract the users password from Active Directory. If you don’t set this to false, you’ll get a lovely exception which isn’t particularly useful, java.lang.IllegalArgumentException: Cannot pass null or empty values to constructor. What this is trying to tell you is that the users password is null, which is correct since the default setting for the Acegi plugin is to try to extract the users password from Active Directory, and we haven’t told Acegi what attribute Active Directory stores the password in. By setting ldapUsePassword to false, the plugin provides a bogus password for the user details, and we’re able to proceed without incident.

So, great! If you’ve made these changes and followed the steps in the tutorial to add a user to the application domain with the same username as your Active Directory user you can authenticate users with the username and password they’re already using to login to their computer, we have a single identity for this person. But remember, our users are used to simply going to a URL and not being prompted to login. How do we reproduce that experience?

NTLM Really Single Sign On

Having realized that using Active Directory/LDAP authentication works, but isn’t an actual single sign on solution I started looking into the other settings in the SecurityConfig.groovy file. Turns out there is an NTLM option, but no corresponding tutorial! Here’s my configuration for using NTLM.

SecurityConfig.groovy

security {
	// see DefaultSecurityConfig.groovy for all settable/overridable properties
	active = true
	useNtlm = true
	ntlm.stripDomain = false
	ntlm.defaultDomain = "yourdomain.com"
	ntlm.netbiosWINS = "<your-domain-controller-ip>"
	loginUserDomainClass = "User"
	authorityDomainClass = "Role"
	requestMapClass = "Requestmap"
}

Nothing really outstanding here, I chose to set ntlm.stripDomain to false, so that the users name is not prefixed by the domain, I.E. DOMAIN\username. Also ntlm.defaultDomain and ntlm.netbiosWINS are both required, and I found that the ntlm.netbiosWINS works better if you actually give it the IP address of your domain controller, rather than the DNS name.

With NTLM configured, our Grails app now accepts the users cached authentication from their windows session. True single sign on!

Securing the Security Controllers and BootStrapping

Now we’ve got an application which will use NTLM to authenticate the user, we restrict access using the requestmap, and we add users and their roles using the user and role controllers. The problem, of course is that if you deploy this application anyone can go right to http://yourdomain.com/sso-app/user and add themselves as a user with any roles they see fit! So we need to make sure that our security controllers are secured, and that there is an authorized user that can get in to add users and roles.

Securing the Security Controllers

The first thing we’re going to want to do is secure our authentication controllers. My preference is to do this with annotations on the controllers, so lets secure the UserController and RoleController with annotations. Shown below we annotate them to show that the “ROLE_USER_ADMINISTRATOR” role is necessary to access any of the pages for either controller.

UserController.groovy

import org.codehaus.groovy.grails.plugins.springsecurity.Secured;
@Secured(["ROLE_USER_ADMINISTRATOR"])
/**
 * User controller.
 */
class UserController {
	/* Snip */
}

RoleController.groovy

import org.codehaus.groovy.grails.plugins.springsecurity.Secured;
@Secured(["ROLE_USER_ADMINISTRATOR"])
/**
 * Authority Controller.
 */
class RoleController {
	/* Snip */
}

Enabling the @Secured annotation

Now if you were simply to run the application like this, you’d find that you can still freely navigate to /user and /role without having to be authenticated, that’s because we are still configured to use the Requestmap to restrict access to specific parts of our application. To configure this for use with annotations instead, we only need to make a couple of small changes to the SecurityConfig.groovy file.

SecurityConfig.groovy

security {
	// see DefaultSecurityConfig.groovy for all settable/overridable properties
	active = true
	useNtlm = true
	ntlm.stripDomain = false
	ntlm.defaultDomain = "yourdomain.com"
	ntlm.netbiosWINS = "<your-domain-controller-ip>"
	loginUserDomainClass = "User"
	authorityDomainClass = "Role"
	//requestMapClass = "Requestmap"
	userRequestMapDomainClass = false
	useControllerAnnotations = true
}

Setting useControllerAnnotations to true gives the @Secured annotations on the user and role controllers meaning. By setting userRequestMapDomainClass to false we tell the Acegi security plugin to not even query for restrictions in the database, but to use only the static configuration defined by the annotations. We also delete the requestMapClass line. I commented it here instead of deleting it so it can be highlighted as a change in the file, but we’re not quite done with the requestmap yet. Now that we’ve configured our application not to use the request map we can delete the controller, domain, and views for it. Go ahead and delete the following files.

• /grails-app/controller/RequestmapController.groovy
• /grails-app/domain/Requestmap.groovy
• /grails-app/views/requestmap/*

BootStrapping

Now that we have our app secured, and we’re using annotations to restrict access we need to make sure that some user can successfully login after we first deploy our application. Otherwise no one will be able to access the pages to add new users! So we use boot strapping to add a user administrator who can add more users and roles for the application.

BootStrap.groovy

class BootStrap {
	def authenticateService
	def init = { servletContext ->
		def role = new Role(authority: 'ROLE_USER_ADMINISTRATOR', description:'User Administrator')
		role.save()
		def user = new User(username: 'admin',
				userRealName: 'Administrator',
				passwd: authenticateService.encodePassword('foobar'),
				enabled: true,
				description: '',
				email: '',
				emailShow: false)
		user.addToAuthorities(role)
		user.save()
     }
     def destroy = {
     }
}

So there you have it, an application which allows users to connect using their cached authentication using NTLM, uses annotations to secure your controllers, and actually allows access to at least one user once it’s deployed. Now, there are still some weaknesses. Particularly the level of permissions you can assign is limited to roles, I.E. “Administrator”, “User”, “Reporting User”, “User Administrator”, etc. Also in a corporate environment, having to go through this configuration for every grails app, and adding users and assigning their roles for each app can be tedious. I’ll be looking into improving these things with Acegi ACL’s and possibly using a centralized database for users and roles in future articles so stay tuned!

In my "Day Job", we design and build our applications using Microsoft technologies. In particular, we’re using C#, Silverlight, and IIS to build and deploy our web applications. This makes good sense because the vendors we use are well versed in the Microsoft technology, and like the IT infrastructure of a lot of medium and large companies Microsoft solutions are at the forefront. It’s becoming apparent though that we’re going to have to consider our options and possibly embrace a different technology stack to properly scale and support the applications we’re building.

While I knew that Java servlets and the Spring Framework were the answers, credit goes to my boss Scott Ellis for really doing a deep dive into what technologies are on offer, and coming up with using Grails and Groovy as the best solution for us. Which brings me to the reason for this blog post. I’ve been spending some time playing around with Grails and Groovy, and familiarizing myself with the technology and what is on offer. I intend to do a series of posts here about my discovery process, what problems I encounter, and how I resolve them.

From the searching I’ve had to do in order to get answers or better understanding about the challenges I’ve faced, I think I have a chance to be a real resource to others who are just starting out with Grails and Groovy. What’s more I’m writing from the perspective of a relative newbie to the Java world. Stay tuned as you follow my journey into Grails and Groovy. *Spoiler alert* – I like it, a LOT!