Eclipse Platform
2.1

org.eclipse.update.core
Interface IFeature

All Superinterfaces:
IAdaptable, IPlatformEnvironment
All Known Implementing Classes:
Feature

public interface IFeature
extends IAdaptable, IPlatformEnvironment

Feature defines the packaging "container" for a group of related plug-ins, plug-in fragments, and optionally non-plug-in files.

Features are treated purely as an installation and packaging construct. They do not play a role during Eclipse plug-in execution. They are simply an inclusive "manifest" of the plug-ins, fragments and other files that make up that feature. If features are logically made up of plug-ins from "sub-features", the top-level feature "manifest" must be fully resolved at packaging time.

Clients may implement this interface. However, in most cases clients should directly instantiate or subclass the provided implementation of this interface.

Since:
2.0
See Also:
Feature

Field Summary
static int SEARCH_LOCATION_BOTH
          Indicates the one-click update will search both the location of the nesting root feature and the location defined by the feature.
static int SEARCH_LOCATION_DEFAULT
          Indicates the one-click update will search the location of the nesting root feature.
static int SEARCH_LOCATION_FEATURE
          Indicates the one-click update will search the location defined by the feature.
static int STATUS_AMBIGUOUS
          Indicates a 'happy' feature A feature is considered to be 'ambiguous' in the context of a local site if all the plug-ins referenced by the feature are installed on the site and other version of any of the plug-ins are installed on any other site of the local site.
static int STATUS_DISABLED
          Indicates a disable feature
static int STATUS_HAPPY
          Indicates a 'happy' feature A feature is considered to be 'happy' in the context of a local site if all the plug-ins referenced by the feature are installed on the site and no other version of any of the plug-ins are installed on any other site of the local site.
static int STATUS_UNHAPPY
          Indicates an 'unhappy' feature A feature is considered to be 'unhappy' in the context of this site, if some of the plug-ins referenced by the feature are not installed on this site.
 
Method Summary
 String getAffinityFeature()
          Returns an optional identifier of a colocation affinity feature.
 String getApplication()
          Returns an optional identifier of an application to be used when starting up the platform with this feature as the primary feature.
 IURLEntry getCopyright()
          Returns the copyright information for the feature.
 IURLEntry getDescription()
          Returns the feature description.
 IURLEntry[] getDiscoverySiteEntries()
          Return an array of information entries referencing locations of other update sites.
 long getDownloadSize()
          Returns the download size of the feature, if it can be determined.
 IFeatureContentConsumer getFeatureContentConsumer()
          Returns the content consumer for this feature.
 IFeatureContentProvider getFeatureContentProvider()
          Returns the content provider for this feature.
 URL getImage()
          Return optional image for the feature.
 IImport[] getImports()
          Return a list of plug-in dependencies for this feature.
 IIncludedFeatureReference[] getIncludedFeatureReferences()
          Returns an array of feature references included by this feature filtered by the operating system, windowing system and architecture system set in Sitemanager
 IInstallHandlerEntry getInstallHandlerEntry()
          Returns and optional custom install handler entry.
 long getInstallSize()
          Returns the install size of the feature, if it can be determined.
 String getLabel()
          Returns the displayable label of the feature.
 IURLEntry getLicense()
          Returns the license information for the feature.
 INonPluginEntry[] getNonPluginEntries()
          Returns an array of non-plug-in entries referenced by this feature filtered by the operating system, windowing system and architecture system set in Sitemanager
 int getNonPluginEntryCount()
          Returns the count of referenced non-plug-in entries.
 IPluginEntry[] getPluginEntries()
          Returns an array of plug-in entries referenced by this feature filtered by the operating system, windowing system and architecture system set in Sitemanager
 int getPluginEntryCount()
          Returns the count of referenced plug-in entries.
 String getPrimaryPluginID()
          Return the identifier of the primary plugin associated to this feature or null if the feature is not a primary feature.
 String getProvider()
          Returns a displayable label identifying the provider of this feature
 IImport[] getRawImports()
          Return a list of plug-in dependencies for this feature.
 IIncludedFeatureReference[] getRawIncludedFeatureReferences()
          Returns an array of feature references included by this feature No filtering occurs
 INonPluginEntry[] getRawNonPluginEntries()
          Returns an array of non-plug-in entries referenced by this feature No filtering occurs
 IPluginEntry[] getRawPluginEntries()
          Returns an array of plug-in entries referenced by this feature No filtering occurs
 ISite getSite()
          Returns the site this feature is associated with.
 IURLEntry getUpdateSiteEntry()
          Returns an information entry referencing the location of the feature update site.
 URL getURL()
          Returns the feature URL.
 VersionedIdentifier getVersionedIdentifier()
          Returns the feature identifier.
 IFeatureReference install(IFeature targetFeature, IFeatureReference[] optionalFeatures, IVerificationListener verificationListener, IProgressMonitor monitor)
          Install the contents of this feature into the specified target feature.
 IFeatureReference install(IFeature targetFeature, IVerificationListener verificationListener, IProgressMonitor monitor)
          Install the contents of this feature into the specified target feature.
 boolean isExclusive()
          Indicates whether the feature must be processed alone during installation and configuration.
 boolean isPatch()
          Returns true if this feature is patching another feature, false otherwise
 boolean isPrimary()
          Indicates whether the feature can be used as a primary feature.
 void setFeatureContentProvider(IFeatureContentProvider featureContentProvider)
          Sets the content provider for this feature.
 void setSite(ISite site)
          Sets the site for this feature.
 
