1 /*
2 * Copyright (c) 2003-2008 by Cosylab d. d.
3 *
4 * This file is part of CosyBeans.
5 *
6 * CosyBeans is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation, either version 3 of the License, or
9 * (at your option) any later version.
10 *
11 * CosyBeans is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with CosyBeans. If not, see <http://www.gnu.org/licenses/>.
18 */
19
20 package com.cosylab.application;
21
22 /**
23 * A specialization of the <code>CosyComponent</code> interface that declares
24 * additional functionality for installing this component into the manager and
25 * container. Plugins must:
26 * <ul>
27 * <li>
28 * Declare a public, default no-arg constructor. The initialization of the
29 * plugin must not occur in the constructor.
30 * </li>
31 * <li>
32 * Implement the <code>installPlugIn</code> method declared in this interface.
33 * The <code>PlugInManager</code> design contract guarantees, that the plugin
34 * will be added to the <code>CosyPanel</code> container <b>before</b> this
35 * method is invoked. Therefore, the plugin can use its <code>getCosyPanelParent</code>
36 * reference in this method.
37 * </li>
38 * </ul>
39 * <p>
40 * Plugins are identified by their class type, i.e. the <code>Class</code> object
41 * used during the <code>installPlugIn</code> call on the manager is used to
42 * instantiate as well as lookup the plugin (after it has been installed). Therefore,
43 * the class object <b>must not</b> represent an abstract class, an interface or any
44 * other non-instantiable object.
45 * </p>
46 * <p>
47 * The manager must, when it is destroying, destroy the plugin before it removes it
48 * from its cosy panel parent. During destruction, the plugin must release its
49 * resources, but handle all subsequent invocations of its methods gracefully (either
50 * by doing NOP, or by returning uninitialized values). This is intended to
51 * prevent other plugins that depend on this one to receive exceptions when they
52 * invoke methods on this as part of their destroy.
53 * </p>
54 * <p>
55 * During installation, this plugin may request the plugin manager to install
56 * other plugins. The manager will throw an exception if cyclic referencing is
57 * discovered. The manager may keep the list of dependencies, but does not need to.
58 * </p>
59 * <p>
60 * If this plugin depends on other plugins, it should, before calling their methods,
61 * check if the plugins are still valid (not destroyed). Even better, instad of
62 * holding fixed references to the plugins, this plugin should invoke
63 * <code>getPlugIn</code> on the manager each time it wants to invoke a method, always
64 * checking for <code>null</code> return value. Another option is for the plugin to
65 * become a <code>CosyPanelListener</code> of its panel and stop executing methods
66 * on other plugins after it receives <code>destroying</code> event.
67 * </p>
68 *
69 */
70 public interface PlugIn {
71
72 /**
73 * Installs the plugin. It is the responsibility of the manager to detect
74 * the cyclic references, add this plugin to the parent cosy panel and its
75 * containment list. Implement this method to provide installation for
76 * the plugin; it can reference the <code>getCosyPanelParent</code>.
77 *
78 * @param manager the reference to the manager installing this plugin
79 *
80 * @exception PlugInException when the installation fails for whatever reason
81 * (invalid preconditions, cyclic reference etc).
82 */
83 public void installPlugIn(PlugInManager manager) throws PlugInException;
84
85 /**
86 * Destroys the plugin and all resources associated with this plugin should
87 * be released.
88 *
89 */
90 public void destroy();
91 }
92