org.netbeans.spi.editor.completion.support

Class AsyncCompletionQuery

java.lang.Object

org.netbeans.spi.editor.completion.support.AsyncCompletionQuery

public abstract class AsyncCompletionQuery
extends Object

Defines query processing of an asynchronous completion task.
The AsyncCompletionQuery.query(CompletionResultSet, Document, int) abstract method needs to be implemented to define the asynchronous querying behavior.
In addition filtering of the result set computed during querying can be implemented by overriding the AsyncCompletionQuery.canFilter(JTextComponent) and AsyncCompletionQuery.filter(CompletionResultSet).

Constructor Summary

Constructors

Constructor and Description
AsyncCompletionQuery()

Method Summary

Modifier and Type	Method and Description
protected boolean	canFilter(JTextComponent component) Check whether the query results can successfully be filtered.
protected void	filter(CompletionResultSet resultSet) Filter the data collected during the last AsyncCompletionQuery.query(CompletionResultSet, Document, int) invocation.
boolean	isTaskCancelled() Check whether the task corresponding to this query was cancelled.
protected void	prepareQuery(JTextComponent component) Collect additional information in AWT thread before AsyncCompletionQuery.query(CompletionResultSet, Document, int) is called asynchronously.
protected void	preQueryUpdate(JTextComponent component) Called in response to CompletionTask.refresh(null).
protected abstract void	query(CompletionResultSet resultSet, Document doc, int caretOffset) Perform the query and add results to the given result set.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AsyncCompletionQuery

public AsyncCompletionQuery()

Method Detail

preQueryUpdate

protected void preQueryUpdate(JTextComponent component)

Called in response to CompletionTask.refresh(null).
The method gets invoked once the the user types a character but the CompletionTask.query() was not yet invoked.
The method may want to inspect the typed character before the caret position and decide whether the completion should be hidden if the typed character is inappropriate e.g. ";" for java completion.

Since:

1.3

query

protected abstract void query(CompletionResultSet resultSet,
                              Document doc,
                              int caretOffset)

Perform the query and add results to the given result set.
This method is always invoked asynchronously in a RequestProcessor thread.

Parameters:

resultSet - result set into which the computed data should be added. The result set must always be finished by CompletionResultSet.finish().

doc - document of the text component on which the query is being run.
Can be null if the corresponding component is null.

caretOffset - present caret offset of the text component on which the query is being run.
Can be -1 if the corresponding component is null.

canFilter

protected boolean canFilter(JTextComponent component)

Check whether the query results can successfully be filtered.
This method is invoked synchronously in response to call of CompletionTask.refresh(CompletionResultSet) in AWT thread. The asynchronous query method AsyncCompletionQuery.query(CompletionResultSet, Document, int) may still be running when this method is invoked.

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.

Parameters:

component - text component for which this provider was constructed. It may be null if no text component was provided.

Returns:

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.

filter

protected void filter(CompletionResultSet resultSet)

Filter the data collected during the last AsyncCompletionQuery.query(CompletionResultSet, Document, int) invocation.
This method is called in response to 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 AsyncCompletionQuery.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.

Parameters:

resultSet - result set to which the filtering must add its results. The result set must always be finished by CompletionResultSet.finish().

prepareQuery

protected void prepareQuery(JTextComponent component)

Collect additional information in AWT thread before AsyncCompletionQuery.query(CompletionResultSet, Document, int) is called asynchronously.

Parameters:

component - text component for which this provider was constructed. It may be null if no text component was provided.

isTaskCancelled

public final boolean isTaskCancelled()

Check whether the task corresponding to this query was cancelled.
Subclasses should check this flag and stop the query computation.

Returns:

true if the task was cancelled or false if not.