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):

• annotation attribute - ANNOTATION_ATTRIBUTE_REF
• anonymous type - ANONYMOUS_CLASS_DECLARATION
• type reference - TYPE_REF
• field reference- FIELD_REF
• keyword - KEYWORD
• label reference - LABEL_REF
• local variable reference - LOCAL_VARIABLE_REF
• method reference - METHOD_REF
• method declaration - METHOD_DECLARATION
• package import or reference - PACKAGE_REF
• variable name - VARIABLE_DECLARATION

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 Assist Options 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) {
   }