| /******************************************************************************* |
| * Copyright (c) 2000, 2009 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; |
| import org.eclipse.core.runtime.IAdaptable; |
| import org.eclipse.core.runtime.IProgressMonitor; |
| import org.eclipse.update.core.model.InstallAbortedException; |
| |
| /** |
| * Feature defines the packaging "container" for a group of related plug-ins, |
| * plug-in fragments, and optionally non-plug-in files. |
| * <p> |
| * 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. |
| * </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.Feature |
| * @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 IFeature extends IAdaptable, IPlatformEnvironment { |
| |
| /** |
| * 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 org.eclipse.update.configuration.IConfiguredSite#getBrokenStatus(IFeature) |
| * @since 2.0 |
| */ |
| public static final int STATUS_HAPPY = 0; |
| |
| /** |
| * 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 org.eclipse.update.configuration.IConfiguredSite#getBrokenStatus(IFeature) |
| */ |
| public static final int STATUS_AMBIGUOUS = 1; |
| |
| /** |
| * 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 org.eclipse.update.configuration.IConfiguredSite#getBrokenStatus(IFeature) |
| * @since 2.0 |
| */ |
| public static final int STATUS_UNHAPPY = 2; |
| |
| |
| /** |
| * Indicates a disable feature |
| * |
| * @see org.eclipse.update.configuration.IConfiguredSite#getBrokenStatus(IFeature) |
| * @since 2.0.2 |
| */ |
| public static final int STATUS_DISABLED = -1; |
| |
| /** |
| * Indicates the one-click update will search the |
| * location of the nesting root feature. |
| * |
| * @since 2.0.1 |
| */ |
| public static final int SEARCH_LOCATION_DEFAULT = 0; |
| |
| /** |
| * Indicates the one-click update will search the |
| * location defined by the feature. |
| * |
| * @since 2.0.1 |
| */ |
| public static final int SEARCH_LOCATION_FEATURE = 1; |
| |
| /** |
| * 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 |
| */ |
| public static final int SEARCH_LOCATION_BOTH = 2; |
| |
| |
| /** |
| * Returns the feature identifier. |
| * |
| * @return the feature identifier. |
| * @since 2.0 |
| */ |
| public VersionedIdentifier getVersionedIdentifier(); |
| |
| /** |
| * Returns the site this feature is associated with. |
| * |
| * @return the site for this feature |
| * @since 2.0 |
| */ |
| public ISite getSite(); |
| |
| /** |
| * Returns the displayable label of the feature. |
| * |
| * @return feature label, or <code>null</code>. |
| * @since 2.0 |
| */ |
| public String getLabel(); |
| |
| /** |
| * 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. * |
| * @return feature URL |
| * @since 2.0 |
| */ |
| public URL getURL(); |
| |
| /** |
| * 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. |
| * |
| * @return update site entry, or <code>null</code>. |
| * @since 2.0 |
| */ |
| public IURLEntry getUpdateSiteEntry(); |
| |
| /** |
| * 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. |
| * |
| * @return an array of site entries, or an empty array. |
| * @since 2.0 |
| */ |
| public IURLEntry[] getDiscoverySiteEntries(); |
| |
| /** |
| * Returns a displayable label identifying the provider of this feature |
| * |
| * @return provider label, or <code>null</code>. |
| * @since 2.0 |
| */ |
| public String getProvider(); |
| |
| /** |
| * Returns and optional custom install handler entry. |
| * |
| * @return install handler entry, or <code>null</code> if |
| * none was specified |
| * @since 2.0 |
| */ |
| public IInstallHandlerEntry getInstallHandlerEntry(); |
| |
| /** |
| * Returns the feature description. |
| * |
| * @return feature description, or <code>null</code>. |
| * @since 2.0 |
| */ |
| public IURLEntry getDescription(); |
| |
| /** |
| * Returns the copyright information for the feature. |
| * |
| * @return copyright information, or <code>null</code>. |
| * @since 2.0 |
| */ |
| public IURLEntry getCopyright(); |
| |
| /** |
| * Returns the license information for the feature. |
| * |
| * @return feature license, or <code>null</code>. |
| * @since 2.0 |
| */ |
| public IURLEntry getLicense(); |
| |
| /** |
| * Return optional image for the feature. |
| * |
| * @return the URL pointing to the image, , or <code>null</code>. |
| * @since 2.0 |
| */ |
| public URL getImage(); |
| |
| /** |
| * 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 <code>SiteManager</code> |
| * |
| * @return the list of required plug-in dependencies, or an empty array. |
| * @since 2.0 |
| */ |
| 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. |
| * No filtering occurs |
| * |
| * @return the list of required plug-in dependencies, or an empty array. |
| * @since 2.1 |
| */ |
| public IImport[] getRawImports(); |
| |
| /** |
| * Return the identifier of the primary plugin associated to this feature |
| * or <code>null</code> 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. |
| * |
| * @return the identifier of the associated primary plugin or <code>null</code> |
| * @since 2.1 |
| */ |
| public String getPrimaryPluginID(); |
| |
| |
| /** |
| * Install the contents of this feature into the specified target feature. |
| * All optional features will be installed |
| * |
| * @param targetFeature |
| * @param verificationListener |
| * @param monitor |
| * @exception InstallAbortedException when the user cancels the install |
| * @exception CoreException |
| * @since 2.0 |
| */ |
| public IFeatureReference install( |
| IFeature targetFeature, |
| 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. |
| * |
| * @param targetFeature |
| * @param optionalFeatures the optional features to be installed |
| * @param verificationListener |
| * @param monitor |
| * @exception InstallAbortedException when the user cancels the install |
| * @exception CoreException |
| * @since 2.0.1 |
| */ |
| public IFeatureReference install( |
| IFeature targetFeature, |
| IFeatureReference[] optionalFeatures, |
| IVerificationListener verificationListener, |
| IProgressMonitor monitor) |
| throws InstallAbortedException,CoreException; |
| |
| /** |
| * Returns an array of feature references included by this feature |
| * filtered by the operating system, windowing system and architecture system |
| * set in <code>SiteManager</code> |
| * |
| * @return an array of feature references, or an empty array. |
| * @since 2.0 |
| */ |
| public IIncludedFeatureReference[] getIncludedFeatureReferences() throws CoreException; |
| |
| /** |
| * Returns an array of feature references included by this feature |
| * No filtering occurs |
| * |
| * @return an array of feature references, or an empty array. |
| * @since 2.0 |
| */ |
| public IIncludedFeatureReference[] getRawIncludedFeatureReferences() throws CoreException; |
| |
| /** |
| * Returns an array of plug-in entries referenced by this feature |
| * filtered by the operating system, windowing system and architecture system |
| * set in <code>SiteManager</code> |
| * |
| * @return an array of plug-in entries, or an empty array. |
| * @since 2.0 |
| */ |
| public IPluginEntry[] getPluginEntries(); |
| |
| /** |
| * Returns an array of plug-in entries referenced by this feature |
| * No filtering occurs |
| * |
| * @return an array of plug-in entries, or an empty array. |
| * @since 2.1 |
| */ |
| public IPluginEntry[] getRawPluginEntries(); |
| |
| /** |
| * Returns the count of referenced plug-in entries. |
| * |
| * @return plug-in entry count |
| * @since 2.0 |
| */ |
| public int getPluginEntryCount(); |
| |
| /** |
| * Returns an array of non-plug-in entries referenced by this feature |
| * filtered by the operating system, windowing system and architecture system |
| * set in <code>SiteManager</code> |
| * |
| * @return an array of non-plug-in entries, or an empty array. |
| * @since 2.0 |
| */ |
| public INonPluginEntry[] getNonPluginEntries(); |
| |
| /** |
| * Returns an array of non-plug-in entries referenced by this feature |
| * No filtering occurs |
| * |
| * @return an array of non-plug-in entries, or an empty array. |
| * @since 2.1 |
| */ |
| public INonPluginEntry[] getRawNonPluginEntries(); |
| |
| /** |
| * Returns the count of referenced non-plug-in entries. |
| * |
| * @return non-plug-in entry count |
| * @since 2.0 |
| */ |
| public int getNonPluginEntryCount(); |
| |
| /** |
| * Returns the download size of the feature, if it can be determined. |
| * |
| * @see org.eclipse.update.core.model.ContentEntryModel#UNKNOWN_SIZE |
| * @return download size of the feature in KiloBytes, or an indication |
| * the size could not be determined |
| * @since 2.0 |
| */ |
| public long getDownloadSize(); |
| |
| /** |
| * Returns the install size of the feature, if it can be determined. |
| * |
| * @see org.eclipse.update.core.model.ContentEntryModel#UNKNOWN_SIZE |
| * @return install size of the feature in KiloBytes, or an indication |
| * the size could not be determined |
| * @since 2.0 |
| */ |
| public long getInstallSize(); |
| |
| /** |
| * Indicates whether the feature can be used as a primary feature. |
| * |
| * @return <code>true</code> if this is a primary feature, |
| * otherwise <code>false</code> |
| * @since 2.0 |
| */ |
| public boolean isPrimary(); |
| |
| /** |
| * Indicates whether the feature must be processed alone during installation |
| * and configuration. Features that are not exclusive can be installed in a |
| * batch. |
| * |
| * @return <code>true</code> if feature requires exclusive processing, |
| * <code>false</code> otherwise. |
| * @since 2.1 |
| */ |
| public boolean isExclusive(); |
| |
| /** |
| * 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 <code>org.eclipse.core.runtime.applications</code> extension point. |
| * |
| * @return application identifier, or <code>null</code> |
| * @since 2.0 |
| */ |
| public String getApplication(); |
| |
| /** |
| * Returns an optional identifier of a co-location affinity feature. |
| * |
| * @return feature identifier, or <code>null</code>. |
| * @since 2.0 |
| */ |
| public String getAffinityFeature(); |
| |
| /** |
| * 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. |
| * |
| * @return feature content provider |
| * @exception CoreException |
| * @since 2.0 |
| */ |
| public IFeatureContentProvider getFeatureContentProvider() |
| 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. |
| * |
| * @return feature content consumer |
| * @exception CoreException |
| * @exception UnsupportedOperationException |
| * @since 2.0 |
| */ |
| public IFeatureContentConsumer getFeatureContentConsumer() |
| 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. |
| * |
| * @param site the site |
| * @throws CoreException site for this feature is already set |
| * @since 2.0 |
| */ |
| public void setSite(ISite site) throws CoreException; |
| |
| /** |
| * 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. |
| * |
| * @param featureContentProvider content provider |
| * @since 2.0 |
| */ |
| public void setFeatureContentProvider(IFeatureContentProvider featureContentProvider); |
| |
| /** |
| * Returns <code>true</code> if this feature is patching another feature, |
| * <code>false</code> otherwise |
| * @return boolean |
| * @since 2.1 |
| */ |
| public boolean isPatch(); |
| |
| |
| } |