Package grails.plugins

Interface GrailsPlugin

  • All Superinterfaces:
    org.springframework.context.ApplicationContextAware, org.springframework.beans.factory.Aware, java.lang.Comparable, grails.plugins.GrailsPluginInfo
    All Known Implementing Classes:
    AbstractGrailsPlugin, BinaryGrailsPlugin, DefaultGrailsPlugin
    public interface GrailsPlugin
extends org.springframework.context.ApplicationContextAware, java.lang.Comparable, grails.plugins.GrailsPluginInfo

    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
    See Also:
    BeanDefinitionRegistry

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String ARTEFACTS
      Define the list of ArtefactHandlers supporting by the plugin
      static java.lang.String DEPENDS_ON
      Defines the name of the property that specifies which plugins this plugin depends on
      static java.lang.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 java.lang.String DO_WITH_DYNAMIC_METHODS  
      static java.lang.String DO_WITH_SPRING
      Defines the name of the property that defines the closure that will be invoked during runtime spring configuration
      static java.lang.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 java.lang.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 java.lang.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 java.lang.String OBSERVE
      The field that represents the plugin names that this plugin is observing for changes.
      static java.lang.String ON_CHANGE
      Defines the name of the property that defines the closure that will be invoked when a watched resource changes
      static java.lang.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 java.lang.String ON_SHUTDOWN
      Defines the name of the property that holds a closure to be invoked when shutdown is called
      static java.lang.String PLUGIN_EXCLUDES
      The field that represents the list of resources to exclude from plugin packaging
      static java.lang.String PLUGIN_LOAD_AFTER_NAMES
      The name of the property that provides a list of plugins this plugin should after before
      static java.lang.String PLUGIN_LOAD_BEFORE_NAMES
      The name of the property that provides a list of plugins this plugin should load before
      static java.lang.String PLUGINS_PATH
      The prefix used in plug-ins paths
      static java.lang.String PROFILES
      The profiles for which this plugin is active
      static java.lang.String PROVIDED_ARTEFACTS
      The name of the property that provides a list of shipped, but overridable artefacts
      static java.lang.String SCOPES
      The scopes to which this plugin applies
      static java.lang.String STATUS
      The status of the plugin.
      static java.lang.String STATUS_DISABLED
      When a plugin is "disabled" it will not be loaded
      static java.lang.String STATUS_ENABLED
      When a plugin is "enabled" it will be loaded as usual.
      static java.lang.String TYPE_FILTERS
      The field that represents the list of type filters a plugin provides
      static java.lang.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

      • Fields inherited from interface grails.plugins.GrailsPluginInfo

        NAME, TRAILING_NAME, VERSION

    • Method Summary

      All Methods Instance Methods Abstract Methods Deprecated Methods 
      Modifier and Type Method Description
      void addExclude​(grails.util.Environment env)
      Makes the plugin excluded for a particular Environment
      void doArtefactConfiguration()
      Called prior to the initialisation of the GrailsApplication instance to allow the registration of additonal ArtefactHandlers
      void doc​(java.lang.String text)
      Deprecated.
      Dynamic document generation no longer supported
      void doWithApplicationContext​(org.springframework.context.ApplicationContext applicationContext)
      This method is called to allow the plugin to add BeanDefinitions to the BeanDefinitionRegistry.
      void doWithDynamicMethods​(org.springframework.context.ApplicationContext applicationContext)
      Calls a "doWithDynamicMethods" closure that allows a plugin to register dynamic methods at runtime
      void doWithRuntimeConfiguration​(org.grails.spring.RuntimeSpringConfiguration springConfig)
      Executes the plugin code that performs runtime configuration as defined in the doWithSpring closure
      java.lang.String[] getDependencyNames()  
      java.lang.String getDependentVersion​(java.lang.String name)
      The version of the specified dependency
      java.lang.String[] getEvictionNames()  
      java.lang.String getFileSystemName()
      Returns the name of the plugin as represented in the file system including the version.
      java.lang.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
      java.lang.String[] getLoadAfterNames()
      Retrieves the names of plugins that this plugin should be loaded after.
      java.lang.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
      java.lang.String[] getObservedPluginNames()
      Retrieve the plugin names that this plugin is observing for changes
      java.lang.Class<?> getPluginClass()
      Returns the underlying class that represents this plugin
      java.util.List<java.lang.String> getPluginExcludes()
      A list of resources that the plugin should exclude from the packaged distribution
      java.lang.String getPluginPath()
      Returns the path of the plug-in
      java.lang.String getPluginPathCamelCase()
      Returns the path of the plug-in using camel case
      org.springframework.core.env.PropertySource<?> getPropertySource()  
      java.lang.Class<?>[] getProvidedArtefacts()
      Retrieves an array of provided Artefacts that are pre-compiled additions to the GrailsApplication object but are overridable by the end-user
      java.util.Collection<? extends org.springframework.core.type.filter.TypeFilter> getTypeFilters()
      Plugin can provide a list of Spring TypeFilters so that annotated components can be scanned into the ApplicationContext
      java.util.List<org.grails.plugins.support.WatchPattern> getWatchedResourcePatterns()
      Resources that this plugin watches
      boolean hasInterestInChange​(java.lang.String path)
      Whether the plugin is interested in a particular change
      boolean isBasePlugin()
      Returns whether this plugin is loaded from the current plugin.
      boolean isEnabled()  
      boolean isEnabled​(java.lang.String[] activeProfiles)
      Check whether the plugin is enabled for the given profile
      java.util.Map notifyOfEvent​(int eventKind, java.lang.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​(java.util.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 setDescriptor​(org.springframework.core.io.Resource descriptor)
      Sets the plugin descriptor for this plugin
      void setManager​(GrailsPluginManager manager)
      Sets the plugin manager for this plugin
      boolean supportsCurrentScopeAndEnvironment()  
      boolean supportsEnvironment​(grails.util.Environment environment)
      Returns whether this plugin supports the given environment name

      • Methods inherited from interface org.springframework.context.ApplicationContextAware

        setApplicationContext

      • Methods inherited from interface java.lang.Comparable

        compareTo

      • Methods inherited from interface grails.plugins.GrailsPluginInfo

        getDescriptor, getFullName, getName, getPluginDir, getProperties, getVersion

    • Field Detail

      • DO_WITH_DYNAMIC_METHODS

        static final java.lang.String DO_WITH_DYNAMIC_METHODS
        See Also:
        Constant Field Values

      • SCOPES

        static final java.lang.String SCOPES
        The scopes to which this plugin applies
        See Also:
        Constant Field Values

      • ENVIRONMENTS

        static final java.lang.String ENVIRONMENTS
        The environments to which this plugin applies
        See Also:
        Constant Field Values

      • PLUGINS_PATH

        static final java.lang.String PLUGINS_PATH
        The prefix used in plug-ins paths
        See Also:
        Constant Field Values

      • WATCHED_RESOURCES

        static final java.lang.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 java.lang.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_ENABLED

        static final java.lang.String STATUS_ENABLED
        When a plugin is "enabled" it will be loaded as usual.
        See Also:
        Constant Field Values

      • STATUS_DISABLED

        static final java.lang.String STATUS_DISABLED
        When a plugin is "disabled" it will not be loaded
        See Also:
        Constant Field Values

      • ON_CHANGE

        static final java.lang.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 java.lang.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 java.lang.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 java.lang.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

      • DO_WITH_SPRING

        static final java.lang.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 java.lang.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 java.lang.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 java.lang.String ARTEFACTS
        Define the list of ArtefactHandlers supporting by the plugin
        See Also:
        Constant Field Values

      • PROVIDED_ARTEFACTS

        static final java.lang.String PROVIDED_ARTEFACTS
        The name of the property that provides a list of shipped, but overridable artefacts
        See Also:
        Constant Field Values

      • PROFILES

        static final java.lang.String PROFILES
        The profiles for which this plugin is active
        See Also:
        Constant Field Values

      • PLUGIN_LOAD_BEFORE_NAMES

        static final java.lang.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 java.lang.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 java.lang.String PLUGIN_EXCLUDES
        The field that represents the list of resources to exclude from plugin packaging
        See Also:
        Constant Field Values

      • TYPE_FILTERS

        static final java.lang.String TYPE_FILTERS
        The field that represents the list of type filters a plugin provides
        See Also:
        Constant Field Values

      • OBSERVE

        static final java.lang.String OBSERVE
        The field that represents the plugin names that this plugin is observing for changes.
        See Also:
        Constant Field Values

    • Method Detail

      • doWithApplicationContext

        void doWithApplicationContext​(org.springframework.context.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​(org.grails.spring.RuntimeSpringConfiguration springConfig)
        Executes the plugin code that performs runtime configuration as defined in the doWithSpring closure
        Parameters:
        springConfig - The RuntimeSpringConfiguration instance

      • addExclude

        void addExclude​(grails.util.Environment env)
        Makes the plugin excluded for a particular Environment
        Parameters:
        env - The Environment

      • supportsEnvironment

        boolean supportsEnvironment​(grails.util.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

      • doc

        @Deprecated
void doc​(java.lang.String text)
        Deprecated.
        Dynamic document generation no longer supported
        Write some documentation to the DocumentationContext
        Parameters:
        text -

      • getPluginPath

        java.lang.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

      • getPluginPathCamelCase

        java.lang.String getPluginPathCamelCase()
        Returns the path of the plug-in using camel case
        Returns:
        A String that makes up the path to the plug-in in the format /plugins/pluginName-PLUGIN_VERSION

      • getDependencyNames

        java.lang.String[] getDependencyNames()
        Returns:
        The names of the plugins this plugin is dependant on

      • getEvictionNames

        java.lang.String[] getEvictionNames()
        Returns:
        The names of the plugins this plugin should evict onload

      • getLoadAfterNames

        java.lang.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

        java.lang.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

        java.lang.String getDependentVersion​(java.lang.String name)
        The version of the specified dependency
        Parameters:
        name - the name of the dependency
        Returns:
        The version

      • getPropertySource

        org.springframework.core.env.PropertySource<?> getPropertySource()

      • 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

      • doWithDynamicMethods

        void doWithDynamicMethods​(org.springframework.context.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

      • isEnabled

        boolean isEnabled​(java.lang.String[] activeProfiles)
        Check whether the plugin is enabled for the given profile
        Parameters:
        activeProfiles -
        Returns:
        True if it is

      • getObservedPluginNames

        java.lang.String[] getObservedPluginNames()
        Retrieve the plugin names that this plugin is observing for changes
        Returns:
        The names of the observed plugins

      • notifyOfEvent

        void notifyOfEvent​(java.util.Map event)
        Notifies this plugin of the specified Event calling the onChange listener
        Parameters:
        event - The event to listen for

      • notifyOfEvent

        java.util.Map notifyOfEvent​(int eventKind,
                            java.lang.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

        java.lang.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

        java.lang.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

        java.lang.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

        java.lang.Class<?> getPluginClass()
        Returns the underlying class that represents this plugin
        Returns:
        The plugin class

      • getPluginExcludes

        java.util.List<java.lang.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

        java.util.Collection<? extends org.springframework.core.type.filter.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

      • getWatchedResourcePatterns

        java.util.List<org.grails.plugins.support.WatchPattern> getWatchedResourcePatterns()
        Resources that this plugin watches
        Returns:
        The watch resource patterns

      • hasInterestInChange

        boolean hasInterestInChange​(java.lang.String path)
        Whether the plugin is interested in a particular change
        Parameters:
        path - The path to the resource that changed
        Returns:
        true if it is

      • setDescriptor

        void setDescriptor​(org.springframework.core.io.Resource descriptor)
        Sets the plugin descriptor for this plugin
        Parameters:
        descriptor - The descriptor