KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > update > core > IFeatureContentProvider


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
13 import java.net.URL JavaDoc;
14
15 import org.eclipse.core.runtime.CoreException;
16
17 /**
18  * Feature content provider.
19  * A feature content provider is an abstraction of each feature internal
20  * packaging structure. It allows the feature content to be accessed in
21  * a standard way regardless of the internal packaging. All concrete feature
22  * implementations need to implement a feature content provider.
23  * <p>
24  * There are two ways of looking at a feature content:
25  * <ol>
26  * <li>the "logical" view, which is a representation of the actual files that
27  * make up the feature. These include any files that describe the feature
28  * itself, files that are the actual implementation of referenced plug-ins,
29  * and files that are the non-plug-in data files associated with the feature
30  * <li>the "packaged" view, which is a set of related archive files that
31  * contain the "logical" files.
32  * </ol>
33  * It is the responsibility of a feature content provider to manage the
34  * mapping between the "packaged" and "logical" views.
35  * </p>
36  * <p>
37  * Clients may implement this interface. However, in most cases clients should
38  * directly instantiate or subclass the provided implementation of this
39  * interface.
40  * </p>
41  * <p>
42  * <b>Note:</b> This class/interface is part of an interim API that is still under development and expected to
43  * change significantly before reaching stability. It is being made available at this early stage to solicit feedback
44  * from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken
45  * (repeatedly) as the API evolves.
46  * </p>
47  * @see org.eclipse.update.core.FeatureContentProvider
48  * @since 2.0
49  */
50 public interface IFeatureContentProvider {
51
52     /**
53      * Returns the feature url.
54      * The exact interpretation of this URL is specific to each content
55      * provider. Typically, the URL is a reference to a file that can be
56      * used directly, or indirectly, to determine the content of the feature.
57      *
58      * @return feature url
59      * @since 2.0
60      */
61     public URL JavaDoc getURL();
62
63     /**
64      * Returns a content reference to the feature manifest. The feature manifest
65      * is an xml file, whose format is specified by the platform. Typically
66      * a feature will contain the manifest as one of the packaged files.
67      * For features that do not contain the manifest, or contain a manifest
68      * that does not follow the specified format, this method returns
69      * a reference to a computed manifest in the appropriate platform
70      * format.
71      *
72      * @param monitor progress monitor, can be <code>null</code>
73      * @return feature manifest reference, or <code>null</code> if the manifest cannot be found.
74      * @since 2.0
75      */
76     public ContentReference getFeatureManifestReference(InstallMonitor monitor)
77         throws CoreException;
78
79     /**
80      * Returns an array of content references of all the "packaged"
81      * archives that make up this feature.
82      * <p>
83      * The number of returned references is dependent on each feature
84      * content provider (i.e is dependent on the packaging mechanism used
85      * by the particular feature type).
86      * </p>
87      *
88      * @param monitor progress monitor, can be <code>null</code>
89      * @return an array of references, or an empty array if no references
90      * are found
91      * @exception CoreException
92      * @since 2.0
93      */
94     public ContentReference[] getArchiveReferences(InstallMonitor monitor)
95         throws CoreException;
96
97     /**
98      * Returns an array of content references of the "packaged"
99      * archives that contain the feature descriptive information.
100      * <p>
101      * In general, the feature descriptive information should be packaged
102      * separately from the "bulk" of the actual feature content.
103      * The feature entry archive(s) must be downloaded from an update
104      * site in order to present information about the feature to the
105      * client. Consequently, keeping the number and size of the feature
106      * entry archive(s) to a minimum will speed up the responsiveness of the
107      * user interface.
108      * </p>
109      * <p>
110      * The number of returned references is dependent on each feature
111      * content provider (i.e is dependent on the packaging mechanism used
112      * by the particular feature type).
113      * </p>
114      *
115      * @see IFeatureContentProvider#getFeatureEntryContentReferences(InstallMonitor)
116      * @param monitor progress monitor, can be <code>null</code>
117      * @return an array of references, or an empty array if no references
118      * are found
119      * @exception CoreException
120      * @since 2.0
121      */
122     public ContentReference[] getFeatureEntryArchiveReferences(InstallMonitor monitor)
123         throws CoreException;
124
125     /**
126      * Returns an array of content references of the "packaged"
127      * archives that contain the files for the specified plug-in entry.
128      * <p>
129      * The number of returned references is dependent on each feature
130      * content provider (i.e is dependent on the packaging mechanism used
131      * by the particular feature type).
132      * </p>
133      *
134      * @see IFeatureContentProvider#getPluginEntryContentReferences(IPluginEntry, InstallMonitor)
135      * @param pluginEntry plug-in entry
136      * @param monitor progress monitor, can be <code>null</code>
137      * @return an array of references, or an empty array if no references
138      * are found
139      * @exception CoreException
140      * @since 2.0
141      */
142     public ContentReference[] getPluginEntryArchiveReferences(
143         IPluginEntry pluginEntry,
144         InstallMonitor monitor)
145         throws CoreException;
146
147     /**
148      * Returns an array of content references of the "packaged"
149      * archives that contain the files for the specified non-plug-in entry.
150      * <p>
151      * The number of returned references is dependent on each feature
152      * content provider (i.e is dependent on the packaging mechanism used
153      * by the particular feature type).
154      * </p>
155      * <p>
156      * Note, that the platform does not interpret non-plug-in entries in any
157      * way, other that performing any required downloads. Non-plug-in entries
158      * are handled by custom install handlers that must be specified for
159      * the feature. Consequently, this interface does not make a distinction
160      * between the "logical" and "packaged" views for non-plug-in entries.
161      * The "packaged" view (returning references to the non-plug-in archives)
162      * is the only one supported. It is the responsibility of the custom install
163      * handler to understand the "logical" view of non-plug-in archives.
164      * </p>
165      *
166      * @param monitor progress monitor, can be <code>null</code>
167      * @return an array of references, or an empty array if no references
168      * are found
169      * @exception CoreException
170      * @since 2.0
171      */
172     public ContentReference[] getNonPluginEntryArchiveReferences(
173         INonPluginEntry nonPluginEntry,
174         InstallMonitor monitor)
175         throws CoreException;
176
177     /**
178      * Returns an array of content references to the feature definition files
179      * (i.e the "logical" view of the files defining the feature). These
180      * are the files required to present information about the feature to the
181      * client, and in general, should not contain references to plug-in and
182      * non-plug-in files.
183      *
184      * @see IFeatureContentProvider#getFeatureEntryArchiveReferences(InstallMonitor)
185      * @param monitor progress monitor, can be <code>null</code>
186      * @return an array of ContentReference or an empty array if no references are found
187      * @exception CoreException when an error occurs
188      * @since 2.0
189      */
190     public ContentReference[] getFeatureEntryContentReferences(InstallMonitor monitor)
191         throws CoreException;
192
193     /**
194      * Returns an array of content references to the files implementing
195      * the specified plug-in. (i.e the "logical" view of the plug-in).
196      *
197      * @see IFeatureContentProvider#getPluginEntryArchiveReferences(IPluginEntry, InstallMonitor)
198      * @param monitor progress monitor, can be <code>null</code>
199      * @return an array of ContentReference or an empty array if no references are found
200      * @exception CoreException
201      * @since 2.0
202      */
203     public ContentReference[] getPluginEntryContentReferences(
204         IPluginEntry pluginEntry,
205         InstallMonitor monitor)
206         throws CoreException;
207
208     /**
209      * Returns the total size of all archives required for the
210      * specified plug-in and non-plug-in entries (the "packaging" view).
211      *
212      * @param pluginEntries an array of plug-in entries
213      * @param nonPluginEntries an array of non-plug-in entries
214      * @return total download size, or an indication that size could not be
215      * determined
216      * @see org.eclipse.update.core.model.ContentEntryModel#UNKNOWN_SIZE
217      * @since 2.0
218      */
219     public long getDownloadSizeFor(
220         IPluginEntry[] pluginEntries,
221         INonPluginEntry[] nonPluginEntries);
222
223     /**
224      * Returns the total size of all files required for the
225      * specified plug-in and non-plug-in entries (the "logical" view).
226      *
227      * @param pluginEntries an array of plug-in entries
228      * @param nonPluginEntries an array of non-plug-in entries
229      * @return total download size, or an indication that size could not be
230      * determined
231      * @see org.eclipse.update.core.model.ContentEntryModel#UNKNOWN_SIZE
232      * @since 2.0
233      */
234     public long getInstallSizeFor(
235         IPluginEntry[] pluginEntries,
236         INonPluginEntry[] nonPluginEntries);
237
238     /**
239      * Returns the verifier for this feature.
240      * If provided, the verifier is called at various point during
241      * installation processing to verify downloaded archives. The
242      * type of verification provided is dependent on the content
243      * provider implementation.
244      *
245      * @return verifier
246      * @exception CoreException
247      * @since 2.0
248      */
249     public IVerifier getVerifier() throws CoreException;
250
251     /**
252      * Returns the feature associated with this content provider.
253      *
254      * @return feature for this content provider
255      * @since 2.0
256      */
257     public IFeature getFeature();
258
259     /**
260      * Sets the feature associated with this content provider.
261      * In general, this method should only be called as part of
262      * feature creation. Once set, the feature should not be reset.
263      *
264      * @param feature feature for this content provider
265      * @since 2.0
266      */
267     public void setFeature(IFeature feature);
268 }
269
Popular Tags