001: /*******************************************************************************
002: * Copyright (c) 2006 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: /**
013: *
014: * Performs calculations that are necessary to determine the correct children to
015: * render in the viewer.
016: *
017: * <p>
018: * This interface is not intended to be implemented by clients.
019: * </p>
020: *
021: * @see INavigatorContentService#getPipelineService()
022: * @see PipelinedShapeModification
023: * @see PipelinedViewerUpdate
024: * @see IPipelinedTreeContentProvider
025: * @since 3.2
026: */
027: public interface INavigatorPipelineService {
028:
029: /**
030: * Intercept attempts to add elements directly to the viewer.
031: *
032: * <p>
033: * For content extensions that reshape the structure of children in a
034: * viewer, their overridden extensions may sometimes use optimized refreshes
035: * to add elements to the tree. These attempts must be intercepted and
036: * mapped to the correct set of model elements in the overridding extension.
037: * Clients may add, remove, or modify elements in the given set of added
038: * children. Clients should return a set for downstream extensions to
039: * massage further.
040: * </p>
041: * <p>
042: * <b>Clients should not call any of the add, remove, refresh, or update
043: * methods on the viewer from this method or any code invoked by the
044: * implementation of this method.</b>
045: * </p>
046: *
047: * @param anAddModification
048: * The shape modification which contains the current suggested
049: * parent and children. Clients may modify this parameter
050: * directly and return it as the new shape modification.
051: * @return The new shape modification to use. Clients should <b>never</b>
052: * return <b>null</b> from this method.
053: */
054: public PipelinedShapeModification interceptAdd(
055: PipelinedShapeModification anAddModification);
056:
057: /**
058: * Intercept attempts to remove elements directly from the viewer.
059: *
060: * <p>
061: * For content extensions that reshape the structure of children in a
062: * viewer, their overridden extensions may sometimes use optimized refreshes
063: * to remove elements to the tree. These attempts must be intercepted and
064: * mapped to the correct set of model elements in the overridding extension.
065: * Clients may add, remove, or modify elements in the given set of removed
066: * children. Clients should return a set for downstream extensions to
067: * massage further.
068: * </p>
069: * <p>
070: * <b>Clients should not call any of the add, remove, refresh, or update
071: * methods on the viewer from this method or any code invoked by the
072: * implementation of this method.</b>
073: * </p>
074: *
075: * @param aRemoveModification
076: * The shape modification which contains the current suggested
077: * parent and children. Clients may modify this parameter
078: * directly and return it as the new shape modification.
079: * @return The new shape modification to use. Clients should <b>never</b>
080: * return <b>null</b> from this method.
081: */
082: public PipelinedShapeModification interceptRemove(
083: PipelinedShapeModification aRemoveModification);
084:
085: /**
086: * Intercept calls to viewer <code>refresh()</code> methods.
087: *
088: * <p>
089: * Clients may modify the given update to add or remove the elements to be
090: * refreshed. Clients may return the same instance that was passed in for
091: * the next downstream extension.
092: * </p>
093: *
094: * <p>
095: * <b>Clients should not call any of the add, remove, refresh, or update
096: * methods on the viewer from this method or any code invoked by the
097: * implementation of this method.</b>
098: * </p>
099: *
100: * @param aRefreshSynchronization
101: * The (current) refresh update to execute against the viewer.
102: * @return The (potentially reshaped) refresh to execute against the viewer.
103: */
104: boolean interceptRefresh(
105: PipelinedViewerUpdate aRefreshSynchronization);
106:
107: /**
108: * Intercept calls to viewer <code>update()</code> methods.
109: *
110: * <p>
111: * Clients may modify the given update to add or remove the elements to be
112: * updated. Clients may also add or remove properties for the given targets
113: * to optimize the refresh. Clients may return the same instance that was
114: * passed in for the next downstream extension.
115: * </p>
116: *
117: * <p>
118: * <b>Clients should not call any of the add, remove, refresh, or update
119: * methods on the viewer from this method or any code invoked by the
120: * implementation of this method.</b>
121: * </p>
122: *
123: * @param anUpdateSynchronization
124: * The (current) update to execute against the viewer.
125: * @return The (potentially reshaped) update to execute against the viewer.
126: */
127: public boolean interceptUpdate(
128: PipelinedViewerUpdate anUpdateSynchronization);
129:
130: }
|