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:

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

The only 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 ICompletionRequestor to accept the possible completions.

Each method in ICompletionRequestor accepts a different kind of proposal for code completion.  The parameters of each method include text that describes the proposed element (its name, declaring type, etc.), its proposed position for insertion in the compilation unit, and its relevance.  

A completion requester can accept many different types of completions including the insertion of the following elements:

The completion requester must also be able to accept compilation errors.  

If your plug-in is not interested in every kind of code completion, a CompletionRequestorAdapter can be used so that you need only implement the kinds of completions you are interested in.  The following example shows an adapter that is only used to accept class completions.

   // Get the compilation unit
   ICompilationUnit unit = ...;
   
   // Get the offset
   int offset = ...;
   
   // Create the requester
   ICompletionRequestor requestor = new CompletionRequestorAdapter() {
      public void acceptClass(
         char[] packageName,
         char[] className,
         char[] completionName,
         int modifiers,
         int completionStart,
         int completionEnd,
         int relevance) {
         System.out.println("propose a class named " + new String(className));
      }
   };
   
   // Compute proposals
   unit.codeComplete(offset, requestor);

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.

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.  

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

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.