Performing code assist on Java code
The JDT API allows other plug-ins to perform code assist or code select on some Java elements.
Elements that allow this manipulation should implement
ICodeAssist
.
There are two kinds of manipulation:
- Code completion - compute the completion of a Java token.
- Code selection - answer the Java element indicated by the selected text of a
given offset and length.
In the Java model there are two elements that implement this interface:
IClassFile
and
ICompilationUnit
.
Code completion and code selection only answer results for a class file if it has attached source.
Code completion
Performing a code completion
One way to programmatically perform code completion is to invoke
ICodeAssist.codeComplete
.
You specify the offset in the compilation unit after which the code completion
is desired. You must also supply an instance of
CompletionRequestor
to accept the possible completions.
The method in
CompletionRequestor.accept(CompletionProposal)
accepts all kinds of proposals for code completion.
The methods of
CompletionProposal
give information that describes the proposed element (its
name, declaring type, etc.), its proposed position for insertion in the
compilation unit, and its relevance.
A completion requestor can accept many different kinds of completions.
This kind is given by
CompletionProposal.getKind
.
Some of the possible completion kinds are (The complete list of possible completion kinds can be seen on
CompletionProposal
):
The completion requestor must also be able to accept compilation
errors.
Completion relevance
Because there may be many different possible completions, the notion of
relevance is used to compare the relevance of a suggested completion to other
proposals. Relevance is represented by a positive integer. The value
has no implicit meaning except to be used relative to the value for other
proposals. The relevance of a code completion candidate can be affected by
the expected type of the expression, as it relates to the types in the
surrounding code, such as variable types, cast types, return types, etc.
The presence of an expected prefix or suffix in a completion also affects its
relevance.
Completion context
An instance of
CompletionRequestor
can also
accept a completion context. This context is given by the method
CompletionRequestor.acceptContext(CompletionContext)
and does not depend on a specific completion proposal. The methods of
CompletionContext
give information that describe
the general context like the offset of completion, the completed token, the completed token kind (name or string literal) and its position.
A
CompletionContext
can also give some
information about elements (
IJavaElement
) which are
related to the completion location. These elements are based on the content of the completed compilation unit's buffer and are not
the result of the last reconcile operation.
Some of these methods are:
-
getEnclosingElement()
- This method returns the innermost enclosing element
which contains the completion location
-
getVisibleElements(String)
- This method returns the elements which are visible from the completion location and which can be assigned to the given type
Code completion options
The JDT Core plug-in defines options that control the behavior of code
completion. These options can be changed by other plug-ins.
- Activate Visibility Sensitive Completion
When this option is active, code completion will not answer elements that are
not visible in the current context. (For example, it will not answer
private methods of a super class.)
- Automatic Qualification of Implicit Members
When this option is active, completion automatically qualifies completion on implicit field references and message expressions.
Additional options allow you to specify prefixes and suffixes for the
proposed completion names for fields, static fields, local variables, and method
arguments.
See
JDT Core Code AssistOptions
for more information about the code assist options and their defaults.
Code selection
Performing a code selection
Code selection is used to find the Java element represented by a range of
text (typically the selected text) in a compilation unit. To programmatically perform code selection,
you must invoke
ICodeAssist.codeSelect
.
You must supply the starting index location of the selection and its
length. The result is an array of Java elements. Most of the time there is only one element in the array, but if the selection is ambiguous then all the possible elements are returned.
In
the following example, code select is invoked for a compilation unit.
// Get the compilation unit
ICompilationUnit unit = ...;
// Get the offset and length
int offset = ...;
int length = ...;
// perform selection
IJavaElement[] elements = unit.codeSelect(offset, length);
System.out.println("the selected element is " + element[0].getElementName());
Selection at cursor location
When the selection length is specified as 0, a selection will be computed by
finding the complete token that encloses the specified offset. Consider
the following example method:
public void fooMethod(Object) {
}
If you specify an offset after the first character of
fooMethod, and you
specify a length of 0, then the selection will be computed to include the
entire token
fooMethod. If instead, you specify a length of 5, the
selection will considered as
ooMet.
