IPlatformConfiguration


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.boot;
12  
13  import java.io.IOException  ;
14  import java.net.URL  ;
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   * 
22   * @since 2.0
23   * @deprecated 
24   * In Eclipse 3.0 the Update mechanism was cleanly separated from the runtime.
25   * <code>IPlatformConfiguration</code> is part of the Update story and as such has
26   * been moved to {@link org.eclipse.update.configurator.IPlatformConfiguration} in the 
27   * <code>org.eclipse.update.configurator</code> plug-in.
28   * <p>
29   * This interface must only be used by plug-ins 
30   * which explicitly require the org.eclipse.core.runtime.compatibility plug-in.
31   * </p>
32   */
33  public interface IPlatformConfiguration {
34  
35      /**
36       * Configuration entry representing an install site.
37       * 
38       * @since 2.0 
39       */
40      public interface ISiteEntry {
41  
42          /**
43           * Returns the URL for this site
44           * 
45           * @return site url
46           * @since 2.0
47           */
48          public URL   getURL();
49  
50          /**
51           * Returns the policy for this site
52           * 
53           * @return site policy
54           * @since 2.0
55           */
56          public ISitePolicy getSitePolicy();
57  
58          /**
59           * Sets the site policy
60           * 
61           * @param policy site policy
62           * @since 2.0
63           */
64          public void setSitePolicy(ISitePolicy policy);
65  
66          /**
67           * Returns a list of features visible on the site. Note, that this is simply a 
68           * reflection of the site content. The features may or may not be actually configured.
69           * 
70           * @return an array of feature entries, or an empty array if no features are found.
71           * A feature entry is returned as a path relative to the site URL
72           * @since 2.0
73           */
74          public String  [] getFeatures();
75  
76          /**
77           * Returns a list of plug-ins visible on the site. Note, that this is simply a 
78           * reflection of the site content and the current policy for the site. The plug-ins
79           * may or may not end up being used by Eclipse (depends on which plug-in are 
80           * actually bound by the platform).
81           * 
82           * @return an array of plug-in entries, or an empty array if no plug-ins are found.
83           * A plug-in entry is returned as a path relative to the site URL        * 
84           * @since 2.0
85           */
86          public String  [] getPlugins();
87  
88          /**
89           * Returns a stamp reflecting the current state of the site. If called repeatedly,
90           * returns the same value as long as no changes were made to the site (changes to
91           * features or plugins).
92           * 
93           * @return site change stamp
94           * @since 2.0
95           */
96          public long getChangeStamp();
97  
98          /**
99           * Returns a stamp reflecting the current state of the features on the site. 
100          * If called repeatedly, returns the same value as long as no changes were made to
101          * features on the site.
102          * 
103          * @return site features change stamp 
104          * @since 2.0
105          */
106         public long getFeaturesChangeStamp();
107 
108         /**
109          * Returns a stamp reflecting the current state of the plug-ins on the site. 
110          * If called repeatedly, returns the same value as long as no changes were made to
111          * plug-ins on the site.
112          * 
113          * @return site plug-ins change stamp 
114          * @since 2.0
115          */
116         public long getPluginsChangeStamp();
117 
118         /**
119          * Returns an indication whether the site can be updated.
120          * 
121          * @return <code>true</code> if site can be updated, <code>false</code> otherwise
122          * @since 2.0
123          */
124         public boolean isUpdateable();
125 
126         /**
127          * Returns an indication whether the site represents an install site
128          * that has been linked via a native installer (using the links/<linkfile>
129          * mechanism)
130          * 
131          * @return <code>true</code> if the site is linked, <code>false</code> otherwise
132          * @since 2.0
133          */
134         public boolean isNativelyLinked();
135     }
136 
137     /**
138      * Site policy. The site policy object determines how plug-ins
139      * contained on the site are processed during startup. In general,
140      * there are 3 ways of configuring a site policy
141      * <ul>
142      * <li>explicitly specify which plug-ins are to be included at
143      * startup (type==USER_INCLUDE). Any other plug-ins located
144      * at the site are ignored at startup. This is typically the best
145      * policy when using remote sites where the user wishes
146      * to retain explicit control over the plug-ins that are included
147      * from such site.
148      * <li>explicitly specify which plug-ins are to be excluded at
149      * startup (type==USER-EXCLUDE). All other plug-ins located
150      * at the site are used at startup. This policy requires that
151      * the site support an access "protocol" that allows plug-in
152      * discovery. In general, these are sites defined using the "file"
153      * URL protocol. This is typically the best policy for local
154      * install sites (on the user system).
155      * </ul>
156      * 
157      * @since 2.0
158      */
159     public interface ISitePolicy extends org.eclipse.update.configurator.IPlatformConfiguration.ISitePolicy {
160 
161         /**
162          * Policy type constants.
163          */
164 
165         /** 
166          * User-defined inclusion list. The list associated with this
167          * policy type is interpreted as path entries to included plugin.xml
168          * or fragment.xml <b>relative</b> to the site URL
169          */
170         public static final int USER_INCLUDE = 0;
171 
172         /**
173          * User-defined exclusion list. The list associated with this
174          * policy type is interpreted as path entries to excluded plugin.xml
175          * or fragment.xml <b>relative</b> to the site URL
176          */
177         public static final int USER_EXCLUDE = 1;
178 
179         /**
180          * Return policy type
181          * 
182          * @return policy type
183          * @since 2.0
184          */
185         public int getType();
186 
187         /**
188          * Return policy inclusion/ exclusion list
189          * 
190          * @return the list as an array
191          * @since 2.0
192          */
193         public String  [] getList();
194 
195         /**
196          * Set new policy list. The list entries are interpreted based on the policy
197          * type. See description of the policy type constants for details.
198          * 
199          * @param list policy inclusion/ exclusion list as an array.
200          * Returns an empty array if there are no entries.
201          * @see #USER_INCLUDE
202          * @see #USER_EXCLUDE
203          * @since 2.0
204          */
205         public void setList(String  [] list);
206     }
207 
208     /**
209      * Feature entry.
210      * Represents runtime "hints" about configured features.
211      * The information is used during execution to locate the
212      * correct attribution information for a feature. Note,
213      * that a typical configuration can declare multiple feature
214      * entries. At execution time, only one can be selected as
215      * the active primary feature. This is determined based on 
216      * specified command line arguments or computed defaults.
217      * 
218      * @since 2.0
219      */
220     public interface IFeatureEntry {
221 
222         /**
223          * Returns feature identifier.
224          * @return feature identifier
225          * @since 2.0
226          */
227         public String   getFeatureIdentifier();
228 
229         /**
230          * Returns the currently configured version for the feature.
231          * @return feature version (as string), or <code>null</code>
232          * @since 2.0
233          */
234         public String   getFeatureVersion();
235 
236         /**
237          * Returns the identifier of the feature plug-in for this feature entry.
238          *  Note,      that there is no guarantee that a feature in fact
239          * supplies a corresponding feature plugin, so the result can be
240          * <code>null</code>. Also, if supplied, there is no guarantee that the
241          * plugin will in fact be loaded into the plug-in registry at runtime
242          * (due to rules and constraint checking performed by the registry
243          * loading support). Consequently code making use of this method must
244          * handle these conditions.
245          * @return feature identifier (as string), or <code>null</code>
246          * @since 2.1
247          */
248         public String   getFeaturePluginIdentifier();
249 
250         /**
251          * Returns the version of the feature plug-in for this feature
252          * entry. Note, that there is no guarantee that a feature in fact
253          * supplies a corresponding feature plugin, so the result can be
254          * <code>null</code>. Also, if supplied, there is no guarantee that the
255          * plugin will in fact be loaded into the plug-in registry at runtime
256          * (due to rules and constraint checking performed by the registry
257          * loading support). Consequently code making use of this method must
258          * handle these conditions.
259          * @return feature version (as string), or <code>null</code>
260          * @since 2.0
261          */
262         public String   getFeaturePluginVersion();
263 
264         /**
265          * Returns the application to run when this feature is the
266          * primary feature.
267          * @return application identifier, or <code>null</code> 
268          * @since 2.0
269          */
270         public String   getFeatureApplication();
271 
272         /**
273          * Returns URLs to the feature "root" locations. The root
274          * URLs are install locations of the feature plugin and its
275          * fragments.
276          *
277          * @return array of URLs, or an empty array
278          * @since 2.0
279          */
280         public URL  [] getFeatureRootURLs();
281 
282         /**
283          * Returns an indication whether this feature has been defined
284          * to act as a primary feature.
285          * @return <code>true</code> if the feature can be primary,
286          * <code>false</code> otherwise.
287          * @since 2.0
288          */
289         public boolean canBePrimary();
290     }
291 
292     /**
293      * Create a site entry
294      *
295      * @param url site URL
296      * @param policy site policy
297      * @return created site entry
298      * @since 2.0
299      */
300     public ISiteEntry createSiteEntry(URL   url, ISitePolicy policy);
301 
302     /**
303      * Create a site policy. The policy determines the way the site
304      * plug-in are processed at startpu
305      *
306      * @param type policy type
307      * @param list an array of site-relative paths representing the
308      * inclusion/ exclusion list
309      * @return created site policy entry
310      * @since 2.0
311      */
312     public ISitePolicy createSitePolicy(int type, String  [] list);
313 
314     /**
315      * Create a feature entry
316      * @param id feature identifier. Must not be <code>null</code>.
317      * @param version feature version (as String). Can be <code>null</code>.
318      * @param pluginVersion version of the feature plugin (as String). Can be
319      * <code>null</code>.
320      * @param primary <code>true</code> if the feature is defined as a primary
321      * feature, otherwise <code>false</code>.
322      * @param application identifier of the application to run when 
323      * this feature is the primary feature. Can be <code>null</code>.
324      * If specified, the identifier must represent a valid extension 
325      * registered in the <code>org.eclipse.core.runtime.applications</code>
326      * extension point.
327      * @param an array of URLs to feature root directories.
328      * These are URLs to install locations for the feature plugin
329      * and its fragments. Can be <code>null</code>.
330      * @return create feature entry
331      * @since 2.0
332      */
333     public IFeatureEntry createFeatureEntry(String   id, String   version, String   pluginVersion, boolean primary, String   application, URL  [] root);
334 
335     /**
336      * Create a feature entry
337      * @param id feature identifier. Must not be <code>null</code>.
338      * @param version feature version (as String). Can be <code>null</code>.
339      * @param pluginIdentifier identifier of the feature plugin (as String). Can
340      * be <code>null</code>.
341      * @param  pluginVersion  version of the feature plugin (as String). Can be
342      * <code>null</code>.
343      * @param primary <code>true</code> if the feature is defined as a primary
344      * feature, otherwise <code>false</code>.
345      * @param application identifier of the application to run when
346      * this feature is the primary feature. Can be <code>null</code>.
347      * If specified, the identifier must represent a valid extension
348      * registered in the <code>org.eclipse.core.runtime.applications</code>
349      * extension point.
350      * @param an array of URLs to feature root directories.
351      * These are URLs to install locations for the feature plugin
352      * and its fragments. Can be <code>null</code>.
353      * @return create feature entry
354      * @since 2.1
355      */
356     public IFeatureEntry createFeatureEntry(String   id, String   version, String   pluginIdentifier, String   pluginVersion, boolean primary, String   application, URL  [] root);
357 
358     /**
359      * Configures the specified site entry. If a site entry with the
360      * same site URL is already configured, the entry is <b>not</b> replaced.
361      * 
362      * @param entry site entry 
363      * @since 2.0
364      */
365     public void configureSite(ISiteEntry entry);
366 
367     /**
368      * Configures the specified site entry. If a site entry with the
369      * same site URL is already configured, the replacement behavior for
370      * the entry can be specified.
371      * 
372      * @param entry site entry 
373      * @param  flag indicating whether an existing configured entry with
374      * the same URL should be replaced (<code>true</code>) or not (<code>false</code>).
375      * @since 2.0
376      */
377     public void configureSite(ISiteEntry entry, boolean replace);
378 
379     /**
380      * Unconfigures the specified entry. Does not do anything if the entry
381      * is not configured.
382      * 
383      * @param entry site entry
384      * @since 2.0
385      */
386     public void unconfigureSite(ISiteEntry entry);
387 
388     /**
389      * Returns configured site entries
390      * 
391      * @return array of site entries. Returns an empty array if no sites are
392      * configured
393      * @since 2.0
394      */
395     public ISiteEntry[] getConfiguredSites();
396 
397     /**
398      * Returns a site entry matching the specified URL
399      * 
400      * @param url site url
401      * @return matching site entry, or <code>null</code> if no match found
402      * @since 2.0
403      */
404     public ISiteEntry findConfiguredSite(URL   url);
405 
406     /**
407      * Configures the feature entry.
408      * If another feature entry with the same feature identifier 
409      * already exists, it is replaced.
410      * @param entry feature entry
411      * @since 2.0
412      */
413     public void configureFeatureEntry(IFeatureEntry entry);
414 
415     /**
416      * Unconfigures the specified feature entry if it exists.
417      * @param entry feature entry
418      * @since 2.0
419      */
420     public void unconfigureFeatureEntry(IFeatureEntry entry);
421 
422     /**
423      * Returns a list of configured feature entries.
424      * @return array or entries, or an empty array if no entries
425      * are configured
426      * @since 2.0
427      */
428     public IFeatureEntry[] getConfiguredFeatureEntries();
429 
430     /**
431      * Locates the specified feature entry.
432      * @param id feature identifier
433      * @return ferature entry, or <code>null</code>.
434      * @since 2.0
435      */
436     public IFeatureEntry findConfiguredFeatureEntry(String   id);
437 
438     /**
439      * Returns the URL location of the configuration information
440      * 
441      * @return configuration location URL, or <code>null</code> if the
442      * configuration location could not be determined.
443      * @since 2.0
444      */
445     public URL   getConfigurationLocation();
446 
447     /**
448      * Returns a stamp reflecting the current state of the configuration. If called repeatedly,
449      * returns the same value as long as no changes were made to the configuration (changes to
450      * sites, features or plugins).
451      * 
452      * @return configuration change stamp
453      * @since 2.0
454      */
455     public long getChangeStamp();
456 
457     /**
458      * Returns a stamp reflecting the current state of the features in the configuration. 
459      * If called repeatedly, returns the same value as long as no changes were made to
460      * features in the configuration.
461      * 
462      * @return configuration features change stamp 
463      * @since 2.0
464      */
465     public long getFeaturesChangeStamp();
466 
467     /**
468      * Returns a stamp reflecting the current state of the plug-ins in the configuration. 
469      * If called repeatedly, returns the same value as long as no changes were made to
470      * plug-ins in the configuration.
471      * 
472      * @return configuration plug-ins change stamp 
473      * @since 2.0
474      */
475     public long getPluginsChangeStamp();
476 
477     /**
478      * Returns the identifier of the configured primary feature. A primary feature
479      * is used to specify product customization information for a running instance
480      * of Eclipse. 
481      * 
482      * @return primary feature identifier, or <code>null</code> if none configured
483      * @since 2.0
484      */
485     public String   getPrimaryFeatureIdentifier();
486 
487     /**
488      * Computes the plug-in path for this configuration. The result includes all plug-ins
489      * visible on each of the configured sites based on each site policy.
490      * 
491      * @return an array of plug-in path elements (full URL entries), or an empty array.
492      * @since 2.0
493      */
494     public URL  [] getPluginPath();
495 
496     /**
497      * Returns an array of bootstrap plugin identifiers whose
498      * location needs to be explicitly identified in the configuration.
499      * 
500      * @return an array of identifiers, or empty array
501      * otherwise
502      * @since 2.0
503      */
504     public String  [] getBootstrapPluginIdentifiers();
505 
506     /**
507      * Sets the location of a bootstrap plugin.
508      * 
509      * @see IPlatformConfiguration#getBootstrapPluginIdentifiers()
510      * @param id plugin identifier. Must match one of the entries returned
511      * by getBootstrapPluginIdentifiers()
512      * @param location
513      * @since 2.0
514      */
515     public void setBootstrapPluginLocation(String   id, URL   location);
516 
517     /**
518      * Returns an indication whether the configuration can be updated.
519      * 
520      * @return <code>true</code> if configuration can be updated, <code>false</code> 
521      * otherwise
522      * @since 2.0
523      */
524     public boolean isUpdateable();
525 
526     /**
527      * Returns an indication whether the configuration is transient. A transient
528      * configuration typically represents a scenario where the configuration
529      * was computed for a single instantiation of the platform and is not
530      * guaranteed to be valid on subsequent instantiations.
531      * 
532      * @return <code>true</code> if configuration is transient, <code>false</code> 
533      * otherwise
534      * @since 2.0
535      */
536     public boolean isTransient();
537 
538     /**
539      * Indicates whether the configuration is transient or not. A transient
540      * configuration typically represents a scenario where the configuration
541      * was computed for a single instantiation of the platform and is not
542      * guaranteed to be valid on subsequent instantiations. This method has
543      * no effect if called on the current platform configuration.
544      * 
545      * @see BootLoader#getCurrentPlatformConfiguration()
546      * @param value <code>true</code> if configuration is transient, <code>false</code> 
547      * otherwise
548      * @since 2.0
549      */
550     public void isTransient(boolean value);
551 
552     /**
553      * Called to refresh the configuration information. In particular,
554      * causes change stamps to be recomputed based on the current
555      * configuration state, and updates the lists of available plug-ins.
556      * @since 2.0
557      */
558     public void refresh();
559 
560     /**
561      * Called to save the configuration information
562      * @since 2.0
563      */
564     public void save() throws IOException  ;
565 
566     /**
567      * Called to save the configuration information in the
568      * specified location
569      * 
570      * @param url save location.
571      * @since 2.0
572      */
573     public void save(URL   url) throws IOException  ;
574 
575 }
576
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags