01: /*******************************************************************************
02: * Copyright (c) 2005, 2006 IBM Corporation and others.
03: * All rights reserved. This program and the accompanying materials
04: * are made available under the terms of the Eclipse Public License v1.0
05: * which accompanies this distribution, and is available at
06: * http://www.eclipse.org/legal/epl-v10.html
07: *
08: * Contributors:
09: * IBM Corporation - initial API and implementation
10: *******************************************************************************/package org.eclipse.ui;
11:
12: import java.util.Map;
13:
14: /**
15: * <p>
16: * A provider of notifications for when a change has occurred to a particular
17: * type of source. These providers can be given to the appropriate service, and
18: * this service will then re-evaluate the appropriate pieces of its internal
19: * state in response to these changes.
20: * </p>
21: * <p>
22: * It is recommended that clients subclass <code>AbstractSourceProvider</code>
23: * instead, as this provides some common support for listeners.
24: * </p>
25: *
26: * @since 3.1
27: * @see org.eclipse.ui.handlers.IHandlerService
28: * @see org.eclipse.ui.ISources
29: */
30: public interface ISourceProvider {
31:
32: /**
33: * Adds a listener to this source provider. This listener will be notified
34: * whenever the corresponding source changes.
35: *
36: * @param listener
37: * The listener to add; must not be <code>null</code>.
38: */
39: public void addSourceProviderListener(
40: ISourceProviderListener listener);
41:
42: /**
43: * Allows the source provider an opportunity to clean up resources (e.g.,
44: * listeners) before being released. This method should be called by the
45: * creator after the source provider has been removed from all the services
46: * with which it was registered.
47: */
48: public void dispose();
49:
50: /**
51: * Returns the current state of the sources tracked by this provider. This
52: * is used to provide a view of the world if the event loop is busy and
53: * things are some state has already changed.
54: *
55: * @return A map of variable names (<code>String</code>) to variable
56: * values (<code>Object</code>). This may be empty, and may be
57: * <code>null</code>.
58: */
59: public Map getCurrentState();
60:
61: /**
62: * Returns the names of those sources provided by this class. This is used
63: * by clients of source providers to determine which source providers they
64: * actually need.
65: *
66: * @return An array of source names. This value should never be
67: * <code>null</code> or empty.
68: */
69: public String[] getProvidedSourceNames();
70:
71: /**
72: * Removes a listener from this source provider. This listener will be
73: * notified whenever the corresponding source changes.
74: *
75: * @param listener
76: * The listener to remove; must not be <code>null</code>.
77: */
78: public void removeSourceProviderListener(
79: ISourceProviderListener listener);
80: }
|