org.eclipse.ui.ISourceProvider Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2005, 2015 IBM Corporation and others.
*
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.ui;
import java.util.Map;
/**
*
* 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.
*
*
* It is recommended that clients subclass AbstractSourceProvider
* instead, as this provides some common support for listeners.
*
*
* @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 null.
*/
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.
*/
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.
*
* For use with core expressions, this map should contain
* IEvaluationContext#UNDEFINED_VARIABLE for properties which are only sometimes
* available.
*
*
* @return A map of variable names (String) to variable values
* (Object). This may be empty, and may be
* null.
*/
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
* null or empty.
*/
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 null.
*/
void removeSourceProviderListener(ISourceProviderListener listener);
}