bundles/org.eclipse.ui.navigator/src/org/eclipse/ui/navigator/INavigatorContentService.java

/*******************************************************************************
 * Copyright (c) 2003, 2006 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;

import java.util.Set;

import org.eclipse.jface.viewers.IContentProvider;
import org.eclipse.jface.viewers.ILabelProvider;
import org.eclipse.jface.viewers.IStructuredContentProvider;
import org.eclipse.jface.viewers.ITreeContentProvider;
import org.eclipse.jface.viewers.ViewerSorter;
import org.eclipse.ui.IMemento;
import org.eclipse.ui.ISaveablesSource;

/**
 * 
 * Manages content extensions for extensible viewers and provides reusable
 * services for filters, sorting, the activation of content extensions, and DND.
 * The service can locate the appropriate providers (for contents or labels) for
 * an element and provide a ready-to-go {@link ITreeContentProvider} and
 * {@link ILabelProvider} for viewers that wish to take advantage of the
 * <b>org.eclipse.ui.navigator.navigatorContent</b> extensions defined for a
 * particular <i>viewerId</i>.
 * 
 * <p>
 * Clients should create instances of the this class using the factory ({@link NavigatorContentServiceFactory}).
 * </p>
 * 
 * <p>
 * Clients may contribute logical extensions using
 * <b>org.eclipse.ui.navigator.navigatorContent</b>. Each extension has three
 * states which determine whether the extension is used by the content service:
 * <ul>
 * <li><a name="visible"><i>visible</i>: If a content extension id matches a
 * <b>viewerContentBinding</b> for the <i>viewerId</i> of this content
 * service, then the extension is <i>visible</i>. Visible extensions may only
 * be configured through <b>viewerContentBinding</b>s. </li>
 * 
 * <li><a name="active"><i>active</i>: The active state may be set to a default using the
 * <i>activeByDefault</i> attribute of <b>navigatorContent</b>. Users may
 * toggle the <i>active</i> state through the "Available customizations"
 * dialog. Clients may also configure the active extensions using
 * {@link INavigatorActivationService#activateExtensions(String[], boolean)} or
 * {@link INavigatorActivationService#deactivateExtensions(String[], boolean)}
 * from the {@link #getActivationService() Activation Service} </li>
 * 
 * <li><a name="enabled"><i>enabled</i>: An extension is <i>enabled</i> for an element if the
 * extension contributed that element or if the element is described in the
 * <i>triggerPoints</i> element of the <b>navigatorContent</b> extension. The
 * findXXX() methods search for <i>enabled</i> extensions. </li>
 * </ul>
 * </p>
 * <p>
 * A new instance of the content service should be created for each viewer.
 * Clients should use {@link #createCommonContentProvider()} and
 * {@link #createCommonLabelProvider()} for the viewer. Each content service
 * tracks the viewer it is attached to. Clients may create the content service
 * with a viewer using ({@link NavigatorContentServiceFactory#createContentService(String)}).
 * Alternatively, when the content provider is created and set on a viewer,
 * {@link IContentProvider#inputChanged(org.eclipse.jface.viewers.Viewer, Object, Object)}
 * will be called and the content provider will update the viewer used by its
 * backing content service. Therefore, only each content service has exactly one
 * content provider and one label provider.
 * </p>
 * <p>
 * Extensions may also coordinate their behavior through a
 * {@link IExtensionStateModel state model}. The state model holds properties
 * and supports property change listeners. Actions can toggle the setting of
 * properties and the corresponding content/label providers will respond to
 * property change event. Each <b>navigatorContent</b> extension has its own
 * contained state model keyed off of the content extension id.
 * </p>
 * <p>
 * Clients may respond when content extensions are loaded by attaching a
 * {@link INavigatorContentServiceListener} to the content service.
 * </p>
 * <p>
 * Some extensions may provide content or label providers which implement
 * {@link IMemento}. Clients must call {@link #restoreState(IMemento)} and
 * {@link #saveState(IMemento)} at the appropriate times for these extensions to
 * prepare themselves with the memento.
 * </p>
 * <p>
 * This interface is not intended to be implemented by clients.
 * </p>
 * 
 * @since 3.2
 * 
 */
public interface INavigatorContentService {

	/**
	 * Create a Content Provider which will use an enhanced delegation model to
	 * locate extension content providers using this content service for each
	 * element in the tree.
	 * 
	 * <p>
	 * The content provider returned will populate the root of the viewer in one
	 * of two ways.
	 * <p>
	 * In the first approach, the content provider will seek out content
	 * extensions which are bound using a <b>viewerContentBinding</b>. If any
	 * of the found <b>viewerContentBindings</b> declare the <i>isRoot</i>
	 * attribute on as true, then that set of extensions will be consulted for
	 * the root elements of the tree. The input of the viewer will be supplied
	 * to each of their {@link IStructuredContentProvider#getElements(Object)}
	 * methods and aggregate the results for the root of the viewer.
	 * </p>
	 * <p>
	 * In the second approach, if no <b>viewerContentBindings</b> declare
	 * <i>isRoot</i> as true, then all matching extensions are consulted based
	 * on their <b>triggerPoints</b> expression in the <b>navigatorContent</b>
	 * extension. Any matching extensions are then consulted via their
	 * {@link IStructuredContentProvider#getElements(Object)} methods and the
	 * results are aggregated into the root.
	 * </p>
	 * <p>
	 * After the root is populated, the children of each root element are
	 * determined by consulting the source extension and all extension which
	 * describe the element in their <b>triggerPoints</b> expression.
	 * </p>
	 * <p>
	 * If clients wish to use a viewer other than the CommonViewer, then they
	 * are responsible for creating the content provider, and setting it on
	 * their viewer.
	 * </p>
	 * 
	 * @return An enhanced content provider that will use this content service
	 *         to drive the viewer.
	 */
	ITreeContentProvider createCommonContentProvider();

	/**
	 * Create a Label Provider which will use an enhanced delegation model to
	 * locate extension label providers using this content service for each
	 * element in the tree.
	 * 
	 * <p>
	 * The label of each element is determined by consulting the source of the
	 * element. If the source chooses to return null, then other extensions
	 * which declare the element in their <b>triggerPoints</b> extension are
	 * consulted. The first non-null value is used (including the empty label).
	 * </p>
	 * 
	 * <p>
	 * If clients wish to use a viewer other than the CommonViewer, then they
	 * are responsible for creating the label provider, and setting it on their
	 * viewer.
	 * </p>
	 * 
	 * @return An enhanced label provider that will use this content service to
	 *         drive labels in the viewer.
	 */
	ILabelProvider createCommonLabelProvider();

	/**
	 * 
	 * @return The description provider for this content service.
	 */
	IDescriptionProvider createCommonDescriptionProvider();

	/**
	 * The state model stores properties associated with the extension. Each
	 * content extension has its own contained state model. Components of the
	 * extension (content provider, label provider, action providers, etc) may
	 * attach themselves as listeners to the model ({@link IExtensionStateModel#addPropertyChangeListener(org.eclipse.jface.util.IPropertyChangeListener)})
	 * and respond to changes to the values of the properties.
	 * 
	 * @param anExtensionId
	 *            The extension id defined by a <b>navigatorContent</b>
	 *            extension.
	 * @return The state model for the given extension id.
	 */
	IExtensionStateModel findStateModel(String anExtensionId);

	/**
	 * The viewer id is used to locate matching <b>viewerContentBindings</b>.
	 * In general, this would be the id of the view defined by a
	 * <b>org.eclipse.ui.views</b> extension. However, there is no formal
	 * requirement that this is the case.
	 * 
	 * @return The viewerId used to create this content service.
	 */
	String getViewerId();

	/**
	 * The viewer descriptor provides some basic information about the abstract
	 * viewer that uses this content service.
	 * 
	 * @return The viewer descriptor for this content service.
	 * @see INavigatorViewerDescriptor
	 */
	INavigatorViewerDescriptor getViewerDescriptor();

