IPipelinedTreeContentProvider


1   /*******************************************************************************
2    * Copyright (c) 2006, 2007 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  
12  package org.eclipse.ui.navigator;
13  
14  import java.util.Set  ;
15  
16  import org.eclipse.jface.viewers.ITreeContentProvider;
17  
18  /**
19   * 
20   * A pipelined content provider allows an extension to reshape the contributions
21   * of an upstream content extension.
22   * 
23   * <p>
24   * An "upstream" extension is either:
25   * <ul>
26   * <li> the extension overridden by this extension using the
27   * <b>org.eclipse.ui.navigatorContent/navigatorContent/override</b> element, or
28   * </li>
29   * <li>another extension that overrides the same extension this extension
30   * overrides, but with higher priority than this extension. </li>
31   * </ul>
32   * </p>
33   * <p>
34   * Overridden extensions form a tree where the nodes of the tree represent the
35   * content extensions, children represent overridding extensions, and the
36   * children are sorted by priority. Pipeline contributions traverse the tree,
37   * allowing children to override the contributions of their parent, giving
38   * precedence to the children of highest priority.
39   * </p> 
40   * 
41   * <p>
42   * Clients may (but are not required to) implement this interface if there is no
43   * cause to do so. {@link ITreeContentProvider} is respected by the Common
44   * Navigator.
45   * </p>
46   * 
47   * @see INavigatorPipelineService
48   * @see INavigatorContentService#getPipelineService()
49   * @since 3.2
50   * 
51   */
52  public interface IPipelinedTreeContentProvider extends ICommonContentProvider {
53  
54      /**
55       * Intercept the children that would be contributed to the viewer and
56       * determine how to change the shape of those children. The set of children
57       * should be modified to contain the correct children to return to the
58       * viewer.
59       * 
60       * 
61       * @param aParent
62       *            A parent from the viewer
63       * @param theCurrentChildren
64       *            The set of children contributed thus far from upstream content
65       *            providers.
66       */
67      void getPipelinedChildren(Object   aParent, Set   theCurrentChildren);
68  
69      /**
70       * Intercept the elements that would be contributed to the root of the
71       * viewer and determine how to change the shape of those children. The given
72       * set of elements should be modified to contain the correct elements to
73       * return to the viewer.
74       * 
75       * @param anInput
76       *            An input from the viewer
77       * @param theCurrentElements
78       *            The set of children contributed thus far from upstream content
79       *            providers.
80       */
81      void getPipelinedElements(Object   anInput, Set   theCurrentElements);
82  
83      /**
84       * Intercept requests for a parent of the given object.
85       * 
86       * @param anObject
87       *            The object being queried for a parent.
88       * @param aSuggestedParent
89       *            The parent already suggested from upstream extensions.
90       * @return The intended parent from this pipelined content provider.
91       */
92      Object   getPipelinedParent(Object   anObject, Object   aSuggestedParent);
93  
94      /**
95       * Intercept attempts to add elements directly to the viewer.
96       * 
97       * <p>
98       * For content extensions that reshape the structure of children in a
99       * viewer, their overridden extensions may sometimes use optimized refreshes
100      * to add elements to the tree. These attempts must be intercepted and
101      * mapped to the correct set of model elements in the overridding extension.
102      * Clients may add, remove, or modify elements in the given set of added
103      * children. Clients should return a set for downstream extensions to
104      * massage further. 
105      * </p>
106      * <p>
107      * Clients may change what parent the reshaped elements are added to, so
108      * long as that parent is not the root of the viewer.
109      * </p>
110      * <p>
111      * Clients should never create their own pipeline shape
112      * modifications, but instead return the shape modification that was passed
113      * in with appropriate changes.
114      * </p>
115      * <p>
116      * <b>Clients should not call any of the add, remove, refresh, or update
117      * methods on the viewer from this method or any code invoked by the
118      * implementation of this method.</b>
119      * </p>
120      * 
121      * @param anAddModification
122      *            The shape modification which contains the current suggested
123      *            parent and children. Clients may modify this parameter
124      *            directly and return it as the new shape modification.
125      * @return The new shape modification to use. Clients should <b>never</b>
126      *         return <b>null</b> from this method.
127      */
128     PipelinedShapeModification interceptAdd(
129             PipelinedShapeModification anAddModification);
130 
131     /**
132      * Intercept attempts to remove elements directly from the viewer.
133      * 
134      * <p>
135      * For content extensions that reshape the structure of children in a
136      * viewer, their overridden extensions may sometimes use optimized refreshes
137      * to remove elements to the tree. These attempts must be intercepted and
138      * mapped to the correct set of model elements in the overridding extension.
139      * Clients may add, remove, or modify elements in the given set of removed
140      * children. Clients should return a set for downstream extensions to
141      * massage further.
142      * </p>
143      * <p>
144      * The parent will be <b>null</b> for remove modifications.
145      * <p>
146      * Clients should never create their own pipeline shape
147      * modifications, but instead return the shape modification that was passed
148      * in with appropriate changes.
149      * </p>
150      * <p>
151      * <b>Clients should not call any of the add, remove, refresh, or update
152      * methods on the viewer from this method or any code invoked by the
153      * implementation of this method.</b>
154      * </p>
155      * 
156      * @param aRemoveModification
157      *            The shape modification which contains the current suggested
158      *            parent and children. Clients may modify this parameter
159      *            directly and return it as the new shape modification.
160      * @return The new shape modification to use. Clients should <b>never</b>
161      *         return <b>null</b> from this method.
162      */
163     PipelinedShapeModification interceptRemove(
164             PipelinedShapeModification aRemoveModification);
165 
166     /**
167      * Intercept calls to viewer <code>refresh()</code> methods.
168      * 
169      * <p>
170      * Clients may modify the given update to add or remove the elements to be
171      * refreshed. Clients may return the same instance that was passed in for
172      * the next downstream extension.
173      * </p>
174      * 
175      * <p>
176      * <b>Clients should not call any of the add, remove, refresh, or update
177      * methods on the viewer from this method or any code invoked by the
178      * implementation of this method.</b>
179      * </p>
180      * 
181      * @param aRefreshSynchronization
182      *            The (current) refresh update to execute against the viewer.
183      * @return True if the viewer update was modified.
184      */
185     boolean interceptRefresh(PipelinedViewerUpdate aRefreshSynchronization);
186 
187     /**
188      * Intercept calls to viewer <code>update()</code> methods.
189      * 
190      * <p>
191      * Clients may modify the given update to add or remove the elements to be
192      * updated. Clients may also add or remove properties for the given targets
193      * to optimize the refresh. Clients may return the same instance that was
194      * passed in for the next downstream extension.
195      * </p>
196      * 
197      * <p>
198      * <b>Clients should not call any of the add, remove, refresh, or update
199      * methods on the viewer from this method or any code invoked by the
200      * implementation of this method.</b>
201      * </p>
202      * 
203      * @param anUpdateSynchronization
204      *            The (current) update to execute against the viewer.
205      * @return True if the viewer update was modified.
206      */
207     boolean interceptUpdate(PipelinedViewerUpdate anUpdateSynchronization);
208 
209 }
210
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags