Eclipse JDT
Release 3.1

org.eclipse.jdt.ui.text.java
Class CompletionProposalCollector

java.lang.Object
  extended byorg.eclipse.jdt.core.CompletionRequestor
      extended byorg.eclipse.jdt.ui.text.java.CompletionProposalCollector

public class CompletionProposalCollector
extends CompletionRequestor

Java UI implementation of CompletionRequestor. Produces IJavaCompletionProposals 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(cu);
 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
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
CompletionProposalCollector(ICompilationUnit cu)
          Creates a new instance ready to collect proposals.
CompletionProposalCollector(IJavaProject project)
          Creates a new instance ready to collect proposals.
 
Method Summary
 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.

 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.
 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.
 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.
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.

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

Subclasses may extend, but must call the super implementation.
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.
 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 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
isIgnored, setIgnored
 
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
Method Detail

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:

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[])

Eclipse JDT
Release 3.1

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