KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > spi > editor > completion > support > AsyncCompletionQuery


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.spi.editor.completion.support;
21
22 import javax.swing.text.Document JavaDoc;
23 import javax.swing.text.JTextComponent JavaDoc;
24 import org.netbeans.spi.editor.completion.CompletionResultSet;
25
26 /**
27  * Defines query processing of an asynchronous completion task.
28  * <br>
29  * The {@link #query(CompletionResultSet, Document, int)} abstract method
30  * needs to be implemented to define the asynchronous querying behavior.
31  * <br>
32  * In addition filtering of the result set computed during querying
33  * can be implemented by overriding the
34  * {@link #canFilter(JTextComponent)} and {@link #filter(CompletionResultSet)}.
35  *
36  * @author Miloslav Metelka, Dusan Balek
37  * @version 1.00
38  */
39
40 public abstract class AsyncCompletionQuery {
41     
42     private AsyncCompletionTask task;
43
44     /**
45      * Called in response to <code>CompletionTask.refresh(null)</code>.
46      * <br/>
47      * The method gets invoked once the the user types a character
48      * but the <code>CompletionTask.query()</code> was not yet invoked.
49      * <br/>
50      * The method may want to inspect the typed character before the caret
51      * position and decide whether the completion should be hidden
52      * if the typed character is inappropriate e.g. ";" for java completion.
53      *
54      * @since 1.3
55      */
56     protected void preQueryUpdate(JTextComponent JavaDoc component) {
57         // Always done in AWT thread - by default do nothing
58 }
59     
60     /**
61      * Perform the query and add results to the given result set.
62      * <br>
63      * This method is always invoked asynchronously in a <code>RequestProcessor</code>
64      * thread.
65      *
66      * @param resultSet result set into which the computed data should be added.
67      * The result set must always be finished
68      * by {@link org.netbeans.spi.editor.completion.CompletionResultSet#finish()}.
69      *
70      * @param doc document of the text component on which the query is being run.
71      * <br>
72      * Can be <code>null</code> if the corresponding component is null.
73      *
74      * @param caretOffset present caret offset of the text component
75      * on which the query is being run.
76      * <br>
77      * Can be <code>-1</code> if the corresponding component is null.
78      */
79     protected abstract void query(CompletionResultSet resultSet, Document JavaDoc doc, int caretOffset);
80     
81     /**
82      * Check whether the query results can successfully be filtered.
83      * <br>
84      * This method is invoked synchronously in response to call
85      * of {@link org.netbeans.spi.editor.completion.CompletionTask#refresh(CompletionResultSet)}
86      * in AWT thread. The asynchronous query method
87      * {@link #query(CompletionResultSet, Document, int)}
88      * may still be running when this method is invoked.
89      *
90      * <p>
91      * The implementation typically gets the text between
92      * caret offset remembered during query and the present caret offset
93      * (can be gathered by <code>component.getCaretPosition()</code>)
94      * and examines whether the results computed (or being computed) during the query
95      * (they should be collected and rememberred in the query method body)
96      * can be filtered appropriately.
97      * <br>
98      * For example in java the user can type e.g. "my" and so all the classes
99      * and fields and methods starting with "my" appropriate for the given context
100      * will be computed during the query.
101      * <br>
102      * If the user continues typing e.g. "myMethod" then the result set
103      * computed during the query can be filtered and this method should return true.
104      * <br>
105      * However if the user has typed e.g. "my()." then the original result
106      * set is useless and this method should return false.
107      *
108      * @param component text component for which this provider was constructed.
109      * It may be null if no text component was provided.
110      *
111      * @return true if the filtering can be done according to the current conditions
112      * (such as caret offset).
113      * <br>
114      * Return <code>false</code> if the filtering cannot be done or is not supported
115      * at all by this query implementation. The full asynchronous query
116      * will be invoked then.
117      * <br>
118      * If there is a query still in progress this method should check
119      * whether the results that the query is computing would be usable
120      * for the present coditions and if not it should tell the query
121      * to stop (e.g. through a boolean flag that the query checks).
122      * <br>
123      * Anyway if there is a query still in progress this method
124      * will be re-called again once the query finishes.
125      * <br>
126      * The default implementation just returns false.
127      */
128     protected boolean canFilter(JTextComponent JavaDoc component) {
129         return false;
130     }
131
132     /**
133      * Filter the data collected during the last
134      * {@link #query(CompletionResultSet, Document, int)} invocation.
135      * <br>
136      * This method is called in response
137      * to {@link org.netbeans.spi.editor.completion.CompletionTask#refresh(CompletionResultSet)} call.
138      * <br>
139      * This method is always invoked in AWT thread and it is supposed
140      * to finish quickly. It will only be invoked when a preceding
141      * synchronous invocation
142      * of {@link #canFilter(JTextComponent)} returned <code>true</code>
143      * and when there is currently no query in progress
144      * so it is safe to use the results computed during the query.
145      *
146      * <p>
147      * The implementation typically gets the text between
148      * caret offset remembered during query and the present caret offset
149      * (can be gathered by <code>component.getCaretPosition()</code>)
150      * and examines whether the results computed during the query
151      * (they should be rememberred in the query method body)
152      * can be filtered appropriately.
153      * <br>
154      * For example in java the user can type e.g. "my" and so all the classes
155      * and fields and methods starting with "my" appropriate for the given context
156      * will be computed during the query.
157      * <br>
158      * If the user continues typing e.g. "myMethod" then the result set
159      * computed during the query can be filtered and this method should return true.
160      * <br>
161      * However if the user has typed e.g. "my()." then the original result
162      * set is useless and this method should return false.
163      *
164      * <p>
165      * The default implementation does not support filtering
166      * and throws <code>IllegalStateException</code>.
167      *
168      * @param resultSet result set to which the filtering must add
169      * its results. The result set must always be finished
170      * by {@link org.netbeans.spi.editor.completion.CompletionResultSet#finish()}.
171      */
172     protected void filter(CompletionResultSet resultSet) {
173         throw new IllegalStateException JavaDoc("Filtering not supported"); // NOI18N
174 }
175     
176     /**
177      * Collect additional information in AWT thread before
178      * {@link #query(CompletionResultSet, Document, int)}
179      * is called asynchronously.
180      *
181      * @param component text component for which this provider was constructed.
182      * It may be null if no text component was provided.
183      */
184     protected void prepareQuery(JTextComponent JavaDoc component) {
185         // Always done in AWT thread - by default do nothing
186 }
187
188     /**
189      * Check whether the task corresponding to this query was cancelled.
190      * <br>
191      * Subclasses should check this flag and stop the query computation.
192      *
193      * @return true if the task was cancelled or false if not.
194      */
195     public final boolean isTaskCancelled() {
196         assert (task != null) : "isTaskCancelled() must not be called from constructor"; // NOI18N
197 return task.isCancelled();
198     }
199     
200     final void initTask(AsyncCompletionTask task) {
201         assert (task != null); // assign non-null task
202 assert (this.task == null); // not assigned yet
203 this.task = task;
204     }
205
206 }
207
Popular Tags