org.eclipse.update.core
Interface IFeature

All Superinterfaces:

IAdaptable

All Known Implementing Classes:

Feature

public interface IFeature

extends IAdaptable

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	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_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.
String	getArch() Returns optional system architecture specification.
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.
IFeatureReference[]	getIncludedFeatureReferences() Returns an array of feature references included by this feature
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.
String	getNL() Returns optional locale specification.
INonPluginEntry[]	getNonPluginEntries() Returns an array of non-plug-in entries referenced by this feature
int	getNonPluginEntryCount() Returns the count of referenced non-plug-in entries.
String	getOS() Returns optional operating system specification.
IPluginEntry[]	getPluginEntries() Returns an array of plug-in entries referenced by this feature
int	getPluginEntryCount() Returns the count of referenced plug-in entries.
String	getProvider() Returns a displayable label identifying the provider of this feature
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.
String	getWS() Returns optional windowing system specification.
IFeatureReference	install(IFeature targetFeature, IVerificationListener verificationListener, IProgressMonitor monitor) Install the contents of this feature into the specified target feature.
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

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.

Since:

2.0

See Also:

ILocalSite#getStatus(IFeature), Constant Field Values

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.

Since:

2.0

See Also:

ILocalSite#getStatus(IFeature), Constant Field Values

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.

Since:

2.0

See Also:

ILocalSite#getStatus(IFeature), Constant Field Values

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

getOS

public String getOS()

Returns optional operating system specification. A comma-separated list of os designators defined by the platform. Indicates this feature should only be installed on one of the specified os systems. If this attribute is not specified, the feature can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of feature regardless of this setting).

Returns:

the operating system specification, or null.

Since:

2.0

See Also:

BootLoader

getWS

public String getWS()

Returns optional windowing system specification. A comma-separated list of ws designators defined by the platform. Indicates this feature should only be installed on one of the specified ws systems. If this attribute is not specified, the feature can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of feature regardless of this setting).

Returns:

the windowing system specification, or null.

Since:

2.0

See Also:

BootLoader

getArch

public String getArch()

Returns optional system architecture specification. A comma-separated list of arch designators defined by the platform. Indicates this feature should only be installed on one of the specified systems. If this attribute is not specified, the feature can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of feature regardless of this setting).

Returns:

system architecture specification, or null.

Since:

2.0

See Also:

BootLoader

getNL

public String getNL()

Returns optional locale specification. A comma-separated list of locale designators defined by Java. Indicates this feature should only be installed on a system running with a compatible locale (using Java locale-matching rules). If this attribute is not specified, the feature can be installed on all systems (language-neutral implementation). This information is used as a hint by the installation and update support (user can force installation of feature regardless of this setting).

Returns:

the locale specification, 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.

Returns:

the list of required plug-in dependencies, or an empty array.

Since:

2.0

install

public IFeatureReference install(IFeature targetFeature,
                                 IVerificationListener verificationListener,
                                 IProgressMonitor monitor)
                          throws InstallAbortedException,
                                 CoreException

Install the contents of this feature into the specified target feature.

Parameters:

targetFeature -

verificationListener -

monitor -

Throws:

InstallAbortedException - when the user cancels the install

CoreException

Since:

2.0

getIncludedFeatureReferences

public IFeatureReference[] getIncludedFeatureReferences()
                                                 throws CoreException

Returns an array of feature references included by this feature

Returns:

an erray of feature references, or an empty array.

CoreException

Since:

2.0

getPluginEntries

public IPluginEntry[] getPluginEntries()

Returns an array of plug-in entries referenced by this feature

Returns:

an erray of plug-in entries, or an empty array.

Since:

2.0

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

Returns:

an erray of non-plug-in entries, or an empty array.

Since:

2.0

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

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

CoreException

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)