KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > ISourceProvider


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