ISite


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.update.core;
12  import java.net.*;
13  
14  import org.eclipse.core.runtime.*;
15  import org.eclipse.update.configuration.*;
16  import org.eclipse.update.core.model.*;
17  
18  /**
19   * Site represents a location containing some number of features (packaged
20   * or installed). Sites are treated purely as an installation and packaging
21   * construct. They do not play a role during Eclipse plug-in execution. 
22   * <p>
23   * Clients may implement this interface. However, in most cases clients should 
24   * directly instantiate or subclass the provided implementation of this 
25   * interface.
26   * </p>
27   * <p>
28   * <b>Note:</b> This class/interface is part of an interim API that is still under development and expected to
29   * change significantly before reaching stability. It is being made available at this early stage to solicit feedback
30   * from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken
31   * (repeatedly) as the API evolves.
32   * </p>
33   * @see org.eclipse.update.core.Site
34   * @since 2.0
35   */
36  public interface ISite extends IAdaptable {
37  
38      /**
39       * Default type for an installed feature. Different concrete feature
40       * implementations can be registered together with their corresponding type
41       * using the <code>org.eclipse.update.core.featureTypes</code> 
42       * extension point.
43       * 
44       * @since 2.0
45       */
46      public static final String   DEFAULT_INSTALLED_FEATURE_TYPE = "org.eclipse.update.core.installed"; //$NON-NLS-1$      
47  
48      /**
49       * Default type for a packaged feature. Different concrete feature
50       * implementations can be registered together with their corresponding type
51       * using the <code>org.eclipse.update.core.featureTypes</code> 
52       * extension point.
53       * 
54       * @since 2.0
55       */
56      public static final String   DEFAULT_PACKAGED_FEATURE_TYPE = "org.eclipse.update.core.packaged"; //$NON-NLS-1$        
57  
58      /**
59       * If we are unable to access a site, the returned CoreException will contain
60       * this return code.
61       * 
62       * @since 2.0.1
63       */
64      public static final int SITE_ACCESS_EXCEPTION = 42;
65  
66      /**
67       * Returns the site URL
68       * 
69       * @return site URL
70       * @since 2.0 
71       */
72      public URL getURL();
73  
74      /**
75       * Return the site type. Different concrete site implementations can be
76       * registered together with their corresponding type using the
77       * <code>org.eclipse.update.core.siteTypes</code> extension point.
78       * 
79       * @return site type, or <code>null</code>.
80       * @since 2.0 
81       */
82      public String   getType();
83  
84      /**
85       * Returns the site description.
86       * 
87       * @return site description, or <code>null</code>.
88       * @since 2.0 
89       */
90      public IURLEntry getDescription();
91  
92      /**
93       * Returns an array of categories defined by the site.
94       * 
95       * @return array of site categories, or an empty array.
96       * @since 2.0 
97       */
98      public ICategory[] getCategories();
99  
100     /**
101      * Returns the named site category.
102      * 
103      * @param name category name
104      * @return named category, or <code>null</code> ifit does not exist
105      * @since 2.0
106      */
107     public ICategory getCategory(String   name);
108 
109     /**
110      * Returns an array of references to features on this site.
111      * 
112      * @return an array of feature references, or an empty array.
113      * @since 2.0 
114      */
115     public ISiteFeatureReference[] getFeatureReferences();
116 
117     /**
118      * Returns an array of references to features on this site.
119      * No filtering occurs.
120      * 
121      * @return an array of feature references, or an empty array..
122      * @since 2.1
123      */
124     public ISiteFeatureReference[] getRawFeatureReferences();
125     
126     /**
127      * Returns a reference to the specified feature if 
128      * it is installed on this site.
129      * filtered by the operating system, windowing system and architecture
130      * system set in <code>Sitemanager</code>
131      * 
132      * @param feature feature
133      * @return feature reference, or <code>null</code> if this feature
134      * cannot be located on this site.
135      * @since 2.0
136      */
137     public ISiteFeatureReference getFeatureReference(IFeature feature);
138 
139     /**
140      * Returns an array of plug-in and non-plug-in archives located
141      * on this site
142      * 
143      * @return an array of archive references, or an empty array if there are
144      * no archives known to this site. Note, that an empty array does not
145      * necessarily indicate there are no archives accessible on this site.
146      * It simply indicates the site has no prior knowledge of such archives.
147      * @since 2.0 
148      */
149     public IArchiveReference[] getArchives();
150 
151     /**
152      * Returns the content provider for this site. A content provider
153      * is an abstraction of each site organization. It allows the 
154      * content of the site to be accessed in a standard way
155      * regardless of the organization. All concrete sites
156      * need to be able to return a content provider.
157      * 
158      * @return site content provider
159      * @exception CoreException
160      * @since 2.0
161      */
162     public ISiteContentProvider getSiteContentProvider() throws CoreException;
163 
164     /**
165      * Returns the default type for a packaged feature supported by this site
166      * 
167      * @return feature type, as registered in the
168      * <code>org.eclipse.update.core.featureTypes</code> extension point.
169      * @since 2.0
170      */
171     public String   getDefaultPackagedFeatureType();
172 
173     /**
174      * Returns an array of entries corresponding to plug-ins installed
175      * on this site.
176      * 
177      * @return array of plug-in entries,or an empty array.
178      * @since 2.0
179      */
180     public IPluginEntry[] getPluginEntries();
181 
182     /**
183      * Returns the number of plug-ins installed on this site
184      * 
185      * @return number of installed plug-ins
186      * @since 2.0
187      */
188     public int getPluginEntryCount();
189 
190     /**
191      * Adds a new plug-in entry to this site.
192      * 
193      * @param pluginEntry plug-in entry
194      * @since 2.0
195      */
196     public void addPluginEntry(IPluginEntry pluginEntry);
197 
198     /**
199      * Returns an array of entries corresponding to plug-ins that are
200      * installed on this site and are referenced only by the specified
201      * feature. These are plug-ins that are not shared with any other
202      * feature.
203      * 
204      * @param feature feature
205      * @return an array of plug-in entries, or an empty array.
206      * @exception CoreException
207      * @since 2.0
208      */
209     public IPluginEntry[] getPluginEntriesOnlyReferencedBy(IFeature feature) throws CoreException;
210 
211     /**
212      * Returns the size of the files that need to be downloaded in order
213      * to install the specified feature on this site, if it can be determined.
214      * This method takes into account any plug-ins that are already
215      * available on this site.
216      * 
217      * @see org.eclipse.update.core.model.ContentEntryModel#UNKNOWN_SIZE
218      * @param feature candidate feature
219      * @return download size of the feature in KiloBytes, or an indication 
220      * the size could not be determined
221      * @since 2.0 
222      */
223     public long getDownloadSizeFor(IFeature feature);
224 
225     /**
226      * Returns the size of the files that need to be installed
227      * for the specified feature on this site, if it can be determined.
228      * This method takes into account any plug-ins that are already
229      * installed on this site.
230      * 
231      * @see org.eclipse.update.core.model.ContentEntryModel#UNKNOWN_SIZE
232      * @param feature candidate feature
233      * @return install size of the feature in KiloBytes, or an indication 
234      * the size could not be determined
235      * @since 2.0 
236      */
237     public long getInstallSizeFor(IFeature feature);
238 
239     /**
240      * Installs the specified feature on this site.
241      * 
242      * @param feature feature to install
243      * @param verificationListener install verification listener
244      * @param monitor install monitor, can be <code>null</code>
245      * @exception InstallAbortedException when the user cancels the install
246      * @exception CoreException
247      * @since 2.0 
248      */
249     public IFeatureReference install(IFeature feature, IVerificationListener verificationListener, IProgressMonitor monitor) throws InstallAbortedException, CoreException;
250 
251     /**
252      * Installs the specified feature on this site.
253      * Only optional features passed as parameter will be installed.
254      * 
255      * @param feature feature to install
256      * @param optionalfeatures list of optional features to be installed
257      * @param verificationListener install verification listener
258      * @param monitor install monitor, can be <code>null</code>
259      * @exception InstallAbortedException when the user cancels the install
260      * @exception CoreException
261      * @since 2.0 
262      */
263     public IFeatureReference install(IFeature feature, IFeatureReference[] optionalfeatures, IVerificationListener verificationListener, IProgressMonitor monitor) throws InstallAbortedException, CoreException;
264 
265     /**
266      * Removes (uninstalls) the specified feature from this site. This method
267      * takes into account plug-in entries referenced by the specified fetaure
268      * that continue to be required by other features installed on this site.
269      * 
270      * @param feature feature to remove
271      * @param monitor progress monitor
272      * @exception CoreException
273      * @since 2.0 
274      */
275     public void remove(IFeature feature, IProgressMonitor monitor) throws CoreException;
276 
277     /**
278      * Sets the site content provider. This is typically performed
279      * as part of the site creation operation. Once set, the 
280      * provider should not be reset.
281      * 
282      * @param siteContentProvider site content provider
283      * @since 2.0
284      */
285     public void setSiteContentProvider(ISiteContentProvider siteContentProvider);
286 
287     /** 
288      * Returns the <code>IConfiguredSite</code> for this site in the current 
289      * configuration or <code>null</code> if none found.
290      * 
291      * @since 2.0.2
292      */
293     public IConfiguredSite getCurrentConfiguredSite();
294 
295     /**
296     * Creates a new feature object. The feature must exist on this site
297     * or a core exception will be thrown. Concrete implementations 
298     * may elect to cache instances, in which case subsequent calls 
299     * to create a feature with the same URL will
300     * return the same instance.
301     * param type the feature type that will be used to select the factory. If
302     * <code>null</code> is passed, default feature type will be used.
303     * param url URL of the feature archive as listed in the site.
304     * return newly created feature object, or a cached value if
305     * caching is implemented by this site.
306     * @deprecated use createFeature(String,URL,IProgressMonitor) instead
307     * @since 2.0.2
308     */
309     IFeature createFeature(String   type, URL url) throws CoreException;
310 
311     /**
312     * Creates a new feature object. The feature must exist on this site
313     * or a core exception will be thrown. Concrete implementations 
314     * may elect to cache instances, in which case subsequent calls 
315     * to create a feature with the same URL will
316     * return the same instance.
317     * param type the feature type that will be used to select the factory. If
318     * <code>null</code> is passed, default feature type will be used.
319     * param url URL of the feature archive as listed in the site.
320     * return newly created feature object, or a cached value if
321     * caching is implemented by this site.
322     * @param monitor the progress monitor
323     * @since 2.1
324     */
325     IFeature createFeature(String   type, URL url,IProgressMonitor monitor) throws CoreException;
326 
327 
328 }
329
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags