org.codehaus.groovy.grails.plugins
Interface GrailsPlugin

All Superinterfaces:

ApplicationContextAware

All Known Implementing Classes:

AbstractGrailsPlugin, AwarePlugin, DefaultGrailsPlugin

public interface GrailsPlugin
extends ApplicationContextAware

Plugin interface that adds Spring BeanDefinitions to a registry based on a GrailsApplication object. After all GrailsPlugin classes have been processed the BeanDefinitions in the registry are loaded in a Spring ApplicationContext that's the singular configuration unit of Grails applications.

It's up to implementation classes to determine where GrailsPlugin instances are loaded from.

Since:

0.2

Author:

Steven Devijver, Graeme Rocher

See Also:

BeanDefinitionRegistry

Field Summary

static String	ARTEFACTS Define the list of ArtefactHandlers supporting by the plugin
static String	DEPENDS_ON Defines the name of the property that specifies which plugins this plugin depends on
static String	DO_WITH_APPLICATION_CONTEXT Defines the name of the property that defines a closure that will be invoked after intialisation and when the application context has been built
static String	DO_WITH_DYNAMIC_METHODS
static String	DO_WITH_SPRING Defines the name of the property that defines the closure that will be invoked during runtime spring configuration
static String	DO_WITH_WEB_DESCRIPTOR Defines the name of the property that defines the closure that will be invoked when the web.xml is being generated
static int	EVENT_ON_CHANGE
static int	EVENT_ON_CONFIG_CHANGE
static String	EVICT Defines the name of the property that specifies a List or plugins that this plugin evicts Eviction occurs when the PluginManager loads
static String	INFLUENCES Defines the name of the property that defines a list of plugin names that this plugin influences.
static String	ON_CHANGE Defines the name of the property that defines the closure that will be invoked when a watched resource changes
static String	ON_CONFIG_CHANGE Defines the name of the property that defines the closure that will be invoked when a the Grails configuration object changes
static String	PROVIDED_ARTEFACTS The name of the property that provides a list of shipped, but overridable artefactssw
static String	STATUS The status of the plugin
static String	STATUS_DISABLED When a plugin is "disabled" it will not be loaded
static String	STATUS_ENABLED When a plugin is "enabled" it will be loaded as usual
static String	TRAILING_NAME Defines the convention that appears within plugin class names
static String	VERSION Defines the name of the property that specifies the plugin version
static String	WATCHED_RESOURCES Defines the name of the property that specifies resources which this plugin monitors for changes in the format a Ant-style path

Method Summary

boolean	checkForChanges() When called this method checks for any changes to the plug-ins watched resources and reloads appropriately
void	doArtefactConfiguration() Called prior to the initialisation of the GrailsApplication instance to allow the registration of additonal ArtefactHandlers
void	doWithApplicationContext(ApplicationContext applicationContext) This method is called to allow the plugin to add BeanDefinitions to the BeanDefinitionRegistry.
void	doWithDynamicMethods(ApplicationContext applicationContext) Calls a "doWithDynamicMethods" closure that allows a plugin to register dynamic methods at runtime
void	doWithRuntimeConfiguration(RuntimeSpringConfiguration springConfig) Executes the plugin code that performs runtime configuration as defined in the doWithSpring closure
void	doWithWebDescriptor(groovy.util.slurpersupport.GPathResult webXml) Handles processing of web.xml.
String[]	getDependencyNames()
String	getDependentVersion(String name) The version of the specified dependency
String[]	getEvictionNames()
groovy.lang.GroovyObject	getInstance() Retrieves the wrapped plugin instance for this plugin
String[]	getLoadAfterNames() Retrieves the names of plugins that this plugin should be loaded after.
GrailsPluginManager	getManager() Retrieves the plugin manager if known, otherwise returns null
String	getName()
String[]	getObservedPluginNames() Retrieve the plugin names that this plugin is observing for changes
Class[]	getProvidedArtefacts() Retrieves an array of provided Artefacts that are pre-compiled additions to the GrailsApplication object but are overridable by the end-user
String	getVersion()
boolean	isEnabled()
Map	notifyOfEvent(int eventKind, Object source) Notifies the plugin of a specific event for the given event id, which is one of ON_CHANGE, ON_CONFIG_CHANGE
void	notifyOfEvent(Map event) Notifies this plugin of the specified Event calling the onChange listener
void	refresh() Refreshes this Grails plugin reloading any watched resources as necessary
void	setApplication(GrailsApplication application)
void	setManager(GrailsPluginManager manager) Sets the plugin manager for this plugin

