CompletionTask.refresh(null).
* CompletionTask.query() was not yet invoked.
* RequestProcessor
* thread.
*
* @param resultSet result set into which the computed data should be added.
* The result set must always be finished
* by {@link org.netbeans.spi.editor.completion.CompletionResultSet#finish()}.
*
* @param doc document of the text component on which the query is being run.
* null if the corresponding component is null.
*
* @param caretOffset present caret offset of the text component
* on which the query is being run.
* -1 if the corresponding component is null.
*/
protected abstract void query(CompletionResultSet resultSet, Document doc, int caretOffset);
/**
* Check whether the query results can successfully be filtered.
*
* The implementation typically gets the text between
* caret offset remembered during query and the present caret offset
* (can be gathered by component.getCaretPosition())
* and examines whether the results computed (or being computed) during the query
* (they should be collected and rememberred in the query method body)
* can be filtered appropriately.
*
* For example in java the user can type e.g. "my" and so all the classes
* and fields and methods starting with "my" appropriate for the given context
* will be computed during the query.
*
* If the user continues typing e.g. "myMethod" then the result set
* computed during the query can be filtered and this method should return true.
*
* However if the user has typed e.g. "my()." then the original result
* set is useless and this method should return false.
*
* @param component text component for which this provider was constructed.
* It may be null if no text component was provided.
*
* @return true if the filtering can be done according to the current conditions
* (such as caret offset).
*
* Return false if the filtering cannot be done or is not supported
* at all by this query implementation. The full asynchronous query
* will be invoked then.
*
* If there is a query still in progress this method should check
* whether the results that the query is computing would be usable
* for the present coditions and if not it should tell the query
* to stop (e.g. through a boolean flag that the query checks).
*
* Anyway if there is a query still in progress this method
* will be re-called again once the query finishes.
*
* The default implementation just returns false.
*/
protected boolean canFilter(JTextComponent component) {
return false;
}
/**
* Filter the data collected during the last
* {@link #query(CompletionResultSet, Document, int)} invocation.
*
* This method is called in response
* to {@link org.netbeans.spi.editor.completion.CompletionTask#refresh(CompletionResultSet)} call.
*
* This method is always invoked in AWT thread and it is supposed
* to finish quickly. It will only be invoked when a preceding
* synchronous invocation
* of {@link #canFilter(JTextComponent)} returned true
* and when there is currently no query in progress
* so it is safe to use the results computed during the query.
*
*
* The implementation typically gets the text between
* caret offset remembered during query and the present caret offset
* (can be gathered by component.getCaretPosition())
* and examines whether the results computed during the query
* (they should be rememberred in the query method body)
* can be filtered appropriately.
*
* For example in java the user can type e.g. "my" and so all the classes
* and fields and methods starting with "my" appropriate for the given context
* will be computed during the query.
*
* If the user continues typing e.g. "myMethod" then the result set
* computed during the query can be filtered and this method should return true.
*
* However if the user has typed e.g. "my()." then the original result
* set is useless and this method should return false.
*
*
* The default implementation does not support filtering
* and throws IllegalStateException.
*
* @param resultSet result set to which the filtering must add
* its results. The result set must always be finished
* by {@link org.netbeans.spi.editor.completion.CompletionResultSet#finish()}.
*/
protected void filter(CompletionResultSet resultSet) {
throw new IllegalStateException("Filtering not supported"); // NOI18N
}
/**
* Collect additional information in AWT thread before
* {@link #query(CompletionResultSet, Document, int)}
* is called asynchronously.
*
* @param component text component for which this provider was constructed.
* It may be null if no text component was provided.
*/
protected void prepareQuery(JTextComponent component) {
// Always done in AWT thread - by default do nothing
}
/**
* Check whether the task corresponding to this query was cancelled.
*
* Subclasses should check this flag and stop the query computation.
*
* @return true if the task was cancelled or false if not.
*/
public final boolean isTaskCancelled() {
assert (task != null) : "isTaskCancelled() must not be called from constructor"; // NOI18N
return task.isCancelled();
}
final void initTask(AsyncCompletionTask task) {
assert (task != null); // assign non-null task
assert (this.task == null); // not assigned yet
this.task = task;
}
}