PluginRegistry


1   /*****************************************************************************
2    * Java Plug-in Framework (JPF)
3    * Copyright (C) 2004-2007 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.registry;
20  
21  import java.net.URL  ;
22  import java.util.Collection  ;
23  import java.util.Map  ;
24  import java.util.Set  ;
25  
26  import org.java.plugin.ObjectFactory;
27  import org.java.plugin.PathResolver;
28  import org.java.plugin.PluginManager;
29  import org.java.plugin.util.ExtendedProperties;
30  
31  /**
32   * Root interface to get access to all meta-information about discovered
33   * plug-ins. All objects accessible from the registry are immutable. You
34   * can imagine registry as a read-only storage of full information about
35   * discovered plug-ins. There is only one exception from this rule: internal
36   * state of registry, plug-in descriptors and plug-in elements can be modified
37   * indirectly by {@link #register(URL[]) registering} or
38   * {@link #unregister(String[]) un-registering} plug-ins with this
39   * registry. If your code is interested to be notified on all modifications
40   * of plug-ins set, you can
41   * {@link #registerListener(PluginRegistry.RegistryChangeListener) register}
42   * an implementation of {@link PluginRegistry.RegistryChangeListener} with this
43   * registry.
44   * <p><i>Notes on unique ID's (UID's)</i></p>
45   * <p>
46   * There are two types of identifiers in the API: ID's and UID's. ID is an
47   * identifier that is unique within set of elements of the same type. UID is
48   * an identifier that unique globally within registry space. ID is usually
49   * defined by developer in plug-in manifest. UID always combined automatically
50   * from several other plug-in "parts". All plug-in elements have method
51   * {@link org.java.plugin.registry.Identity#getId() getId()} that come from
52   * basic {@link org.java.plugin.registry.Identity} interface, but not all
53   * elements have UID - only those that inherits
54   * {@link org.java.plugin.registry.UniqueIdentity}interface.
55   * </p>
56   * <p>There are several utility methods available in this interface that aimed
57   * to build UID from different plug-in "parts" and also split UID to it's
58   * original elements: {@link #makeUniqueId(String, Version)},
59   * {@link #makeUniqueId(String, String)}, {@link #extractPluginId(String)},
60   * {@link #extractId(String)} and {@link #extractVersion(String)}.
61   * </p>
62   * 
63   * @see org.java.plugin.ObjectFactory#createRegistry()
64   * 
65   * @version $Id: PluginRegistry.java,v 1.8 2007/01/05 13:22:10 ddimon Exp $
66   */
67  public interface PluginRegistry {
68      /**
69       * Registers plug-ins and plug-in fragments in this registry. Note that
70       * this method not makes plug-ins available for activation
71       * by any {@link PluginManager} instance as it is not aware of any manager.
72       * Using this method just makes plug-in meta-data available for reading from
73       * this registry.
74       * <p>
75       * If more than one version of the same plug-in or plug-in fragment given,
76       * the only latest version should be registered. If some plug-in or plug-in
77       * fragment already registered it should be ignored by this method. Client
78       * application have to un-register such plug-ins first before registering
79       * their newest versions.
80       * @param manifests array of manifest locations
81       * @return map where keys are URL's and values are registered plug-ins
82       *         or plug-in fragments, URL's for unprocessed manifests are
83       *         not included
84       * @throws ManifestProcessingException if manifest processing error has
85       *         occurred (optional behavior)
86       * 
87       * @see PluginManager#publishPlugins(PluginManager.PluginLocation[])
88       */
89      Map   register(URL  [] manifests) throws ManifestProcessingException;
90      
91      /**
92       * Reads basic information from a plug-in or plug-in fragment manifest.
93       * @param manifest manifest data URL
94       * @return manifest info
95       * @throws ManifestProcessingException if manifest data can't be read
96       */
97      ManifestInfo readManifestInfo(URL   manifest)
98              throws ManifestProcessingException;
99      
100     /**
101      * Unregisters plug-ins and plug-in fragments with given ID's
102      * (including depending plug-ins and plug-in fragments).
103      * @param ids ID's of plug-ins and plug-in fragments to be
104      *        unregistered
105      * @return collection of UID's of actually unregistered plug-ins and plug-in
106      *         fragments
107      */
108     Collection   unregister(String  [] ids);
109     
110     /**
111      * Returns descriptor of plug-in with given ID.
112      * <br>
113      * If plug-in descriptor with given ID can't be found or such plug-in
114      * exists but is damaged this method have to throw an
115      * {@link IllegalArgumentException}. In other words, this method
116      * shouldn't return <code>null</code>.
117      * @param pluginId plug-id ID
118      * @return plug-in descriptor
119      */
120     PluginDescriptor getPluginDescriptor(String   pluginId);
121     
122     /**
123      * Checks if plug-in exists and is in valid state. If this method
124      * returns <code>true</code>, the method
125      * {@link #getPluginDescriptor(String)} should always return valid plug-in
126      * descriptor.
127      * @param pluginId plug-in ID
128      * @return <code>true</code> if plug-in exists and valid
129      */
130     boolean isPluginDescriptorAvailable(String   pluginId);
131     
132     /**
133      * Returns collection of descriptors of all plug-ins that was successfully
134      * populated by this registry.
135      * @return collection of {@link PluginDescriptor} objects
136      */
137     Collection   getPluginDescriptors();
138 
139     /**
140      * Looks for extension point. This method have throw an
141      * {@link IllegalArgumentException} if requested extension point
142      * can't be found or is in invalid state.
143      * @param pluginId plug-in ID
144      * @param pointId extension point ID
145      * @return plug-in extension point
146      * @see ExtensionPoint#isValid()
147      */
148     ExtensionPoint getExtensionPoint(String   pluginId, String   pointId);
149 
150     /**
151      * Looks for extension point.
152      * @param uniqueId extension point unique ID
153      * @return plug-in extension point
154      * @see #getExtensionPoint(String, String)
155      */
156     ExtensionPoint getExtensionPoint(String   uniqueId);
157     
158     /**
159      * Checks if extension point exists and is in valid state. If this method
160      * returns <code>true</code>, the method
161      * {@link #getExtensionPoint(String, String)} should always return valid
162      * extension point.
163      * @param pluginId plug-in ID
164      * @param pointId extension point ID
165      * @return <code>true</code> if extension point exists and valid
166      */
167     boolean isExtensionPointAvailable(String   pluginId, String   pointId);
168     
169     /**
170      * Checks if extension point exists and is in valid state.
171      * @param uniqueId extension point unique ID
172      * @return <code>true</code> if extension point exists and valid
173      * @see #isExtensionPointAvailable(String, String)
174      */
175     boolean isExtensionPointAvailable(String   uniqueId);
176 
177     /**
178      * Returns collection of descriptors of all plug-in fragments that was
179      * successfully populated by this registry.
180      * @return collection of {@link PluginFragment} objects
181      */
182     Collection   getPluginFragments();
183     
184     /**
185      * Utility method that recursively collects all plug-ins that depends on
186      * the given plug-in.
187      * @param descr descriptor of plug-in to collect dependencies for
188      * @return collection of {@link PluginDescriptor plug-in descriptors}
189      *         that depend on given plug-in
190      */
191     Collection   getDependingPlugins(PluginDescriptor descr);
192 
193     /**
194      * Performs integrity check of all registered plug-ins and generates result
195      * as a collection of standard report items.
196      * @param pathResolver optional path resolver
197      * @return integrity check report
198      */
199     IntegrityCheckReport checkIntegrity(PathResolver pathResolver);
200     
201     /**
202      * Performs integrity check of all registered plug-ins and generates result
203      * as a collection of standard report items.
204      * @param pathResolver optional path resolver
205      * @param includeRegistrationReport if <code>true</code>, the plug-ins
206      *                                  registration report will be included
207      *                                  into resulting report
208      * @return integrity check report
209      */
210     IntegrityCheckReport checkIntegrity(PathResolver pathResolver,
211             boolean includeRegistrationReport);
212     
213     /**
214      * @return plug-ins registration report for this registry
215      */
216     IntegrityCheckReport getRegistrationReport();
217     
218     /**
219      * Constructs unique identifier for some plug-in element from it's ID.
220      * @param pluginId plug-in ID
221      * @param elementId element ID
222      * @return unique ID
223      */
224     String   makeUniqueId(String   pluginId, String   elementId);
225     
226     /**
227      * Constructs unique identifier for plug-in with given ID.
228      * @param pluginId plug-in ID
229      * @param version plug-in version identifier
230      * @return unique plug-in ID
231      */
232     String   makeUniqueId(String   pluginId, Version version);
233     
234     /**
235      * Extracts plug-in ID from some unique identifier.
236      * @param uniqueId unique ID
237      * @return plug-in ID
238      */
239     String   extractPluginId(String   uniqueId);
240 
241     /**
242      * Extracts plug-in element ID from some unique identifier.
243      * @param uniqueId unique ID
244      * @return element ID
245      */
246     String   extractId(String   uniqueId);
247     
248     /**
249      * Extracts plug-in version identifier from some unique identifier
250      * (plug-in or plug-in fragment).
251      * @param uniqueId unique ID
252      * @return plug-in version identifier
253      */
254     Version extractVersion(String   uniqueId);
255     
256     /**
257      * Registers plug-in registry change event listener. If given listener has
258      * been registered before, this method should throw an
259      * {@link IllegalArgumentException}.
260      * @param listener new registry change event listener
261      */
262     void registerListener(RegistryChangeListener listener);
263     
264     /**
265      * Unregisters registry change event listener. If given listener hasn't been
266      * registered before, this method should throw an
267      * {@link IllegalArgumentException}.
268      * @param listener registered listener
269      */
270     void unregisterListener(RegistryChangeListener listener);
271     
272     /**
273      * Configures this registry instance. Usually this method is called from
274      * {@link ObjectFactory object factory} implementation.
275      * @param config registry configuration data
276      */
277     void configure(ExtendedProperties config);
278     
279     /**
280      * Plug-in registry changes callback interface.
281      * @version $Id: PluginRegistry.java,v 1.8 2007/01/05 13:22:10 ddimon Exp $
282      */
283     interface RegistryChangeListener {
284         /**
285          * This method will be called by the framework when changes are made
286          * on registry (via {@link PluginRegistry#register(URL[])} or
287          * {@link PluginRegistry#unregister(String[])} methods).
288          * @param data registry changes data
289          */
290         void registryChanged(RegistryChangeData data);
291     }
292     
293     /**
294      * Registry changes data holder interface.
295      * @version $Id: PluginRegistry.java,v 1.8 2007/01/05 13:22:10 ddimon Exp $
296      */
297     interface RegistryChangeData {
298         /**
299          * @return collection of ID's of newly added plug-ins
300          */
301         Set   addedPlugins();
302         
303         /**
304          * @return collection of ID's of removed plug-ins
305          */
306         Set   removedPlugins();
307         
308         /**
309          * @return collection of ID's of changed plug-ins
310          */
311         Set   modifiedPlugins();
312         
313         /**
314          * @return collection of unique ID's of newly connected extensions
315          */
316         Set   addedExtensions();
317         
318         /**
319          * @param extensionPointUid unique ID of extension point to filter
320          *                          result
321          * @return collection of unique ID's of newly connected extensions
322          */
323         Set   addedExtensions(String   extensionPointUid);
324         
325         /**
326          * @return collection of unique ID's of disconnected extensions
327          */
328         Set   removedExtensions();
329         
330         /**
331          * @param extensionPointUid unique ID of extension point to filter
332          *                          result
333          * @return collection of unique ID's of disconnected extensions
334          */
335         Set   removedExtensions(String   extensionPointUid);
336 
337         /**
338          * @return collection of unique ID's of modified extensions
339          */
340         Set   modifiedExtensions();
341 
342         /**
343          * @param extensionPointUid unique ID of extension point to filter
344          *                          result
345          * @return collection of unique ID's of modified extensions
346          */
347         Set   modifiedExtensions(String   extensionPointUid);
348     }
349     
350     /**
351      * Manifest info holder interface.
352      * 
353      * @see PluginRegistry#readManifestInfo(URL)
354      * @version $Id: PluginRegistry.java,v 1.8 2007/01/05 13:22:10 ddimon Exp $
355      */
356     interface ManifestInfo {
357         /**
358          * @return plug-in or plug-in fragment identifier
359          */
360         String   getId();
361         
362         /**
363          * @return plug-in or plug-in fragment version identifier
364          */
365         Version getVersion();
366         
367         /**
368          * @return plug-in or plug-in fragment vendor
369          */
370         String   getVendor();
371         
372         /**
373          * @return plug-in identifier this, fragment contributes to or
374          *         <code>null</code> if this info is for plug-in manifest
375          */
376         String   getPluginId();
377         
378         /**
379          * @return plug-in version identifier, this fragment contributes to or
380          *         <code>null</code> if this info is for plug-in manifest
381          */
382         Version getPluginVersion();
383         
384         /**
385          * @return plug-in version matching rule or <code>null</code> if this
386          *         info is for plug-in manifest
387          */
388         String   getMatchingRule();
389     }
390 }
391
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags