KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > modules > tasklist > client > SuggestionManager


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */
19
20 package org.netbeans.modules.tasklist.client;
21
22 import javax.swing.event.EventListenerList JavaDoc;
23 import org.openide.filesystems.FileObject;
24 import org.openide.util.Lookup;
25
26 import java.util.List JavaDoc;
27 import javax.swing.event.ChangeListener JavaDoc;
28
29 /**
30  * The SuggestionManager manages suggestions, suggestion providers,
31  * etc. Modules can obtain a reference to the SuggestionManager
32  * and then register suggestions.
33  * <p>
34  * Here's how you add suggestions to the tasklist:
35  * <ol>
36  * <li> Obtain a reference to the SuggestionManager:
37  * <pre>
38  * SuggestionManager manager = SuggestionManager.getDefault();
39  * </pre>
40  * Note: this may return null (in the case where the Suggestions
41  * module is not available/enabled) so check the return value!
42  * <p>
43  * <li> Check to make sure that the type of suggestion you're about
44  * to add is welcome by the user:
45  * <pre>
46  * if (manager.isEnabled(suggestionTypeId) &&
47  * manager.isObserved(suggestionTypeId)) {
48  * </pre>
49  * <p>
50  * <li> Create a new {@link org.netbeans.modules.tasklist.client.Suggestion}:
51  * <pre>
52  * Suggestion suggestion = manager.createSuggestion("myid",
53  * "my suggestion description",
54  * new SuggestionPerformer() {
55  * public void perform(Suggestion s) {
56  * beep();
57  * }
58  * public Object getConfirmation(Suggestion s) {
59  * return null;
60  * }
61  * public boolean hasConfirmation() {
62  * return false;
63  * }
64  * },
65  * null
66  * );
67  * suggestion.setPriority(SuggestionPriority.HIGH);
68  * </pre>
69  * <li> Register the suggestion with the SuggestionManager:
70  * <pre>
71  * List addList = new ArrayList(1);
72  * addList.add(suggestion);
73  * manager.register("myid", addList, null, null);
74  * </pre>
75  * </ol>
76  * Done! (Also see the {@link org.netbeans.modules.tasklist.providers.SuggestionProvider}
77  * API for how to write specialized suggestion providers. The above
78  * scenario is optimized for the case where you're already doing some
79  * computation where you have suggestions as a side effect. If you
80  * want to write some code which is only run if the suggestions window
81  * is visible etc. etc. that's a better route.)
82  * <p>
83  *
84  * @author Tor Norbye
85  */
86 abstract public class SuggestionManager {
87     protected EventListenerList JavaDoc listeners = new EventListenerList JavaDoc();
88         
89     /** Construct a new SuggestionManager instance. */
90     protected SuggestionManager() {
91     }
92
93     /**
94      * Construct a new suggestion, of the given type, with the given
95      * summary, and performing the designated action.
96      *
97      * @param fo FileObject associated with this suggestion or null
98      * @param type The type of this suggestion. This is a unique string
99      * id, which corresponds to the layer-declaration of a
100      * Suggestion Type which has a user description; you can
101      * also query the SuggestionManager to ask if this
102      * type of Suggestion has been disabled by the user.
103      * @param summary A one-line summary of the task; this is what appears
104      * in the Suggestions Window main column.
105      * @param action An action to be performed when the user "runs" this
106      * task. Some actions may actually fix the problem that
107      * the suggestion is describing, for example "update
108      * the copyright to include 2002" might edit the document
109      * when the action is run; other actions may point the
110      * user to the problem: the compiler may add tasks to
111      * fix errors and running these actions open the editor
112      * on the relevant source line. This parameter may be
113      * null. This is typically the case for suggestions where
114      * we can't safely fix the problem, and only "Go To
115      * Source" is provided.
116      * @param seed Initial provider's data provided for this suggestion,
117      * if any. May be null.
118      * @return A new suggestion matching the input parameters which can then
119      * be registered with the manager.
120      *
121      * @since 1.4
122      *
123      * @todo Provide specific guidelines here for how these sentences
124      * should be worded so that we get a consistent set of
125      * descriptions.
126      *
127      * @todo Support multiple actions solving found problems instead
128      * of current practice (reporting it as several suggestions).
129      *
130      */
131     abstract public SuggestionAgent createSuggestion(
132         FileObject fo, String JavaDoc type, String JavaDoc summary, SuggestionPerformer action,
133         Object JavaDoc seed);
134     
135     /**
136      * Return true iff the type of suggestion indicated by the
137      * id argument is enabled. By default, all suggestion types
138      * are enabled, but users can disable suggestion types they're
139      * not interested in.
140      * <p>
141      *
142      * @param id The String id of the Suggestion Type. See the
143      * {@link org.netbeans.modules.tasklist.client.Suggestion} documentation for how Suggestion Types
144      * are registered and named.
145      *
146      * @return True iff the given suggestion type is enabled
147      */
148     abstract public boolean isEnabled(String JavaDoc id);
149
150     /**
151      * Return true iff the user appears to be "reading" the
152      * suggestions. This means it will return false if the
153      * Suggestion window is not open. This means that if a suggestion
154      * is only temporarily interesting, this method lets you
155      * skip creating a suggestion since if the suggestion window
156      * isn't open, the user won't see it anyway, and since this
157      * is a temporarily-interesting suggestion by the time the
158      * window is opened the suggestion isn't relevant anymore.
159      * (Yes, it's obviously possible that the suggestion window
160      * is open but the user is NOT looking at it; that will be
161      * fixed in tasklist version 24.0 when we have eye scanning
162      * hardware and access-APIs.)
163      * <p>
164      *
165      * @param id The String id of the Suggestion Type we're
166      * interested in. You may pass null to ask about any/all
167      * Suggestion Types. See the {@link org.netbeans.modules.tasklist.client.Suggestion} documentation
168           for how Suggestion Types are registered and named.
169      *
170      *
171      * @return True iff the suggestions are observed by the user.
172      */
173     abstract public boolean isObserved(String JavaDoc id);
174
175     /**
176      * Add and remove lists of suggestions from the suggestion
177      * registry.
178      * <p>
179      * The tasks will remain in the list until the IDE is shut down,
180      * or until the user performs the tasks, or until the tasks are explicitly
181      * removed by you.
182      * <p>
183      * If you have multiple suggestions to register for the same type,
184      * register them all at once. This is better for performance, but
185      * also allows the suggestions framework to decide to group a series
186      * of related suggestions together, for example.
187      * <p>
188      * Note: if these suggestion corresponds to a disabled suggestion type,
189      * they will not be added to the list. To avoid computing Suggestion
190      * objects in the first place, check isEnabled().
191      * <p>
192      * Note: only suggestions created by calling {@link #createSuggestion}
193      * should be registered here.
194      * <p>
195      * @todo Consider adding a "time-to-live" attribute here where you
196      * can indicate the persistence of the task; some suggestions should
197      * probably expire if the user doesn't act on it for 5(?) minutes,
198      * others should perhaps survive even IDE restarts.
199      *
200      * @param type The type of suggestions being added. May be null,
201      * in which case the suggestion manager will check each suggestion
202      * for its declared type. This allows you to register suggestions
203      * of multiple types, but means more work for the suggestion manager
204      * (so specifying a homogeneous list gives better performance.)
205      * @param add List of suggestions that should be added
206      * @param remove List of suggestions that should be removed. Note that
207      * the remove is performed before the add, so if a task appears
208      * in both list it will not be removed.
209      */
210     abstract public void register(String JavaDoc type, List JavaDoc add, List JavaDoc remove);
211
212     /** Get the default Suggestion Manager.
213      * <p>
214      * @return the default instance from lookup
215      */
216     public static SuggestionManager getDefault() {
217         return (SuggestionManager)Lookup.getDefault().
218             lookup(SuggestionManager.class);
219     }
220 }
221
Popular Tags