IFeature


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  
12  package org.eclipse.update.core;
13  
14  import java.net.URL  ;
15  
16  import org.eclipse.core.runtime.CoreException;
17  import org.eclipse.core.runtime.IAdaptable;
18  import org.eclipse.core.runtime.IProgressMonitor;
19  import org.eclipse.update.core.model.InstallAbortedException;
20  
21  /**
22   * Feature defines the packaging "container" for a group of related plug-ins,
23   * plug-in fragments, and optionally non-plug-in files. 
24   * <p>
25   * Features are treated purely as an installation and packaging construct. 
26   * They do not play a role during Eclipse plug-in execution.
27   * They are simply an inclusive "manifest" of the plug-ins, fragments 
28   * and other files that make up that feature. If features are logically made 
29   * up of plug-ins from "sub-features", the top-level feature "manifest"
30   * must be fully resolved at packaging time.
31   * </p>
32   * <p>
33   * Clients may implement this interface. However, in most cases clients should 
34   * directly instantiate or subclass the provided implementation of this 
35   * interface.
36   * </p>
37   * <p>
38   * <b>Note:</b> This class/interface is part of an interim API that is still under development and expected to
39   * change significantly before reaching stability. It is being made available at this early stage to solicit feedback
40   * from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken
41   * (repeatedly) as the API evolves.
42   * </p>
43   * @see org.eclipse.update.core.Feature
44   * @since 2.0
45   */
46  public interface IFeature extends IAdaptable, IPlatformEnvironment {
47  
48      /**
49       * Indicates a 'happy' feature
50       * A feature is considered to be 'happy' in the context of a local site
51       * if all the plug-ins referenced by the feature are installed on the site and no other
52       * version of any of the plug-ins are installed on any other site of the local site.
53       * 
54       * @see org.eclipse.update.configuration.IConfiguredSite#getBrokenStatus(IFeature)
55       * @since 2.0
56       */
57      public static final int STATUS_HAPPY = 0;
58  
59      /**
60       * Indicates a 'happy' feature
61       * A feature is considered to be 'ambiguous' in the context of a local site
62       * if all the plug-ins referenced by the feature are installed on the site and other
63       * version of any of the plug-ins are installed on any other site of the local site.
64       * 
65       * @see org.eclipse.update.configuration.IConfiguredSite#getBrokenStatus(IFeature)
66       */ 
67      public static final int STATUS_AMBIGUOUS = 1;
68      
69      /**
70       * Indicates an 'unhappy' feature
71       * A feature is considered to be 'unhappy' in the context of this site,
72       * if some of the plug-ins referenced by the feature are not installed on this site.
73       * 
74       * @see org.eclipse.update.configuration.IConfiguredSite#getBrokenStatus(IFeature)
75       * @since 2.0
76       */ 
77      public static final int STATUS_UNHAPPY = 2;
78      
79      
80      /**
81       * Indicates a disable feature
82       * 
83       * @see org.eclipse.update.configuration.IConfiguredSite#getBrokenStatus(IFeature)
84       * @since 2.0.2
85       */ 
86      public static final int STATUS_DISABLED = -1;
87          
88      /**
89       * Indicates the one-click update will search the 
90       * location of the nesting root feature.
91       * 
92       * @since 2.0.1
93       */ 
94      public static final int SEARCH_LOCATION_DEFAULT = 0;    
95  
96      /**
97       * Indicates the one-click update will search the 
98       * location defined by the feature.
99       * 
100      * @since 2.0.1
101      */ 
102     public static final int SEARCH_LOCATION_FEATURE = 1;    
103 
104     /**
105      * Indicates the one-click update will search both the 
106      * location of the nesting root feature and the 
107      * location defined by the feature.
108      * 
109      * @since 2.0.1
110      */ 
111     public static final int SEARCH_LOCATION_BOTH = 2;   
112 
113     
114     /**
115      * Returns the feature identifier.
116      * 
117      * @return the feature identifier.
118      * @since 2.0 
119      */
120     public VersionedIdentifier getVersionedIdentifier();
121 
122     /**
123      * Returns the site this feature is associated with.
124      * 
125      * @return the site for this feature
126      * @since 2.0 
127      */
128     public ISite getSite();
129 
130     /**
131      * Returns the displayable label of the feature.
132      * 
133      * @return feature label, or <code>null</code>.
134      * @since 2.0 
135      */
136     public String   getLabel();
137 
138     /**
139      * Returns the feature URL.
140      * This is the URL that was used to create the feature. The interpretation
141      * of the URL is dependent on the concrete feature implementation.  * 
142      * @return feature URL
143      * @since 2.0 
144      */
145     public URL   getURL();
146 
147     /**
148      * Returns an information entry referencing the location of the
149      * feature update site. The update site can be accessed to obtain
150      * feature updates for this feature.
151      * 
152      * @return update site entry, or <code>null</code>.
153      * @since 2.0 
154      */
155     public IURLEntry getUpdateSiteEntry();
156 
157     /**
158      * Return an array of information entries referencing locations of other
159      * update sites. This mechanism can be used by features to distribute
160      * location information about general update sites to clients.
161      * 
162      * @return an array of site entries, or an empty array.
163      * @since 2.0 
164      */
165     public IURLEntry[] getDiscoverySiteEntries();
166 
167     /**
168      * Returns a displayable label identifying the provider of this feature
169      * 
170      * @return provider label, or <code>null</code>.
171      * @since 2.0 
172      */
173     public String   getProvider();
174 
175     /**
176      * Returns and optional custom install handler entry.
177      * 
178      * @return install handler entry, or <code>null</code> if
179      * none was specified
180      * @since 2.0
181      */
182     public IInstallHandlerEntry getInstallHandlerEntry();
183 
184     /**
185      * Returns the feature description.
186      * 
187      * @return feature rescription, or <code>null</code>.
188      * @since 2.0 
189      */
190     public IURLEntry getDescription();
191 
192     /**
193      * Returns the copyright information for the feature.
194      * 
195      * @return copyright information, or <code>null</code>.
196      * @since 2.0 
197      */
198     public IURLEntry getCopyright();
199 
200     /**
201      * Returns the license information for the feature.
202      * 
203      * @return feature license, or <code>null</code>.
204      * @since 2.0 
205      */
206     public IURLEntry getLicense();
207 
208     /**
209      * Return optional image for the feature.
210      * 
211      * @return the URL pointing to the image, , or <code>null</code>.
212      * @since 2.0 
213      */
214     public URL   getImage();
215 
216     /**
217      * Return a list of plug-in dependencies for this feature. A plug-in
218      * dependency is a reference to a plug-in required for feature execution
219      * that is not packaged as part of the feature.
220      * filtered by the operating system, windowing system and architecture system
221      * set in <code>Sitemanager</code>
222      * 
223      * @return the list of required plug-in dependencies, or an empty array.
224      * @since 2.0 
225      */
226     public IImport[] getImports();
227 
228     /**
229      * Return a list of plug-in dependencies for this feature. A plug-in
230      * dependency is a reference to a plug-in required for feature execution
231      * that is not packaged as part of the feature.
232      * No filtering occurs
233      * 
234      * @return the list of required plug-in dependencies, or an empty array.
235      * @since 2.1
236      */
237     public IImport[] getRawImports();
238     
239     /**
240      * Return the identifier of the primary plugin associated to this feature
241      * or <code>null</code> if the feature is not a primary feature.
242      * If the primary plugin id is not specified and the feature is a primary
243      * feature, returns the feature identifier.
244      * 
245      * @return the identifier of the associated primary plugin or <code>null</code>
246      * @since 2.1 
247      */
248     public String   getPrimaryPluginID();
249 
250 
251     /**
252      * Install the contents of this feature into the specified target feature.
253      * All optional features will be installed
254      * 
255      * @param targetFeature
256      * @param verificationListener
257      * @param monitor
258      * @exception InstallAbortedException when the user cancels the install
259      * @exception CoreException
260      * @since 2.0
261      */
262     public IFeatureReference install(
263         IFeature targetFeature,
264         IVerificationListener verificationListener,
265         IProgressMonitor monitor)
266         throws InstallAbortedException,CoreException;
267 
268     /**
269      * Install the contents of this feature into the specified target feature.
270      * Only the listed optional features will be installed.
271      * 
272      * @param targetFeature
273      * @param optionalFeatures the optional features to be installed
274      * @param verificationListener
275      * @param monitor
276      * @exception InstallAbortedException when the user cancels the install
277      * @exception CoreException
278      * @since 2.0.1
279      */
280     public IFeatureReference install(
281         IFeature targetFeature,
282         IFeatureReference[] optionalFeatures,
283         IVerificationListener verificationListener,
284         IProgressMonitor monitor)
285         throws InstallAbortedException,CoreException;
286 
287     /**
288      * Returns an array of feature references included by this feature
289      * filtered by the operating system, windowing system and architecture system
290      * set in <code>Sitemanager</code>
291      * 
292      * @return an erray of feature references, or an empty array.
293      * @since 2.0
294      */
295     public IIncludedFeatureReference[] getIncludedFeatureReferences() throws CoreException;
296 
297     /**
298      * Returns an array of feature references included by this feature
299      * No filtering occurs
300      * 
301      * @return an erray of feature references, or an empty array.
302      * @since 2.0
303      */
304     public IIncludedFeatureReference[] getRawIncludedFeatureReferences() throws CoreException;
305 
306     /**
307      * Returns an array of plug-in entries referenced by this feature
308      * filtered by the operating system, windowing system and architecture system
309      * set in <code>Sitemanager</code>
310      * 
311      * @return an erray of plug-in entries, or an empty array.
312      * @since 2.0
313      */
314     public IPluginEntry[] getPluginEntries();
315 
316     /**
317      * Returns an array of plug-in entries referenced by this feature
318      * No filtering occurs
319      * 
320      * @return an erray of plug-in entries, or an empty array.
321      * @since 2.1
322      */
323     public IPluginEntry[] getRawPluginEntries();
324 
325     /**
326      * Returns the count of referenced plug-in entries.
327      * 
328      * @return plug-in entry count
329      * @since 2.0
330      */
331     public int getPluginEntryCount();
332 
333     /**
334      * Returns an array of non-plug-in entries referenced by this feature
335      * filtered by the operating system, windowing system and architecture system
336      * set in <code>Sitemanager</code>
337      * 
338      * @return an erray of non-plug-in entries, or an empty array.
339      * @since 2.0
340      */
341     public INonPluginEntry[] getNonPluginEntries();
342 
343     /**
344      * Returns an array of non-plug-in entries referenced by this feature
345      * No filtering occurs
346      * 
347      * @return an erray of non-plug-in entries, or an empty array.
348      * @since 2.1
349      */
350     public INonPluginEntry[] getRawNonPluginEntries();
351 
352     /**
353      * Returns the count of referenced non-plug-in entries.
354      * 
355      * @return non-plug-in entry count
356      * @since 2.0
357      */
358     public int getNonPluginEntryCount();
359 
360     /**
361      * Returns the download size of the feature, if it can be determined.
362      * 
363      * @see org.eclipse.update.core.model.ContentEntryModel#UNKNOWN_SIZE
364      * @return download size of the feature in KiloBytes, or an indication 
365      * the size could not be determined
366      * @since 2.0 
367      */
368     public long getDownloadSize();
369 
370     /**
371      * Returns the install size of the feature, if it can be determined.
372      * 
373      * @see org.eclipse.update.core.model.ContentEntryModel#UNKNOWN_SIZE
374      * @return install size of the feature in KiloBytes, or an indication 
375      * the size could not be determined
376      * @since 2.0 
377      */
378     public long getInstallSize();
379 
380     /**
381      * Indicates whether the feature can be used as a primary feature.
382      * 
383      * @return <code>true</code> if this is a primary feature, 
384      * otherwise <code>false</code>
385      * @since 2.0 
386      */
387     public boolean isPrimary();
388     
389     /**
390      * Indicates whether the feature must be processed alone during installation
391      * and configuration. Features that are not exclusive can be installed in a
392      * batch.
393      * 
394      * @return <code>true</code> if feature requires exclusive processing,
395      * <code>false</code> otherwise.
396      * @since 2.1
397      */
398     public boolean isExclusive();
399 
400     /**
401      * Returns an optional identifier of an application to be used when
402      * starting up the platform with this feature as the primary feature.
403      * The application identifier must represent a valid application registered
404      * in the <code>org.eclipse.core.runtime.applications</code> extension point.
405      * 
406      * @return application identifier, or <code>null</code>
407      * @since 2.0 
408      */
409     public String   getApplication();
410     
411     /**
412      * Returns an optional identifier of a colocation affinity feature.
413      * 
414      * @return feature identifier, or <code>null</code>.
415      * @since 2.0
416      */
417     public String   getAffinityFeature();
418 
419     /**
420      * Returns the content provider for this feature. A content provider
421      * is an abstraction of each feature internal packaging structure.
422      * It allows the feature content to be accessed in a standard way
423      * regardless of the internal packaging. All concrete features
424      * need to be able to return a content provider.
425      * 
426      * @return feature content provider
427      * @exception CoreException
428      * @since 2.0
429      */
430     public IFeatureContentProvider getFeatureContentProvider()
431         throws CoreException;
432 
433     /**
434      * Returns the content consumer for this feature. A content consumer
435      * is an abstraction of each feature internal packaging mechanism.
436      * It allows content to be stored into a feature in a standard way
437      * regardless of the packaging mechanism used. Only concrete features
438      * that support storing need to implement a content consumer. The platform
439      * implements at least one feature type supporting content consumer.
440      * This is the feature type representing a locally-installed
441      * feature.
442      * 
443      * @return feature content consumer
444      * @exception CoreException
445      * @exception UnsupportedOperationException
446      * @since 2.0
447      */
448     public IFeatureContentConsumer getFeatureContentConsumer()
449         throws CoreException;
450 
451     /**
452      * Sets the site for this feature. This is typically performed as part
453      * of the feature creation operation. Once set, the site
454      * should not be reset.
455      * 
456      * @param site the site
457      * @throws CoreException site for this feature is already set
458      * @since 2.0 
459      */
460     public void setSite(ISite site) throws CoreException;
461 
462     /**
463      * Sets the content provider for this feature. This is typically
464      * performed as part of the feature creation operation. Once set, the 
465      * provider should not be reset.
466      * 
467      * @param featureContentProvider content provider
468      * @since 2.0
469      */
470     public void setFeatureContentProvider(IFeatureContentProvider featureContentProvider);
471 
472     /**
473      * Returns <code>true</code> if this feature is patching another feature,
474      * <code>false</code> otherwise
475      * @return boolean
476      * @since 2.1
477      */
478     public boolean isPatch();
479 
480 
481 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags