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 /** 18 * 19 * Performs calculations that are necessary to determine the correct children to 20 * render in the viewer. 21 * 22 * @see INavigatorContentService#getPipelineService() 23 * @see PipelinedShapeModification 24 * @see PipelinedViewerUpdate 25 * @see IPipelinedTreeContentProvider 26 * 27 * @noimplement This interface is not intended to be implemented by clients. 28 * @noextend This interface is not intended to be extended by clients. 29 * @since 3.2 30 */ 31 public interface INavigatorPipelineService { 32 33 /** 34 * Intercept attempts to add elements directly to the viewer. 35 * 36 * <p> 37 * For content extensions that reshape the structure of children in a 38 * viewer, their overridden extensions may sometimes use optimized refreshes 39 * to add elements to the tree. These attempts must be intercepted and 40 * mapped to the correct set of model elements in the overriding extension. 41 * Clients may add, remove, or modify elements in the given set of added 42 * children. Clients should return a set for downstream extensions to 43 * massage further. 44 * </p> 45 * <p> 46 * <b>Clients should not call any of the add, remove, refresh, or update 47 * methods on the viewer from this method or any code invoked by the 48 * implementation of this method.</b> 49 * </p> 50 * 51 * @param anAddModification 52 * The shape modification which contains the current suggested 53 * parent and children. Clients may modify this parameter 54 * directly and return it as the new shape modification. 55 * @return The new shape modification to use. Clients should <b>never</b> 56 * return <b>null</b> from this method. 57 */ interceptAdd( PipelinedShapeModification anAddModification)58 public PipelinedShapeModification interceptAdd( 59 PipelinedShapeModification anAddModification); 60 61 /** 62 * Intercept attempts to remove elements directly from the viewer. 63 * 64 * <p> 65 * For content extensions that reshape the structure of children in a 66 * viewer, their overridden extensions may sometimes use optimized refreshes 67 * to remove elements to the tree. These attempts must be intercepted and 68 * mapped to the correct set of model elements in the overriding extension. 69 * Clients may add, remove, or modify elements in the given set of removed 70 * children. Clients should return a set for downstream extensions to 71 * massage further. 72 * </p> 73 * <p> 74 * <b>Clients should not call any of the add, remove, refresh, or update 75 * methods on the viewer from this method or any code invoked by the 76 * implementation of this method.</b> 77 * </p> 78 * 79 * @param aRemoveModification 80 * The shape modification which contains the current suggested 81 * parent and children. Clients may modify this parameter 82 * directly and return it as the new shape modification. 83 * @return The new shape modification to use. Clients should <b>never</b> 84 * return <b>null</b> from this method. 85 */ interceptRemove( PipelinedShapeModification aRemoveModification)86 public PipelinedShapeModification interceptRemove( 87 PipelinedShapeModification aRemoveModification); 88 89 /** 90 * Intercept calls to viewer <code>refresh()</code> methods. 91 * 92 * <p> 93 * Clients may modify the given update to add or remove the elements to be 94 * refreshed. Clients may return the same instance that was passed in for 95 * the next downstream extension. 96 * </p> 97 * 98 * <p> 99 * <b>Clients should not call any of the add, remove, refresh, or update 100 * methods on the viewer from this method or any code invoked by the 101 * implementation of this method.</b> 102 * </p> 103 * 104 * @param aRefreshSynchronization 105 * The (current) refresh update to execute against the viewer. 106 * @return The (potentially reshaped) refresh to execute against the viewer. 107 */ interceptRefresh(PipelinedViewerUpdate aRefreshSynchronization)108 boolean interceptRefresh(PipelinedViewerUpdate aRefreshSynchronization); 109 110 /** 111 * Intercept calls to viewer <code>update()</code> methods. 112 * 113 * <p> 114 * Clients may modify the given update to add or remove the elements to be 115 * updated. Clients may also add or remove properties for the given targets 116 * to optimize the refresh. Clients may return the same instance that was 117 * passed in for the next downstream extension. 118 * </p> 119 * 120 * <p> 121 * <b>Clients should not call any of the add, remove, refresh, or update 122 * methods on the viewer from this method or any code invoked by the 123 * implementation of this method.</b> 124 * </p> 125 * 126 * @param anUpdateSynchronization 127 * The (current) update to execute against the viewer. 128 * @return The (potentially reshaped) update to execute against the viewer. 129 */ interceptUpdate( PipelinedViewerUpdate anUpdateSynchronization)130 public boolean interceptUpdate( 131 PipelinedViewerUpdate anUpdateSynchronization); 132 133 } 134