org.eclipse.update.core
Interface IFeatureContentProvider

All Known Implementing Classes:

FeatureContentProvider

public interface IFeatureContentProvider

Feature content provider. A feature 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 feature implementations need to implement a feature content provider.

There are two ways of looking at a feature content:

1. the "logical" view, which is a representation of the actual files that make up the feature. These include any files that describe the feature itself, files that are the actual implementation of referenced plug-ins, and files that are the non-plug-in data files associated with the feature
2. the "packaged" view, which is a set of related archive files that contain the "logical" files.

It is the responsibility of a feature content provider to manage the mapping between the "packaged" and "logical" views.

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:

FeatureContentProvider

Method Summary

ContentReference[]	getArchiveReferences(InstallMonitor monitor) Returns an array of content references of all the "packaged" archives that make up this feature.
long	getDownloadSizeFor(IPluginEntry[] pluginEntries, INonPluginEntry[] nonPluginEntries) Returns the total size of all archives required for the specified plug-in and non-plug-in entries (the "packaging" view).
IFeature	getFeature() Returns the feature associated with this content provider.
ContentReference[]	getFeatureEntryArchiveReferences(InstallMonitor monitor) Returns an array of content references of the "packaged" archives that contain the feature descriptive information.
ContentReference[]	getFeatureEntryContentReferences(InstallMonitor monitor) Returns an array of content references to the feature definition files (ie.
ContentReference	getFeatureManifestReference(InstallMonitor monitor) Returns a content reference to the feature manifest.
long	getInstallSizeFor(IPluginEntry[] pluginEntries, INonPluginEntry[] nonPluginEntries) Returns the total size of all files required for the specified plug-in and non-plug-in entries (the "logical" view).
ContentReference[]	getNonPluginEntryArchiveReferences(INonPluginEntry nonPluginEntry, InstallMonitor monitor) Returns an array of content references of the "packaged" archives that contain the files for the specified non-plug-in entry.
ContentReference[]	getPluginEntryArchiveReferences(IPluginEntry pluginEntry, InstallMonitor monitor) Returns an array of content references of the "packaged" archives that contain the files for the specified plug-in entry.
ContentReference[]	getPluginEntryContentReferences(IPluginEntry pluginEntry, InstallMonitor monitor) Returns an array of content references to the files implementing the specified plug-in.
URL	getURL() Returns the feature url.
IVerifier	getVerifier() Returns the verifier for this feature.
void	setFeature(IFeature feature) Sets the feature associated with this content provider.

Method Detail

getURL

public URL getURL()

Returns the feature url. The exact interpretation of this URL is specific to each content provider. Typically, the URL is a reference to a file that can be used directly, or indirectly, to determine the content of the feature.

Returns:

feature url

Since:

2.0

getFeatureManifestReference

public ContentReference getFeatureManifestReference(InstallMonitor monitor)
                                             throws CoreException

Returns a content reference to the feature manifest. The feature manifest is an xml file, whose format is specified by the platform. Typically a feature will contain the manifest as one of the packaged files. For features that do not contain the manifest, or contain a manifest that does not follow the specified format, this method returns a reference to a computed manifest in the appropriate platform format.

Parameters:

monitor - progress monitor, can be null

Returns:

feature manifest reference, or null if the manifest cannot be found.

CoreException

Since:

2.0

getArchiveReferences

public ContentReference[] getArchiveReferences(InstallMonitor monitor)
                                        throws CoreException

Returns an array of content references of all the "packaged" archives that make up this feature.

The number of returned references is dependent on each feature content provider (ie. is dependent on the packaging mechanism used by the particular feature type).

Parameters:

monitor - progress monitor, can be null

Returns:

an array of references, or an empty array if no references are found

Throws:

CoreException

Since:

2.0

getFeatureEntryArchiveReferences

public ContentReference[] getFeatureEntryArchiveReferences(InstallMonitor monitor)
                                                    throws CoreException

Returns an array of content references of the "packaged" archives that contain the feature descriptive information.

In general, the feature descriptive information should be packaged separately from the "bulk" of the actual feature content. The feature entry archive(s) must be downloaded from an update site in order to present information about the feature to the client. Consequently, keeping the number and size of the feature entry archive(s) to a minimum will speed up the responsiveness of the user interface.

The number of returned references is dependent on each feature content provider (ie. is dependent on the packaging mechanism used by the particular feature type).

Parameters:

monitor - progress monitor, can be null

Returns:

an array of references, or an empty array if no references are found

Throws:

CoreException

Since:

2.0

See Also:

getFeatureEntryContentReferences(InstallMonitor)

getPluginEntryArchiveReferences

public ContentReference[] getPluginEntryArchiveReferences(IPluginEntry pluginEntry,
                                                          InstallMonitor monitor)
                                                   throws CoreException

Returns an array of content references of the "packaged" archives that contain the files for the specified plug-in entry.

The number of returned references is dependent on each feature content provider (ie. is dependent on the packaging mechanism used by the particular feature type).

Parameters:

pluginEntry - plug-in entry

monitor - progress monitor, can be null

Returns:

an array of references, or an empty array if no references are found

Throws:

CoreException

Since:

2.0

See Also:

getPluginEntryContentReferences(IPluginEntry, InstallMonitor)

getNonPluginEntryArchiveReferences

public ContentReference[] getNonPluginEntryArchiveReferences(INonPluginEntry nonPluginEntry,
                                                             InstallMonitor monitor)
                                                      throws CoreException

Returns an array of content references of the "packaged" archives that contain the files for the specified non-plug-in entry.

The number of returned references is dependent on each feature content provider (ie. is dependent on the packaging mechanism used by the particular feature type).

Note, that the platform does not interpret non-plug-in entries in any way, other that performing any required downloads. Non-plug-in entries are handled by custom install handlers that must be specified for the feature. Consequently, this interface does not make a distinction between the "logical" and "packaged" views for non-plug-in entries. The "packaged" view (returning references to the non-plug-in archives) is the only one supported. It is the responsibility of the custom install handler to understand the "logical" view of non-plug-in archives.

Parameters:

monitor - progress monitor, can be null

Returns:

an array of references, or an empty array if no references are found

Throws:

CoreException

Since:

2.0

getFeatureEntryContentReferences

public ContentReference[] getFeatureEntryContentReferences(InstallMonitor monitor)
                                                    throws CoreException

Returns an array of content references to the feature definition files (ie. the "logical" view of the files defining the feature). These are the files required to present information about the feature to the client, and in general, should not contain references to plug-in and non-plug-in files.

Parameters:

monitor - progress monitor, can be null

Returns:

an array of ContentReference or an empty array if no references are found

Throws:

CoreException - when an error occurs

Since:

2.0

See Also:

getFeatureEntryArchiveReferences(InstallMonitor)

getPluginEntryContentReferences

public ContentReference[] getPluginEntryContentReferences(IPluginEntry pluginEntry,
                                                          InstallMonitor monitor)
                                                   throws CoreException

Returns an array of content references to the files implementing the specified plug-in. (ie. the "logical" view of the plug-in).

Parameters:

monitor - progress monitor, can be null

Returns:

an array of ContentReference or an empty array if no references are found

Throws:

CoreException

Since:

2.0

See Also:

getPluginEntryArchiveReferences(IPluginEntry, InstallMonitor)

getDownloadSizeFor

public long getDownloadSizeFor(IPluginEntry[] pluginEntries,
                               INonPluginEntry[] nonPluginEntries)

Returns the total size of all archives required for the specified plug-in and non-plug-in entries (the "packaging" view).

Parameters:

pluginEntries - an array of plug-in entries

nonPluginEntries - an array of non-plug-in entries

Returns:

total download size, or an indication that size could not be determined

Throws:

CoreException

Since:

2.0

See Also:

ContentEntryModel.UNKNOWN_SIZE

getInstallSizeFor

public long getInstallSizeFor(IPluginEntry[] pluginEntries,
                              INonPluginEntry[] nonPluginEntries)

Returns the total size of all files required for the specified plug-in and non-plug-in entries (the "logical" view).

Parameters:

pluginEntries - an array of plug-in entries

nonPluginEntries - an array of non-plug-in entries

Returns:

total download size, or an indication that size could not be determined

Throws:

CoreException

Since:

2.0

See Also:

ContentEntryModel.UNKNOWN_SIZE

getVerifier

public IVerifier getVerifier()
                      throws CoreException

Returns the verifier for this feature. If provided, the verifier is called at various point during installation processing to verify downloaded archives. The type of verification provided is dependent on the content provider implementation.

Returns:

verifier

Throws:

CoreException

Since:

2.0

getFeature

public IFeature getFeature()

Returns the feature associated with this content provider.

Returns:

feature for this content provider

Since:

2.0

setFeature

public void setFeature(IFeature feature)

Sets the feature associated with this content provider. In general, this method should only be called as part of feature creation. Once set, the feature should not be reset.

Parameters:

feature - feature for this content provider

Since:

2.0