/******************************************************************************* | |
* Copyright (c) 2000, 2004 IBM Corporation and others. | |
* All rights reserved. This program and the accompanying materials | |
* are made available under the terms of the Common Public License v1.0 | |
* which accompanies this distribution, and is available at | |
* http://www.eclipse.org/legal/cpl-v10.html | |
* | |
* Contributors: | |
* IBM Corporation - initial API and implementation | |
*******************************************************************************/ | |
package org.eclipse.update.core; | |
import java.net.*; | |
import org.eclipse.core.runtime.*; | |
/** | |
* 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. | |
* <p> | |
* There are two ways of looking at a feature content: | |
* <ol> | |
* <li>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 | |
* <li>the "packaged" view, which is a set of related archive files that | |
* contain the "logical" files. | |
* </ol> | |
* It is the responsibility of a feature content provider to manage the | |
* mapping between the "packaged" and "logical" views. | |
* </p> | |
* <p> | |
* Clients may implement this interface. However, in most cases clients should | |
* directly instantiate or subclass the provided implementation of this | |
* interface. | |
* </p> | |
* <p> | |
* <b>Note:</b> This class/interface is part of an interim API that is still under development and expected to | |
* change significantly before reaching stability. It is being made available at this early stage to solicit feedback | |
* from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken | |
* (repeatedly) as the API evolves. | |
* </p> | |
* @see org.eclipse.update.core.FeatureContentProvider | |
* @since 2.0 | |
*/ | |
public interface IFeatureContentProvider { | |
/** | |
* 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. | |
* | |
* @return feature url | |
* @since 2.0 | |
*/ | |
public URL getURL(); | |
/** | |
* 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. | |
* | |
* @param monitor progress monitor, can be <code>null</code> | |
* @return feature manifest reference, or <code>null</code> if the manifest cannot be found. | |
* @since 2.0 | |
*/ | |
public ContentReference getFeatureManifestReference(InstallMonitor monitor) | |
throws CoreException; | |
/** | |
* Returns an array of content references of all the "packaged" | |
* archives that make up this feature. | |
* <p> | |
* The number of returned references is dependent on each feature | |
* content provider (i.e is dependent on the packaging mechanism used | |
* by the particular feature type). | |
* </p> | |
* | |
* @param monitor progress monitor, can be <code>null</code> | |
* @return an array of references, or an empty array if no references | |
* are found | |
* @exception CoreException | |
* @since 2.0 | |
*/ | |
public ContentReference[] getArchiveReferences(InstallMonitor monitor) | |
throws CoreException; | |
/** | |
* Returns an array of content references of the "packaged" | |
* archives that contain the feature descriptive information. | |
* <p> | |
* 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. | |
* </p> | |
* <p> | |
* The number of returned references is dependent on each feature | |
* content provider (i.e is dependent on the packaging mechanism used | |
* by the particular feature type). | |
* </p> | |
* | |
* @see IFeatureContentProvider#getFeatureEntryContentReferences(InstallMonitor) | |
* @param monitor progress monitor, can be <code>null</code> | |
* @return an array of references, or an empty array if no references | |
* are found | |
* @exception CoreException | |
* @since 2.0 | |
*/ | |
public ContentReference[] getFeatureEntryArchiveReferences(InstallMonitor monitor) | |
throws CoreException; | |
/** | |
* Returns an array of content references of the "packaged" | |
* archives that contain the files for the specified plug-in entry. | |
* <p> | |
* The number of returned references is dependent on each feature | |
* content provider (i.e is dependent on the packaging mechanism used | |
* by the particular feature type). | |
* </p> | |
* | |
* @see IFeatureContentProvider#getPluginEntryContentReferences(IPluginEntry, InstallMonitor) | |
* @param pluginEntry plug-in entry | |
* @param monitor progress monitor, can be <code>null</code> | |
* @return an array of references, or an empty array if no references | |
* are found | |
* @exception CoreException | |
* @since 2.0 | |
*/ | |
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 non-plug-in entry. | |
* <p> | |
* The number of returned references is dependent on each feature | |
* content provider (i.e is dependent on the packaging mechanism used | |
* by the particular feature type). | |
* </p> | |
* <p> | |
* 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. | |
* </p> | |
* | |
* @param monitor progress monitor, can be <code>null</code> | |
* @return an array of references, or an empty array if no references | |
* are found | |
* @exception CoreException | |
* @since 2.0 | |
*/ | |
public ContentReference[] getNonPluginEntryArchiveReferences( | |
INonPluginEntry nonPluginEntry, | |
InstallMonitor monitor) | |
throws CoreException; | |
/** | |
* Returns an array of content references to the feature definition files | |
* (i.e 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. | |
* | |
* @see IFeatureContentProvider#getFeatureEntryArchiveReferences(InstallMonitor) | |
* @param monitor progress monitor, can be <code>null</code> | |
* @return an array of ContentReference or an empty array if no references are found | |
* @exception CoreException when an error occurs | |
* @since 2.0 | |
*/ | |
public ContentReference[] getFeatureEntryContentReferences(InstallMonitor monitor) | |
throws CoreException; | |
/** | |
* Returns an array of content references to the files implementing | |
* the specified plug-in. (i.e the "logical" view of the plug-in). | |
* | |
* @see IFeatureContentProvider#getPluginEntryArchiveReferences(IPluginEntry, InstallMonitor) | |
* @param monitor progress monitor, can be <code>null</code> | |
* @return an array of ContentReference or an empty array if no references are found | |
* @exception CoreException | |
* @since 2.0 | |
*/ | |
public ContentReference[] getPluginEntryContentReferences( | |
IPluginEntry pluginEntry, | |
InstallMonitor monitor) | |
throws CoreException; | |
/** | |
* Returns the total size of all archives required for the | |
* specified plug-in and non-plug-in entries (the "packaging" view). | |
* | |
* @param pluginEntries an array of plug-in entries | |
* @param nonPluginEntries an array of non-plug-in entries | |
* @return total download size, or an indication that size could not be | |
* determined | |
* @see org.eclipse.update.core.model.ContentEntryModel#UNKNOWN_SIZE | |
* @since 2.0 | |
*/ | |
public long getDownloadSizeFor( | |
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). | |
* | |
* @param pluginEntries an array of plug-in entries | |
* @param nonPluginEntries an array of non-plug-in entries | |
* @return total download size, or an indication that size could not be | |
* determined | |
* @see org.eclipse.update.core.model.ContentEntryModel#UNKNOWN_SIZE | |
* @since 2.0 | |
*/ | |
public long getInstallSizeFor( | |
IPluginEntry[] pluginEntries, | |
INonPluginEntry[] nonPluginEntries); | |
/** | |
* 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. | |
* | |
* @return verifier | |
* @exception CoreException | |
* @since 2.0 | |
*/ | |
public IVerifier getVerifier() throws CoreException; | |
/** | |
* Returns the feature associated with this content provider. | |
* | |
* @return feature for this content provider | |
* @since 2.0 | |
*/ | |
public IFeature getFeature(); | |
/** | |
* 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. | |
* | |
* @param feature feature for this content provider | |
* @since 2.0 | |
*/ | |
public void setFeature(IFeature feature); | |
} |