| /******************************************************************************* |
| * 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.*; |
| |
| import org.eclipse.core.runtime.*; |
| import org.eclipse.update.configuration.*; |
| import org.eclipse.update.core.model.*; |
| |
| /** |
| * Site represents a location containing some number of features (packaged |
| * or installed). Sites are treated purely as an installation and packaging |
| * construct. They do not play a role during Eclipse plug-in execution. |
| * <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.Site |
| * @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 ISite extends IAdaptable { |
| |
| /** |
| * Default type for an installed feature. Different concrete feature |
| * implementations can be registered together with their corresponding type |
| * using the <code>org.eclipse.update.core.featureTypes</code> |
| * extension point. |
| * |
| * @since 2.0 |
| */ |
| public static final String DEFAULT_INSTALLED_FEATURE_TYPE = "org.eclipse.update.core.installed"; //$NON-NLS-1$ |
| |
| /** |
| * Default type for a packaged feature. Different concrete feature |
| * implementations can be registered together with their corresponding type |
| * using the <code>org.eclipse.update.core.featureTypes</code> |
| * extension point. |
| * |
| * @since 2.0 |
| */ |
| public static final String DEFAULT_PACKAGED_FEATURE_TYPE = "org.eclipse.update.core.packaged"; //$NON-NLS-1$ |
| |
| /** |
| * If we are unable to access a site, the returned CoreException will contain |
| * this return code. |
| * |
| * @since 2.0.1 |
| */ |
| public static final int SITE_ACCESS_EXCEPTION = 42; |
| |
| /** |
| * Returns the site URL |
| * |
| * @return site URL |
| * @since 2.0 |
| */ |
| public URL getURL(); |
| |
| /** |
| * Return the site type. Different concrete site implementations can be |
| * registered together with their corresponding type using the |
| * <code>org.eclipse.update.core.siteTypes</code> extension point. |
| * |
| * @return site type, or <code>null</code>. |
| * @since 2.0 |
| */ |
| public String getType(); |
| |
| /** |
| * Returns the site description. |
| * |
| * @return site description, or <code>null</code>. |
| * @since 2.0 |
| */ |
| public IURLEntry getDescription(); |
| |
| /** |
| * Returns an array of categories defined by the site. |
| * |
| * @return array of site categories, or an empty array. |
| * @since 2.0 |
| */ |
| public ICategory[] getCategories(); |
| |
| /** |
| * Returns the named site category. |
| * |
| * @param name category name |
| * @return named category, or <code>null</code> ifit does not exist |
| * @since 2.0 |
| */ |
| public ICategory getCategory(String name); |
| |
| /** |
| * Returns an array of references to features on this site. |
| * |
| * @return an array of feature references, or an empty array. |
| * @since 2.0 |
| */ |
| public ISiteFeatureReference[] getFeatureReferences(); |
| |
| /** |
| * Returns an array of references to features on this site. |
| * No filtering occurs. |
| * |
| * @return an array of feature references, or an empty array.. |
| * @since 2.1 |
| */ |
| public ISiteFeatureReference[] getRawFeatureReferences(); |
| |
| /** |
| * Returns a reference to the specified feature if |
| * it is installed on this site. |
| * filtered by the operating system, windowing system and architecture |
| * system set in <code>Sitemanager</code> |
| * |
| * @param feature feature |
| * @return feature reference, or <code>null</code> if this feature |
| * cannot be located on this site. |
| * @since 2.0 |
| */ |
| public ISiteFeatureReference getFeatureReference(IFeature feature); |
| |
| /** |
| * Returns an array of plug-in and non-plug-in archives located |
| * on this site |
| * |
| * @return an array of archive references, or an empty array if there are |
| * no archives known to this site. Note, that an empty array does not |
| * necessarily indicate there are no archives accessible on this site. |
| * It simply indicates the site has no prior knowledge of such archives. |
| * @since 2.0 |
| */ |
| public IArchiveReference[] getArchives(); |
| |
| /** |
| * Returns the content provider for this site. A content provider |
| * is an abstraction of each site organization. It allows the |
| * content of the site to be accessed in a standard way |
| * regardless of the organization. All concrete sites |
| * need to be able to return a content provider. |
| * |
| * @return site content provider |
| * @exception CoreException |
| * @since 2.0 |
| */ |
| public ISiteContentProvider getSiteContentProvider() throws CoreException; |
| |
| /** |
| * Returns the default type for a packaged feature supported by this site |
| * |
| * @return feature type, as registered in the |
| * <code>org.eclipse.update.core.featureTypes</code> extension point. |
| * @since 2.0 |
| */ |
| public String getDefaultPackagedFeatureType(); |
| |
| /** |
| * Returns an array of entries corresponding to plug-ins installed |
| * on this site. |
| * |
| * @return array of plug-in entries,or an empty array. |
| * @since 2.0 |
| */ |
| public IPluginEntry[] getPluginEntries(); |
| |
| /** |
| * Returns the number of plug-ins installed on this site |
| * |
| * @return number of installed plug-ins |
| * @since 2.0 |
| */ |
| public int getPluginEntryCount(); |
| |
| /** |
| * Adds a new plug-in entry to this site. |
| * |
| * @param pluginEntry plug-in entry |
| * @since 2.0 |
| */ |
| public void addPluginEntry(IPluginEntry pluginEntry); |
| |
| /** |
| * Returns an array of entries corresponding to plug-ins that are |
| * installed on this site and are referenced only by the specified |
| * feature. These are plug-ins that are not shared with any other |
| * feature. |
| * |
| * @param feature feature |
| * @return an array of plug-in entries, or an empty array. |
| * @exception CoreException |
| * @since 2.0 |
| */ |
| public IPluginEntry[] getPluginEntriesOnlyReferencedBy(IFeature feature) throws CoreException; |
| |
| /** |
| * Returns the size of the files that need to be downloaded in order |
| * to install the specified feature on this site, if it can be determined. |
| * This method takes into account any plug-ins that are already |
| * available on this site. |
| * |
| * @see org.eclipse.update.core.model.ContentEntryModel#UNKNOWN_SIZE |
| * @param feature candidate feature |
| * @return download size of the feature in KiloBytes, or an indication |
| * the size could not be determined |
| * @since 2.0 |
| */ |
| public long getDownloadSizeFor(IFeature feature); |
| |
| /** |
| * Returns the size of the files that need to be installed |
| * for the specified feature on this site, if it can be determined. |
| * This method takes into account any plug-ins that are already |
| * installed on this site. |
| * |
| * @see org.eclipse.update.core.model.ContentEntryModel#UNKNOWN_SIZE |
| * @param feature candidate feature |
| * @return install size of the feature in KiloBytes, or an indication |
| * the size could not be determined |
| * @since 2.0 |
| */ |
| public long getInstallSizeFor(IFeature feature); |
| |
| /** |
| * Installs the specified feature on this site. |
| * |
| * @param feature feature to install |
| * @param verificationListener install verification listener |
| * @param monitor install monitor, can be <code>null</code> |
| * @exception InstallAbortedException when the user cancels the install |
| * @exception CoreException |
| * @since 2.0 |
| */ |
| public IFeatureReference install(IFeature feature, IVerificationListener verificationListener, IProgressMonitor monitor) throws InstallAbortedException, CoreException; |
| |
| /** |
| * Installs the specified feature on this site. |
| * Only optional features passed as parameter will be installed. |
| * |
| * @param feature feature to install |
| * @param optionalfeatures list of optional features to be installed |
| * @param verificationListener install verification listener |
| * @param monitor install monitor, can be <code>null</code> |
| * @exception InstallAbortedException when the user cancels the install |
| * @exception CoreException |
| * @since 2.0 |
| */ |
| public IFeatureReference install(IFeature feature, IFeatureReference[] optionalfeatures, IVerificationListener verificationListener, IProgressMonitor monitor) throws InstallAbortedException, CoreException; |
| |
| /** |
| * Removes (uninstalls) the specified feature from this site. This method |
| * takes into account plug-in entries referenced by the specified fetaure |
| * that continue to be required by other features installed on this site. |
| * |
| * @param feature feature to remove |
| * @param monitor progress monitor |
| * @exception CoreException |
| * @since 2.0 |
| */ |
| public void remove(IFeature feature, IProgressMonitor monitor) throws CoreException; |
| |
| /** |
| * Sets the site content provider. This is typically performed |
| * as part of the site creation operation. Once set, the |
| * provider should not be reset. |
| * |
| * @param siteContentProvider site content provider |
| * @since 2.0 |
| */ |
| public void setSiteContentProvider(ISiteContentProvider siteContentProvider); |
| |
| /** |
| * Returns the <code>IConfiguredSite</code> for this site in the current |
| * configuration or <code>null</code> if none found. |
| * |
| * @since 2.0.2 |
| */ |
| public IConfiguredSite getCurrentConfiguredSite(); |
| |
| /** |
| * Creates a new feature object. The feature must exist on this site |
| * or a core exception will be thrown. Concrete implementations |
| * may elect to cache instances, in which case subsequent calls |
| * to create a feature with the same URL will |
| * return the same instance. |
| * param type the feature type that will be used to select the factory. If |
| * <code>null</code> is passed, default feature type will be used. |
| * param url URL of the feature archive as listed in the site. |
| * return newly created feature object, or a cached value if |
| * caching is implemented by this site. |
| * @deprecated use createFeature(String,URL,IProgressMonitor) instead |
| * @since 2.0.2 |
| */ |
| IFeature createFeature(String type, URL url) throws CoreException; |
| |
| /** |
| * Creates a new feature object. The feature must exist on this site |
| * or a core exception will be thrown. Concrete implementations |
| * may elect to cache instances, in which case subsequent calls |
| * to create a feature with the same URL will |
| * return the same instance. |
| * param type the feature type that will be used to select the factory. If |
| * <code>null</code> is passed, default feature type will be used. |
| * param url URL of the feature archive as listed in the site. |
| * return newly created feature object, or a cached value if |
| * caching is implemented by this site. |
| * @param monitor the progress monitor |
| * @since 2.1 |
| */ |
| IFeature createFeature(String type, URL url,IProgressMonitor monitor) throws CoreException; |
| |
| |
| } |