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

/**
 * 
 * Determines if an extension is <i>active</i> within the context of a given
 * viewer and manages the persistence of this information. If an extension is
 * <i>active</i> then the extension will contribute functionality to the
 * viewer. If an extension is not <i>active</i>, then the extension will not be
 * given opportunities to contribute functionality to the given viewer. See
 * {@link INavigatorContentService} for more detail on what states are
 * associated with a content extension.
 * 
 * @since 3.2
 * 
 */
public interface INavigatorActivationService {

	/**
	 * 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.
	 * 
	 * <p>
	 * Clients must call {@link #persistExtensionActivations()} to save the the
	 * activation state after activating or deactivating extensions.
	 * </p>
	 * 
	 * @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 activated as
	 *         a result of this call. This will be the set of
	 *         INavigatorContentDescriptors that corresponds exactly to the set
	 *         of given extensionIds.
	 */
	public 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.
	 * 
	 * <p>
	 * Clients must call {@link #persistExtensionActivations()} to save the the
	 * activation state after activating or deactivating extensions.
	 * </p>
	 * 
	 * @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 activated 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.
	 */
	public INavigatorContentDescriptor[] deactivateExtensions(
			String[] extensionIds, boolean toActivateAllOthers);

	/**
	 * 
	 * Checks the known activation state for the given viewer id to determine if
	 * the given navigator extension is 'active'.
	 * 
	 * @param aNavigatorExtensionId
	 *            The unique identifier associated with a given extension.
	 * 
	 * @return True if the extension is active in the context of the viewer id.
	 */
	public boolean isNavigatorExtensionActive(String aNavigatorExtensionId);

	/**
	 * Save the activation state of each content extension for the associated
	 * content service. Clients should persist the activation state after any
	 * call to {@link #activateExtensions(String[], boolean)} or
	 * {@link #deactivateExtensions(String[], boolean)}.
	 * 
	 */
	public void persistExtensionActivations();

	/**
	 * Request notification when the activation state changes.
	 * 
	 * @param aListener
	 *            An implementation of {@link IExtensionActivationListener}
	 */
	public void addExtensionActivationListener(
			IExtensionActivationListener aListener);

	/**
	 * No longer receive notification when activation state changes.
	 * 
	 * @param aListener
	 *            An implementation of {@link IExtensionActivationListener}
	 */
	public void removeExtensionActivationListener(
			IExtensionActivationListener aListener);
}