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