org.codehaus.groovy.grails.plugins
Interface GrailsPlugin

All Superinterfaces:

ApplicationContextAware, Comparable

All Known Implementing Classes:

AbstractGrailsPlugin, DefaultGrailsPlugin

public interface GrailsPlugin
extends ApplicationContextAware, Comparable

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 String	ENVIRONMENTS The environments to which this plugin applies
static int	EVENT_ON_CHANGE
static int	EVENT_ON_CONFIG_CHANGE
static int	EVENT_ON_SHUTDOWN
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	NAME The name of the plugin
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	ON_SHUTDOWN Defines the name of the property that holds a closure to be invoked when shutdown is called
static String	PLUGIN_EXCLUDES The field that reperesents the list of resources to exclude from plugin packaging
static String	PLUGIN_LOAD_AFTER_NAMES The name of the property that provides a list of plugins this plugin should after before
static String	PLUGIN_LOAD_BEFORE_NAMES The name of the property that provides a list of plugins this plugin should load before
static String	PLUGINS_PATH The prefix used in plug-ins paths
static String	PROVIDED_ARTEFACTS The name of the property that provides a list of shipped, but overridable artefactssw
static String	SCOPES The scopes to which this plugin applies
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	TYPE_FILTERS The field that reperesents the list of type filters a plugin provides
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	doc(String text) Write some documentation to the DocumentationContext
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()
String	getFileSystemName() Returns the name of the plugin as represented in the file system including the version.
String	getFileSystemShortName() Returns the name of the plugin as represented on the file system without the version.
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.
String[]	getLoadBeforeNames() Retrieves the names of plugins that this plugin should be loaded before.
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	getPluginClass() Returns the underlying class that represents this plugin
List<String>	getPluginExcludes() A list of resources that the plugin should exclude from the packaged distribution
String	getPluginPath() Returns the path of the plug-in
Class[]	getProvidedArtefacts() Retrieves an array of provided Artefacts that are pre-compiled additions to the GrailsApplication object but are overridable by the end-user
Collection<? extends TypeFilter>	getTypeFilters() Plugin can provide a list of Spring TypeFilters so that annotated components can be scanned into the ApplicationContext
String	getVersion()
boolean	isBasePlugin() Returns whether this plugin is loaded from the current plugin.
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	setBasePlugin(boolean isBase) Sets whether this plugin is the base plugin
void	setManager(GrailsPluginManager manager) Sets the plugin manager for this plugin
boolean	supportsCurrentScopeAndEnvironment()
boolean	supportsEnvironment(Environment environment) Returns whether this plugin supports the given environment name
boolean	supportsScope(BuildScope buildScope) Return whether this plugin supports the given PluginScope

Methods inherited from interface org.springframework.context.ApplicationContextAware

setApplicationContext

Methods inherited from interface java.lang.Comparable

compareTo

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

EVENT_ON_SHUTDOWN

static final int EVENT_ON_SHUTDOWN

See Also:

Constant Field Values

DO_WITH_DYNAMIC_METHODS

static final String DO_WITH_DYNAMIC_METHODS

See Also:

Constant Field Values

SCOPES

static final String SCOPES

The scopes to which this plugin applies

See Also:

Constant Field Values

ENVIRONMENTS

static final String ENVIRONMENTS

The environments to which this plugin applies

See Also:

Constant Field Values

PLUGINS_PATH

static final String PLUGINS_PATH

The prefix used in plug-ins paths

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_SHUTDOWN

static final String ON_SHUTDOWN

Defines the name of the property that holds a closure to be invoked when shutdown is called

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

PLUGIN_LOAD_BEFORE_NAMES

static final String PLUGIN_LOAD_BEFORE_NAMES

The name of the property that provides a list of plugins this plugin should load before

See Also:

Constant Field Values

PLUGIN_LOAD_AFTER_NAMES

static final String PLUGIN_LOAD_AFTER_NAMES

The name of the property that provides a list of plugins this plugin should after before

See Also:

Constant Field Values

PLUGIN_EXCLUDES

static final String PLUGIN_EXCLUDES

The field that reperesents the list of resources to exclude from plugin packaging

See Also:

Constant Field Values

TYPE_FILTERS

static final String TYPE_FILTERS

The field that reperesents the list of type filters a plugin provides

See Also:

Constant Field Values

NAME

static final String NAME

The name of the plugin

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

supportsScope

boolean supportsScope(BuildScope buildScope)

Return whether this plugin supports the given PluginScope

Parameters:

buildScope - The PluginScope

Returns:

True if it does

supportsEnvironment

boolean supportsEnvironment(Environment environment)

Returns whether this plugin supports the given environment name

Parameters:

environment - The environment name

Returns:

True if it does

supportsCurrentScopeAndEnvironment

boolean supportsCurrentScopeAndEnvironment()

Returns:

True if the current plugin supports the current BuildScope and Environment

getVersion

String getVersion()

Returns:

The version of the plug-in

doc

void doc(String text)

Write some documentation to the DocumentationContext

getPluginPath

String getPluginPath()

Returns the path of the plug-in

Returns:

A String that makes up the path to the plug-in in the format /plugins/PLUGIN_NAME-PLUGIN_VERSION

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

getLoadBeforeNames

String[] getLoadBeforeNames()

Retrieves the names of plugins that this plugin should be loaded before. As with getLoadAfterNames() it is not a requirement that the specified plugins exist

Returns:

The names of the plugins that this plugin should load before

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

getFileSystemName

String getFileSystemName()

Returns the name of the plugin as represented in the file system including the version. For example TagLibGrailsPlugin would result in "tag-lib-0.1"

Returns:

The file system representation of the plugin name

getFileSystemShortName

String getFileSystemShortName()

Returns the name of the plugin as represented on the file system without the version. For example TagLibGrailsPlugin would result in "tag-lib"

Returns:

The file system name

getPluginClass

Class getPluginClass()

Returns the underlying class that represents this plugin

Returns:

The plugin class

getPluginExcludes

List<String> getPluginExcludes()

A list of resources that the plugin should exclude from the packaged distribution

Returns:

a List of resources

isBasePlugin

boolean isBasePlugin()

Returns whether this plugin is loaded from the current plugin. In other words when you execute grails run-app from a plugin project the plugin project's *GrailsPlugin.groovy file represents the base plugin and this method will return true for this plugin

Returns:

True if it is the base plugin

setBasePlugin

void setBasePlugin(boolean isBase)

Sets whether this plugin is the base plugin

Parameters:

isBase - True if is

See Also:

isBasePlugin()

getTypeFilters

Collection<? extends TypeFilter> getTypeFilters()

Plugin can provide a list of Spring TypeFilters so that annotated components can be scanned into the ApplicationContext

Returns:

A collection of TypeFilter instance