001: /*******************************************************************************
002: * Copyright (c) 2006, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.navigator;
011:
012: import java.util.Set;
013:
014: import org.eclipse.jface.viewers.ITreeContentProvider;
015:
016: /**
017: *
018: * A pipelined content provider allows an extension to reshape the contributions
019: * of an upstream content extension.
020: *
021: * <p>
022: * An "upstream" extension is either:
023: * <ul>
024: * <li> the extension overridden by this extension using the
025: * <b>org.eclipse.ui.navigatorContent/navigatorContent/override</b> element, or
026: * </li>
027: * <li>another extension that overrides the same extension this extension
028: * overrides, but with higher priority than this extension. </li>
029: * </ul>
030: * </p>
031: * <p>
032: * Overridden extensions form a tree where the nodes of the tree represent the
033: * content extensions, children represent overridding extensions, and the
034: * children are sorted by priority. Pipeline contributions traverse the tree,
035: * allowing children to override the contributions of their parent, giving
036: * precedence to the children of highest priority.
037: * </p>
038: *
039: * <p>
040: * Clients may (but are not required to) implement this interface if there is no
041: * cause to do so. {@link ITreeContentProvider} is respected by the Common
042: * Navigator.
043: * </p>
044: *
045: * @see INavigatorPipelineService
046: * @see INavigatorContentService#getPipelineService()
047: * @since 3.2
048: *
049: */
050: public interface IPipelinedTreeContentProvider extends
051: ICommonContentProvider {
052:
053: /**
054: * Intercept the children that would be contributed to the viewer and
055: * determine how to change the shape of those children. The set of children
056: * should be modified to contain the correct children to return to the
057: * viewer.
058: *
059: *
060: * @param aParent
061: * A parent from the viewer
062: * @param theCurrentChildren
063: * The set of children contributed thus far from upstream content
064: * providers.
065: */
066: void getPipelinedChildren(Object aParent, Set theCurrentChildren);
067:
068: /**
069: * Intercept the elements that would be contributed to the root of the
070: * viewer and determine how to change the shape of those children. The given
071: * set of elements should be modified to contain the correct elements to
072: * return to the viewer.
073: *
074: * @param anInput
075: * An input from the viewer
076: * @param theCurrentElements
077: * The set of children contributed thus far from upstream content
078: * providers.
079: */
080: void getPipelinedElements(Object anInput, Set theCurrentElements);
081:
082: /**
083: * Intercept requests for a parent of the given object.
084: *
085: * @param anObject
086: * The object being queried for a parent.
087: * @param aSuggestedParent
088: * The parent already suggested from upstream extensions.
089: * @return The intended parent from this pipelined content provider.
090: */
091: Object getPipelinedParent(Object anObject, Object aSuggestedParent);
092:
093: /**
094: * Intercept attempts to add elements directly to the viewer.
095: *
096: * <p>
097: * For content extensions that reshape the structure of children in a
098: * viewer, their overridden extensions may sometimes use optimized refreshes
099: * to add elements to the tree. These attempts must be intercepted and
100: * mapped to the correct set of model elements in the overridding extension.
101: * Clients may add, remove, or modify elements in the given set of added
102: * children. Clients should return a set for downstream extensions to
103: * massage further.
104: * </p>
105: * <p>
106: * Clients may change what parent the reshaped elements are added to, so
107: * long as that parent is not the root of the viewer.
108: * </p>
109: * <p>
110: * Clients should never create their own pipeline shape
111: * modifications, but instead return the shape modification that was passed
112: * in with appropriate changes.
113: * </p>
114: * <p>
115: * <b>Clients should not call any of the add, remove, refresh, or update
116: * methods on the viewer from this method or any code invoked by the
117: * implementation of this method.</b>
118: * </p>
119: *
120: * @param anAddModification
121: * The shape modification which contains the current suggested
122: * parent and children. Clients may modify this parameter
123: * directly and return it as the new shape modification.
124: * @return The new shape modification to use. Clients should <b>never</b>
125: * return <b>null</b> from this method.
126: */
127: PipelinedShapeModification interceptAdd(
128: PipelinedShapeModification anAddModification);
129:
130: /**
131: * Intercept attempts to remove elements directly from the viewer.
132: *
133: * <p>
134: * For content extensions that reshape the structure of children in a
135: * viewer, their overridden extensions may sometimes use optimized refreshes
136: * to remove elements to the tree. These attempts must be intercepted and
137: * mapped to the correct set of model elements in the overridding extension.
138: * Clients may add, remove, or modify elements in the given set of removed
139: * children. Clients should return a set for downstream extensions to
140: * massage further.
141: * </p>
142: * <p>
143: * The parent will be <b>null</b> for remove modifications.
144: * <p>
145: * Clients should never create their own pipeline shape
146: * modifications, but instead return the shape modification that was passed
147: * in with appropriate changes.
148: * </p>
149: * <p>
150: * <b>Clients should not call any of the add, remove, refresh, or update
151: * methods on the viewer from this method or any code invoked by the
152: * implementation of this method.</b>
153: * </p>
154: *
155: * @param aRemoveModification
156: * The shape modification which contains the current suggested
157: * parent and children. Clients may modify this parameter
158: * directly and return it as the new shape modification.
159: * @return The new shape modification to use. Clients should <b>never</b>
160: * return <b>null</b> from this method.
161: */
162: PipelinedShapeModification interceptRemove(
163: PipelinedShapeModification aRemoveModification);
164:
165: /**
166: * Intercept calls to viewer <code>refresh()</code> methods.
167: *
168: * <p>
169: * Clients may modify the given update to add or remove the elements to be
170: * refreshed. Clients may return the same instance that was passed in for
171: * the next downstream extension.
172: * </p>
173: *
174: * <p>
175: * <b>Clients should not call any of the add, remove, refresh, or update
176: * methods on the viewer from this method or any code invoked by the
177: * implementation of this method.</b>
178: * </p>
179: *
180: * @param aRefreshSynchronization
181: * The (current) refresh update to execute against the viewer.
182: * @return True if the viewer update was modified.
183: */
184: boolean interceptRefresh(
185: 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(
208: PipelinedViewerUpdate anUpdateSynchronization);
209:
210: }
|