INavigatorContentService


1   /*******************************************************************************
2    * Copyright (c) 2003, 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.ui.navigator;
12  
13  import java.util.Set  ;
14  
15  import org.eclipse.jface.viewers.IContentProvider;
16  import org.eclipse.jface.viewers.ILabelProvider;
17  import org.eclipse.jface.viewers.IStructuredContentProvider;
18  import org.eclipse.jface.viewers.ITreeContentProvider;
19  import org.eclipse.jface.viewers.ViewerSorter;
20  import org.eclipse.ui.IMemento;
21  import org.eclipse.ui.ISaveablesSource;
22  
23  /**
24   * 
25   * Manages content extensions for extensible viewers and provides reusable
26   * services for filters, sorting, the activation of content extensions, and DND.
27   * The service can locate the appropriate providers (for contents or labels) for
28   * an element and provide a ready-to-go {@link ITreeContentProvider} and
29   * {@link ILabelProvider} for viewers that wish to take advantage of the
30   * <b>org.eclipse.ui.navigator.navigatorContent</b> extensions defined for a
31   * particular <i>viewerId</i>.
32   * 
33   * <p>
34   * Clients should create instances of the this class using the factory ({@link NavigatorContentServiceFactory}).
35   * </p>
36   * 
37   * <p>
38   * Clients may contribute logical extensions using
39   * <b>org.eclipse.ui.navigator.navigatorContent</b>. Each extension has three
40   * states which determine whether the extension is used by the content service:
41   * <ul>
42   * <li><a name="visible"><i>visible</i>: If a content extension id matches a
43   * <b>viewerContentBinding</b> for the <i>viewerId</i> of this content
44   * service, then the extension is <i>visible</i>. Visible extensions may only
45   * be configured through <b>viewerContentBinding</b>s. </li>
46   * 
47   * <li><a name="active"><i>active</i>: The active state may be set to a default using the
48   * <i>activeByDefault</i> attribute of <b>navigatorContent</b>. Users may
49   * toggle the <i>active</i> state through the "Available customizations"
50   * dialog. Clients may also configure the active extensions using
51   * {@link INavigatorActivationService#activateExtensions(String[], boolean)} or
52   * {@link INavigatorActivationService#deactivateExtensions(String[], boolean)}
53   * from the {@link #getActivationService() Activation Service} </li>
54   * 
55   * <li><a name="enabled"><i>enabled</i>: An extension is <i>enabled</i> for an element if the
56   * extension contributed that element or if the element is described in the
57   * <i>triggerPoints</i> element of the <b>navigatorContent</b> extension. The
58   * findXXX() methods search for <i>enabled</i> extensions. </li>
59   * </ul>
60   * </p>
61   * <p>
62   * A new instance of the content service should be created for each viewer.
63   * Clients should use {@link #createCommonContentProvider()} and
64   * {@link #createCommonLabelProvider()} for the viewer. Each content service
65   * tracks the viewer it is attached to. Clients may create the content service
66   * with a viewer using ({@link NavigatorContentServiceFactory#createContentService(String)}).
67   * Alternatively, when the content provider is created and set on a viewer,
68   * {@link IContentProvider#inputChanged(org.eclipse.jface.viewers.Viewer, Object, Object)}
69   * will be called and the content provider will update the viewer used by its
70   * backing content service. Therefore, only each content service has exactly one
71   * content provider and one label provider.
72   * </p>
73   * <p>
74   * Extensions may also coordinate their behavior through a
75   * {@link IExtensionStateModel state model}. The state model holds properties
76   * and supports property change listeners. Actions can toggle the setting of
77   * properties and the corresponding content/label providers will respond to
78   * property change event. Each <b>navigatorContent</b> extension has its own
79   * contained state model keyed off of the content extension id.
80   * </p>
81   * <p>
82   * Clients may respond when content extensions are loaded by attaching a
83   * {@link INavigatorContentServiceListener} to the content service.
84   * </p>
85   * <p>
86   * Some extensions may provide content or label providers which implement
87   * {@link IMemento}. Clients must call {@link #restoreState(IMemento)} and
88   * {@link #saveState(IMemento)} at the appropriate times for these extensions to
89   * prepare themselves with the memento.
90   * </p>
91   * <p>
92   * This interface is not intended to be implemented by clients.
93   * </p>
94   * 
95   * @since 3.2
96   * 
97   */
98  public interface INavigatorContentService {
99  
100     /**
101      * Create a Content Provider which will use an enhanced delegation model to
102      * locate extension content providers using this content service for each
103      * element in the tree.
104      * 
105      * <p>
106      * The content provider returned will populate the root of the viewer in one
107      * of two ways.
108      * <p>
109      * In the first approach, the content provider will seek out content
110      * extensions which are bound using a <b>viewerContentBinding</b>. If any
111      * of the found <b>viewerContentBindings</b> declare the <i>isRoot</i>
112      * attribute on as true, then that set of extensions will be consulted for
113      * the root elements of the tree. The input of the viewer will be supplied
114      * to each of their {@link IStructuredContentProvider#getElements(Object)}
115      * methods and aggregate the results for the root of the viewer.
116      * </p>
117      * <p>
118      * In the second approach, if no <b>viewerContentBindings</b> declare
119      * <i>isRoot</i> as true, then all matching extensions are consulted based
120      * on their <b>triggerPoints</b> expression in the <b>navigatorContent</b>
121      * extension. Any matching extensions are then consulted via their
122      * {@link IStructuredContentProvider#getElements(Object)} methods and the
123      * results are aggregated into the root.
124      * </p>
125      * <p>
126      * After the root is populated, the children of each root element are
127      * determined by consulting the source extension and all extension which
128      * describe the element in their <b>triggerPoints</b> expression.
129      * </p>
130      * <p>
131      * If clients wish to use a viewer other than the CommonViewer, then they
132      * are responsible for creating the content provider, and setting it on
133      * their viewer.
134      * </p>
135      * 
136      * @return An enhanced content provider that will use this content service
137      *         to drive the viewer.
138      */
139     ITreeContentProvider createCommonContentProvider();
140 
141     /**
142      * Create a Label Provider which will use an enhanced delegation model to
143      * locate extension label providers using this content service for each
144      * element in the tree.
145      * 
146      * <p>
147      * The label of each element is determined by consulting the source of the
148      * element. If the source chooses to return null, then other extensions
149      * which declare the element in their <b>triggerPoints</b> extension are
150      * consulted. The first non-null value is used (including the empty label).
151      * </p>
152      * 
153      * <p>
154      * If clients wish to use a viewer other than the CommonViewer, then they
155      * are responsible for creating the label provider, and setting it on their
156      * viewer.
157      * </p>
158      * 
159      * @return An enhanced label provider that will use this content service to
160      *         drive labels in the viewer.
161      */
162     ILabelProvider createCommonLabelProvider();
163 
164     /**
165      * 
166      * @return The description provider for this content service.
167      */
168     IDescriptionProvider createCommonDescriptionProvider();
169 
170     /**
171      * The state model stores properties associated with the extension. Each
172      * content extension has its own contained state model. Components of the
173      * extension (content provider, label provider, action providers, etc) may
174      * attach themselves as listeners to the model ({@link IExtensionStateModel#addPropertyChangeListener(org.eclipse.jface.util.IPropertyChangeListener)})
175      * and respond to changes to the values of the properties.
176      * 
177      * @param anExtensionId
178      *            The extension id defined by a <b>navigatorContent</b>
179      *            extension.
180      * @return The state model for the given extension id.
181      */
182     IExtensionStateModel findStateModel(String   anExtensionId);
183 
184     /**
185      * The viewer id is used to locate matching <b>viewerContentBindings</b>.
186      * In general, this would be the id of the view defined by a
187      * <b>org.eclipse.ui.views</b> extension. However, there is no formal
188      * requirement that this is the case.
189      * 
190      * @return The viewerId used to create this content service.
191      */
192     String   getViewerId();
193 
194     /**
195      * The viewer descriptor provides some basic information about the abstract
196      * viewer that uses this content service.
197      * 
198      * @return The viewer descriptor for this content service.
199      * @see INavigatorViewerDescriptor
200      */
201     INavigatorViewerDescriptor getViewerDescriptor();
202 
203     /**
204      * See <a HREF="#active">above</a> for the definition of <i>active</i>.
205      * 
206      * @param anExtensionId
207      *            The unqiue identifier from a content extension.
208      * @return True if and only if the given extension id is <i>active</i> for
209      *         this content service.
210      * @see INavigatorContentService For more information on what <i>active</i>
211      *      means.
212      * 
213      */
214     boolean isActive(String   anExtensionId);
215 
216     /**
217      *  See <a HREF="#visible">above</a> for the definition of <i>visible</i>.
218      *  
219      * @param anExtensionId
220      *            The unqiue identifier from a content extension.
221      * @return True if and only if the given extension id is <i>visible</i> to
222      *         this content service.
223      * @see INavigatorContentService For more information on what <i>visible</i>
224      *      means.
225      */
226     boolean isVisible(String   anExtensionId);
227 
228     /**
229      * Return the set of <i>visible</i> extension ids for this content service,
230      * which includes those that are bound through <b>viewerContentBinding</b>s
231      * and those that are bound through
232      * {@link #bindExtensions(String[], boolean)}.
233      * 
234      * @return The set of <i>visible</i> extension ids for this content service
235      */
236     String  [] getVisibleExtensionIds();
237 
238     /**
239      * Return the set of <i>visible</i> content descriptors for this content
240      * service, which includes those that are bound through
241      * <b>viewerContentBinding</b>s and those that are bound through
242      * {@link #bindExtensions(String[], boolean)}.
243      * 
244      * @return The set of <i>visible</i> content descriptors for this content
245      *         service
246      */
247     INavigatorContentDescriptor[] getVisibleExtensions();
248 
249     /**
250      * Bind the set of given extensions to this content service. Programmatic
251      * bindings allow clients to make extensions <i>visible</i> to an instance
252      * of the content service by appending to the bindings declared through
253      * <b>org.eclipse.ui.navigator.viewer</b>. Programmtic bindings are not
254      * persisted and are not remembered or propagated to other instances of the
255      * INavigatorContentService in the same session. Programmatic bindings
256      * cannot be undone for a given instance of the INavigatorContentService and
257      * do not override declarative bindings.
258      * <p>
259      * Once a content extension has been bound to the INavigatorContentService,
260      * clients may use
261      * {@link INavigatorActivationService#activateExtensions(String[], boolean) }
262      * or
263      * {@link  INavigatorActivationService#deactivateExtensions(String[], boolean) }
264      * to control the <i>activation</i> state of the extension. See
265      * {@link INavigatorContentService} for more information on the difference
266      * between <i>visible</i> and <i>active</i>.
267      * </p>
268      * 
269      * @param extensionIds
270      *            The list of extensions to make visible.
271      * @param isRoot
272      *            whether the context provider shold be a root content provider
273      * @return A list of all INavigatorContentDescriptors that correspond to the
274      *         given extensionIds.
275      */
276     INavigatorContentDescriptor[] bindExtensions(String  [] extensionIds,
277             boolean isRoot);
278 
279     /**
280      * Restore the state associated with the memento.
281      * 
282      * @param aMemento
283      *            The memento for extensions to use when restoring previous
284      *            settings.
285      */
286     void restoreState(IMemento aMemento);
287 
288     /**
289      * Persist any session-to-session state with the memento.
290      * 
291      * @param aMemento
292      *            The memento for extensions to use when persisting previous
293      *            settings.
294      */
295     void saveState(IMemento aMemento);
296 
297     /**
298      * Add a listener to be notified whenever an extension is loaded.
299      * 
300      * @param aListener
301      *            A listener to be attached.
302      */
303     void addListener(INavigatorContentServiceListener aListener);
304 
305     /**
306      * Remove a listener (by identity) from the set of listeners.
307      * 
308      * @param aListener
309      *            A listener to be detached.
310      */
311     void removeListener(INavigatorContentServiceListener aListener);
312 
313     /**
314      * The root content providers are recalculated by this method. The attached
315      * viewer is also refreshed as a result of this method.
316      * 
317      */
318     void update();
319 
320     /**
321      * Release any acquired resources and instantiated content extensions.
322      * 
323      */
324     void dispose();
325 
326     /**
327      * Search for extensions that declare the given element in their
328      * <b>triggerPoints</b> expression or that indicate they should be bound as
329      * a root extension.
330      * 
331      * @param anElement
332      *            The element to use in the query
333      * @return The set of {@link INavigatorContentExtension}s that are
334      *         <i>visible</i> and <i>active</i> for this content service and
335      *         either declared through a
336      *         <b>org.eclipse.ui.navigator.viewer/viewerContentBinding</b> to
337      *         be a root element or have a <b>triggerPoints</b> expression that
338      *         is <i>enabled</i> for the given element.
339      */
340     Set   findRootContentExtensions(Object   anElement);
341 
342     /**
343      * Search for extensions that declare the given element in their
344      * <b>triggerPoints</b> expression.
345      * 
346      * @param anElement
347      *            The element to use in the query
348      * @return The set of {@link INavigatorContentExtension}s that are
349      *         <i>visible</i> and <i>active</i> for this content service and
350      *         have a <b>triggerPoints</b> expression that is <i>enabled</i>
351      *         for the given element.
352      */
353     Set   findContentExtensionsByTriggerPoint(Object   anElement);
354 
355     /**
356      * Search for extensions that declare the given element in their
357      * <b>possibleChildren</b> expression.
358      * 
359      * @param anElement
360      *            The element to use in the query
361      * @return The set of {@link INavigatorContentExtension}s that are
362      *         <i>visible</i> and <i>active</i> for this content service and
363      *         have a <b>possibleChildren</b> expression that is <i>enabled</i>
364      *         for the given element.
365      */
366     Set   findContentExtensionsWithPossibleChild(Object   anElement);
367 
368     /**
369      * The filter service can provide the available filters for the viewer, and
370      * manage which filters are <i>active</i>.
371      * 
372      * @return An {@link INavigatorFilterService} that can provide information
373      *         to a viewer about what filters are <i>visible</i> and <i>active</i>.
374      */
375     INavigatorFilterService getFilterService();
376 
377     /**
378      * The sorter service provides the appropriate sorter based on the current
379      * items being sorted. By default, the CommonViewer uses
380      * {@link CommonViewerSorter} which delegates to this service. Clients do
381      * not need to provide their own {@link ViewerSorter} unless they wish to
382      * override this functionality.
383      * 
384      * @return An {@link INavigatorSorterService} that can provide
385      *         {@link ViewerSorter} based on the context of the parent.
386      */
387     INavigatorSorterService getSorterService();
388 
389     /**
390      * The pipeline service calculates the appropriate viewer modification or
391      * refresh that should be applied for viewers that wish to take advantage of
392      * the model pipelining that some extensions use to massage or reshape
393      * contents in the viewer. Clients that use the {@link CommonViewer} do not
394      * need to be concerned with this service as the refreshes are automatically
395      * computed using this service.
396      * 
397      * 
398      * @return The {@link INavigatorPipelineService} which can determine the
399      *         correct updates to apply to a viewer.
400      */
401     INavigatorPipelineService getPipelineService();
402 
403     /**
404      * The DND Service provides instances of {@link CommonDragAdapterAssistant}
405      * and {@link CommonDropAdapterAssistant} for this content service.
406      * 
407      * @return The {@link INavigatorDnDService} which can add additional
408      *         TransferTypes for the DragAdapter and setup the data correctly
409      *         for those extended Transfer Types.
410      */
411     INavigatorDnDService getDnDService();
412 
413     /**
414      * The activation service is used to toggle whether certain extensions have
415      * the opportunity to contribute content and/or actions.
416      * 
417      * @return The {@link INavigatorActivationService} for this content service.
418      */
419     INavigatorActivationService getActivationService();
420     
421     /**
422      * The saveable service helps implementing {@link ISaveablesSource}.
423      * 
424      * @return the {@link INavigatorSaveablesService} for this content service.
425      */
426     INavigatorSaveablesService getSaveablesService();
427     
428     /** 
429      * Return the content extension for the given id. 
430      * 
431      * @param anExtensionId The id used to define the <b>org.eclipse.ui.navigator.navigatorContent/navigatorContent</b> extension.
432      * @return An instance of the content extension for the given extension id. May return <b>null</b> if the id is invalid.
433      */
434     public INavigatorContentExtension getContentExtensionById(String   anExtensionId);
435     
436     /** 
437      * Return the content extension for the given id. 
438      * 
439      * @param anExtensionId The id used to define the <b>org.eclipse.ui.navigator.navigatorContent/navigatorContent</b> extension.
440      * @return An instance of the content extension for the given extension id. May return <b>null</b> if the id is invalid.
441      * @since 3.3
442      */
443     public INavigatorContentDescriptor getContentDescriptorById(String   anExtensionId);
444 
445 
446 
447 }
448
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags