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