/*******************************************************************************
* Copyright (c) 2006, 2015 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
******************************************************************************/
package org.eclipse.ui.navigator;
/**
*
* Performs calculations that are necessary to determine the correct children to
* render in the viewer.
*
* @see INavigatorContentService#getPipelineService()
* @see PipelinedShapeModification
* @see PipelinedViewerUpdate
* @see IPipelinedTreeContentProvider
*
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
* @since 3.2
*/
public interface INavigatorPipelineService {
/**
* Intercept attempts to add elements directly to the viewer.
*
* <p>
* For content extensions that reshape the structure of children in a
* viewer, their overridden extensions may sometimes use optimized refreshes
* to add elements to the tree. These attempts must be intercepted and
* mapped to the correct set of model elements in the overriding extension.
* Clients may add, remove, or modify elements in the given set of added
* children. Clients should return a set for downstream extensions to
* massage further.
* </p>
* <p>
* <b>Clients should not call any of the add, remove, refresh, or update
* methods on the viewer from this method or any code invoked by the
* implementation of this method.</b>
* </p>
*
* @param anAddModification
* The shape modification which contains the current suggested
* parent and children. Clients may modify this parameter
* directly and return it as the new shape modification.
* @return The new shape modification to use. Clients should <b>never</b>
* return <b>null</b> from this method.
*/
public PipelinedShapeModification interceptAdd(
PipelinedShapeModification anAddModification);
/**
* Intercept attempts to remove elements directly from the viewer.
*
* <p>
* For content extensions that reshape the structure of children in a
* viewer, their overridden extensions may sometimes use optimized refreshes
* to remove elements to the tree. These attempts must be intercepted and
* mapped to the correct set of model elements in the overriding extension.
* Clients may add, remove, or modify elements in the given set of removed
* children. Clients should return a set for downstream extensions to
* massage further.
* </p>
* <p>
* <b>Clients should not call any of the add, remove, refresh, or update
* methods on the viewer from this method or any code invoked by the
* implementation of this method.</b>
* </p>
*
* @param aRemoveModification
* The shape modification which contains the current suggested
* parent and children. Clients may modify this parameter
* directly and return it as the new shape modification.
* @return The new shape modification to use. Clients should <b>never</b>
* return <b>null</b> from this method.
*/
public PipelinedShapeModification interceptRemove(
PipelinedShapeModification aRemoveModification);
/**
* Intercept calls to viewer <code>refresh()</code> methods.
*
* <p>
* Clients may modify the given update to add or remove the elements to be
* refreshed. Clients may return the same instance that was passed in for
* the next downstream extension.
* </p>
*
* <p>
* <b>Clients should not call any of the add, remove, refresh, or update
* methods on the viewer from this method or any code invoked by the
* implementation of this method.</b>
* </p>
*
* @param aRefreshSynchronization
* The (current) refresh update to execute against the viewer.
* @return The (potentially reshaped) refresh to execute against the viewer.
*/
boolean interceptRefresh(PipelinedViewerUpdate aRefreshSynchronization);
/**
* Intercept calls to viewer <code>update()</code> methods.
*
* <p>
* Clients may modify the given update to add or remove the elements to be
* updated. Clients may also add or remove properties for the given targets
* to optimize the refresh. Clients may return the same instance that was
* passed in for the next downstream extension.
* </p>
*
* <p>
* <b>Clients should not call any of the add, remove, refresh, or update
* methods on the viewer from this method or any code invoked by the
* implementation of this method.</b>
* </p>
*
* @param anUpdateSynchronization
* The (current) update to execute against the viewer.
* @return The (potentially reshaped) update to execute against the viewer.
*/
public boolean interceptUpdate(
PipelinedViewerUpdate anUpdateSynchronization);
}