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 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 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()
           
 String getFileSystemName()
          Returns the name of the plugin as represented in the file system including 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
 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
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

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

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()


Copyright (c) 2005-2009 The Grails project