Methods inherited from interface org.eclipse.core.runtime.IAdaptable
getAdapter
 
Methods inherited from interface org.eclipse.update.core.IPlatformEnvironment
getNL, getOS, getOSArch, getWS
 

Field Detail

STATUS_HAPPY

public static final int STATUS_HAPPY
Indicates a 'happy' feature A feature is considered to be 'happy' in the context of a local site if all the plug-ins referenced by the feature are installed on the site and no other version of any of the plug-ins are installed on any other site of the local site.
See Also:
IConfiguredSite.getBrokenStatus(IFeature)
Since:
2.0

STATUS_AMBIGUOUS

public static final int STATUS_AMBIGUOUS
Indicates a 'happy' feature A feature is considered to be 'ambiguous' in the context of a local site if all the plug-ins referenced by the feature are installed on the site and other version of any of the plug-ins are installed on any other site of the local site.
See Also:
IConfiguredSite.getBrokenStatus(IFeature)

STATUS_UNHAPPY

public static final int STATUS_UNHAPPY
Indicates an 'unhappy' feature A feature is considered to be 'unhappy' in the context of this site, if some of the plug-ins referenced by the feature are not installed on this site.
See Also:
IConfiguredSite.getBrokenStatus(IFeature)
Since:
2.0

STATUS_DISABLED

public static final int STATUS_DISABLED
Indicates a disable feature
See Also:
IConfiguredSite.getBrokenStatus(IFeature)
Since:
2.0.2

SEARCH_LOCATION_DEFAULT

public static final int SEARCH_LOCATION_DEFAULT
Indicates the one-click update will search the location of the nesting root feature.
Since:
2.0.1

SEARCH_LOCATION_FEATURE

public static final int SEARCH_LOCATION_FEATURE
Indicates the one-click update will search the location defined by the feature.
Since:
2.0.1

SEARCH_LOCATION_BOTH

public static final int SEARCH_LOCATION_BOTH
Indicates the one-click update will search both the location of the nesting root feature and the location defined by the feature.
Since:
2.0.1
Method Detail

getVersionedIdentifier

public VersionedIdentifier getVersionedIdentifier()
Returns the feature identifier.
Returns:
the feature identifier.
Since:
2.0

getSite

public ISite getSite()
Returns the site this feature is associated with.
Returns:
the site for this feature
Since:
2.0

getLabel

public String getLabel()
Returns the displayable label of the feature.
Returns:
feature label, or null.
Since:
2.0

getURL

public URL getURL()
Returns the feature URL. This is the URL that was used to create the feature. The interpretation of the URL is dependent on the concrete feature implementation. *
Returns:
feature URL
Since:
2.0
See Also:
IFeatureFactory.createFeature(URL, ISite)

getUpdateSiteEntry

