## 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 `BeanDefinition`s to a registry based on a `GrailsApplication` object. After all `GrailsPlugin` classes have been processed the `BeanDefinition`s 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 `BeanDefinition`s 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 `BeanDefinition`s 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