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 * Interface defining an object capable of managing simple plugins. The methods
24 * of this interface allow the user to install a plug in, register plugin
25 * listener (for receiving containment and state changes regarding the
26 * plugins) and browse the list of installed plugins. Note that in principle
27 * the plugin manager can be an object completely separate from the
28 * <code>CosyPanel</code> instance, which is affected by installed plugins.
29 * Moreover, there could be one manager per a large number of
30 * <code>CosyPanels</code> (e.g. one manager per application), which could
31 * reduce the memory footprint of the application.
32 *
33 * <p>
34 * All methods except for the <code>installPlugIn</code> have straightforward
35 * behavior. The implementation must be thread safe, especially the
36 * combination of install and browse methods.
37 * </p>
38 *
39 * <p>
40 * A plugin is added to the manager after it has been installed successfully. A
41 * plugin is removed from the manager after a destroy has been attempted.
42 * Adding and destroying the plugin are the responsibilities of the manager.
43 * </p>
44 *
45 * <p>
46 * Listeners wanting to receive the updates about the plugin state should
47 * listen primarily to <code>PlugInEvent</code>s and not
48 * <code>CosyPanelEvent</code>s; in case of failed plugin installation, the
49 * plugin (in the role of cosy component) will first be added and then removed
50 * from the cosy panel (two event notifications). However,
51 * <code>PlugInEvent</code> will be raised by the plugin manager <b>only
52 * if</b> the installation of the plugin completes successfully.
53 * </p>
54 *
55 * <p>
56 * Calling <code>destroy()</code> on manager also destroys all contained
57 * plugins. Plugins GUI components are first removed from
58 * <code>CosyApplicationPanel</code>, then <code>destroyed</code> is called on
59 * plugin and finally they are removed from cosy containment tree- parent is
60 * set to null.
61 * </p>
62 */
63 public interface PlugInManager
64 {
65 /**
66 * Installs a new plugin into this manager. Installing a plugin involves,
67 * in the order prescribed below:
68 *
69 * <ul>
70 * <li>
71 * Checking if the plugin is already installed (check by class type). If
72 * so, return.
73 * </li>
74 * <li>
75 * Instantiate the plugin with the default no-arg constructor.
76 * </li>
77 * <li>
78 * Add the plugin to the <code>CosyPanel</code> instance, blocking on
79 * <code>getHierarchyLock</code>. Within the same guarded section invoke
80 * <code>setCosyPanelParent</code> on the plugin, passing the cosy panel
81 * itself as a parameter.
82 * </li>
83 * <li>
84 * Invoke <code>installPlugIn(this)</code> on the plugin, allowing the
85 * plugin to initialize. NOTE: if this method fails by throwing an
86 * exception, remove the plugin as cosy component from the cosy panel.
87 * </li>
88 * <li>
89 * Inform the plugin listeners that a new plugin was installed, if no
90 * exception was thrown in the preceding call.
91 * </li>
92 * </ul>
93 *
94 * <p>
95 * The method must actively guard against the cyclic references among
96 * plugins. Therefore, if, during installation of plug A, plug B is being
97 * installed, which requests plug A installation (cycle), the plugin
98 * manager must raise a <code>PlugInException</code>.
99 * </p>
100 *
101 * @param plugType the Class type marking the plug to be installed. The
102 * plug must implement the <code>PlugIn</code> interface, otherwise
103 * a <code>PlugInException</code> must be raised.
104 */
105 public void installPlugIn(Class plugType) throws PlugInException;
106
107 /**
108 * Removes plugin with provided type, if installed. First destroy() is
109 * called, plugin must remove itself from CosyApplicationPanel.
110 *
111 * @param plugType to be removed
112 *
113 * @throws PlugInException
114 */
115 public void removePlugIn(Class plugType);
116
117 /**
118 * Returns a list of all plugins installed by this plugin manager.
119 *
120 * @return PlugIn[] plugins
121 */
122 public PlugIn[] getPlugIns();
123
124 /**
125 * Returns a plugin installed with <code>plugType</code> type or
126 * <code>null</code> if such plugin has not been installed.
127 *
128 * @return PlugIn the plugin of type <code>plugType</code> or
129 * <code>null</code>
130 */
131 public PlugIn getPlugIn(Class plugType);
132 /**
133 * Returns a plugin with <code>plugType</code> type. If manager does not have recquired plugub, trys to install it first.
134 *
135 *
136 * @return PlugIn the plugin of type <code>plugType</code> or
137 * <code>null</code>
138 */
139 public PlugIn acquirePlugIn(Class plugType) throws PlugInException;
140
141 /**
142 * Adds a plugin listener.
143 *
144 * @param l listener object.
145 */
146 public void addPlugInListener(PlugInListener l);
147
148 /**
149 * Remove a plugin listener.
150 *
151 * @param l listener object
152 */
153 public void removePlugInListener(PlugInListener l);
154
155 /**
156 * Returns all plugin listeners as per Java 1.4 beans specifications.
157 *
158 * @return PlugInListener[] array of currently registered listeners
159 */
160 public PlugInListener[] getPlugInListeners();
161
162 /**
163 * Sets the panel which is the owner of the plugin.
164 *
165 * @param owner
166 */
167 public void setOwnerPanel(ApplicationPanel owner);
168
169 /**
170 * Returns the owner panel.
171 *
172 * @return
173 */
174 public ApplicationPanel getOwnerPanel();
175 }
176
177 /* __oOo__ */