Using those _Install.groovy and _Upgrade.groovy scripts

So you’ve created your first Grails plugin and notice that you have these _Install.groovy and _Upgrade.groovy files in your plugin scripts directory.  ”What are these for?” you ask, and promptly remove them - but if utilized them correctly, they’re a great way to make sure your plugin works well with whichever version of Grails your clients are using.

For example, I recently updated the Code-Coverage plugin to work with Grails 1.0.4.  ”Events.groovy” is now deprecated, instead we’re supposed to start using “_Events.groovy” (result of JIRA bug 3467).  The Code-Coverage plugin uses an Events.groovy script to exclude the Cobertura jar files from the WAR file so you don’t end up with Cobertura resources in a production environment.  I could just rename the file from Events.groovy to _Events.groovy and release a new version of the plugin - but that would mean that anyone using the latest version of the plugin on Grails versions prior to 1.0.4 wouldn’t get the exclusion feature that Events.groovy provides!  It would be better to find a fix that’s more backwards compatible.

Enter the _Install.groovy and _Upgrade.groovy scripts!  Using the _Install.groovy script, I can add some logic that Grails will execute as part of the “grails install-plugin” command.

String pluginDir = binding.getVariable('code-coveragePluginDir')
 
if (grailsVersion == '1.0.4'){
	Ant.move(file:"${pluginDir}/scripts/Events.groovy", 
		tofile:"${pluginDir}/scripts/_Events.groovy", 
		failonerror:false)
}

In this example, I’m checking to see if the version of Grails is 1.0.4, and if it is, I rename the file and add an underscore to the name.  This means that if someone installs the plugin with Grails 1.0.3, they’ll have an Events.groovy file - but if they have Grails 1.0.4, the file will be renamed to _Events.groovy for them automatically.

Aside: I thought I would be able to use the ${codeCoveragePluginDir} variable but there’s a small bug in the InstallPlugin script that doesn’t set the pluginDir variable correctly (it’s using the directory name instead of getting it from the plugin definition file, e.g. CodeCoveragePlugin.groovy) - so instead I get the variable directly out of the Groovy binding.

The _Upgrade.groovy script works the same way - although in this case I can simply use the “codeCoveragePluginDir” variable that is bound through GrailsScriptRunner to find the correct plugin directory.

if (grailsVersion == '1.0.4'){
	Ant.move(file:"${codeCoveragePluginDir}/scripts/Events.groovy", 
		tofile:"${codeCoveragePluginDir}/scripts/_Events.groovy", 
		failonerror:false)
}

Now if a client of the plugin is using Grails 1.0.3 and upgrades to 1.0.4, the _Upgrade.groovy script will rename Events.groovy to _Events.groovy for them (and therefore they won’t see the nice “Use of ‘Events.groovy’ is DEPRECATED.  Please rename to ‘_Events.groovy’.” warning message every time they run a Grails command.