KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > update > configurator > IPlatformConfiguration


1 /*******************************************************************************
2  * Copyright (c) 2000, 2005 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.update.configurator;
12
13 import java.io.IOException JavaDoc;
14 import java.net.URL JavaDoc;
15
16 /**
17  * Platform configuration interface. Represents the runtime
18  * configuration used by the Eclipse platform. Any configuration
19  * changes do not take effect until next startup of the Eclipse
20  * platform.
21  * <p>
22  * Do not provide implementations of this interface or its nested interfaces. Use the factory methods
23  * on IPlatformConfigurationFactory to create a IPlatformConfiguration, then use the factory methods
24  * on the IPlatformConfiguration to create instances of ISiteEntry,IFeatureEntry and ISitePolicy.
25  * </p>
26  * <p>
27  * <b>Note:</b> This class/interface is part of an interim API that is still under development and expected to
28  * change significantly before reaching stability. It is being made available at this early stage to solicit feedback
29  * from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken
30  * (repeatedly) as the API evolves.
31  * </p>
32  * @since 3.0
33  */

34 public interface IPlatformConfiguration {
35
36     /**
37      * Configuration entry representing an install site.
38      *
39      * @since 2.0
40      */

41     public interface ISiteEntry {
42
43         /**
44          * Returns the URL for this site
45          *
46          * @return site url
47          * @since 2.0
48          */

49         public URL JavaDoc getURL();
50
51         /**
52          * Returns the policy for this site
53          *
54          * @return site policy
55          * @since 2.0
56          */

57         public ISitePolicy getSitePolicy();
58
59         /**
60          * Sets the site policy
61          *
62          * @param policy site policy
63          * @since 2.0
64          */

65         public void setSitePolicy(ISitePolicy policy);
66
67         /**
68          * Returns a list of features visible on the site. Note, that this is simply a
69          * reflection of the site content. The features may or may not be actually configured.
70          *
71          * @return an array of feature entries, or an empty array if no features are found.
72          * A feature entry is returned as a path relative to the site URL
73          * @since 2.0
74          */

75         public String JavaDoc[] getFeatures();
76
77         /**
78          * Returns a list of plug-ins visible on the site. Note, that this is simply a
79          * reflection of the site content and the current policy for the site. The plug-ins
80          * may or may not end up being used by Eclipse (depends on which plug-in are
81          * actually bound by the platform).
82          *
83          * @return an array of plug-in entries, or an empty array if no plug-ins are found.
84          * A plug-in entry is returned as a path relative to the site URL *
85          * @since 2.0
86          */

87         public String JavaDoc[] getPlugins();
88
89         /**
90          * Returns a stamp reflecting the current state of the site. If called repeatedly,
91          * returns the same value as long as no changes were made to the site (changes to
92          * features or plugins).
93          *
94          * @return site change stamp
95          * @since 2.0
96          */

97         public long getChangeStamp();
98
99         /**
100          * Returns a stamp reflecting the current state of the features on the site.
101          * If called repeatedly, returns the same value as long as no changes were made to
102          * features on the site.
103          *
104          * @return site features change stamp
105          * @since 2.0
106          * @deprecated Do not use this method
107          */

108         public long getFeaturesChangeStamp();
109
110         /**
111          * Returns a stamp reflecting the current state of the plug-ins on the site.
112          * If called repeatedly, returns the same value as long as no changes were made to
113          * plug-ins on the site.
114          *
115          * @return site plug-ins change stamp
116          * @since 2.0
117          * @deprecated Do not use this method
118          */

119         public long getPluginsChangeStamp();
120
121         /**
122          * Returns an indication whether the site can be updated.
123          *
124          * @return <code>true</code> if site can be updated, <code>false</code> otherwise
125          * @since 2.0
126          */

127         public boolean isUpdateable();
128
129         /**
130          * Returns an indication whether the site represents an install site
131          * that has been linked via a native installer (using the links/<linkfile>
132          * mechanism)
133          *
134          * @return <code>true</code> if the site is linked, <code>false</code> otherwise
135          * @since 2.0
136          */

137         public boolean isNativelyLinked();
138     }
139
140     /**
141      * Site policy. The site policy object determines how plug-ins
142      * contained on the site are processed during startup. In general,
143      * there are 3 ways of configuring a site policy
144      * <ul>
145      * <li>explicitly specify which plug-ins are to be included at
146      * startup (type==USER_INCLUDE). Any other plug-ins located
147      * at the site are ignored at startup. This is typically the best
148      * policy when using remote sites where the user wishes
149      * to retain explicit control over the plug-ins that are included
150      * from such site.
151      * <li>explicitly specify which plug-ins are to be excluded at
152      * startup (type==USER-EXCLUDE). All other plug-ins located
153      * at the site are used at startup. This policy requires that
154      * the site support an access "protocol" that allows plug-in
155      * discovery. In general, these are sites defined using the "file"
156      * URL protocol. This is typically the best policy for local
157      * install sites (on the user system).
158      * </ul>
159      *
160      * @since 2.0
161      */

162     public interface ISitePolicy {
163
164         /**
165          * Policy type constants.
166          */

167
168         /**
169          * User-defined inclusion list. The list associated with this
170          * policy type is interpreted as path entries to included plugin.xml
171          * or fragment.xml <b>relative</b> to the site URL
172          */

173         public static final int USER_INCLUDE = 0;
174
175         /**
176          * User-defined exclusion list. The list associated with this
177          * policy type is interpreted as path entries to excluded plugin.xml
178          * or fragment.xml <b>relative</b> to the site URL
179          */

180         public static final int USER_EXCLUDE = 1;
181         
182         /**
183          * When this site policy is used, only plug-ins specified by the configured features
184          * are contributed to the runtime.
185          * @since 3.1
186          */

187         public static final int MANAGED_ONLY = 2;
188
189         /**
190          * Return policy type
191          *
192          * @return policy type
193          * @since 2.0
194          */

195         public int getType();
196
197         /**
198          * Return policy inclusion/ exclusion list
199          *
200          * @return the list as an array
201          * @since 2.0
202          */

203         public String JavaDoc[] getList();
204
205         /**
206          * Set new policy list. The list entries are interpreted based on the policy
207          * type. See description of the policy type constants for details.
208          *
209          * @param list policy inclusion/ exclusion list as an array.
210          * Returns an empty array if there are no entries.
211          * @see #USER_INCLUDE
212          * @see #USER_EXCLUDE
213          * @since 2.0
214          */

215         public void setList(String JavaDoc[] list);
216     }
217
218     /**
219      * Feature entry.
220      * Represents runtime "hints" about configured features.
221      * The information is used during execution to locate the
222      * correct attribution information for a feature. Note,
223      * that a typical configuration can declare multiple feature
224      * entries. At execution time, only one can be selected as
225      * the active primary feature. This is determined based on
226      * specified command line arguments or computed defaults.
227      *
228      * @since 2.0
229      */

230     public interface IFeatureEntry {
231
232         /**
233          * Returns feature identifier.
234          * @return feature identifier
235          * @since 2.0
236          */

237         public String JavaDoc getFeatureIdentifier();
238
239         /**
240          * Returns the currently configured version for the feature.
241          * @return feature version (as string), or <code>null</code>
242          * @since 2.0
243          */

244         public String JavaDoc getFeatureVersion();
245
246         /**
247          * Returns the identifier of the feature plug-in for this feature entry.
248              * Note, that there is no guarantee that a feature in fact
249              * supplies a corresponding feature plugin, so the result can be
250              * <code>null</code>. Also, if supplied, there is no guarantee that the
251              * plugin will in fact be loaded into the plug-in registry at runtime
252              * (due to rules and constraint checking performed by the registry
253              * loading support). Consequently code making use of this method must
254              * handle these conditions.
255          * @return feature identifier (as string), or <code>null</code>
256          * @since 2.1
257          */

258         public String JavaDoc getFeaturePluginIdentifier();
259
260         /**
261          * Returns the version of the feature plug-in for this feature
262          * entry. Note, that there is no guarantee that a feature in fact
263          * supplies a corresponding feature plugin, so the result can be
264          * <code>null</code>. Also, if supplied, there is no guarantee that the
265          * plugin will in fact be loaded into the plug-in registry at runtime
266          * (due to rules and constraint checking performed by the registry
267          * loading support). Consequently code making use of this method must
268          * handle these conditions.
269          * @return feature version (as string), or <code>null</code>
270          * @since 2.0
271          */

272         public String JavaDoc getFeaturePluginVersion();
273
274         /**
275          * Returns the application to run when this feature is the
276          * primary feature.
277          * @return application identifier, or <code>null</code>
278          * @since 2.0
279          */

280         public String JavaDoc getFeatureApplication();
281
282         /**
283          * Returns URLs to the feature "root" locations. The root
284          * URLs are install locations of the feature plugin and its
285          * fragments.
286          *
287          * @return array of URLs, or an empty array
288          * @since 2.0
289          */

290         public URL JavaDoc[] getFeatureRootURLs();
291
292         /**
293          * Returns an indication whether this feature has been defined
294          * to act as a primary feature.
295          * @return <code>true</code> if the feature can be primary,
296          * <code>false</code> otherwise.
297          * @since 2.0
298          */

299         public boolean canBePrimary();
300     }
301
302     /**
303      * Create a site entry
304      *
305      * @param url site URL
306      * @param policy site policy
307      * @return created site entry
308      * @since 2.0
309      */

310     public ISiteEntry createSiteEntry(URL JavaDoc url, ISitePolicy policy);
311
312     /**
313      * Create a site policy. The policy determines the way the site
314      * plug-in are processed at startpu
315      *
316      * @param type policy type
317      * @param list an array of site-relative paths representing the
318      * inclusion/ exclusion list
319      * @return created site policy entry
320      * @since 2.0
321      */

322     public ISitePolicy createSitePolicy(int type, String JavaDoc[] list);
323
324     /**
325      * Create a feature entry
326      * @param id feature identifier. Must not be <code>null</code>.
327      * @param version feature version (as String). Can be <code>null</code>.
328      * @param pluginVersion version of the feature plugin (as String). Can be
329      * <code>null</code>.
330      * @param primary <code>true</code> if the feature is defined as a primary
331      * feature, otherwise <code>false</code>.
332      * @param application identifier of the application to run when
333      * this feature is the primary feature. Can be <code>null</code>.
334      * If specified, the identifier must represent a valid extension
335      * registered in the <code>org.eclipse.core.runtime.applications</code>
336      * extension point.
337      * @param root an array of URLs to feature root directories.
338      * These are URLs to install locations for the feature plugin
339      * and its fragments. Can be <code>null</code>.
340      * @return create feature entry
341      * @since 2.0
342      */

343     public IFeatureEntry createFeatureEntry(String JavaDoc id, String JavaDoc version, String JavaDoc pluginVersion, boolean primary, String JavaDoc application, URL JavaDoc[] root);
344
345     /**
346      * Create a feature entry
347      * @param id feature identifier. Must not be <code>null</code>.
348      * @param version feature version (as String). Can be <code>null</code>.
349      * @param pluginIdentifier identifier of the feature plugin (as String). Can
350      * be <code>null</code>.
351      * @param pluginVersion version of the feature plugin (as String). Can be
352      * <code>null</code>.
353      * @param primary <code>true</code> if the feature is defined as a primary
354      * feature, otherwise <code>false</code>.
355      * @param application identifier of the application to run when
356      * this feature is the primary feature. Can be <code>null</code>.
357      * If specified, the identifier must represent a valid extension
358      * registered in the <code>org.eclipse.core.runtime.applications</code>
359      * extension point.
360      * @param root an array of URLs to feature root directories.
361      * These are URLs to install locations for the feature plugin
362      * and its fragments. Can be <code>null</code>.
363      * @return create feature entry
364      * @since 2.1
365      */

366     public IFeatureEntry createFeatureEntry(String JavaDoc id, String JavaDoc version, String JavaDoc pluginIdentifier, String JavaDoc pluginVersion, boolean primary, String JavaDoc application, URL JavaDoc[] root);
367
368     /**
369      * Configures the specified site entry. If a site entry with the
370      * same site URL is already configured, the entry is <b>not</b> replaced.
371      *
372      * @param entry site entry
373      * @since 2.0
374      */

375     public void configureSite(ISiteEntry entry);
376
377     /**
378      * Configures the specified site entry. If a site entry with the
379      * same site URL is already configured, the replacement behavior for
380      * the entry can be specified.
381      *
382      * @param entry site entry
383      * @param replace indicating whether an existing configured entry with
384      * the same URL should be replaced (<code>true</code>) or not (<code>false</code>).
385      * @since 2.0
386      */

387     public void configureSite(ISiteEntry entry, boolean replace);
388
389     /**
390      * Unconfigures the specified entry. Does not do anything if the entry
391      * is not configured.
392      *
393      * @param entry site entry
394      * @since 2.0
395      */

396     public void unconfigureSite(ISiteEntry entry);
397
398     /**
399      * Returns configured site entries
400      *
401      * @return array of site entries. Returns an empty array if no sites are
402      * configured
403      * @since 2.0
404      */

405     public ISiteEntry[] getConfiguredSites();
406
407     /**
408      * Returns a site entry matching the specified URL
409      *
410      * @param url site url
411      * @return matching site entry, or <code>null</code> if no match found
412      * @since 2.0
413      */

414     public ISiteEntry findConfiguredSite(URL JavaDoc url);
415
416     /**
417      * Configures the feature entry.
418      * If another feature entry with the same feature identifier
419      * already exists, it is replaced.
420      * @param entry feature entry
421      * @since 2.0
422      */

423     public void configureFeatureEntry(IFeatureEntry entry);
424
425     /**
426      * Unconfigures the specified feature entry if it exists.
427      * @param entry feature entry
428      * @since 2.0
429      */

430     public void unconfigureFeatureEntry(IFeatureEntry entry);
431
432     /**
433      * Returns a list of configured feature entries.
434      * @return array or entries, or an empty array if no entries
435      * are configured
436      * @since 2.0
437      */

438     public IFeatureEntry[] getConfiguredFeatureEntries();
439
440     /**
441      * Locates the specified feature entry.
442      * @param id feature identifier
443      * @return ferature entry, or <code>null</code>.
444      * @since 2.0
445      */

446     public IFeatureEntry findConfiguredFeatureEntry(String JavaDoc id);
447
448     /**
449      * Returns the URL location of the configuration information
450      *
451      * @return configuration location URL, or <code>null</code> if the
452      * configuration location could not be determined.
453      * @since 2.0
454      */

455     public URL JavaDoc getConfigurationLocation();
456
457     /**
458      * Returns a stamp reflecting the current state of the configuration. If called repeatedly,
459      * returns the same value as long as no changes were made to the configuration (changes to
460      * sites, features or plugins).
461      *
462      * @return configuration change stamp
463      * @since 2.0
464      */

465     public long getChangeStamp();
466
467     /**
468      * Returns a stamp reflecting the current state of the features in the configuration.
469      * If called repeatedly, returns the same value as long as no changes were made to
470      * features in the configuration.
471      *
472      * @return configuration features change stamp
473      * @since 2.0
474      * @deprecated Do not use this method.
475      */

476     public long getFeaturesChangeStamp();
477
478     /**
479      * Returns a stamp reflecting the current state of the plug-ins in the configuration.
480      * If called repeatedly, returns the same value as long as no changes were made to
481      * plug-ins in the configuration.
482      *
483      * @return configuration plug-ins change stamp
484      * @since 2.0
485      * @deprecated Do not use this method
486      */

487     public long getPluginsChangeStamp();
488
489     /**
490      * Returns the identifier of the configured primary feature. A primary feature
491      * is used to specify product customization information for a running instance
492      * of Eclipse.
493      *
494      * @return primary feature identifier, or <code>null</code> if none configured
495      * @since 2.0
496      */

497     public String JavaDoc getPrimaryFeatureIdentifier();
498
499     /**
500      * Computes the plug-in path for this configuration. The result includes all plug-ins
501      * visible on each of the configured sites based on each site policy.
502      *
503      * @return an array of plug-in path elements (full URL entries), or an empty array.
504      * @since 2.0
505      */

506     public URL JavaDoc[] getPluginPath();
507
508     /**
509      * Returns an array of bootstrap plugin identifiers whose
510      * location needs to be explicitly identified in the configuration.
511      *
512      * @return an array of identifiers, or empty array
513      * otherwise
514      * @since 2.0
515      * @deprecated Do not use this method. Check the osgi.bundles system property for the
516      * urls of the automatically started bundles
517      */

518     public String JavaDoc[] getBootstrapPluginIdentifiers();
519
520     /**
521      * Sets the location of a bootstrap plugin.
522      *
523      * @see IPlatformConfiguration#getBootstrapPluginIdentifiers()
524      * @param id plugin identifier. Must match one of the entries returned
525      * by getBootstrapPluginIdentifiers()
526      * @param location
527      * @since 2.0
528      * @deprecated Do not use this method. Use the osig.bundles system property contains
529      * the urls of the automatically started bundles.
530      */

531     public void setBootstrapPluginLocation(String JavaDoc id, URL JavaDoc location);
532
533     /**
534      * Returns an indication whether the configuration can be updated.
535      *
536      * @return <code>true</code> if configuration can be updated, <code>false</code>
537      * otherwise
538      * @since 2.0
539      */

540     public boolean isUpdateable();
541
542     /**
543      * Returns an indication whether the configuration is transient. A transient
544      * configuration typically represents a scenario where the configuration
545      * was computed for a single instantiation of the platform and is not
546      * guaranteed to be valid on subsequent instantiations.
547      *
548      * @return <code>true</code> if configuration is transient, <code>false</code>
549      * otherwise
550      * @since 2.0
551      */

552     public boolean isTransient();
553
554     /**
555      * Indicates whether the configuration is transient or not. A transient
556      * configuration typically represents a scenario where the configuration
557      * was computed for a single instantiation of the platform and is not
558      * guaranteed to be valid on subsequent instantiations. This method has
559      * no effect if called on the current platform configuration.
560      *
561      * @param value <code>true</code> if configuration is transient, <code>false</code>
562      * otherwise
563      * @since 2.0
564      */

565     public void isTransient(boolean value);
566
567     /**
568      * Called to refresh the configuration information. In particular,
569      * causes change stamps to be recomputed based on the current
570      * configuration state, and updates the lists of available plug-ins.
571      * @since 2.0
572      */

573     public void refresh();
574
575     /**
576      * Called to save the configuration information
577      * @since 2.0
578      */

579     public void save() throws IOException JavaDoc;
580
581     /**
582      * Called to save the configuration information in the
583      * specified location
584      *
585      * @param url save location.
586      * @since 2.0
587      */

588     public void save(URL JavaDoc url) throws IOException JavaDoc;
589
590 }
591
Popular Tags