public IURLEntry getUpdateSiteEntry()
Returns an information entry referencing the location of the feature update site. The update site can be accessed to obtain feature updates for this feature.
Returns:
update site entry, or null.
Since:
2.0

getDiscoverySiteEntries

public IURLEntry[] getDiscoverySiteEntries()
Return an array of information entries referencing locations of other update sites. This mechanism can be used by features to distribute location information about general update sites to clients.
Returns:
an array of site entries, or an empty array.
Since:
2.0

getProvider

public String getProvider()
Returns a displayable label identifying the provider of this feature
Returns:
provider label, or null.
Since:
2.0

getInstallHandlerEntry

public IInstallHandlerEntry getInstallHandlerEntry()
Returns and optional custom install handler entry.
Returns:
install handler entry, or null if none was specified
Since:
2.0

getDescription

public IURLEntry getDescription()
Returns the feature description.
Returns:
feature rescription, or null.
Since:
2.0

getCopyright

public IURLEntry getCopyright()
Returns the copyright information for the feature.
Returns:
copyright information, or null.
Since:
2.0

getLicense

public IURLEntry getLicense()
Returns the license information for the feature.
Returns:
feature license, or null.
Since:
2.0

getImage

public URL getImage()
Return optional image for the feature.
Returns:
the URL pointing to the image, , or null.
Since:
2.0

getImports

public IImport[] getImports()
Return a list of plug-in dependencies for this feature. A plug-in dependency is a reference to a plug-in required for feature execution that is not packaged as part of the feature. filtered by the operating system, windowing system and architecture system set in Sitemanager
Returns:
the list of required plug-in dependencies, or an empty array.
Since:
2.0

getRawImports

public IImport[] getRawImports()
Return a list of plug-in dependencies for this feature. A plug-in dependency is a reference to a plug-in required for feature execution that is not packaged as part of the feature. No filtering occurs
Returns:
the list of required plug-in dependencies, or an empty array.
Since:
2.1

getPrimaryPluginID

public String getPrimaryPluginID()
Return the identifier of the primary plugin associated to this feature or null if the feature is not a primary feature. If the primary plugin id is not specified and the feature is a primary feature, returns the feature identifier.
Returns:
the identifier of the associated primary plugin or null
Since:
2.1

install

public IFeatureReference install(IFeature targetFeature,
                                 IVerificationListener verificationListener,
                                 IProgressMonitor monitor)
                          throws InstallAbortedException,
                                 CoreException
Install the contents of this feature into the specified target feature. All optional features will be installed
Parameters:
targetFeature -  
verificationListener -  
monitor -  
Throws:
InstallAbortedException - when the user cancels the install
CoreException -  
Since:
2.0

install

public IFeatureReference install(IFeature targetFeature,
                                 IFeatureReference[] optionalFeatures,
                                 IVerificationListener verificationListener,
                                 IProgressMonitor monitor)
                          throws InstallAbortedException,
                                 CoreException
Install the contents of this feature into the specified target feature. Only the listed optional features will be installed.
Parameters:
targetFeature -  
optionalFeatures - the optional features to be installed
verificationListener -  
monitor -  
Throws:
InstallAbortedException - when the user cancels the install
CoreException -  
Since:
2.0.1

getIncludedFeatureReferences

public IIncludedFeatureReference[] getIncludedFeatureReferences()
                                                         throws CoreException
Returns an array of feature references included by this feature filtered by the operating system, windowing system and architecture system set in Sitemanager
Returns:
an erray of feature references, or an empty array.
Since:
2.0

getRawIncludedFeatureReferences

public IIncludedFeatureReference[] getRawIncludedFeatureReferences()
                                                            throws CoreException
Returns an array of feature references included by this feature No filtering occurs
Returns:
an erray of feature references, or an empty array.
Since:
2.0

getPluginEntries

public IPluginEntry[] getPluginEntries()
Returns an array of plug-in entries referenced by this feature filtered by the operating system, windowing system and architecture system set in Sitemanager
Returns:
an erray of plug-in entries, or an empty array.
Since:
2.0

getRawPluginEntries

