IPluginDescriptor


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.core.runtime;
12  
13  import java.net.URL  ;
14  import java.util.*;
15  
16  /**
17   * A plug-in descriptor contains information about a plug-in
18   * obtained from the plug-in's manifest (<code>plugin.xml</code>) file.
19   * <p>
20   * Plug-in descriptors are platform-defined objects that exist
21   * in the plug-in registry independent of whether a plug-in has
22   * been started. In contrast, a plug-in's runtime object 
23   * (<code>getPlugin</code>) generally runs plug-in-defined code.
24   * </p>
25   * <p>This interface is not intended to be implemented by clients.
26   * </p>
27   *
28   * @deprecated 
29   * <code>IPluginDescriptor</code> was refactored in Eclipse 3.0.
30   * Most of the functionality has moved to {@link Platform} and the 
31   * plug-in descriptor has been replaced with the OSGi <code>Bundle</code> 
32   * object.
33   * <p>
34   * This interface must only be used by plug-ins 
35   * which explicitly require the org.eclipse.core.runtime.compatibility plug-in.
36   * </p>
37   * <p>
38   * For most uses the bundle object can be treated as an opaque token
39   * representing your plug-in to the system -- It must be supplied to various 
40   * <code>Platform</code> methods but need not be interrogated itself.
41   * There are a small number of plug-in descriptor method equivalents 
42   * supplied by <code>Bundle</code> itself.  The details are spelled out
43   * in the comments on each <code>IPluginDescriptor</code> method.
44   * </p>
45   * <p>
46   * Clients of this interface have a reference to an <code>IPluginDescriptor</code> 
47   * corresponding to a plug-in.  To adapt to the deprecation, the bundle corresponding
48   * to the plug-in generally needs to be acquired. There are several cases:
49   * <ul>
50   * <li>the descriptor was discovered using methods such as 
51   * <code>IPluginRegistry.getPluginDescriptor()</code>.  The code should be 
52   * updated to use one of the bundle discovery mechanisms such as 
53   * <code>Platform.getBundle()</code>.
54   * </li>
55   * <li>the descriptor is from the plug-in itself.  The code should be updated to
56   * use the plug-in's bundle instead.
57   * </li>
58   * <li>the descriptor is supplied by a third party.  The plug-in writer must 
59   * cooperate with that party to obtain a bundle rather than a descriptor.
60   * </li>
61   * </ul>
62   * </p>
63   * <p>
64   * The resulting bundle object can be used
65   * to carry out the adaptation steps outlined for each of the 
66   * <code>IPluginDescriptor</code> methods.
67   * </p>
68   * 
69   * @see #getPlugin()
70   */
71  public interface IPluginDescriptor {
72      /**
73       * Returns the extension with the given simple identifier declared in
74       * this plug-in, or <code>null</code> if there is no such extension.
75       * Since an extension might not have an identifier, some extensions
76       * can only be found via the <code>getExtensions</code> method.
77       *
78       * @param extensionName the simple identifier of the extension (e.g. <code>"main"</code>).
79       * @return the extension, or <code>null</code>
80       * @deprecated 
81       * Use 
82       * <pre>
83       *     Platform.getExtensionRegistry().getExtension(id + "." + extensionName) 
84       * </pre>
85       * where <code>id</code> is the plug-in id.
86       */
87      public IExtension getExtension(String   extensionName);
88  
89      /**
90       * Returns the extension point with the given simple identifier
91       * declared in this plug-in, or <code>null</code> if there is no such extension point.
92       *
93       * @param extensionPointId the simple identifier of the extension point (e.g. <code>"wizard"</code>).
94       * @return the extension point, or <code>null</code>
95       * @deprecated  
96       * Use 
97       * <pre>
98       *     Platform.getExtensionRegistry().getExtensionPoint(id, extensionPointId) 
99       * </pre>
100      * where <code>id</code> is the plug-in id.
101      */
102     public IExtensionPoint getExtensionPoint(String   extensionPointId);
103 
104     /**
105      * Returns all extension points declared by this plug-in.
106      * Returns an empty array if this plug-in does not declare any extension points.
107      *
108      * @return the extension points declared by this plug-in
109      * @deprecated 
110      * Use 
111      * <pre>
112      *     Platform.getExtensionRegistry().getExtensionPoints(id) 
113      * </pre>
114      * where <code>id</code> is the plug-in id.
115      */
116     public IExtensionPoint[] getExtensionPoints();
117 
118     /**
119      * Returns all extensions declared by this plug-in.
120      * Returns an empty array if this plug-in does not declare any extensions.
121      *
122      * @return the extensions declared by this plug-in
123      * @deprecated 
124      * Use 
125      * <pre>
126      *     Platform.getExtensionRegistry().getExtensions(id) 
127      * </pre>
128      * where <code>id</code> is the plug-in id.
129      */
130     public IExtension[] getExtensions();
131 
132     /**
133      * Returns the URL of this plug-in's install directory. 
134      * This is the directory containing
135      * the plug-in manifest file, resource bundle, runtime libraries,
136      * and any other files supplied with this plug-in. This directory is usually
137      * read-only. Plug-in relative information should be written to the location 
138      * provided by <code>Plugin.getStateLocation</code>.
139      *
140      * @return the URL of this plug-in's install directory
141      * @see #getPlugin()
142      * @see Plugin#getStateLocation()
143      * @deprecated 
144      * Use 
145      * <pre>
146      *     bundle.getEntry("/");
147      * </pre>
148      * where <code>bundle</code> is the bundle associated with 
149      * the relevant plug-in or simply use the <code>getEntry</code> API
150      * to construct the desired URL.
151      */
152     public URL   getInstallURL();
153 
154     /**
155      * Returns a displayable label for this plug-in.
156      * Returns the empty string if no label for this plug-in
157      * is specified in the plug-in manifest file.
158      * <p> Note that any translation specified in the plug-in manifest
159      * file is automatically applied.
160      * </p>
161      *
162      * @return a displayable string label for this plug-in,
163      *    possibly the empty string
164      * @see #getResourceString(String)
165      * @deprecated 
166      * Use 
167      * <pre>
168      *     bundle.getHeaders().get(org.osgi.framework.Constants.BUNDLE_NAME) 
169      * </pre>
170      * where <code>bundle</code> is the bundle associated with 
171      * the relevant plug-in.
172      */
173     public String   getLabel();
174 
175     /**
176      * Returns the plug-in runtime object corresponding to this
177      * plug-in descriptor. Unlike other methods on this object,
178      * invoking this method may activate the plug-in.
179      * The returned object is an instance of the plug-in runtime class
180      * specified in the plug-in's manifest file;
181      * if a class is not specified there, the returned object
182      * is an internally-supplied one that does not react to life cycle requests.
183      *
184      * @return the plug-in runtime object
185      * @exception CoreException 
186      *   if this plug-in's runtime object could not be created.
187      * @see #isPluginActivated()
188      * @deprecated 
189      * In Eclipse 3.0 plug-in runtime objects are not globally managed and
190      * so are not generically accessible.  Rather, each plug-in is free to declare
191      * API which exposes the plug-in runtime object (e.g., <code>MyPlugin.getInstance()</code>).
192      * 
193      * If this method is being used to activate a plug-in then the following code is
194      * equivalent:
195      * <pre>
196      *     bundle.start()
197      * </pre>
198      * where <code>bundle</code> is the bundle associated with 
199      * the relevant plug-in.
200      */
201     public Plugin getPlugin() throws CoreException;
202 
203     /**
204      * Returns the plug-in class loader used to load classes and resources
205      * for this plug-in. The class loader can be used to directly access
206      * plug-in resources and classes. Note that accessing a resource will
207      * <b>not activate</b> the corresponding plug-in. Successfully loading 
208      * a class will <b>always activate</b> the corresponding plug-in.
209      * <p> 
210      * The following examples illustrate the direct use of the plug-in class
211      * loader and its effect on plug-in activation (example ignores error
212      * handling).
213      *
214      * <pre>
215      *     ClassLoader loader = descriptor.getPluginClassLoader();
216      *
217      *     // Load resource by name. Will not activate the plug-in.
218      *     URL res = loader.getResource("com/example/Foo/button.gif");
219      *     InputStream is = loader.getResourceAsStream("splash.jpg");
220      *
221      *     // Load resource for class. Will activate the plug-in because
222      *     // the referenced class is loaded first and triggers activation.
223      *     URL u = com.example.Foo.class.getResource("button.gif");
224      *
225      *     // Load class by name. Will activate the plug-in.
226      *     Class c = loader.loadClass("com.example.Bar");
227      *
228      *     // Load a resource bundle. May, or may not activate the plug-in, depending
229      *     // on the bundle implementation. If implemented as a class, the plug-in
230      *     // will be activated. If implemented as a properties file, the plug-in will
231      *     // not be activated.
232      *     ResourceBundle b = 
233      *         ResourceBundle.getBundle("bundle", Locale.getDefault(), loader);
234      * </pre>
235      *
236      * @return the plug-in class loader
237      * @see IConfigurationElement#createExecutableExtension(String)
238      * @see #isPluginActivated()
239      * @see #getResourceBundle()
240      * @deprecated 
241      * Use 
242      * <pre>
243      *     bundle.loadClass(className)
244      * </pre>
245      * where <code>bundle</code> is the bundle associated with 
246      * the relevant plug-in.
247      */
248     public ClassLoader   getPluginClassLoader();
249 
250     /**
251      * Returns a list of plug-in prerequisites required
252      * for correct execution of this plug-in.
253      *
254      * @return an array of plug-in prerequisites, or an empty array
255      * if no prerequisites were specified
256      * @deprecated 
257      * Use 
258      * <pre>
259      *     import org.eclipse.osgi.util.ManifestElement;
260      *     import org.osgi.framework.Constants;
261      *     ...
262      *     String requires = (String)bundle.getHeaders().get(Constants.REQUIRE_BUNDLE);
263      *     ManifestElement[] elements = ManifestElement.parseHeader(Constants.REQUIRE_BUNDLE, requires);
264      * </pre>
265      * where <code>bundle</code> is the bundle associated with 
266      * the relevant plug-in.  The resultant elements array contains one
267      * entry for each required plug-in.
268      */
269     public IPluginPrerequisite[] getPluginPrerequisites();
270 
271     /**
272      * Returns the name of the provider of this plug-in.
273      * Returns the empty string if no provider name is specified in 
274      * the plug-in manifest file.
275      * <p> Note that any translation specified in the plug-in manifest
276      * file is automatically applied.
277      * </p>
278      * @return the name of the provider, possibly the empty string
279      * @see #getResourceString(String)
280      * @deprecated
281      * Use 
282      * <pre>
283      *     bundle.getHeaders().get(org.osgi.framework.Constants.BUNDLE_VENDOR) 
284      * </pre>
285      * where <code>bundle</code> is the bundle associated with 
286      * the relevant plug-in.
287      */
288     public String   getProviderName();
289 
290     /**
291      * Returns this plug-in's resource bundle for the current locale. 
292      * <p>
293      * The bundle is stored as the <code>plugin.properties</code> file 
294      * in the plug-in install directory, and contains any translatable
295      * strings used in the plug-in manifest file (<code>plugin.xml</code>)
296      * along with other resource strings used by the plug-in implementation.
297      * </p>
298      *
299      * @return the resource bundle
300      * @exception MissingResourceException if the resource bundle was not found
301      * @deprecated 
302      * Use 
303      * <pre>
304      *     Platform.getResourceBundle(bundle)
305      * </pre>
306      * where <code>bundle</code> is the bundle associated with 
307      * the relevant plug-in.
308      */
309     public ResourceBundle getResourceBundle() throws MissingResourceException;
310 
311     /**
312      * Returns a resource string corresponding to the given argument value.
313      * If the argument value specifies a resource key, the string
314      * is looked up in the default resource bundle. If the argument does not
315      * specify a valid key, the argument itself is returned as the
316      * resource string. The key lookup is performed in the
317      * plugin.properties resource bundle. If a resource string 
318      * corresponding to the key is not found in the resource bundle
319      * the key value, or any default text following the key in the
320      * argument value is returned as the resource string.
321      * A key is identified as a string beginning with the "%" character.
322      * Note, that the "%" character is stripped off prior to lookup
323      * in the resource bundle.
324      * <p>
325      * Equivalent to <code>getResourceString(value, getResourceBundle())</code>
326      * </p>
327      *
328      * @param value the value
329      * @return the resource string
330      * @see #getResourceBundle()
331      * @deprecated 
332      * Use 
333      * <pre>
334      *     Platform.getResourceString(bundle, value)
335      * </pre>
336      * where <code>bundle</code> is the bundle associated with 
337      * the relevant plug-in.
338      */
339     public String   getResourceString(String   value);
340 
341     /**
342      * Returns a resource string corresponding to the given argument 
343      * value and bundle.
344      * If the argument value specifies a resource key, the string
345      * is looked up in the given resource bundle. If the argument does not
346      * specify a valid key, the argument itself is returned as the
347      * resource string. The key lookup is performed against the
348      * specified resource bundle. If a resource string 
349      * corresponding to the key is not found in the resource bundle
350      * the key value, or any default text following the key in the
351      * argument value is returned as the resource string.
352      * A key is identified as a string beginning with the "%" character.
353      * Note that the "%" character is stripped off prior to lookup
354      * in the resource bundle.
355      * <p>
356      * For example, assume resource bundle plugin.properties contains
357      * name = Project Name
358      * <pre>
359      *     getResourceString("Hello World") returns "Hello World"</li>
360      *     getResourceString("%name") returns "Project Name"</li>
361      *     getResourceString("%name Hello World") returns "Project Name"</li>
362      *     getResourceString("%abcd Hello World") returns "Hello World"</li>
363      *     getResourceString("%abcd") returns "%abcd"</li>
364      *     getResourceString("%%name") returns "%name"</li>
365      * </pre>
366      * </p>
367      *
368      * @param value the value
369      * @param resourceBundle the resource bundle
370      * @return the resource string
371      * @see #getResourceBundle()
372      * @deprecated 
373      * Use 
374      * <pre>
375      *     Platform.getResourceString(bundle, value, resourceBundle) 
376      * </pre>
377      * where <code>bundle</code> is the bundle associated with 
378      * the relevant plug-in.
379      */
380     public String   getResourceString(String   value, ResourceBundle resourceBundle);
381 
382     /**
383      * Returns all runtime libraries declared by this plug-in.
384      * Returns an empty array if this plug-in has no runtime libraries.
385      *
386      * @return the runtime libraries declared by this plug-in
387      * @deprecated 
388      * Use 
389      * <pre>
390      *     import org.eclipse.osgi.util.ManifestElement;
391      *     import org.osgi.framework.Constants;
392      *     ...
393      *     String requires = (String)bundle.getHeaders().get(Constants.BUNDLE_CLASSPATH);
394      *     ManifestElement[] elements = ManifestElement.parseHeader(Constants.BUNDLE_CLASSPATH, requires);
395      * </pre>
396      * where <code>bundle</code> is the bundle associated with 
397      * the relevant plug-in.  The resultant elements array contains one
398      * entry for each entry on the bundle's classpath..
399      */
400     public ILibrary[] getRuntimeLibraries();
401 
402     /**
403      * Returns the unique identifier of this plug-in.
404      * This identifier is a non-empty string and is unique 
405      * within the plug-in registry.
406      *
407      * @return the unique identifier of the plug-in (e.g. <code>"org.eclipse.core.runtime"</code>)
408      * @deprecated 
409      * Use 
410      * <pre>
411      *     bundle.getSymbolicName() 
412      * </pre>
413      * where <code>bundle</code> is the bundle associated with 
414      * the relevant plug-in.
415      */
416     public String   getUniqueIdentifier();
417 
418     /**
419      * Returns the version identifier of this plug-in.
420      *
421      * @return the plug-in version identifier
422      * @deprecated 
423      * Use 
424      * <pre>
425      *     String version = (String) bundle.getHeaders().get(org.osgi.framework.Constants.BUNDLE_VERSION);
426      *     new PluginVersionIdentifier(version); 
427      * </pre>
428      * where <code>bundle</code> is the bundle associated with 
429      * the relevant plug-in.
430      */
431     public PluginVersionIdentifier getVersionIdentifier();
432 
433     /**
434      * Returns whether the plug-in described by this descriptor
435      * has been activated. Invoking this method will not cause the
436      * plug-in to be activated.
437      *
438      * @return <code>true</code> if this plug-in is activated, and
439      *   <code>false</code> otherwise
440      * @see #getPlugin()
441      * @deprecated 
442      * Use 
443      * <pre>
444      *     bundle.getState == org.osgi.framework.Bundle.ACTIVE 
445      * </pre>
446      * where <code>bundle</code> is the bundle associated with 
447      * the relevant plug-in.
448      */
449     public boolean isPluginActivated();
450 
451     /**
452      * Returns a URL for the given path.  Returns <code>null</code> if the URL
453      * could not be computed or created.
454      * 
455      * @param path path relative to plug-in installation location 
456      * @return a URL for the given path or <code>null</code>  It is not
457      * necessary to perform a 'resolve' on this URL.
458      * 
459      * @since 2.0
460      * @deprecated 
461      * Use 
462      * <pre>
463      *     Platform.find(bundle, file) 
464      * </pre>
465      * where <code>bundle</code> is the bundle associated with 
466      * the relevant plug-in.
467      */
468     public URL   find(IPath path);
469 
470     /**
471      * Returns a URL for the given path.  Returns <code>null</code> if the URL
472      * could not be computed or created.
473      * 
474      * find will look for this path under the directory structure for this plugin
475      * and any of its fragments.  If this path will yield a result outside the
476      * scope of this plugin, <code>null</code> will be returned.  Note that
477      * there is no specific order to the fragments.
478      * 
479      * The following arguments may also be used
480      * 
481      *  $nl$ - for language specific information
482      *  $os$ - for operating system specific information
483      *  $ws$ - for windowing system specific information
484      * 
485      * A path of $nl$/about.properties in an environment with a default 
486      * locale of en_CA will return a URL corresponding to the first place
487      * about.properties is found according to the following order:
488      *   plugin root/nl/en/CA/about.properties
489      *   fragment1 root/nl/en/CA/about.properties
490      *   fragment2 root/nl/en/CA/about.properties
491      *   ...
492      *   plugin root/nl/en/about.properties
493      *   fragment1 root/nl/en/about.properties
494      *   fragment2 root/nl/en/about.properties
495      *   ...
496      *   plugin root/about.properties
497      *   fragment1 root/about.properties
498      *   fragment2 root/about.properties
499      *   ...
500      * 
501      * If a locale other than the default locale is desired, use an
502      * override map.
503      * 
504      * @param path file path relative to plug-in installation location
505      * @param override map of override substitution arguments to be used for
506      * any $arg$ path elements. The map keys correspond to the substitution
507      * arguments (eg. "$nl$" or "$os$"). The resulting
508      * values must be of type java.lang.String. If the map is <code>null</code>,
509      * or does not contain the required substitution argument, the default
510      * is used.
511      * @return a URL for the given path or <code>null</code>.  It is not
512      * necessary to perform a 'resolve' on this URL.
513      * 
514      * @since 2.0
515      * @deprecated 
516      * Use 
517      * <pre>
518      *     Platform.find(bundle, path, override) 
519      * </pre>
520      * where <code>bundle</code> is the bundle associated with 
521      * the relevant plug-in.
522      */
523     public URL   find(IPath path, Map override);
524 }
525
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags