Eclipse JDT
Release 3.0

org.eclipse.jdt.core
Class CompletionProposal

java.lang.Object
  extended byorg.eclipse.jdt.core.CompletionProposal

public final class CompletionProposal
extends Object

Completion proposal.

In typical usage, the user working in a Java code editor issues a code assist command. This command results in a call to ICodeAssist.codeComplete(position, completionRequestor) passing the current position in the source code. The code assist engine analyzes the code in the buffer, determines what kind of Java language construct is at that position, and proposes ways to complete that construct. These proposals are instances of subclasses of CompletionProposal. These proposals, perhaps after sorting and filtering, are presented to the user to make a choice.

The proposal is as follows: insert the completion string into the source file buffer, replacing the characters between the start and end. The string can be arbitrary; for example, it might include not only the name of a method but a set of parentheses. Moreover, the source range may include source positions before or after the source position where ICodeAssist.codeComplete was invoked. The rest of the information associated with the proposal is to provide context that may help a user to choose from among competing proposals.

The completion engine creates instances of this class; it is not intended to be used by other clients.

Since:
3.0
See Also:
ICodeAssist.codeComplete(int, CompletionRequestor)

Field Summary
static int ANONYMOUS_CLASS_DECLARATION
          Completion is a declaration of an anonymous class.
static int FIELD_REF
          Completion is a reference to a field.
static int KEYWORD
          Completion is a keyword.
static int LABEL_REF
          Completion is a reference to a label.
static int LOCAL_VARIABLE_REF
          Completion is a reference to a local variable.
static int METHOD_DECLARATION
          Completion is a declaration of a method.
static int METHOD_REF
          Completion is a reference to a method.
static int PACKAGE_REF
          Completion is a reference to a package.
static int TYPE_REF
          Completion is a reference to a type.
static int VARIABLE_DECLARATION
          Completion is a declaration of a variable (locals, parameters, fields, etc.).
 
