/*******************************************************************************
 * Copyright (c) 2003, 2005 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 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.ui.IMemento;

/**
 * 
 * The INavigatorContentService manages extensions for extensible viewers. 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><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 'visible'. Visible extensions may only be
 *                     configured through <b>viewerContentBinding</b>s. 
 * </li>
 * <li><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 'active' state through the 
 *                    'Available extensions' dialog. Clients may also 
 *                    configure the active extensions using
 *                     {@link #activateExtensions(String[], boolean)} or
 *                     {@link #deactivateExtensions(String[], boolean)}. 
 * </li>
 * <li><i>enabled</i>: An extension is 'enabled' 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 'enabled' 
 *                     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, org.eclipse.jface.viewers.StructuredViewer)}).
 * 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>
 * <strong>EXPERIMENTAL</strong>. This class or interface has been added as
 * part of a work in progress. There is a guarantee neither that this API will
 * work nor that it will remain the same. Please do not use this API without
 * consulting with the Platform/UI team.
 * </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();

	/**
	 * 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);

	/**
	 * Return a set of content providers that could provide
	 * a parent for the given element. These content extensions
	 * are determined by consulting the <b>possibleChildren</b> 
	 * expression in the <b>navigatorContent</b> extension.
	 * 
	 * <p>
	 * Clients that wish to tap into the link with editor support
	 * must describe all of their possible children in their 
	 * <b>possibleChildren</b> expressions.
	 * </p>
	 * 
	 * @param anElement An element from the tree (generally from a setSelection() method). 
	 * @return The set of content providers that may be able to provide a parent. 
	 */
	ITreeContentProvider[] findParentContentProviders(Object anElement);

	/**
	 * <p>
	 * Return all of the content providers that are relevant for the viewer. The
	 * viewer is determined by the ID used to create the INavigatorContentService 
	 * ({@link #getViewerId() }). See {@link #createCommonContentProvider() }
	 * for more information about how content providers are located
	 * for the root of the viewer. The root content providers are calculated once. If
	 * a new element is supplied, a client must call {@link #update() } prior in
	 * order to reset the calculated root providers. 
	 * </p>
	 * 
	 * @param anElement An element from the tree (generally the input of the viewer)
	 * @return The set of content providers that can provide root elements for a viewer.
	 */
	ITreeContentProvider[] findRootContentProviders(Object anElement);

	/** 
	 * Return all of the content providers that are enabled for the given
	 * element. An 'enabled' content provider is either the (1) source
	 * of the element (the element was returned as a child of its 
	 * parent by the content provider) or (2) a content extension
	 * which describes the element in its <b>triggerPoints</b> expression.
	 * 
	 * @param anElement An element from the tree (generally the element expanded by the user)
	 * @return The set of content providers that can provide valid children for the element.
	 */
	ITreeContentProvider[] findRelevantContentProviders(Object anElement);

	/**
	 * 
	 * Return all of the label providers that are enabled for the given
	 * element. A label provider is 'enabled' if its corresponding content 
	 * provider returned the element, or the element is described in the
	 * content extension's <b>triggerPoints</b> expression.  
	 * 
	 * @param anElement An element from the tree (any element contributed to the tree). 
	 * @return The set of label providers that may be able to provide a valid (non-null) label.
	 */

	ILabelProvider[] findRelevantLabelProviders(Object anElement);

	/**
	 * 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();
	
	/**
	 * @return The set of visible extension ids for this content service
	 */
	String[] getVisibleExtensionIds();
	
	/**
	 * @return The set of 'visible' content descriptors for this content service
	 */
	INavigatorContentDescriptor[] getVisibleExtensions();

	/**
	 * Activate the extensions specified by the extensionIds array. Clients
	 * may also choose to disable all other extensions. The set of descriptors
	 * returned is the set that were activated as a result of this call. In
	 * the case of this method, that means that a descriptor will be returned
	 * for each extensionId in the array, regardless of whether that extension 
	 * is already enabled. 
	 * 
	 * @param extensionIds
	 *            The list of extensions to activate
	 * @param toDeactivateAllOthers
	 *            True will deactivate all other extensions; False will leave the
	 *            other activations as-is
	 * @return A list of all INavigatorContentDescriptors that were enabled as a
	 *         result of this call. This will be the set of INavigatorContentDescriptors
	 *         that corresponds exactly to the set of given extensionIds.
	 */ 
	INavigatorContentDescriptor[] activateExtensions(String[] extensionIds,
			boolean toDeactivateAllOthers);

	/**
	 * Deactivate the extensions specified by the extensionIds. Clients may 
	 * choose to activate all other extensions which are not explicitly 
	 * disabled. If toActivateAllOthers is true, the array of returned 
	 * descriptors will be the collection of all extensions not 
	 * specified in the extensionIds array. If it is false, the array
	 * will be empty.
	 * 
	 * @param extensionIds
	 *            The list of extensions to activate
	 * @param toActivateAllOthers
	 *            True will activate all other extensions; False will leave the
	 *            other activations as-is
	 * @return A list of all INavigatorContentDescriptors that were enabled as a
	 *         result of this call. If toActivateAllOthers is false, the result 
	 *         will be an empty array. Otherwise, it will be the set of all visible
	 *         extensions minus those given in the 'extensionIds' parameter. 
	 */
	INavigatorContentDescriptor[] deactivateExtensions(String[] extensionIds,
			boolean toActivateAllOthers);

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

	/**
	 * 
	 * @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 calculated once in {@link #findRootContentProviders(Object) }
	 * and reset 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();

}