src/commons/org/codehaus/groovy/grails/plugins/GrailsPluginManager.java

   1 /*
   2  * Copyright 2004-2005 the original author or authors.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 package org.codehaus.groovy.grails.plugins;
  17
  18 import org.codehaus.groovy.grails.commons.GrailsApplication;
  19 import org.codehaus.groovy.grails.commons.spring.RuntimeSpringConfiguration;
  20 import org.codehaus.groovy.grails.plugins.exceptions.PluginException;
  21 import org.springframework.context.ApplicationContext;
  22 import org.springframework.context.ApplicationContextAware;
  23 import org.springframework.core.io.Resource;
  24 import org.springframework.web.context.ServletContextAware;
  25
  26 import java.io.File;
  27 import java.io.Writer;
  28 import java.util.Collection;
  29 import java.util.Map;
  30
  31 /**
  32  * <p>A class that handles the loading and management of plug-ins in the Grails system.
  33  * A plugin a just like a normal Grails application except that it contains a file ending
  34  * in *Plugin.groovy  in the root of the directory.
  35  *
  36  * <p>A Plugin class is a Groovy class that has a version and optionally closures
  37  * called doWithSpring, doWithContext and doWithWebDescriptor
  38  *
  39  * <p>The doWithSpring closure uses the BeanBuilder syntax (@see grails.spring.BeanBuilder) to
  40  * provide runtime configuration of Grails via Spring
  41  *
  42  * <p>The doWithContext closure is called after the Spring ApplicationContext is built and accepts
  43  * a single argument (the ApplicationContext)
  44  *
  45  * <p>The doWithWebDescriptor uses mark-up building to provide additional functionality to the web.xml
  46  * file
  47  *
  48  *<p> Example:
  49  * <pre>
  50  * class ClassEditorGrailsPlugin {
  51  *      def version = 1.1
  52  *      def doWithSpring = { application ->
  53  *              classEditor(org.springframework.beans.propertyeditors.ClassEditor, application.classLoader)
  54  *      }
  55  * }
  56  * </pre>
  57  *
  58  * <p>A plugin can also define "dependsOn" and "evict" properties that specify what plugins the plugin
  59  * depends on and which ones it is incompatable with and should evict
  60  *
  61  * @author Graeme Rocher
  62  * @since 0.4
  63  *
  64  */
  65 public interface GrailsPluginManager extends ApplicationContextAware, ServletContextAware {
  66
  67         String BEAN_NAME = "pluginManager";
  68
  69     /**
  70      * Returns an array of all the loaded plug-ins
  71      * @return An array of plug-ins
  72      */
  73     GrailsPlugin[] getAllPlugins();
  74
  75     /**
  76          * Performs the initial load of plug-ins throwing an exception if any dependencies
  77          * don't resolve
  78          *
  79          * @throws PluginException Thrown when an error occurs loading the plugins
  80          */
  81         public abstract void loadPlugins() throws PluginException;
  82
  83         /**
  84          * Executes the runtime configuration phase of plug-ins
  85          *
  86          * @param springConfig The RuntimeSpringConfiguration instance
  87          */
  88         public abstract void doRuntimeConfiguration(
  89                         RuntimeSpringConfiguration springConfig);
  90
  91         /**
  92          * Performs post initialization configuration for each plug-in, passing
  93          * the built application context
  94          *
  95          * @param applicationContext The ApplicationContext instance
  96          */
  97         public abstract void doPostProcessing(ApplicationContext applicationContext);
  98
  99         /**
 100          * Takes the specified web descriptor reference and configures it with all the plugins outputting
 101          * the result to the target Writer instance
 102          *
 103          * @param descriptor The Resource of the descriptor
 104          * @param target The Writer to write the result to
 105          */
 106         public abstract void doWebDescriptor(Resource descriptor, Writer target);
 107
 108         /**
 109          * @see #doWebDescriptor(Resource, Writer)
 110          *
 111          * @param descriptor The File of the descriptor
 112          * @param target The target to write the changes to
 113          */
 114         public abstract void doWebDescriptor(File descriptor, Writer target);
 115
 116         /**
 117          * This is called on all plugins so that they can add new methods/properties/constructors etc.
 118          *
 119          */
 120         public abstract void doDynamicMethods();
 121         /**
 122          * Retrieves a name Grails plugin instance
 123          *
 124          * @param name The name of the plugin
 125          * @return The GrailsPlugin instance or null if it doesn't exist
 126          */
 127         public abstract GrailsPlugin getGrailsPlugin(String name);
 128
 129         /**
 130          *
 131          * @param name The name of the plugin
 132          * @return True if the the manager has a loaded plugin with the given name
 133          */
 134         public boolean hasGrailsPlugin(String name);
 135
 136     /**
 137      * Retrieves a plug-in that failed to load, or null if it doesn't exist
 138      *
 139      * @param name The name of the plugin
 140      * @return A GrailsPlugin or null
 141      */
 142     public GrailsPlugin getFailedPlugin(String name);
 143
 144     /**
 145          * Retrieves a plug-in for its name and version
 146          *
 147          * @param name The name of the plugin
 148          * @param version The version of the plugin
 149          * @return The GrailsPlugin instance or null if it doesn't exist
 150          */
 151         public abstract GrailsPlugin getGrailsPlugin(String name, Object version);
 152
 153         /**
 154          * Executes the runtime configuration for a specific plugin AND all its dependencies
 155          *
 156          * @param pluginName The name of he plugin
 157          * @param springConfig The runtime spring config instance
 158          */
 159         public abstract void doRuntimeConfiguration(String pluginName, RuntimeSpringConfiguration springConfig);
 160
 161         /**
 162          * Checks all the plugins to see whether they have any changes
 163          *
 164          */
 165         public abstract void checkForChanges();
 166
 167         /**
 168          * Sets the GrailsApplication used be this plugin manager
 169          * @param application The GrailsApplication instance
 170          */
 171         public abstract void setApplication(GrailsApplication application);
 172
 173         /**
 174          * @return the initialised
 175          */
 176         public boolean isInitialised();
 177
 178     /**
 179      * Refreshes the specified plugin. A refresh will force to plugin to "touch" each of its watched resources
 180      * and fire modified events for each
 181      *
 182      * @param name The name of the plugin to refresh
 183      */
 184     public void refreshPlugin(String name);
 185
 186     /**
 187      * Retrieves a collection of plugins that are observing the specified plugin
 188      *
 189      * @param plugin The plugin to retrieve observers for
 190      * @return A collection of observers
 191      */
 192     public Collection getPluginObservers(GrailsPlugin plugin);
 193
 194     /**
 195      * inform the specified plugins observers of the event specified by the passsed Map instance
 196      *
 197      * @param pluginName The name of the plugin
 198      * @param event The event
 199      */
 200     public void informObservers(String pluginName, Map event);
 201
 202     /**
 203      * Called prior to the initialisation of the GrailsApplication object to allow registration of additional ArtefactHandler objects
 204      *
 205      * @see org.codehaus.groovy.grails.commons.ArtefactHandler
 206      *
 207      */
 208     public void doArtefactConfiguration();
 209
 210     /**
 211      * Registers pre-compiled artefacts with the GrailsApplication instance, only overriding if the application doesn't already provide an artefact of the same
 212      * name
 213      *
 214      * @param application The GrailsApplication object
 215      */
 216     void registerProvidedArtefacts(GrailsApplication application);
 217
 218     /**
 219      * Shuts down the PluginManager
 220      */
 221     void shutdown();
 222 }