update/org.eclipse.update.core/src/org/eclipse/update/core/ISite.java - platform/eclipse.platform - Git at Google

 /*******************************************************************************
  *  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;


 }
	/*******************************************************************************
	* 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;


	}