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  ;
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   * <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   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  [] 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  [] 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  [] 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  [] 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   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   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   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   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   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  [] 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   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  [] 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   id, String   version, String   pluginVersion, boolean primary, String   application, URL  [] 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   id, String   version, String   pluginIdentifier, String   pluginVersion, boolean primary, String   application, URL  [] 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   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   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   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   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  [] 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  [] 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   id, URL   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  ;
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   url) throws IOException  ;
589 
590 }
591
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags