Setting up mail support in your Grails application

At some point in your Grails application development you’ll find yourself invariably needing your application to send mail.  With the Grails mail plugin, it’s a snap.  Essentially the mail plugin is a wrapper to configure a Spring MailSender instance.  And the Spring MailSender is a wrapper to the JavaMail API. As long as you know about these libraries and implementation details, using Grails mail is pretty straightforward.  First start by adding following dependency reference to your plugins section of your project’s BuildConfig.groovy file:

 
    plugins {
        //.. other plugs 
        compile ":mail:1.0.1"
    }

You can also use the “standard” approach to install the plugin as well:

grails install-plugin mail

Next you need to configure the mail plugin to know what smtp server to use in Config.groovy:

 

grails {
    mail {
        host = "mail.yourdomain"
        port = 25
        props = ["mail.smtp.from":"david.orrissjr@yourdomain"]
    }
}

The ‘props’ section can be populated with any of the properties defined in the JavaMail API to leverage the various SMTP features.  Take note to be very careful with them and read the RFCs on the SMTP protocol before you attempt to use something you aren’t familiar with.

Finally a simple call in your controller to the sendMail method that you provide a closure for is all that’s needed to send an email.

 
class MailSendController {

    def sendMessage () {
        sendMail {
            to "davido@yourdomain"
            subject "Hello from the sendmail plugin"
            body "Hello from the sendmail plugin.  Here's the email you wanted."
        }

        render "EMail sent."

    }

} 

There are plenty of other ways you can leverage the mail plugin as well.  You can find more details on the grails mail plugin page:

http://grails.org/plugin/mail

And the Mail Plugin documentation page: http://gpc.github.io/grails-mail/

To see what other features you can leverage you should also read about the JavaMail plugin itself and the SMTP properties that can be set in the JavaMail session object.  You can find out more about that subject here:

http://javamail.kenai.com/nonav/javadocs/com/sun/mail/smtp/package-summary.html

Grails and Legacy Data – Composite Keys in your Tables

When developing a Grails app, you don’t always have the luxury of using GORM (the Grails ORM) ‘out of the box’ against new schemas. Sometimes you just have to work with legacy data as you get it with little modification (if any). Today I’m going to show some of the tricks/traps for working with legacy data when creating a new grails application. There are a few pitfalls that aren’t well-documented with the help of this article you should be able to avoid them.

Mapping Metadata to your Domain Class

GORM is really powerful, but it imposes its own “world view” on table and metadata structures. That can be fine when you start from scratch on a new application. But what happens when you have data that doesn’t match that world view? You could consider revising the table structure and impact all of your other applications. Or you can simply structure your Grails domain class to fit the data you’re working with.

Consider the following table. For this example I’m using MySQL but any popular SQL server  would work:

