org.eclipse.ui.AbstractSourceProvider Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2005, 2016 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;
import org.eclipse.core.commands.util.Tracing;
import org.eclipse.core.runtime.ListenerList;
import org.eclipse.ui.internal.misc.Policy;
import org.eclipse.ui.services.IServiceLocator;
/**
*
* An implementation of ISourceProvider that provides listener
* support. Subclasses need only call fireSourceChanged whenever
* appropriate.
*
*
* @since 3.1
*/
public abstract class AbstractSourceProvider implements ISourceProvider {
/**
* Whether source providers should print out debugging information to the
* console when events arrive.
*
* @since 3.2
*/
protected static boolean DEBUG = Policy.DEBUG_SOURCES;
/**
* The listeners to this source provider. This value is never null.
*/
private final ListenerList listeners = new ListenerList<>(ListenerList.IDENTITY);
@Override
public final void addSourceProviderListener(final ISourceProviderListener listener) {
if (listener == null) {
throw new NullPointerException("The listener cannot be null"); //$NON-NLS-1$
}
listeners.add(listener);
}
/**
* Notifies all listeners that a single source has changed.
*
* @param sourcePriority The source priority that has changed.
* @param sourceName The name of the source that has changed; must not be
* null.
* @param sourceValue The new value for the source; may be null.
*/
protected final void fireSourceChanged(final int sourcePriority, final String sourceName,
final Object sourceValue) {
for (ISourceProviderListener listener : listeners) {
listener.sourceChanged(sourcePriority, sourceName, sourceValue);
}
}
/**
* Notifies all listeners that multiple sources have changed.
*
* @param sourcePriority The source priority that has changed.
* @param sourceValuesByName The map of source names (String) to
* source values (Object) that have
* changed; must not be null. The names
* must not be null, but the values may
* be null.
*/
protected final void fireSourceChanged(final int sourcePriority, final Map sourceValuesByName) {
for (ISourceProviderListener listener : listeners) {
listener.sourceChanged(sourcePriority, sourceValuesByName);
}
}
/**
* Logs a debugging message in an appropriate manner. If the message is
* null or the DEBUG is false, then this
* method does nothing.
*
* @param message The debugging message to log; if null, then
* nothing is logged.
* @since 3.2
*/
protected final void logDebuggingInfo(final String message) {
if (DEBUG && (message != null)) {
Tracing.printTrace("SOURCES", message); //$NON-NLS-1$
}
}
@Override
public final void removeSourceProviderListener(final ISourceProviderListener listener) {
if (listener == null) {
throw new NullPointerException("The listener cannot be null"); //$NON-NLS-1$
}
listeners.remove(listener);
}
/**
* This method is called when the source provider is instantiated by
* org.eclipse.ui.services. Clients may override this method to
* perform initialization.
*
* @param locator The global service locator. It can be used to retrieve
* services like the IContextService
* @since 3.4
*/
public void initialize(final IServiceLocator locator) {
}
}