public IPluginEntry[] getRawPluginEntries()
Returns an array of plug-in entries referenced by this feature No filtering occurs
Returns:
an erray of plug-in entries, or an empty array.
Since:
2.1

getPluginEntryCount

public int getPluginEntryCount()
Returns the count of referenced plug-in entries.
Returns:
plug-in entry count
Since:
2.0

getNonPluginEntries

public INonPluginEntry[] getNonPluginEntries()
Returns an array of non-plug-in entries referenced by this feature filtered by the operating system, windowing system and architecture system set in Sitemanager
Returns:
an erray of non-plug-in entries, or an empty array.
Since:
2.0

getRawNonPluginEntries

public INonPluginEntry[] getRawNonPluginEntries()
Returns an array of non-plug-in entries referenced by this feature No filtering occurs
Returns:
an erray of non-plug-in entries, or an empty array.
Since:
2.1

getNonPluginEntryCount

public int getNonPluginEntryCount()
Returns the count of referenced non-plug-in entries.
Returns:
non-plug-in entry count
Since:
2.0

getDownloadSize

public long getDownloadSize()
Returns the download size of the feature, if it can be determined.
Returns:
download size of the feature in KiloBytes, or an indication the size could not be determined
Since:
2.0
See Also:
ContentEntryModel.UNKNOWN_SIZE

getInstallSize

public long getInstallSize()
Returns the install size of the feature, if it can be determined.
Returns:
install size of the feature in KiloBytes, or an indication the size could not be determined
Since:
2.0
See Also:
ContentEntryModel.UNKNOWN_SIZE

isPrimary

public boolean isPrimary()
Indicates whether the feature can be used as a primary feature.
Returns:
true if this is a primary feature, otherwise false
Since:
2.0

isExclusive

public boolean isExclusive()
Indicates whether the feature must be processed alone during installation and configuration. Features that are not exclusive can be installed in a batch.
Returns:
true if feature requires exclusive processing, false otherwise.
Since:
2.1

getApplication

public String getApplication()
Returns an optional identifier of an application to be used when starting up the platform with this feature as the primary feature. The application identifier must represent a valid application registered in the org.eclipse.core.runtime.applications extension point.
Returns:
application identifier, or null
Since:
2.0

getAffinityFeature

public String getAffinityFeature()
Returns an optional identifier of a colocation affinity feature.
Returns:
feature identifier, or null.
Since:
2.0

getFeatureContentProvider

public IFeatureContentProvider getFeatureContentProvider()
                                                  throws CoreException
Returns the content provider for this feature. A content provider is an abstraction of each feature internal packaging structure. It allows the feature content to be accessed in a standard way regardless of the internal packaging. All concrete features need to be able to return a content provider.
Returns:
feature content provider
Throws:
CoreExcepton -  
Since:
2.0

getFeatureContentConsumer

public IFeatureContentConsumer getFeatureContentConsumer()
                                                  throws CoreException
Returns the content consumer for this feature. A content consumer is an abstraction of each feature internal packaging mechanism. It allows content to be stored into a feature in a standard way regardless of the packaging mechanism used. Only concrete features that support storing need to implement a content consumer. The platform implements at least one feature type supporting content consumer. This is the feature type representing a locally-installed feature.
Returns:
feature content consumer
Throws:
CoreException -  
UnsupportedOperationException -  
Since:
2.0

setSite

public void setSite(ISite site)
             throws CoreException
Sets the site for this feature. This is typically performed as part of the feature creation operation. Once set, the site should not be reset.
Parameters:
site - the site
Throws:
CoreException - site for this feature is already set
Since:
2.0

setFeatureContentProvider

public void setFeatureContentProvider(IFeatureContentProvider featureContentProvider)
Sets the content provider for this feature. This is typically performed as part of the feature creation operation. Once set, the provider should not be reset.
Parameters:
featureContentProvider - content provider
Since:
2.0
See Also:
IFeatureFactory.createFeature(URL, ISite)

isPatch

public boolean isPatch()
Returns true if this feature is patching another feature, false otherwise
Returns:
boolean
Since:
2.1

Eclipse Platform
2.1

Copyright (c) IBM Corp. and others 2000, 2003. All Rights Reserved.