PluginManager


1   /*****************************************************************************
2    * Java Plug-in Framework (JPF)
3    * Copyright (C) 2004-2006 Dmitry Olshansky
4    * 
5    * This library is free software; you can redistribute it and/or
6    * modify it under the terms of the GNU Lesser General Public
7    * License as published by the Free Software Foundation; either
8    * version 2.1 of the License, or (at your option) any later version.
9    * 
10   * This library is distributed in the hope that it will be useful,
11   * but WITHOUT ANY WARRANTY; without even the implied warranty of
12   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13   * Lesser General Public License for more details.
14   * 
15   * You should have received a copy of the GNU Lesser General Public
16   * License along with this library; if not, write to the Free Software
17   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18   *****************************************************************************/
19  package org.java.plugin;
20  
21  import java.net.URL  ;
22  import java.util.Map  ;
23  
24  import org.java.plugin.registry.PluginDescriptor;
25  import org.java.plugin.registry.PluginRegistry;
26  
27  /**
28   * JPF "runtime" class - the entry point to the framework API. It is
29   * expected that only one instance of this class will be created per
30   * application (other scenarios may be possible but not tested).
31   * <p>
32   * Usage example. Somewhere in the beginning of your application:
33   * <pre>
34   * manager = factory.createManager();
35   * manager.publishPlugins(getLocations(dir));
36   * </pre>
37   * Later on, before accessing plug-in:
38   * <pre>
39   * manager.activatePlugin(pluginId);
40   * </pre>
41   * 
42   * @see org.java.plugin.ObjectFactory#createManager()
43   * 
44   * @version $Id: PluginManager.java,v 1.23 2006/09/07 18:16:57 ddimon Exp $
45   */
46  public abstract class PluginManager {
47      /**
48       * Looks for plug-in manager instance for given object.
49       * @param obj any object that may be managed by some plug-in manager
50       * @return plug-in manager instance or <code>null</code> if given object
51       *         doesn't belong to any plug-in (possibly it is part of "host"
52       *         application) and thus doesn't managed by the Framework directly
53       *         or indirectly.
54       */
55      public static PluginManager lookup(final Object   obj) {
56          if (obj == null) {
57              return null;
58          }
59          ClassLoader   clsLoader;
60          if (obj instanceof Plugin) {
61              return ((Plugin) obj).getManager();
62          } else if (obj instanceof Class  ) {
63              clsLoader = ((Class  ) obj).getClassLoader();
64          } else if (obj instanceof ClassLoader  ) {
65              clsLoader = (ClassLoader  ) obj;
66          } else {
67              clsLoader = obj.getClass().getClassLoader();
68          }
69          if (!(clsLoader instanceof PluginClassLoader)) {
70              return lookup(clsLoader.getParent());
71          }
72          return ((PluginClassLoader) clsLoader).getPluginManager();
73      }
74  
75      /**
76       * @return registry, used by this manager
77       */
78      public abstract PluginRegistry getRegistry();
79  
80      /**
81       * @return path resolver
82       */
83      public abstract PathResolver getPathResolver();
84  
85      /**
86       * Registers plug-ins and their locations with this plug-in manager. You
87       * should use this method to register new plug-ins to make them available
88       * for activation with this manager instance (compare this to
89       * {@link PluginRegistry#register(URL[])} method that just makes plug-in's
90       * meta-data available for reading and doesn't "know" where are things
91       * actually located).
92       * <p>
93       * Note that this method only load plug-ins to this manager but not activate
94       * them. Call {@link #activatePlugin(String)} method to make plug-in
95       * activated. It is recommended to do this immediately before first plug-in
96       * use.
97       * @param locations plug-in locations data
98       * @return map where keys are manifest URL's and values are registered
99       *         plug-ins or plug-in fragments, URL's for unprocessed manifests
100      *         are not included
101      * @throws JpfException if given plug-ins can't be registered or published
102      *         (optional behavior)
103      * 
104      * @see org.java.plugin.registry.PluginDescriptor
105      * @see org.java.plugin.registry.PluginFragment
106      */
107     public abstract Map   publishPlugins(final PluginLocation[] locations)
108             throws JpfException;
109     
110     /**
111      * Looks for plug-in with given ID and activates it if it is not activated
112      * yet. Note that this method will never return <code>null</code>.
113      * @param id plug-in ID
114      * @return found plug-in
115      * @throws PluginLifecycleException if plug-in can't be found or activated
116      */
117     public abstract Plugin getPlugin(final String   id)
118             throws PluginLifecycleException;
119 
120     /**
121      * Activates plug-in with given ID if it is not activated yet. Actually this
122      * makes plug-in "running" and calls {@link Plugin#doStart()} method. This
123      * method will effectively activate all depending plug-ins. It is safe to
124      * call this method more than once.
125      * @param id plug-in ID
126      * @throws PluginLifecycleException if plug-in can't be found or activated
127      */
128     public abstract void activatePlugin(final String   id)
129             throws PluginLifecycleException;
130 
131     /**
132      * Looks for plug-in, given object belongs to.
133      * @param obj any object that maybe belongs to some plug-in
134      * @return plug-in or <code>null</code> if given object doesn't belong
135      *         to any plug-in (possibly it is part of "host" application)
136      *         and thus doesn't managed by the Framework directly
137      *         or indirectly
138      */
139     public abstract Plugin getPluginFor(final Object   obj);
140 
141     /**
142      * @param descr plug-in descriptor
143      * @return <code>true</code> if plug-in with given descriptor is activated
144      */
145     public abstract boolean isPluginActivated(final PluginDescriptor descr);
146 
147     /**
148      * @param descr plug-in descriptor
149      * @return <code>true</code> if plug-in disabled as it's activation fails
150      */
151     public abstract boolean isBadPlugin(final PluginDescriptor descr);
152 
153     /**
154      * @param descr plug-in descriptor
155      * @return <code>true</code> if plug-in is currently activating
156      */
157     public abstract boolean isPluginActivating(final PluginDescriptor descr);
158     
159     /**
160      * Returns instance of plug-in's class loader and not tries to activate
161      * plug-in. Use this method if you need to get access to plug-in resources
162      * and don't want to cause plug-in activation.
163      * @param descr plug-in descriptor
164      * @return class loader instance for plug-in with given descriptor
165      */
166     public abstract PluginClassLoader getPluginClassLoader(
167             final PluginDescriptor descr);
168     
169     /**
170      * Shuts down the framework.
171      * <br>
172      * Calling this method will deactivate all active plug-ins in order,
173      * reverse to the order they was activated. It also releases all resources
174      * allocated by this manager (class loaders, plug-in descriptors etc.).
175      * All disabled plug-ins will be marked as "enabled", all registered event
176      * listeners will be unregistered.
177      */
178     public abstract void shutdown();
179     
180     /**
181      * Deactivates plug-in with given ID if it has been successfully activated
182      * before. This method makes plug-in "not running" and calls
183      * {@link Plugin#doStop()} method. Note that this method will effectively
184      * deactivate all depending plug-ins.
185      * @param id plug-in ID
186      */
187     public abstract void deactivatePlugin(final String   id);
188     
189     /**
190      * Disables plug-in (with dependencies) in this manager instance.
191      * Disabled plug-in can't be activated although it may be valid and
192      * successfully registered with plug-in registry. Before disabling,
193      * plug-in will be deactivated if it was successfully activated.
194      * <p>
195      * Be careful with this method as it can effectively disable large set
196      * of inter-depending plug-ins and your application may become unstable
197      * or even disabled as whole.
198      * @param descr descriptor of plug-in to be disabled
199      * @return descriptors of plug-ins that was actually disabled
200      */
201     public abstract PluginDescriptor[] disablePlugin(
202             final PluginDescriptor descr);
203     
204     /**
205      * Enables plug-in (or plug-ins) in this manager instance. Don't miss this
206      * with plug-in activation semantic. Enabled plug-in is simply ready to be
207      * activated. By default all loaded plug-ins are enabled.
208      * @param descr descriptor of plug-in to be enabled
209      * @param includeDependings if <code>true</code>, depending plug-ins will
210      *                          be also enabled
211      * @return descriptors of plug-ins that was actually enabled
212      * @see #disablePlugin(PluginDescriptor)
213      */
214     public abstract PluginDescriptor[] enablePlugin(
215             final PluginDescriptor descr, final boolean includeDependings);
216     
217     /**
218      * @param descr plug-in descriptor
219      * @return <code>true</code> if given plug-in is disabled in this manager
220      */
221     public abstract boolean isPluginEnabled(final PluginDescriptor descr);
222     
223     /**
224      * Registers plug-in manager event listener. If given listener has been
225      * registered before, this method will throw an
226      * {@link IllegalArgumentException}.
227      * @param listener new manager event listener
228      */
229     public abstract void registerListener(final EventListener listener);
230     
231     /**
232      * Unregisters manager event listener. If given listener hasn't been
233      * registered before, this method will throw an
234      * {@link IllegalArgumentException}.
235      * @param listener registered listener
236      */
237     public abstract void unregisterListener(final EventListener listener);
238     
239     // Delegating methods
240     
241     /**
242      * Initializes given plug-in with this manager instance and given
243      * descriptor.
244      * @param plugin plug-in instance to be initialized
245      * @param descr plug-in descriptor
246      */
247     protected final void initPlugin(final Plugin plugin,
248             final PluginDescriptor descr) {
249         plugin.setManager(this);
250         plugin.setDescriptor(descr);
251     }
252     
253     /**
254      * Starts given plug-in. Simply forward call to {@link Plugin#doStart()}
255      * method.
256      * @param plugin plug-in to be started
257      * @throws Exception if any error has occurred during plug-in start
258      */
259     protected final void startPlugin(final Plugin plugin) throws Exception   {
260         plugin.start();
261     }
262     
263     /**
264      * Stops given plug-in. Simply forward call to {@link Plugin#doStop()} method.
265      * @param plugin plug-in to be stopped
266      * @throws Exception if any error has occurred during plug-in stop
267      */
268     protected final void stopPlugin(final Plugin plugin) throws Exception   {
269         plugin.stop();
270     }
271     
272     /**
273      * Forwards call to {@link PluginClassLoader#dispose()} method.
274      * @param cl plug-in class loader to be disposed
275      */
276     protected final void disposeClassLoader(final PluginClassLoader cl) {
277         cl.dispose();
278     }
279     
280     /**
281      * Forwards call to {@link PluginClassLoader#pluginsSetChanged()} method.
282      * @param cl plug-in class loader to be notified
283      */
284     protected final void notifyClassLoader(final PluginClassLoader cl) {
285         cl.pluginsSetChanged();
286     }
287     
288     /**
289      * Plug-ins life-cycle events callback interface.
290      * @version $Id: PluginManager.java,v 1.23 2006/09/07 18:16:57 ddimon Exp $
291      */
292     public interface EventListener {
293         /**
294          * This method will be called by the manager just after plug-in
295          * has been successfully activated.
296          * @param plugin just activated plug-in
297          */
298         void pluginActivated(Plugin plugin);
299         
300         /**
301          * This method will be called by the manager just before plug-in
302          * deactivation.
303          * @param plugin plug-in to be deactivated
304          */
305         void pluginDeactivated(Plugin plugin);
306         
307         /**
308          * This method will be called by the manager just before plug-in
309          * disabling.
310          * @param descriptor descriptor of plug-in to be disabled
311          */
312         void pluginDisabled(PluginDescriptor descriptor);
313         
314         /**
315          * This method will be called by the manager just after plug-in
316          * enabling.
317          * @param descriptor descriptor of enabled plug-in
318          */
319         void pluginEnabled(PluginDescriptor descriptor);
320     }
321     
322     /**
323      * An abstract adapter class for receiving plug-ins life-cycle events. The
324      * methods in this class are empty. This class exists as convenience for
325      * creating listener objects.
326      * @version $Id: PluginManager.java,v 1.23 2006/09/07 18:16:57 ddimon Exp $
327      */
328     public abstract static class EventListenerAdapter implements EventListener {
329         /**
330          * @see org.java.plugin.PluginManager.EventListener#pluginActivated(
331          *      org.java.plugin.Plugin)
332          */
333         public void pluginActivated(final Plugin plugin) {
334             // no-op
335         }
336 
337         /**
338          * @see org.java.plugin.PluginManager.EventListener#pluginDeactivated(
339          *      org.java.plugin.Plugin)
340          */
341         public void pluginDeactivated(final Plugin plugin) {
342             // no-op
343         }
344 
345         /**
346          * @see org.java.plugin.PluginManager.EventListener#pluginDisabled(
347          *      org.java.plugin.registry.PluginDescriptor)
348          */
349         public void pluginDisabled(final PluginDescriptor descriptor) {
350             // no-op
351         }
352 
353         /**
354          * @see org.java.plugin.PluginManager.EventListener#pluginEnabled(
355          *      org.java.plugin.registry.PluginDescriptor)
356          */
357         public void pluginEnabled(final PluginDescriptor descriptor) {
358             // no-op
359         }
360     }
361     
362     /**
363      * Simple callback interface to hold info about plug-in manifest and
364      * plug-in data locations.
365      * @version $Id: PluginManager.java,v 1.23 2006/09/07 18:16:57 ddimon Exp $
366      */
367     public static interface PluginLocation {
368         /**
369          * @return location of plug-in manifest
370          */
371         URL   getManifestLocation();
372         
373         /**
374          * @return location of plug-in context ("home")
375          */
376         URL   getContextLocation();
377     }
378 }
379
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags