KickJava   Java API By Example, From Geeks To Geeks.

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


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 java.awt.Image JavaDoc;
23 import java.beans.PropertyChangeListener JavaDoc;
24 import java.beans.PropertyChangeSupport JavaDoc;
25 import org.openide.filesystems.FileObject;
26
27 import org.openide.text.Line;
28 import org.netbeans.modules.tasklist.client.SuggestionPriority;
29
30 /**
31  * A suggestion is an item in the Suggestions Viev. It has an associated
32  * description/summary, an associated icon, an associated action, etc.
33  * <p>
34  * Suggestions have an associated "type". For example, there
35  * is a copyright suggestion which adds suggestions for how to
36  * fix copyrights in your files; whenever it sees you editing a file
37  * where the current year is not included, it will add a specific
38  * suggestion which when performed edits your code to update the
39  * copyright. These copyright suggestions all have the same
40  * suggestion type: copyright.
41  *
42  * <p>
43  * This type is used for two purposes:
44  * <ul>
45  * <li> Enabling/disabling a class of suggestions. If the user doesn't
46  * want to change the copyright years, the user can disable
47  * this type of suggestion and it will no longer appear in the
48  * suggestion list.
49  * <li> Filtering the list. For example, you can choose to see only the
50  * suggestions pertaining to code metrics.
51  * </ul>
52  * <p>
53  *
54  * If you are providing suggestions, you need to create a new Suggestion
55  * Type for yourself. It's very easy. All you need to do is pick a unique
56  * id, and a brief (4 words or less) description.
57  * For example, the background compilation of java files may add suggestions
58  * that list the error messages and file position; the description of this
59  * suggestion type should be "Compiler Errors". This text will be shown
60  * in the popup menu where users can filter the list by suggestion type
61  * ("Show -> "All", "Compiler Errors", "Copyright Problems", "Audit Problems",
62  * "Performance Hotspots", etc.).
63  * <p>
64  * Then just register this suggestion type in your module's XML layer file,
65  * by adding something like this (under the top level &lt;filesystem&gt; tag) :
66  *
67
68  * <pre>
69  * &lt;folder name="Suggestions"&gt;
70  * &lt;folder name="Types"&gt;
71  * &lt;file name="copyrightcheck.xml" url="copyrightcheck.xml"/&gt;
72  * &lt;/folder&gt;
73  * &lt;/folder&gt;
74  * </pre>
75  * and then the file copyrightcheck.xml in your module (in the same
76  * directory as your layer file) contains something like this:
77  * <pre>
78  * &lt;?xml version="1.0"?&gt;
79  * &lt;!DOCTYPE type PUBLIC "-//NetBeans//DTD suggestion type 1.0//EN" "http://www.netbeans.org/dtds/suggestion-type-1_0.dtd"&gt;
80  * &lt;type
81  * name='CopyrightCheck'
82  * description_key='HINT_COPYRIGHT'
83  * long_description_key='HINT_COPYRIGHT'
84  * localizing_bundle='com.foo.bar.Bundle'
85  * icon='nbresloc:/com/foo/bar/copyrightCheck.gif'
86  * /&gt;
87  *
88  * </pre>
89  * <p>
90  * Then in your Bundle file identified above, add an entry like:
91  * <pre>
92  * HINT_COPYRIGHT=Copyright Problems
93  * LONGHINT_copyrighttype=Identify copyright notices in files where the copyright year does not include the current year.
94  * </pre>
95  * <p>
96  * Finally, pass in "copyrights" as the id for this type of suggestion
97  * to the Suggestion constructor as the type argument.
98  * Note: type ids have to be unique, so make sure you pick some string
99  * which is not going to conflict with any other modules' registered
100  * suggestion types. The "copyrights" example could probably be made
101  * more unique by adding a company prefix to it, e.g.
102  * "com.foo.bar-copyrights". I recommend you do that. For NetBeans
103  * modules (e.g. modules hosted on NetBeans' CVS server", simply use
104  * "nb-{modulename}-whatever". For example, the tasklist module would
105  * use a prefix of "nb-tasklist-".
106  *
107  * @author Tor Norbye
108  */
109 abstract public class Suggestion {
110
111     /** Agent that can mutate this suggestion */
112     SuggestionAgent agent;
113
114     private final PropertyChangeSupport JavaDoc supp = new PropertyChangeSupport JavaDoc(this);
115
116     /** Id of bound summary property. */
117     public static final String JavaDoc PROP_SUMMARY = "summary";
118
119     /** Id of bound icon property. */
120     public static final String JavaDoc PROP_ICON = "icon";
121
122     /** Id of bound details property. */
123     public static final String JavaDoc PROP_DETAILS = "details";
124
125     /** Id of bound priority property. */
126     public static final String JavaDoc PROP_PRIORITY = "priority";
127
128     /** Id of bound priority property. */
129     public static final String JavaDoc PROP_VALID = "valid";
130
131     private boolean valid;
132
133     // Attributes:
134
135     /** The icon to be used for this task - or null to use the default */
136     private Image JavaDoc icon = null;
137     /** A summary (one-line description) of the task */
138     private String JavaDoc summary = null;
139
140     /** A (possibly) multi-line summary of the task */
141     private String JavaDoc details = null;
142
143     // TODO - use special classes (e.g. Category, File, SuggestionType)
144 // for the category, file and type fields?
145
146     /** The category of this task */
147     //private String category = null;
148
149     /** The priority of this suggestion, defaults to SuggestionPriority.MEDIUM */
150     private SuggestionPriority priority = SuggestionPriority.MEDIUM;
151     
152     /** The type of task; for example source errors and import warnings are
153      * different types of tasks. This should be a user-readable (localized)
154      * string.
155     */
156     private String JavaDoc type = null;
157
158     /** The line position associated with the task */
159     private Line line = null;
160     
161     private SuggestionPerformer action = null;
162     
163     private FileObject fo;
164     
165     //private TimeToLive ttl = TimeToLive.SESSION;
166
167     // Note - if you add additional fields, remember to keep
168 // Task.copyFrom in sync.
169
170     /**
171      * Use {@link org.netbeans.modules.tasklist.client.SuggestionManager#createSuggestion}
172      * to create these.
173      * <p>
174      * NOTE: This constructor may not be called except by a
175      * SuggestionManager subclass; SuggestionManager implementations
176      * may refuse to add Suggestion instances not created by
177      * themselves.
178      *
179      * @param fo a FileObject this suggestion is associated with or null.
180      * @param type Type of the suggestion. See the class javadoc for a
181      * description of what this means.
182      * @param summary Summary to show for the suggestion
183      * @param action Action to perform when the suggestion should be fixed. May
184      * be null.
185      */
186     protected Suggestion(FileObject fo, final String JavaDoc type,
187         final String JavaDoc summary, final SuggestionPerformer action) {
188         this.fo = fo;
189         this.type = type;
190         this.summary = summary;
191         this.action = action;
192         valid = true;
193     }
194
195     /**
196      * Returns the FileObject accociated with this suggestion
197      *
198      * @return FileObject associated with this suggestion or null
199      */
200     public FileObject getFileObject() {
201         return fo;
202     }
203     
204     /**
205      * Associate another FileObject with this suggestion.
206      *
207      * @param fo FileObject associated with this suggestion or null
208      */
209     protected void setFileObject(FileObject fo) {
210         this.fo = fo;
211     }
212     
213     /**
214      * Set the summary of the task. This is a one-line description
215      * of the task. The summary should not be null.
216      *
217      * @param summary The summary of the task.
218      *
219      * @deprecated use SuggestionAgent#setSummary
220      */
221     protected void setSummary(final String JavaDoc summary) {
222         if (summary == null) {
223             throw new NullPointerException JavaDoc();
224         }
225         String JavaDoc old = getSummary();
226         if (old.equals(summary)) return;
227         this.summary = summary;
228         firePropertyChange(PROP_SUMMARY, old, summary);
229     }
230
231     /**
232      * Get the summary of the task.
233      * <p>
234      *
235      * @return The summary of the task.
236      */
237     public String JavaDoc getSummary() {
238         if (summary == null) {
239             summary = "";
240         }
241         return summary;
242     }
243
244     /**
245      * Set the details of the task. This could be multiple lines
246      * of description of the task. Can be null.
247      *
248      * @param details The details of the task
249      *
250      * @deprecated use SuggestionAgent#setDetails
251      */
252     protected void setDetails(final String JavaDoc details) {
253         String JavaDoc old = getDetails();
254         if (old.equals(details)) return;
255         this.details = details;
256         firePropertyChange(PROP_DETAILS, old, details);
257     }
258
259     /**
260      * Get the details of the task. Will never be null (but may
261      * be an empty string.)
262      * <p>
263      *
264      * @return The details of the task
265      */
266     public String JavaDoc getDetails() {
267         if (details == null) {
268             details = "";
269         }
270         return details;
271     }
272     
273     // No category for now; use the SuggestionType instead?
274 // /**
275 // * Set the category of the task. May be null.
276 // * <p>
277 // *
278 // * @param category The category of the task.
279 // */
280 // public void setCategory(String category) {
281 // this.category = category;
282 // }
283 //
284 // /**
285 // * Get the category of the task. May be null if no category
286 // * has been specified.
287 // * <p>
288 // *
289 // * @return The category of the task.
290 // */
291 // public String getCategory() {
292 // return category;
293 // }
294 //
295
296     /**
297      * Set the priority of the task.
298      * <p>
299      *
300      * @param priority The priority of the task.
301      *
302      * @deprecated use SuggestionAgent#setPriority
303      */
304     protected void setPriority(final SuggestionPriority priority) {
305         SuggestionPriority old = getPriority();
306         if (old == priority) return;
307         this.priority = priority;
308         firePropertyChange(PROP_PRIORITY, old, priority);
309     }
310
311     /**
312      * Get the priority of the task.
313      * <p>
314      *
315      * @return The priority of the task.
316      */
317     public SuggestionPriority getPriority() {
318         return priority;
319     }
320
321     /**
322      * Set the icon for the task. May be null; if so the default icon will
323      * be shown.
324      * <p>
325      *
326      * @param icon The icon to be shown with the task.
327      *
328      * @deprecated use SuggestionAgent#setIcon
329      */
330     protected void setIcon(final Image JavaDoc icon) {
331         Image JavaDoc old = getIcon();
332         if (old == icon) return;
333         this.icon = icon;
334         firePropertyChange(PROP_ICON, old, icon);
335     }
336
337     /**
338      * Get the icon for the task. May be null if no icon
339      * has been specified; if so the default will be used.
340      * <p>
341      *
342      * @return The icon for the task.
343      */
344     public Image JavaDoc getIcon() {
345         return icon;
346     }
347
348     /**
349      * Set the line (file position) associated with the suggestion.
350      * <p>
351      *
352      * @param line The line associated with the suggestion.
353      *
354      * @deprecated use SuggestionAgent#setLine, moreover it should be moved to contructor
355      */
356     protected void setLine(final Line line) {
357         this.line = line;
358     }
359
360     /**
361      * Get the line position for the suggestion.
362      * <p>
363      *
364      * @return The line position for the suggestion.
365      */
366     public Line getLine() {
367         return line;
368     }
369
370     /**
371      * Set the action to be performed when the task is executed.
372      * <p>
373      *
374      * @param action The action that the task represents.
375      *
376      * @deprecated use SuggestionAgent#setAction
377      */
378     protected final void setAction(final SuggestionPerformer action) {
379         this.action = action;
380     }
381
382     /**
383      * Get the action to be performed when this task is executed.
384      * Will not be null.
385      * <p>
386      *
387      * @return The action number in the task's file.
388      */
389     public SuggestionPerformer getAction() {
390         return action;
391     }
392
393     /**
394      * Set the type associated with this suggestion.
395      * Should not be null.
396      * <p>
397      *
398      * @param type The type name for this suggestion
399      *
400      * @deprecated should be constant since contruction time
401      */
402     protected void setType(final String JavaDoc type) {
403         this.type = type;
404     }
405
406     /**
407      * Get the type associated with this suggestion.
408      * <p>
409      *
410      * @return The type name for this suggestion
411      */
412     public String JavaDoc getType() {
413         return type;
414     }
415
416     /**
417      * Get data passed by the provider which created this
418      * suggestion. Exact meaning is provider dependent.
419      *
420      * @return The provider's data, or null.
421      * @since 1.4
422      */
423     public abstract Object JavaDoc getSeed();
424
425     /**
426      * Provider sets to invalid once it stop maintaining it.
427      *
428      * @return false if invalid
429      * @since 1.11
430      */
431     public boolean isValid() {
432         return valid;
433     }
434
435     void invalidate() {
436         if (valid == false) return;
437         valid = false;
438         supp.firePropertyChange(PROP_VALID, true, false);
439     }
440
441     /**
442      * Listen to changes in bean properties.
443      * @param l listener to be notified of changes
444      *
445      * @since 1.11
446      */
447     public final void addPropertyChangeListener(PropertyChangeListener JavaDoc l) {
448         supp.removePropertyChangeListener(l);
449         supp.addPropertyChangeListener(l);
450     }
451
452     /**
453      * Stop listening to changes in bean properties.
454      *
455      * @param l listener who will no longer be notified of changes
456      *
457      * @since 1.11
458      */
459     public final void removePropertyChangeListener(PropertyChangeListener JavaDoc l) {
460         supp.removePropertyChangeListener(l);
461     }
462
463
464     /**
465      * Fires a PropertyChangeEvent
466      *
467      * @param propertyName changed property
468      * @param oldValue old value (may be null)
469      * @param newValue new value (may be null)
470      *
471      * @since 1.11
472      */
473     protected void firePropertyChange(String JavaDoc propertyName, Object JavaDoc oldValue, Object JavaDoc newValue) {
474         supp.firePropertyChange(propertyName, oldValue, newValue);
475     }
476 }
477
Popular Tags