CREATE TABLE `application_config` (
  `CONFIG_NAME` varchar(128) NOT NULL,
  `KEYNAME` varchar(128) NOT NULL,
  `VALUE` varchar(1024) NOT NULL,
  `DESCRIPTION` mediumtext,
  `LAST_UPDATED` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  `VERSION` decimal(10,0) NOT NULL DEFAULT '0',
  PRIMARY KEY (`CONFIG_NAME`,`KEYNAME`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8

This looks simple enough, but Grails will puke on it if you try to use it as-is for a couple of reasons:

  • GORM wants an auto-incrementing large integer field called ‘id’ to be the primary and unique key for the table. A primary key is required by GORM and quite frankly you shouldn’t even bother doing work in SQL databases if you’re not going to use them.
  • GORM also wants a version field for managing changes via optimistic locking. This isn’t a requirement, but I’d strongly recommend adding this field to your tables. Even a simple non-null field defaulting to a value of ‘1’ would be sufficient and your grails app will be more robust for it.

According to the Grails documentation there is support for Composite Primary Keys.  From their website:

GORM supports the concept of composite identifiers (identifiers composed from 2 or more properties). It is not an approach we recommend, but is available to you if you need it.

They aren’t kidding.  They not only don’t recommend it but they don’t document very well how to do it, either.

First step is to create your domain class.  For this we’ll call it AppConfigInfo:

grails create-domain-class AppConfigInfo

After being greeted with your empty domain class, lets start adding the data members that will be mapped to the database:

class AppConfigInfo implements Serializable {
	String configName
	String propertyName
	String propertyValue
	String description
	Date updated

	static constraints = {
    }
}

I’ve added the reference to implements Serializable because as we add the rest of the mapping information to the class serialization will be required.

The next thing we need to do is configure constraints for the table.  While not required I’d strongly recommend it.  This way you don’t have issues with your primary key having blank entries.

/*
 * basic constraints to specify the field order. needed when
 * views are generated for the controller
 *
 */
 static constraints = {
	configName (blank:false)
	propertyName (blank:false)
	propertyValue (blank:false)
	description (maxSize:80)
	updated()
 }

Now we’ve enforced basic input validation, but we still need to map the data attributes of this class back to the columns in the table. That’s what the mapping block is for:

/*
 * this mapping configures the columns to match up to the legacy
 * database table.
 */
static mapping = {
	table 'APPLICATION_CONFIG'
	// this line will disable the version number support required
	// for GORM optimistic locking.  comment out or remove
	// if you want to support locking (recommended, not required)
	version false
	id composite:['configName','propertyName']
		
	//maps the columns to the properties in the domain
	columns {
		configName column:'CONFIG_NAME'
		propertyName column:'KEY_NAME'
		propertyValue column:'VALUE'
		description column:'DESCRIPTION', type:'text'
		updated column:'LAST_UPDATED'
	}
}

 

Note the columns block above. That’s the final piece for the mapping. With that block, grails knows which fields will be mapped to your legacy table. That leaves us with only a couple other lines tasks left. We need the code to handle the field called updated and the code to return the composite key to your controller. Also if you have two different fields for creation and update timestamps instead of one, you can skip the handling code below and just write the code that returns the primary key:

//if you have separate columns for created and updated timestamps
//you can skip this code and map the above columns accordingly
//most of the time in my experience, schemas have only one column for this
	
def beforeInsert = {
	updated = new Date()
}
	
def beforeUpdate = {
	updated = new Date()
}
	
def getPK() {
	["configName":configName, "propertyName":propertyName]
}

At this point if you got the idea that you could just generate a controller and use the built-in dynamic scaffolding like this to test out the design so far:

class ConfigureController {
    def scaffold=AppConfigInfo
}

It’ll sort of work, but you’ll have some hiccups. For example: you will be able to create new records like this

Grails Create Screen1

But you won’t be able to edit the entry because the scaffold only recognizes the GORM model of using the standard ‘id’ unique key. Note the empty column for ID:

Grails List Screen1

This fix for this requires generating the full set of views and the fully implemented controller. From there we can modify the views and controller to do what we need. Besides, you’d never actually use the dynamic scaffolding for any real work, anyway

grails generate-all AppConfigInfo

There’s a few other things that have to be updated also. We’ll have to replace the code that supports the GORM id field with code that enables the use of our composite key. When you try to start your application, list will work but clicking the ‘Details’ link generate exceptions like this:

Error 500: Executing action [show] of controller [example.AppConfigInfoController] caused
 exception: groovy.lang.MissingMethodException: No signature of method: example.AppConfigInfo.getPK() 
is applicable for argument types: (org.codehaus.groovy.grails.web.servlet.mvc.GrailsParameterMap) 
values: [[propertyName:english.language.error.expired.password, configName:I18N, action:show, 
controller:appConfigInfo]] Possible solutions: getPK(), getId(), get(java.lang.Object), 
getAt(java.lang.String), getAll(), getLog()

On the bright side, create may just work for you immediately so that’s at least one area you’ll be able to leave alone. Fortunately, Grails actually is attempting to give you a hint on how to resolve this as well with the following line:

Possible solutions: getPK(), getId(), get(java.lang.Object), 
getAt(java.lang.String), getAll(), getLog()

The use of get(java.lang.Object) is the hint. Note that your controller for the ‘show’ action has a line like this:

def appConfigInfoInstance = AppConfigInfo.get(params.id)

In order to leverage the composite key we’ll need to modify two files, the controller and the views for the show and list actions. First change your controllers show action to something like this:

def appConfigInfoInstance = AppConfigInfo.get(new AppConfigInfo(params))

This fulfills the contract suggested by grails stacktrace.

Next the view for the list action (list.gsp) has to be modified so that we can click on the “Details” link and correctly load the show action. Modifying the line shown below is the trick:

<g:each in="${appConfigInfoInstanceList}" status="i" var="appConfigInfoInstance">
    <tr class="${(i % 2) == 0 ? 'odd' : 'even'}">
    
        <td><g:link action="show" id="${appConfigInfoInstance.getPK()}">Details</g:link></td>
    
…

</g:each>

Changing the id attribute to a params attribute bridges the gap to the controller:

<g:each in="${appConfigInfoInstanceList}" status="i" var="appConfigInfoInstance">
    <tr class="${(i % 2) == 0 ? 'odd' : 'even'}">
    
        <td><g:link action="show" params="${appConfigInfoInstance.getPK()}">Details</g:link></td>
    
…

</g:each>

Next, we need to modify the views for Edit and Delete. Let’s tackle Edit first. GORM supports optimistic locking via a numeric “version” field for tables that are set up to support it. For this demo we’ve disabled it. So change edit.gsp from this:

<g:form method="post" >
    <g:hiddenField name="id" value="${appConfigInfoInstance?.id}" />
    <g:hiddenField name="version" value="${appConfigInfoInstance?.version}" />

To this:

<g:form method="post" >
    <g:hiddenField name="id" value="${appConfigInfoInstance.configName}" />
    <g:hiddenField name="value" value="${appConfigInfoInstance.propertyName}" />

To complete the change we also need to the show.gsp view:

<div class="buttons">
    <g:form>
        <g:hiddenField name="id" value="${appConfigInfoInstance?.id}" />
        <span class="button"><g:actionSubmit class="edit" action="edit" value="${message(code: 'default.button.edit.label', default: 'Edit')}" /></span>
        <span class="button"><g:actionSubmit class="delete" action="delete" value="${message(code: 'default.button.delete.label', default: 'Delete')}" onclick="return confirm('${message(code: 'default.button.delete.confirm.message', default: 'Are you sure?')}');" /></span>
    </g:form>
</div>

To reflect the composite key as shown:

<div class="buttons">
    <g:form>
        <g:hiddenField name="id" value="${appConfigInfoInstance.configName}" />
        <g:hiddenField name="value" value="${appConfigInfoInstance.propertyName}" />
        <span class="button"><g:actionSubmit class="edit" action="edit" value="${message(code: 'default.button.edit.label', default: 'Edit')}" /></span>
        <span class="button"><g:actionSubmit class="delete" action="delete" value="${message(code: 'default.button.delete.label', default: 'Delete')}" onclick="return confirm('${message(code: 'default.button.delete.confirm.message', default: 'Are you sure?')}');" /></span>
    </g:form>
</div> 

For the sake of completeness I’ve also included the sample code from my application here. This application was built in SpringSource Tools Suite – if you use the same toolset you should have no problem importing it and playing with it.

AppConfigTool.zip

Grails is a powerful framework, geared toward maximizing web application productivity in the Java ecosphere. With a few adjustments you can leverage this powerful framework in a variety of situations.

Getting Started with Grails

Grails is an open-source, rapid web application development framework that provides a super-productive full-stack programming model based on the Groovy scripting language and built on top of Spring, Hibernate, and other standard Java frameworks.

At least that’s what the marketing hype says.

My take – Grails is an open-source answer to Rails for the Java Enterprise crowd.  It’s got all the flexibility of Ruby on Rails with the added benefit of being able to quickly leverage Java SDK resources from within the underlying language (called Groovy).  I’ve recently been working with Grails and a can say it’s an excellent platform for rapidly developing web front-ends that can work with your existing enterprise infrastructure.  Even better, it can work with almost seamlessly with your current/legacy Java application codebase.  But the trick to all of this is getting started.  The available documentation that you find online could be FAR better (and I’ll talk about that in other posts) but here are some resources and books that I’ve found to be excellent starting points.

Programming Groovy: Dynamic Productivity for the Java Developer

by Venkat Subramaniam

Vslg To become proficient at Grails, you need to understand the Groovy Programming language, it’s constructs, and it’s importance in contrast to the Java ecosphere. Dr. Subramaniam’s book provides an excellent foundation and starting point. I’ve kept the printed edition in my backpack with me and refer to it regularly. I’ve found the information and insights Dr. Subramaniam provides to be invaluable.You can order the printed and PDF book editions at the Pragmatic Programmer’s Website:


http://pragprog.com/book/vslg/programming-groovy

Getting Started with Grails, Second Edition

Scott Davis & Jason Rudolph

LandingPageCoverSo you’ve started reading about Groovy, but you need to find out more about Grails… This book is the next logical step in that progression. Davis’ and Rudolph’s book provides a step-by-step example showing how to create a basic application (called Racetrack) that takes you along the same development lines that the Depot application in the Dave Thomas/David Heinemeier Hansson Rails book does. You’ll learn how to leverage the underlying Hibernate layer via GORM (Grails Object Relational Mapping), connecting to external databases, the basics for developing robust MVC-based applications using GSP and Grails controllers, implementing basic security and user authentication, and working with the vast plugin library available to Grails developers. The best part is you can the book is in a “try before you buy” model. You can download the book for free from the InfoQ website, and if you find you like the book and find it useful, you can support the author’s efforts and buy a print version. I found the book valuable and was able to get a basic version of an application completed for a project in a day after working through the Racetrack example.

http://www.infoq.com/minibooks/grails-getting-started

The Groovy Language Homepage

Before you can do Grails – you need to get Groovy. Go here and get your Groove on.

http://groovy.codehaus.org/

The Grails Quick Start

Get grails direct from the source at Grails.org. If you want to spin up a Grails application and you are familiar with Ruby and Rails – this will get you going fast. Be sure to read the Installation section for getting the Grails environment configured and running before you use the Quick Start or you’ll get nowhere fast.

http://grails.org/Quick+Start