Methods inherited from interface org.springframework.context.ApplicationContextAware

setApplicationContext

Field Detail

EVENT_ON_CHANGE

static final int EVENT_ON_CHANGE

See Also:

Constant Field Values

EVENT_ON_CONFIG_CHANGE

static final int EVENT_ON_CONFIG_CHANGE

See Also:

Constant Field Values

DO_WITH_DYNAMIC_METHODS

static final String DO_WITH_DYNAMIC_METHODS

See Also:

Constant Field Values

WATCHED_RESOURCES

static final String WATCHED_RESOURCES

Defines the name of the property that specifies resources which this plugin monitors for changes in the format a Ant-style path

See Also:

Constant Field Values

EVICT

static final String EVICT

Defines the name of the property that specifies a List or plugins that this plugin evicts Eviction occurs when the PluginManager loads

See Also:

Constant Field Values

STATUS

static final String STATUS

The status of the plugin

See Also:

Constant Field Values

STATUS_ENABLED

static final String STATUS_ENABLED

When a plugin is "enabled" it will be loaded as usual

See Also:

Constant Field Values

STATUS_DISABLED

static final String STATUS_DISABLED

When a plugin is "disabled" it will not be loaded

See Also:

Constant Field Values

INFLUENCES

static final String INFLUENCES

Defines the name of the property that defines a list of plugin names that this plugin influences. A influenced plugin will be refreshed (@see refresh()) when a watched resource changes

See Also:

Constant Field Values

ON_CHANGE

static final String ON_CHANGE

Defines the name of the property that defines the closure that will be invoked when a watched resource changes

See Also:

Constant Field Values

ON_CONFIG_CHANGE

static final String ON_CONFIG_CHANGE

Defines the name of the property that defines the closure that will be invoked when a the Grails configuration object changes

See Also:

Constant Field Values

DO_WITH_WEB_DESCRIPTOR

static final String DO_WITH_WEB_DESCRIPTOR

Defines the name of the property that defines the closure that will be invoked when the web.xml is being generated

See Also:

Constant Field Values

TRAILING_NAME

static final String TRAILING_NAME

Defines the convention that appears within plugin class names

See Also:

Constant Field Values

VERSION

static final String VERSION

Defines the name of the property that specifies the plugin version

See Also:

Constant Field Values

DO_WITH_SPRING

static final String DO_WITH_SPRING

Defines the name of the property that defines the closure that will be invoked during runtime spring configuration

See Also:

Constant Field Values

DO_WITH_APPLICATION_CONTEXT

static final String DO_WITH_APPLICATION_CONTEXT

Defines the name of the property that defines a closure that will be invoked after intialisation and when the application context has been built

See Also:

Constant Field Values

DEPENDS_ON

static final String DEPENDS_ON

Defines the name of the property that specifies which plugins this plugin depends on

See Also:

Constant Field Values

ARTEFACTS

static final String ARTEFACTS

Define the list of ArtefactHandlers supporting by the plugin

See Also:

Constant Field Values

PROVIDED_ARTEFACTS

static final String PROVIDED_ARTEFACTS

The name of the property that provides a list of shipped, but overridable artefactssw

See Also:

Constant Field Values

Method Detail

