org.eclipse.jdt.ui.text.java

## Class CompletionProposalCollector

- java.lang.Object
- - org.eclipse.jdt.core.CompletionRequestor
  - - org.eclipse.jdt.ui.text.java.CompletionProposalCollector

    public class CompletionProposalCollector
    extends CompletionRequestor

Java UI implementation of `CompletionRequestor`. Produces `IJavaCompletionProposal`s from the proposal descriptors received via the `CompletionRequestor` interface.

The lifecycle of a `CompletionProposalCollector` instance is very simple:

     ICompilationUnit unit= ...
     int offset= ...

     CompletionProposalCollector collector= new CompletionProposalCollector(unit);
     unit.codeComplete(offset, collector);
     IJavaCompletionProposal[] proposals= collector.getJavaCompletionProposals();
     String errorMessage= collector.getErrorMessage();

     // display / process proposals

Note that after a code completion operation, the collector will store any received proposals, which may require a considerable amount of memory, so the collector should not be kept as a reference after a completion operation.

Clients may instantiate or subclass.

Since:
  3.1

### Field Summary

Fields
`protected static char[]` `METHOD_TRIGGERS` Triggers for method proposals without parameters.
`protected static char[]` `METHOD_WITH_ARGUMENTS_TRIGGERS` Triggers for method proposals.
`protected static char[]` `TYPE_TRIGGERS` Triggers for types.
`protected static char[]` `VAR_TRIGGER` Triggers for variables.

### Constructor Summary

Constructors
Constructor and Description
`CompletionProposalCollector(ICompilationUnit cu)` Creates a new instance ready to collect proposals.
`CompletionProposalCollector(ICompilationUnit cu, boolean ignoreAll)` Creates a new instance ready to collect proposals.
`CompletionProposalCollector(IJavaProject project)` Creates a new instance ready to collect proposals.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `accept(CompletionProposal proposal)` Proposes a completion.
`void` `acceptContext(CompletionContext context)` Propose the context in which the completion occurs.
`void` `beginReporting()` Pro forma notification sent before reporting a batch of completion proposals.
`void` `completionFailure(IProblem problem)` Notification of failure to produce any completions.
`protected int` `computeRelevance(CompletionProposal proposal)` Computes the relevance for a given `CompletionProposal`.
`protected IJavaCompletionProposal` `createJavaCompletionProposal(CompletionProposal proposal)` Creates a new java completion proposal from a core proposal.
`protected IContextInformation` `createMethodContextInformation(CompletionProposal methodProposal)` Creates the context information for a given method reference proposal.
`void` `endReporting()` Pro forma notification sent after reporting a batch of completion proposals.
`protected ICompilationUnit` `getCompilationUnit()` Returns the compilation unit that the receiver operates on, or `null` if the `IJavaProject` constructor was used to create the receiver.
`protected CompletionContext` `getContext()` Returns the `CompletionContext` for this completion operation.
`protected char[]` `getDeclaringType(CompletionProposal proposal)` Returns the type signature of the declaring type of a `CompletionProposal`, or `null` for proposals that do not have a declaring type.
`String` `getErrorMessage()` Returns an error message about any error that may have occurred during code completion, or the empty string if none.
`protected Image` `getImage(ImageDescriptor descriptor)` Returns a cached image for the given descriptor.
`protected JavaContentAssistInvocationContext` `getInvocationContext()` Returns the invocation context.
`IJavaCompletionProposal[]` `getJavaCompletionProposals()` Returns the unsorted list of received proposals.
`IJavaCompletionProposal[]` `getKeywordCompletionProposals()` Returns the unsorted list of received keyword proposals.
`protected CompletionProposalLabelProvider` `getLabelProvider()` Returns the proposal label provider used by the receiver.
`protected int` `getLength(CompletionProposal proposal)` Returns the replacement length of a given completion proposal.
`protected boolean` `isFiltered(CompletionProposal proposal)` Returns `true` if `proposal` is filtered, e.g.
`void` `setIgnored(int completionProposalKind, boolean ignore)` Sets whether the given kind of completion proposal is ignored.
`void` `setInvocationContext(JavaContentAssistInvocationContext context)` Sets the invocation context.
`void` `setReplacementLength(int length)` If the replacement length is set, it overrides the length returned from the content assist infrastructure.

### Methods inherited from class org.eclipse.jdt.core.CompletionRequestor

`getFavoriteReferences, isAllowingRequiredProposals, isExtendedContextRequired, isIgnored, setAllowsRequiredProposals, setFavoriteReferences, setRequireExtendedContext`

### Methods inherited from class java.lang.Object

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

### Field Detail

#### METHOD_TRIGGERS

    protected static final char[] METHOD_TRIGGERS

Triggers for method proposals without parameters. Do not modify.

