Scripting events

Added by Marc Palmer, last edited by Marc Palmer on Jun 08, 2007  (view change)

Scripting events

As of v0.5 there is now the ability to hook into scripting events. These are events triggered during execution of Grails target and plugin scripts.

For example, you can hook into status update output (i.e. "Tests passed", "Server running") and the creation of files or artefacts.

The mechanism is deliberately simple and loosely specified. The list of possible events is not fixed in any way, so it is possible to hook into events triggered by plugin scripts, for which there is no equivalent event in the core target scripts.

Defining event handlers

Event handlers are defined in a script called Events.groovy either in the scripts/ folder of a plugin, or in your .grails/scripts/ folder in your user home directory. All events scripts are called whenever an event occurs, so you can have 10 plugins handling events and also a custom per-user script.

Event handlers are closures defined in Events.groovy, with a name beginning with "event". The following example can be put in your <home>/.grails/scripts/:

Events.groovy
eventCreatedArtefact = { type, name ->
   println "Created $type $name"
}

eventStatusUpdate = { msg ->
	println msg
}

eventStatusFinal = { msg ->
	println msg
}

You can see here the three handlers eventCreatedArtefact, eventStatusUpdate, eventStatusFinal. Currently Grails scripting will generate the following events:

Not all the scripts have been updated in SVN head so not all of these occur, and some only occur for certain targets.


Event Parameters Description
StatusUpdate message Passed a string indicating current script status/progress
StatusError message Passed a string indicating an error message from the current script
StatusFinal message Passed a string indicating the final script status message, i.e. when completing a target, even if the target does not exit the scripting environment
CreatedArtefact artefactType,artefactName Called when a create-xxxx script has completed and created an artefact
CreatedFile fileName Called whenever a project source filed is created, not including files constantly managed by Grails
Exiting returnCode Called when the scripting environment is about to exit cleanly
PluginInstalled pluginName Called after a plugin has been installed (Since 0.5.5)
CompileStart kind Called when compilation starts, passing the kind of compile - source or tests (Since 0.5.5)
CompileEnd kind Called when compilation is finished, passing the kind of compile - source or tests (Since 0.5.5)
SetClasspath rootLoader Called during classpath initialization so plugins can augment the classpath with rootLoader.addURL(...). Note that this augments the classpath after event scripts are loaded so you cannot use this to load a class that your event script needs to import, although you can do this if you load the class by name. (Since 0.5.5)

Triggering events

If you are writing a custom script for a plugin you should ensure that you follow existing conventions for event generation, and add any new useful events relating to your plugin.

To trigger an event simply include the Init.groovy script and call the event() closure:

Ant.property(environment:"env")
grailsHome = Ant.antProject.properties."env.GRAILS_HOME"

includeTargets << new File ( "${grailsHome}/scripts/Init.groovy" )

...

event("StatusFinal", ["Super duper plugin action complete!"])

Labels

 
(None)