1 /******************************************************************************* 2 * Copyright (c) 2006, 2015 IBM Corporation and others. 3 * 4 * This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License 2.0 6 * which accompanies this distribution, and is available at 7 * https://www.eclipse.org/legal/epl-2.0/ 8 * 9 * SPDX-License-Identifier: EPL-2.0 10 * 11 * Contributors: 12 * IBM Corporation - initial API and implementation 13 *******************************************************************************/ 14 15 package org.eclipse.ui.navigator; 16 17 import java.util.Set; 18 19 /** 20 * 21 * To correctly implement pipelining you should implement 22 * {@link IPipelinedTreeContentProvider2} which provides the 23 * additional 24 * {@link IPipelinedTreeContentProvider2#hasChildren(Object)} method. 25 * This allows the calculation of hasChildren to match what will be provided in 26 * calculating the children. If you don't implement the hasChildren, you may get 27 * "false positive" hasChildrens which will result in a "+" indication in the 28 * tree in the event that the pipelined children calculation. 29 * 30 * The only reason these are two separate interfaces is historical. 31 * 32 * @since 3.2 33 * 34 */ 35 public interface IPipelinedTreeContentProvider extends ICommonContentProvider { 36 37 /** 38 * Intercept the children that would be contributed to the viewer and 39 * determine how to change the shape of those children. The set of children 40 * should be modified to contain the correct children to return to the 41 * viewer. 42 * 43 * @param aParent 44 * A parent from the viewer 45 * @param theCurrentChildren 46 * The set of children contributed thus far from upstream content 47 * providers. 48 */ getPipelinedChildren(Object aParent, Set theCurrentChildren)49 void getPipelinedChildren(Object aParent, Set theCurrentChildren); 50 51 /** 52 * Intercept the elements that would be contributed to the root of the 53 * viewer and determine how to change the shape of those children. The given 54 * set of elements should be modified to contain the correct elements to 55 * return to the viewer. 56 * 57 * @param anInput 58 * An input from the viewer 59 * @param theCurrentElements 60 * The set of children contributed thus far from upstream content 61 * providers. 62 */ getPipelinedElements(Object anInput, Set theCurrentElements)63 void getPipelinedElements(Object anInput, Set theCurrentElements); 64 65 /** 66 * Intercept requests for a parent of the given object. 67 * 68 * @param anObject 69 * The object being queried for a parent. 70 * @param aSuggestedParent 71 * The parent already suggested from upstream extensions. 72 * @return The intended parent from this pipelined content provider. If you 73 * wish to not influence the parent, then return the 74 * aSuggestedParent value. 75 */ getPipelinedParent(Object anObject, Object aSuggestedParent)76 Object getPipelinedParent(Object anObject, Object aSuggestedParent); 77 78 /** 79 * Intercept attempts to add elements directly to the viewer. 80 * 81 * <p> 82 * For content extensions that reshape the structure of children in a 83 * viewer, their overridden extensions may sometimes use optimized refreshes 84 * to add elements to the tree. These attempts must be intercepted and 85 * mapped to the correct set of model elements in the overriding extension. 86 * Clients may add, remove, or modify elements in the given set of added 87 * children. Clients should return a set for downstream extensions to 88 * massage further. 89 * </p> 90 * <p> 91 * Clients may change what parent the reshaped elements are added to, so 92 * long as that parent is not the root of the viewer. 93 * </p> 94 * <p> 95 * Clients should never create their own pipeline shape modifications, but 96 * instead return the shape modification that was passed in with appropriate 97 * changes. 98 * </p> 99 * <p> 100 * <b>Clients should not call any of the add, remove, refresh, or update 101 * methods on the viewer from this method or any code invoked by the 102 * implementation of this method.</b> 103 * </p> 104 * 105 * @param anAddModification 106 * The shape modification which contains the current suggested 107 * parent and children. Clients may modify this parameter 108 * directly and return it as the new shape modification. 109 * @return The new shape modification to use. Clients should <b>never</b> 110 * return <b>null</b> from this method. 111 */ interceptAdd(PipelinedShapeModification anAddModification)112 PipelinedShapeModification interceptAdd(PipelinedShapeModification anAddModification); 113 114 /** 115 * Intercept attempts to remove elements directly from the viewer. 116 * 117 * <p> 118 * For content extensions that reshape the structure of children in a 119 * viewer, their overridden extensions may sometimes use optimized refreshes 120 * to remove elements to the tree. These attempts must be intercepted and 121 * mapped to the correct set of model elements in the overriding extension. 122 * Clients may add, remove, or modify elements in the given set of removed 123 * children. Clients should return a set for downstream extensions to 124 * massage further. 125 * </p> 126 * <p> 127 * The parent will be <b>null</b> for remove modifications. 128 * <p> 129 * Clients should never create their own pipeline shape modifications, but 130 * instead return the shape modification that was passed in with appropriate 131 * changes. 132 * </p> 133 * <p> 134 * <b>Clients should not call any of the add, remove, refresh, or update 135 * methods on the viewer from this method or any code invoked by the 136 * implementation of this method.</b> 137 * </p> 138 * 139 * @param aRemoveModification 140 * The shape modification which contains the current suggested 141 * parent and children. Clients may modify this parameter 142 * directly and return it as the new shape modification. 143 * @return The new shape modification to use. Clients should <b>never</b> 144 * return <b>null</b> from this method. 145 */ interceptRemove(PipelinedShapeModification aRemoveModification)146 PipelinedShapeModification interceptRemove(PipelinedShapeModification aRemoveModification); 147 148 /** 149 * Intercept calls to viewer <code>refresh()</code> methods. 150 * 151 * <p> 152 * Clients may modify the given update to add or remove the elements to be 153 * refreshed. Clients may return the same instance that was passed in for 154 * the next downstream extension. 155 * </p> 156 * 157 * <p> 158 * <b>Clients should not call any of the add, remove, refresh, or update 159 * methods on the viewer from this method or any code invoked by the 160 * implementation of this method.</b> 161 * </p> 162 * 163 * @param aRefreshSynchronization 164 * The (current) refresh update to execute against the viewer. 165 * @return True if the viewer update was modified. 166 */ interceptRefresh(PipelinedViewerUpdate aRefreshSynchronization)167 boolean interceptRefresh(PipelinedViewerUpdate aRefreshSynchronization); 168 169 /** 170 * Intercept calls to viewer <code>update()</code> methods. 171 * 172 * <p> 173 * Clients may modify the given update to add or remove the elements to be 174 * updated. Clients may also add or remove properties for the given targets 175 * to optimize the refresh. Clients may return the same instance that was 176 * passed in for the next downstream extension. 177 * </p> 178 * 179 * <p> 180 * <b>Clients should not call any of the add, remove, refresh, or update 181 * methods on the viewer from this method or any code invoked by the 182 * implementation of this method.</b> 183 * </p> 184 * 185 * @param anUpdateSynchronization 186 * The (current) update to execute against the viewer. 187 * @return True if the viewer update was modified. 188 */ interceptUpdate(PipelinedViewerUpdate anUpdateSynchronization)189 boolean interceptUpdate(PipelinedViewerUpdate anUpdateSynchronization); 190 191 } 192