doWithApplicationContext

void doWithApplicationContext(ApplicationContext applicationContext)

This method is called to allow the plugin to add BeanDefinitions to the BeanDefinitionRegistry.

Parameters:

applicationContext - The Spring ApplicationContext instance

doWithRuntimeConfiguration

void doWithRuntimeConfiguration(RuntimeSpringConfiguration springConfig)

Executes the plugin code that performs runtime configuration as defined in the doWithSpring closure

Parameters:

springConfig - The RuntimeSpringConfiguration instance

doWithWebDescriptor

void doWithWebDescriptor(groovy.util.slurpersupport.GPathResult webXml)

Handles processing of web.xml. The method is passed a GPathResult which is parsed by groovy.util.XmlSlurper. A plug-in can then manipulate the in-memory XML however it chooses Once all plug-ins have been processed the web.xml is then written to disk based on its in-memory form

Parameters:

webXml - The GPathResult representing web.xml

getName

String getName()

Returns:

The name of the plug-in

getVersion

String getVersion()

Returns:

The version of the plug-in

getDependencyNames

String[] getDependencyNames()

Returns:

The names of the plugins this plugin is dependant on

getEvictionNames

String[] getEvictionNames()

Returns:

The names of the plugins this plugin should evict onload

getLoadAfterNames

String[] getLoadAfterNames()

Retrieves the names of plugins that this plugin should be loaded after. This differs from dependencies in that if that plugin doesn't exist this plugin will still be loaded. It is a way of enforcing plugins are loaded before, but not necessarily needed

Returns:

The names of the plugins that this plugin should be loaded after

getDependentVersion

String getDependentVersion(String name)

The version of the specified dependency

Parameters:

name - the name of the dependency

Returns:

The version

checkForChanges

boolean checkForChanges()

When called this method checks for any changes to the plug-ins watched resources and reloads appropriately

Returns:

Returns true when the plug-in itself changes in some way, as oppose to plug-in resources

refresh

void refresh()

Refreshes this Grails plugin reloading any watched resources as necessary

getManager

GrailsPluginManager getManager()

Retrieves the plugin manager if known, otherwise returns null

Returns:

The PluginManager or null

getInstance

groovy.lang.GroovyObject getInstance()

Retrieves the wrapped plugin instance for this plugin

Returns:

The plugin instance

setManager

void setManager(GrailsPluginManager manager)

Sets the plugin manager for this plugin

Parameters:

manager - A GrailsPluginManager instance

setApplication

void setApplication(GrailsApplication application)

doWithDynamicMethods

void doWithDynamicMethods(ApplicationContext applicationContext)

Calls a "doWithDynamicMethods" closure that allows a plugin to register dynamic methods at runtime

Parameters:

applicationContext - The Spring ApplicationContext instance

isEnabled

boolean isEnabled()

Returns:

Whether the plugin is enabled or not

getObservedPluginNames

String[] getObservedPluginNames()

Retrieve the plugin names that this plugin is observing for changes

Returns:

The names of the observed plugins

notifyOfEvent

void notifyOfEvent(Map event)

Notifies this plugin of the specified Event calling the onChange listener

Parameters:

event - The event to listen for

notifyOfEvent

Map notifyOfEvent(int eventKind,
                  Object source)

Notifies the plugin of a specific event for the given event id, which is one of ON_CHANGE, ON_CONFIG_CHANGE

Parameters:

eventKind - The event kind

source - The source of the event

Returns:

a Map that represents the event

doArtefactConfiguration

void doArtefactConfiguration()

Called prior to the initialisation of the GrailsApplication instance to allow the registration of additonal ArtefactHandlers

See Also:

ArtefactHandler

getProvidedArtefacts

Class[] getProvidedArtefacts()

Retrieves an array of provided Artefacts that are pre-compiled additions to the GrailsApplication object but are overridable by the end-user

Returns:

A list of provided artefacts