| /******************************************************************************* |
| * Copyright (c) 2000, 2010 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.update.core; |
| |
| import java.net.URL; |
| |
| import org.eclipse.core.runtime.CoreException; |
| |
| /** |
| * 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 |
| * @deprecated The org.eclipse.update component has been replaced by Equinox p2. |
| * This API will be deleted in a future release. See bug 311590 for details. |
| */ |
| 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); |
| } |