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

import java.util.Map;

/**
 * <p>
 * A provider of notifications for when a change has occurred to a particular
 * type of source. These providers can be given to the appropriate service, and
 * this service will then re-evaluate the appropriate pieces of its internal
 * state in response to these changes.
 * </p>
 * <p>
 * It is recommended that clients subclass <code>AbstractSourceProvider</code>
 * instead, as this provides some common support for listeners.
 * </p>
 * 
 * @since 3.1
 * @see org.eclipse.ui.handlers.IHandlerService
 * @see org.eclipse.ui.ISources
 */
public interface ISourceProvider {

	/**
	 * Adds a listener to this source provider. This listener will be notified
	 * whenever the corresponding source changes.
	 * 
	 * @param listener
	 *            The listener to add; must not be <code>null</code>.
	 */
	public void addSourceProviderListener(ISourceProviderListener listener);

	/**
	 * Allows the source provider an opportunity to clean up resources (e.g.,
	 * listeners) before being released. This method should be called by the
	 * creator after the source provider has been removed from all the services
	 * with which it was registered.
	 */
	public void dispose();

	/**
	 * Returns the current state of the sources tracked by this provider. This
	 * is used to provide a view of the world if the event loop is busy and
	 * things are some state has already changed.
	 * <p>
	 * For use with core expressions, this map should contain 
	 * IEvaluationContext#UNDEFINED_VARIABLE for properties which
	 * are only sometimes available.
	 * </p>
	 * 
	 * @return A map of variable names (<code>String</code>) to variable
	 *         values (<code>Object</code>). This may be empty, and may be
	 *         <code>null</code>.
	 */
	public Map getCurrentState();

	/**
	 * Returns the names of those sources provided by this class. This is used
	 * by clients of source providers to determine which source providers they
	 * actually need.
	 * 
	 * @return An array of source names. This value should never be
	 *         <code>null</code> or empty.
	 */
	public String[] getProvidedSourceNames();

	/**
	 * Removes a listener from this source provider. This listener will be
	 * notified whenever the corresponding source changes.
	 * 
	 * @param listener
	 *            The listener to remove; must not be <code>null</code>.
	 */
	public void removeSourceProviderListener(ISourceProviderListener listener);
}