	/**
	 * See <a href="#active">above</a> for the definition of <i>active</i>.
	 * 
	 * @param anExtensionId
	 *            The unqiue identifier from a content extension.
	 * @return True if and only if the given extension id is <i>active</i> for
	 *         this content service.
	 * @see INavigatorContentService For more information on what <i>active</i>
	 *      means.
	 * 
	 */
	boolean isActive(String anExtensionId);

	/**
	 *  See <a href="#visible">above</a> for the definition of <i>visible</i>.
	 *  
	 * @param anExtensionId
	 *            The unqiue identifier from a content extension.
	 * @return True if and only if the given extension id is <i>visible</i> to
	 *         this content service.
	 * @see INavigatorContentService For more information on what <i>visible</i>
	 *      means.
	 */
	boolean isVisible(String anExtensionId);

	/**
	 * Return the set of <i>visible</i> extension ids for this content service,
	 * which includes those that are bound through <b>viewerContentBinding</b>s
	 * and those that are bound through
	 * {@link #bindExtensions(String[], boolean)}.
	 * 
	 * @return The set of <i>visible</i> extension ids for this content service
	 */
	String[] getVisibleExtensionIds();

	/**
	 * Return the set of <i>visible</i> content descriptors for this content
	 * service, which includes those that are bound through
	 * <b>viewerContentBinding</b>s and those that are bound through
	 * {@link #bindExtensions(String[], boolean)}.
	 * 
	 * @return The set of <i>visible</i> content descriptors for this content
	 *         service
	 */
	INavigatorContentDescriptor[] getVisibleExtensions();

	/**
	 * Bind the set of given extensions to this content service. Programmatic
	 * bindings allow clients to make extensions <i>visible</i> to an instance
	 * of the content service by appending to the bindings declared through
	 * <b>org.eclipse.ui.navigator.viewer</b>. Programmtic bindings are not
	 * persisted and are not remembered or propagated to other instances of the
	 * INavigatorContentService in the same session. Programmatic bindings
	 * cannot be undone for a given instance of the INavigatorContentService and
	 * do not override declarative bindings.
	 * <p>
	 * Once a content extension has been bound to the INavigatorContentService,
	 * clients may use
	 * {@link INavigatorActivationService#activateExtensions(String[], boolean) }
	 * or
	 * {@link  INavigatorActivationService#deactivateExtensions(String[], boolean) }
	 * to control the <i>activation</i> state of the extension. See
	 * {@link INavigatorContentService} for more information on the difference
	 * between <i>visible</i> and <i>active</i>.
	 * </p>
	 * 
	 * @param extensionIds
	 *            The list of extensions to make visible.
	 * @param isRoot
	 *            whether the context provider shold be a root content provider
	 * @return A list of all INavigatorContentDescriptors that correspond to the
	 *         given extensionIds.
	 */
	INavigatorContentDescriptor[] bindExtensions(String[] extensionIds,
			boolean isRoot);

	/**
	 * Restore the state associated with the memento.
	 * 
	 * @param aMemento
	 *            The memento for extensions to use when restoring previous
	 *            settings.
	 */
	void restoreState(IMemento aMemento);

	/**
	 * Persist any session-to-session state with the memento.
	 * 
	 * @param aMemento
	 *            The memento for extensions to use when persisting previous
	 *            settings.
	 */
	void saveState(IMemento aMemento);

	/**
	 * Add a listener to be notified whenever an extension is loaded.
	 * 
	 * @param aListener
	 *            A listener to be attached.
	 */
	void addListener(INavigatorContentServiceListener aListener);

	/**
	 * Remove a listener (by identity) from the set of listeners.
	 * 
	 * @param aListener
	 *            A listener to be detached.
	 */
	void removeListener(INavigatorContentServiceListener aListener);

	/**
	 * The root content providers are recalculated by this method. The attached
	 * viewer is also refreshed as a result of this method.
	 * 
	 */
	void update();

	/**
	 * Release any acquired resources and instantiated content extensions.
	 * 
	 */
	void dispose();