Method Summary
static CompletionProposal create(int kind, int completionOffset)
          Creates a basic completion proposal.
 char[][] findParameterNames(IProgressMonitor monitor)
          Finds the method parameter names.
 char[] getCompletion()
          Returns the proposed sequence of characters to insert into the source file buffer, replacing the characters at the specified source range.
 int getCompletionLocation()
          Returns the character index in the source file buffer where source completion was requested (the offsetparameter to ICodeAssist.codeComplete.
 char[] getDeclarationSignature()
          Returns the type or package signature of the relevant declaration in the context, or null if none.
 int getFlags()
          Returns the modifier flags relevant in the context, or Flags.AccDefault if none.
 int getKind()
          Returns the kind of completion being proposed.
 char[] getName()
          Returns the simple name of the method, field, member, or variable relevant in the context, or null if none.
 int getRelevance()
          Returns the relative relevance rating of this proposal.
 int getReplaceEnd()
          Returns the character index of the end of the subrange in the source file buffer to be replaced by the completion string.
 int getReplaceStart()
          Returns the character index of the start of the subrange in the source file buffer to be replaced by the completion string.
 char[] getSignature()
          Returns the signature of the method or type relevant in the context, or null if none.
 int getTokenEnd()
          Returns the character index of the end (exclusive) of the subrange in the source file buffer containing the relevant token.
 int getTokenStart()
          Returns the character index of the start of the subrange in the source file buffer containing the relevant token being completed.
 void setCompletion(char[] completion)
          Sets the proposed sequence of characters to insert into the source file buffer, replacing the characters at the specified source range.
 void setDeclarationSignature(char[] signature)
          Sets the type or package signature of the relevant declaration in the context, or null if none.
 void setFlags(int flags)
          Sets the modifier flags relevant in the context.
 void setName(char[] name)
          Sets the simple name of the method, field, member, or variable relevant in the context, or null if none.
 void setParameterNames(char[][] parameterNames)
          Sets the method parameter names.
 void setRelevance(int rating)
          Sets the relative relevance rating of this proposal.
 void setReplaceRange(int startIndex, int endIndex)
          Sets the character indices of the subrange in the source file buffer to be replaced by the completion string.
 void setSignature(char[] signature)
          Sets the signature of the method, field type, member type, relevant in the context, or null if none.
 void setTokenRange(int startIndex, int endIndex)
          Sets the character indices of the subrange in the source file buffer containing the relevant token being completed.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ANONYMOUS_CLASS_DECLARATION

public static final int ANONYMOUS_CLASS_DECLARATION
Completion is a declaration of an anonymous class. This kind of completion might occur in a context like "new List^;" and complete it to "new List() {}".

The following additional context information is available for this kind of completion proposal at little extra cost:

See Also:
getKind(), Constant Field Values

FIELD_REF

public static final int FIELD_REF
Completion is a reference to a field. This kind of completion might occur in a context like "this.ref^ = 0;" and complete it to "this.refcount = 0;".

The following additional context information is available for this kind of completion proposal at little extra cost:

See Also:
getKind(), Constant Field Values

KEYWORD

public static final int KEYWORD
Completion is a keyword. This kind of completion might occur in a context like "public cl^ Foo {}" and complete it to "public class Foo {}".

The following additional context information is available for this kind of completion proposal at little extra cost:

See Also:
getKind(), Constant Field Values

LABEL_REF

public static final int LABEL_REF
Completion is a reference to a label. This kind of completion might occur in a context like "break lo^;" and complete it to "break loop;".

The following additional context information is available for this kind of completion proposal at little extra cost:

See Also:
getKind(), Constant Field Values

LOCAL_VARIABLE_REF

public static final int LOCAL_VARIABLE_REF
Completion is a reference to a local variable. This kind of completion might occur in a context like "ke^ = 4;" and complete it to "keys = 4;".

The following additional context information is available for this kind of completion proposal at little extra cost:

See Also:
getKind(), Constant Field Values

METHOD_REF

public static final int METHOD_REF
Completion is a reference to a method. This kind of completion might occur in a context like "System.out.pr^();" and complete it to ""System.out.println();".

The following additional context information is available for this kind of completion proposal at little extra cost:

See Also:
getKind(), Constant Field Values

METHOD_DECLARATION

public static final int METHOD_DECLARATION
Completion is a declaration of a method. This kind of completion might occur in a context like "new List() {si^};" and complete it to "new List() {public int size() {} };".

The following additional context information is available for this kind of completion proposal at little extra cost:

See Also:
getKind(), Constant Field Values

PACKAGE_REF

public static final int PACKAGE_REF
Completion is a reference to a package. This kind of completion might occur in a context like "import java.u^.*;" and complete it to "import java.util.*;".

The following additional context information is available for this kind of completion proposal at little extra cost:

See Also:
getKind(), Constant Field Values

TYPE_REF

public static final int TYPE_REF
Completion is a reference to a type. Any kind of type is allowed, including primitive types, reference types, array types, parameterized types, and type variables. This kind of completion might occur in a context like "public static Str^ key;" and complete it to "public static String key;".

The following additional context information is available for this kind of completion proposal at little extra cost:

See Also:
getKind(), Constant Field Values

VARIABLE_DECLARATION

public static final int VARIABLE_DECLARATION
Completion is a declaration of a variable (locals, parameters, fields, etc.).

The following additional context information is available for this kind of completion proposal at little extra cost:

See Also:
getKind(), Constant Field Values
Method Detail

create

public static CompletionProposal create(int kind,
                                        int completionOffset)
Creates a basic completion proposal. All instance field have plausible default values unless otherwise noted.

Note that the constructors for this class are internal to the Java model implementation. Clients cannot directly create CompletionProposal objects.

Parameters:
kind - one of the kind constants declared on this class
completionOffset - original offset of code completion request
Returns:
a new completion proposal

getKind

public int getKind()
Returns the kind of completion being proposed.

The set of different kinds of completion proposals is expected to change over time. It is strongly recommended that clients do not assume that the kind is one of the ones they know about, and code defensively for the possibility of unexpected future growth.

Returns:
the kind; one of the kind constants declared on this class, or possibly a kind unknown to the caller

getCompletionLocation

public int getCompletionLocation()
Returns the character index in the source file buffer where source completion was requested (the offsetparameter to ICodeAssist.codeComplete.

Returns:
character index in source file buffer
See Also:
ICodeAssist.codeComplete(int,CompletionRequestor)

getTokenStart

public int getTokenStart()
Returns the character index of the start of the subrange in the source file buffer containing the relevant token being completed. This token is either the identifier or Java language keyword under, or immediately preceding, the original request offset. If the original request offset is not within or immediately after an identifier or keyword, then the position returned is original request offset and the token range is empty.

Returns:
character index of token start position (inclusive)

getTokenEnd

public int getTokenEnd()
Returns the character index of the end (exclusive) of the subrange in the source file buffer containing the relevant token. When there is no relevant token, the range is empty (getEndToken() == getStartToken()).

Returns:
character index of token end position (exclusive)

setTokenRange

public void setTokenRange(int startIndex,
                          int endIndex)
Sets the character indices of the subrange in the source file buffer containing the relevant token being completed. This token is either the identifier or Java language keyword under, or immediately preceding, the original request offset. If the original request offset is not within or immediately after an identifier or keyword, then the source range begins at original request offset and is empty.

If not set, defaults to empty subrange at [0,0).

Parameters:
startIndex - character index of token start position (inclusive)
endIndex - character index of token end position (exclusive)

getCompletion

public char[] getCompletion()
Returns the proposed sequence of characters to insert into the source file buffer, replacing the characters at the specified source range. The string can be arbitrary; for example, it might include not only the name of a method but a set of parentheses.

The client must not modify the array returned.

Returns:
the completion string

setCompletion

public void setCompletion(char[] completion)
Sets the proposed sequence of characters to insert into the source file buffer, replacing the characters at the specified source range. The string can be arbitrary; for example, it might include not only the name of a method but a set of parentheses.

If not set, defaults to an empty character array.

The completion engine creates instances of this class and sets its properties; this method is not intended to be used by other clients.

Parameters:
completion - the completion string

getReplaceStart

public int getReplaceStart()
Returns the character index of the start of the subrange in the source file buffer to be replaced by the completion string. If the subrange is empty (getReplaceEnd() == getReplaceStart()), the completion string is to be inserted at this index.

Note that while the token subrange is precisely specified, the replacement range is loosely constrained and may not bear any direct relation to the original request offset. For example, a it would be possible for a type completion to propose inserting an import declaration at the top of the compilation unit; or the completion might include trailing parentheses and punctuation for a method completion.

Returns:
replacement start position (inclusive)

getReplaceEnd

public int getReplaceEnd()
Returns the character index of the end of the subrange in the source file buffer to be replaced by the completion string. If the subrange is empty (getReplaceEnd() == getReplaceStart()), the completion string is to be inserted at this index.

Returns:
replacement end position (exclusive)

setReplaceRange

public void setReplaceRange(int startIndex,
                            int endIndex)
Sets the character indices of the subrange in the source file buffer to be replaced by the completion string. If the subrange is empty (startIndex == endIndex), the completion string is to be inserted at this index.

If not set, defaults to empty subrange at [0,0).

The completion engine creates instances of this class and sets its properties; this method is not intended to be used by other clients.

Parameters:
startIndex - character index of replacement start position (inclusive)
endIndex - character index of replacement end position (exclusive)

getRelevance

public int getRelevance()
Returns the relative relevance rating of this proposal.

Returns:
relevance rating of this proposal; ratings are positive; higher means better

setRelevance

public void setRelevance(int rating)
Sets the relative relevance rating of this proposal.

If not set, defaults to the lowest possible rating (1).

The completion engine creates instances of this class and sets its properties; this method is not intended to be used by other clients.

Parameters:
rating - relevance rating of this proposal; ratings are positive; higher means better

getDeclarationSignature

public char[] getDeclarationSignature()
Returns the type or package signature of the relevant declaration in the context, or null if none.

This field is available for the following kinds of completion proposals:

For kinds of completion proposals, this method returns null. Clients must not modify the array returned.

Returns:
the declaration signature, or null if none
See Also:
Signature

setDeclarationSignature

public void setDeclarationSignature(char[] signature)
Sets the type or package signature of the relevant declaration in the context, or null if none.

If not set, defaults to none.

The completion engine creates instances of this class and sets its properties; this method is not intended to be used by other clients.

Parameters:
signature - the type or package signature, or null if none

getName

public char[] getName()
Returns the simple name of the method, field, member, or variable relevant in the context, or null if none.

This field is available for the following kinds of completion proposals:

For kinds of completion proposals, this method returns null. Clients must not modify the array returned.

Returns:
the keyword, field, method, local variable, or member name, or null if none

setName

public void setName(char[] name)
Sets the simple name of the method, field, member, or variable relevant in the context, or null if none.

If not set, defaults to none.

The completion engine creates instances of this class and sets its properties; this method is not intended to be used by other clients.

Parameters:
name - the keyword, field, method, local variable, or member name, or null if none

getSignature

public char[] getSignature()
Returns the signature of the method or type relevant in the context, or null if none.

This field is available for the following kinds of completion proposals:

For kinds of completion proposals, this method returns null. Clients must not modify the array returned.

Returns:
the signature, or null if none
See Also:
Signature

setSignature

public void setSignature(char[] signature)
Sets the signature of the method, field type, member type, relevant in the context, or null if none.

If not set, defaults to none.

The completion engine creates instances of this class and sets its properties; this method is not intended to be used by other clients.

Parameters:
signature - the signature, or null if none

getFlags

public int getFlags()
Returns the modifier flags relevant in the context, or Flags.AccDefault if none.

This field is available for the following kinds of completion proposals:

For kinds of completion proposals, this method returns Flags.AccDefault.

Returns:
the modifier flags, or Flags.AccDefault if none
See Also:
Flags

setFlags

public void setFlags(int flags)
Sets the modifier flags relevant in the context.

If not set, defaults to none.

The completion engine creates instances of this class and sets its properties; this method is not intended to be used by other clients.

Parameters:
flags - the modifier flags, or Flags.AccDefault if none

findParameterNames

public char[][] findParameterNames(IProgressMonitor monitor)
Finds the method parameter names. This information is relevant to method reference (and method declaration proposals). Returns null if not available or not relevant.

The client must not modify the array returned.

Note that this is an expensive thing to compute, which may require parsing Java source files, etc. Use sparingly.

Parameters:
monitor - the progress monitor, or null if none
Returns:
the parameter names, or null if none or not available or not relevant

setParameterNames

public void setParameterNames(char[][] parameterNames)
Sets the method parameter names. This information is relevant to method reference (and method declaration proposals).

The completion engine creates instances of this class and sets its properties; this method is not intended to be used by other clients.

Parameters:
parameterNames - the parameter names, or null if none

Eclipse JDT
Release 3.0

Copyright (c) IBM Corp. and others 2000, 2004. All Rights Reserved.