#### METHOD_WITH_ARGUMENTS_TRIGGERS

    protected static final char[] METHOD_WITH_ARGUMENTS_TRIGGERS

Triggers for method proposals. Do not modify.

#### TYPE_TRIGGERS

    protected static final char[] TYPE_TRIGGERS

Triggers for types. Do not modify.

#### VAR_TRIGGER

    protected static final char[] VAR_TRIGGER

Triggers for variables. Do not modify.

### Constructor Detail

#### CompletionProposalCollector

    public CompletionProposalCollector(ICompilationUnit cu)

Creates a new instance ready to collect proposals. If the passed `ICompilationUnit` is not contained in an `IJavaProject`, no javadoc will be available as `additional info` on the created proposals.

Parameters:
  `cu` - the compilation unit that the result collector will operate on

#### CompletionProposalCollector

    public CompletionProposalCollector(IJavaProject project)

Creates a new instance ready to collect proposals. Note that proposals for anonymous types and method declarations are not created when using this constructor, as those need to know the compilation unit that they are created on. Use `CompletionProposalCollector(ICompilationUnit)` instead to get all proposals.

If the passed Java project is `null`, no javadoc will be available as `additional info` on the created (e.g. method and type) proposals.

Parameters:
  `project` - the project that the result collector will operate on, or `null`

#### CompletionProposalCollector

    public CompletionProposalCollector(ICompilationUnit cu,
                                       boolean ignoreAll)

Creates a new instance ready to collect proposals. If the passed `ICompilationUnit` is not contained in an `IJavaProject`, no javadoc will be available as `additional info` on the created proposals.

Parameters:
  `cu` - the compilation unit that the result collector will operate on
  `ignoreAll` - `true` to ignore all kinds of completion proposals
Since:
  3.4

### Method Detail

#### setIgnored

    public void setIgnored(int completionProposalKind,
                           boolean ignore)

Description copied from class: `CompletionRequestor`
Sets whether the given kind of completion proposal is ignored.

Overrides:
  `setIgnored` in class `CompletionRequestor`
Parameters:
  `completionProposalKind` - one of the kind constants declared on `CompletionProposal`
  `ignore` - `true` if the given kind of completion proposal is ignored by this requestor, and `false` if it is of interest
See Also:
  `CompletionRequestor.isIgnored(int)`, `CompletionProposal.getKind()`

#### setInvocationContext

    public void setInvocationContext(JavaContentAssistInvocationContext context)

Sets the invocation context.

Subclasses may extend.

Parameters:
  `context` - the invocation context
Since:
  3.2
See Also:
  `getInvocationContext()`

#### getInvocationContext

    protected final JavaContentAssistInvocationContext getInvocationContext()

Returns the invocation context. If none has been set via `setInvocationContext(JavaContentAssistInvocationContext)`, a new one is created.

Returns:
  invocationContext the invocation context
Since:
  3.2

#### accept

    public void accept(CompletionProposal proposal)

Proposes a completion. Has no effect if the kind of proposal is being ignored by this requestor. Callers should consider checking `CompletionRequestor.isIgnored(int)` before avoid creating proposal objects that would only be ignored.

Similarly, implementers should check `isIgnored(proposal.getKind())` and ignore proposals that have been declared as uninteresting. The proposal object passed is only valid for the duration of completion operation.

Subclasses may replace, but usually should not need to. Consider replacing createJavaCompletionProposal instead.

Specified by:
  `accept` in class `CompletionRequestor`
Parameters:
  `proposal` - the completion proposal

#### acceptContext

    public void acceptContext(CompletionContext context)

Propose the context in which the completion occurs.

This method is called one and only one time before any call to `CompletionRequestor.accept(CompletionProposal)`. The default implementation of this method does nothing. Clients may override.

Subclasses may extend, but usually should not need to.

Overrides:
  `acceptContext` in class `CompletionRequestor`
Parameters:
  `context` - the completion context
See Also:
  `getContext()`

#### beginReporting

    public void beginReporting()

Pro forma notification sent before reporting a batch of completion proposals.

The default implementation of this method does nothing. Clients may override.

Subclasses may extend, but must call the super implementation.

Overrides:
  `beginReporting` in class `CompletionRequestor`

#### completionFailure

    public void completionFailure(IProblem problem)

Notification of failure to produce any completions. The problem object explains what prevented completing.

The default implementation of this method does nothing. Clients may override to receive this kind of notice.

Subclasses may extend, but must call the super implementation.

Overrides:
  `completionFailure` in class `CompletionRequestor`
Parameters:
  `problem` - the problem object

#### endReporting

    public void endReporting()

Pro forma notification sent after reporting a batch of completion proposals.

The default implementation of this method does nothing. Clients may override.

Subclasses may extend, but must call the super implementation.

Overrides:
  `endReporting` in class `CompletionRequestor`