	/**
	 * Search for extensions that declare the given element in their
	 * <b>triggerPoints</b> expression or that indicate they should be bound as
	 * a root extension.
	 * 
	 * @param anElement
	 *            The element to use in the query
	 * @return The set of {@link INavigatorContentExtension}s that are
	 *         <i>visible</i> and <i>active</i> for this content service and
	 *         either declared through a
	 *         <b>org.eclipse.ui.navigator.viewer/viewerContentBinding</b> to
	 *         be a root element or have a <b>triggerPoints</b> expression that
	 *         is <i>enabled</i> for the given element.
	 */
	Set findRootContentExtensions(Object anElement);

	/**
	 * Search for extensions that declare the given element in their
	 * <b>triggerPoints</b> expression.
	 * 
	 * @param anElement
	 *            The element to use in the query
	 * @return The set of {@link INavigatorContentExtension}s that are
	 *         <i>visible</i> and <i>active</i> for this content service and
	 *         have a <b>triggerPoints</b> expression that is <i>enabled</i>
	 *         for the given element.
	 */
	Set findContentExtensionsByTriggerPoint(Object anElement);

	/**
	 * Search for extensions that declare the given element in their
	 * <b>possibleChildren</b> expression.
	 * 
	 * @param anElement
	 *            The element to use in the query
	 * @return The set of {@link INavigatorContentExtension}s that are
	 *         <i>visible</i> and <i>active</i> for this content service and
	 *         have a <b>possibleChildren</b> expression that is <i>enabled</i>
	 *         for the given element.
	 */
	Set findContentExtensionsWithPossibleChild(Object anElement);

	/**
	 * The filter service can provide the available filters for the viewer, and
	 * manage which filters are <i>active</i>.
	 * 
	 * @return An {@link INavigatorFilterService} that can provide information
	 *         to a viewer about what filters are <i>visible</i> and <i>active</i>.
	 */
	INavigatorFilterService getFilterService();

	/**
	 * The sorter service provides the appropriate sorter based on the current
	 * items being sorted. By default, the CommonViewer uses
	 * {@link CommonViewerSorter} which delegates to this service. Clients do
	 * not need to provide their own {@link ViewerSorter} unless they wish to
	 * override this functionality.
	 * 
	 * @return An {@link INavigatorSorterService} that can provide
	 *         {@link ViewerSorter} based on the context of the parent.
	 */
	INavigatorSorterService getSorterService();

	/**
	 * The pipeline service calculates the appropriate viewer modification or
	 * refresh that should be applied for viewers that wish to take advantage of
	 * the model pipelining that some extensions use to massage or reshape
	 * contents in the viewer. Clients that use the {@link CommonViewer} do not
	 * need to be concerned with this service as the refreshes are automatically
	 * computed using this service.
	 * 
	 * 
	 * @return The {@link INavigatorPipelineService} which can determine the
	 *         correct updates to apply to a viewer.
	 */
	INavigatorPipelineService getPipelineService();

	/**
	 * The DND Service provides instances of {@link CommonDragAdapterAssistant}
	 * and {@link CommonDropAdapterAssistant} for this content service.
	 * 
	 * @return The {@link INavigatorDnDService} which can add additional
	 *         TransferTypes for the DragAdapter and setup the data correctly
	 *         for those extended Transfer Types.
	 */
	INavigatorDnDService getDnDService();

	/**
	 * The activation service is used to toggle whether certain extensions have
	 * the opportunity to contribute content and/or actions.
	 * 
	 * @return The {@link INavigatorActivationService} for this content service.
	 */
	INavigatorActivationService getActivationService();
	
	/**
	 * The saveable service helps implementing {@link ISaveablesSource}.
	 * 
	 * @return the {@link INavigatorSaveablesService} for this content service.
	 */
	INavigatorSaveablesService getSaveablesService();
	
	/** 
	 * Return the content extension for the given id. 
	 * 
	 * @param anExtensionId The id used to define the <b>org.eclipse.ui.navigator.navigatorContent/navigatorContent</b> extension.
	 * @return An instance of the content extension for the given extension id. May return <b>null</b> if the id is invalid.
	 */
	public INavigatorContentExtension getContentExtensionById(String anExtensionId);


}