KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > modules > tasklist > providers > DocumentSuggestionProvider


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.providers;
21
22 import java.util.List JavaDoc;
23 import javax.swing.text.Document JavaDoc;
24 import org.openide.loaders.DataObject;
25
26 /**
27  * This class is used for passive SuggestionProviders.
28  * Typically, you just need to implement <code>scan()</code> and
29  * <code>rescan()</code>.
30  * <p>
31  * The API does not define which thread these methods are called on,
32  * so don't make any assumptions. If you want to post something on
33  * the AWT event dispatching thread for example use SwingUtilities.
34  * <p>
35  * Note that changes in document attributes only are "ignored" (in
36  * the sense that they do not cause document edit notification.)
37  *
38  * <p>
39  * @author Tor Norbye
40  * @author Petr Kuzel, SuggestionContext refactoring
41  * @since 1.3 (well all signatures changed in this version)
42  *
43  * @todo why it extends SuggestionProvider. Its events are absolutely useless
44  * in this request-responce mode. I'd revert it beause being able to push
45  * suggestions is more advanced provider side feature tnan simply responding.
46  */
47 abstract public class DocumentSuggestionProvider extends SuggestionProvider {
48
49     /**
50      * Scan the given document for suggestions. Typically called
51      * when a document is shown or when a document is edited, but
52      * could also be called for example as part of a directory
53      * scan for suggestions.
54      * <p>
55      * @param env The environment being scanned
56      * @return list of tasks that result from the scan. May be null.
57      * <p>
58      * This method is called internally by the toolkit and should not be
59      * called directly by programs.
60      *
61      * @todo suggestions are created by SuggestionManager
62      * and that disallows to change equals logic
63      * that is needed to merge lists by clients. It
64      * can be solved by <code>List merge(List old, List updated)</code>
65      *
66      * @todo provider can find out that condions have
67      * changed (it can attach listeners to specifics sources)
68      * so it would like to inform consumer about change.
69      * E.g. SourceTaskProvider listens on settings change.
70      * On the other hand it's strange that SourceTaskProvider
71      * does not listen on document changes and leaves
72      * it on consumer. It's OK for this method but
73      * wrong for SuggestionManager registered ones.
74      * <p>
75      * Also fixing provides need to notify that fix
76      * eliminated the suggestion. Here could help
77      * suggestion valid flag intead of changing list
78      * membership.
79      *
80      * @todo another subtle obstacle right here is caused
81      * fact that implementation does not allow suggestion/task
82      * to be member of more tasklists. So all method clients
83      * must clone right now until this bug fixed. See
84      * SuggestionsBroker#performRescanInRP.
85      *
86      */
87     abstract public List JavaDoc scan(SuggestionContext env);
88 }
89
Popular Tags