#### getErrorMessage

    public String getErrorMessage()

Returns an error message about any error that may have occurred during code completion, or the empty string if none.

Subclasses may replace or extend.

Returns:
  an error message or the empty string

#### getJavaCompletionProposals

    public final IJavaCompletionProposal[] getJavaCompletionProposals()

Returns the unsorted list of received proposals.

Returns:
  the unsorted list of received proposals

#### getKeywordCompletionProposals

    public final IJavaCompletionProposal[] getKeywordCompletionProposals()

Returns the unsorted list of received keyword proposals.

Returns:
  the unsorted list of received keyword proposals

#### setReplacementLength

    public final void setReplacementLength(int length)

If the replacement length is set, it overrides the length returned from the content assist infrastructure. Use this setting if code assist is called with a none empty selection.

Parameters:
  `length` - the new replacement length, relative to the code assist offset. Must be equal to or greater than zero.

#### computeRelevance

    protected int computeRelevance(CompletionProposal proposal)

Computes the relevance for a given `CompletionProposal`.

Subclasses may replace, but usually should not need to.

Parameters:
  `proposal` - the proposal to compute the relevance for
Returns:
  the relevance for `proposal`

#### createJavaCompletionProposal

    protected IJavaCompletionProposal createJavaCompletionProposal(CompletionProposal proposal)

Creates a new java completion proposal from a core proposal. This may involve computing the display label and setting up some context.

This method is called for every proposal that will be displayed to the user, which may be hundreds. Implementations should therefore defer as much work as possible: Labels should be computed lazily to leverage virtual table usage, and any information only needed when applying a proposal should not be computed yet.

Implementations may return `null` if a proposal should not be included in the list presented to the user.

Subclasses may extend or replace this method.

Parameters:
  `proposal` - the core completion proposal to create a UI proposal for
Returns:
  the created java completion proposal, or `null` if no proposal should be displayed

#### createMethodContextInformation

    protected final IContextInformation createMethodContextInformation(CompletionProposal methodProposal)

Creates the context information for a given method reference proposal. The passed proposal must be of kind `CompletionProposal.METHOD_REF`.

Parameters:
  `methodProposal` - the method proposal for which to create context information
Returns:
  the context information for `methodProposal`

#### getCompilationUnit

    protected final ICompilationUnit getCompilationUnit()

Returns the compilation unit that the receiver operates on, or `null` if the `IJavaProject` constructor was used to create the receiver.

Returns:
  the compilation unit that the receiver operates on, or `null`

#### getContext

    protected final CompletionContext getContext()

Returns the `CompletionContext` for this completion operation.

Returns:
  the `CompletionContext` for this completion operation
See Also:
  `CompletionRequestor.acceptContext(CompletionContext)`

#### getImage

    protected final Image getImage(ImageDescriptor descriptor)

Returns a cached image for the given descriptor.

Parameters:
  `descriptor` - the image descriptor to get an image for, may be `null`
Returns:
  the image corresponding to `descriptor`

#### getLabelProvider

    protected final CompletionProposalLabelProvider getLabelProvider()

Returns the proposal label provider used by the receiver.

Returns:
  the proposal label provider used by the receiver

#### getLength

    protected final int getLength(CompletionProposal proposal)

Returns the replacement length of a given completion proposal. The replacement length is usually the difference between the return values of `proposal.getReplaceEnd` and `proposal.getReplaceStart`, but this behavior may be overridden by calling `setReplacementLength(int)`.

Parameters:
  `proposal` - the completion proposal to get the replacement length for
Returns:
  the replacement length for `proposal`

#### isFiltered

    protected boolean isFiltered(CompletionProposal proposal)

Returns `true` if `proposal` is filtered, e.g. should not be proposed to the user, `false` if it is valid.

Subclasses may extends this method. The default implementation filters proposals set to be ignored via setIgnored and types set to be ignored in the preferences.

Parameters:
  `proposal` - the proposal to filter
Returns:
  `true` to filter `proposal`, `false` to let it pass

#### getDeclaringType

    protected final char[] getDeclaringType(CompletionProposal proposal)

Returns the type signature of the declaring type of a `CompletionProposal`, or `null` for proposals that do not have a declaring type. The return value is not `null` for proposals of the following kinds:

- METHOD_DECLARATION
- METHOD_NAME_REFERENCE
- METHOD_REF
- ANNOTATION_ATTRIBUTE_REF
- POTENTIAL_METHOD_DECLARATION
- ANONYMOUS_CLASS_DECLARATION
- FIELD_REF
- PACKAGE_REF (returns the package, but no type)
- TYPE_REF

Parameters:
  `proposal` - the completion proposal to get the declaring type for
Returns:
  the type signature of the declaring type, or `null` if there is none
See Also:
  `Signature.toCharArray(char[])`