org.eclipse.wst.jsdt.core
Class CompletionRequestor

java.lang.Object
  extended by org.eclipse.wst.jsdt.core.CompletionRequestor
Direct Known Subclasses:
CompletionProposalCollector

public abstract class CompletionRequestor
extends java.lang.Object

Abstract base class for a completion requestor which is passed completion proposals as they are generated in response to a code assist request.

This class is intended to be subclassed by clients.

The code assist engine normally invokes methods on completion requestor in the following sequence:

 requestor.beginReporting();
 requestor.acceptContext(context);
 requestor.accept(proposal_1);
 requestor.accept(proposal_2);
 ...
 requestor.endReporting();
 
If, however, the engine is unable to offer completion proposals for whatever reason, completionFailure is called with a problem object describing why completions were unavailable. In this case, the sequence of calls is:
 requestor.beginReporting();
 requestor.acceptContext(context);
 requestor.completionFailure(problem);
 requestor.endReporting();
 
In either case, the bracketing beginReporting endReporting calls are always made as well as acceptContext call.

See Also:
Provisional API: This class/interface is part of an interim API that is still under development and expected to change significantly before reaching stability. It is being made available at this early stage to solicit feedback from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken (repeatedly) as the API evolves.

Constructor Summary
CompletionRequestor()
          Creates a new completion requestor.
 
Method Summary
abstract  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.
 void endReporting()
          Pro forma notification sent after reporting a batch of completion proposals.
 java.lang.String[] getFavoriteReferences()
          Returns the favorite references which are used to compute some completion proposals.
 boolean isAllowingRequiredProposals(int proposalKind, int requiredProposalKind)
          Returns whether a proposal of a given kind with a required proposal of the given kind is allowed.
 boolean isIgnored(int completionProposalKind)
          Returns whether the given kind of completion proposal is ignored.
 void setAllowsRequiredProposals(int proposalKind, int requiredProposalKind, boolean allow)
          Sets whether a proposal of a given kind with a required proposal of the given kind is allowed.
 void setFavoriteReferences(java.lang.String[] favoriteImports)
          Set the favorite references which will be used to compute some completion proposals.
 void setIgnored(int completionProposalKind, boolean ignore)
          Sets whether the given kind of completion proposal is ignored.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CompletionRequestor

public CompletionRequestor()
Creates a new completion requestor. The requestor is interested in all kinds of completion proposals; none will be ignored.

Method Detail

isIgnored

public boolean isIgnored(int completionProposalKind)
Returns whether the given kind of completion proposal is ignored.

Parameters:
completionProposalKind - one of the kind constants declared on CompletionProposal
Returns:
true if the given kind of completion proposal is ignored by this requestor, and false if it is of interest
See Also:
setIgnored(int, boolean), CompletionProposal.getKind()

setIgnored

public void setIgnored(int completionProposalKind,
                       boolean ignore)
Sets whether the given kind of completion proposal is ignored.

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:
isIgnored(int), CompletionProposal.getKind()

isAllowingRequiredProposals

public boolean isAllowingRequiredProposals(int proposalKind,
                                           int requiredProposalKind)
Returns whether a proposal of a given kind with a required proposal of the given kind is allowed.

Parameters:
proposalKind - one of the kind constants declared
requiredProposalKind - one of the kind constants declared on CompletionProposal
Returns:
true if a proposal of a given kind with a required proposal of the given kind is allowed by this requestor, and false if it isn't of interest.

By default, all kinds of required proposals aren't allowed.

See Also:
setAllowsRequiredProposals(int, int, boolean), CompletionProposal.getKind(), CompletionProposal.getRequiredProposals()

setAllowsRequiredProposals

public void setAllowsRequiredProposals(int proposalKind,
                                       int requiredProposalKind,
                                       boolean allow)
Sets whether a proposal of a given kind with a required proposal of the given kind is allowed. Currently only a subset of kinds support required proposals. To see what combinations are supported you must look at CompletionProposal.getRequiredProposals() documentation.

Parameters:
proposalKind - one of the kind constants declared
requiredProposalKind - one of the kind constants declared on CompletionProposal
allow - true if a proposal of a given kind with a required proposal of the given kind is allowed by this requestor, and false if it isn't of interest
See Also:
isAllowingRequiredProposals(int, int), CompletionProposal.getKind(), CompletionProposal.getRequiredProposals()

getFavoriteReferences

public java.lang.String[] getFavoriteReferences()
Returns the favorite references which are used to compute some completion proposals.

Currently only on demand type references ("java.util.Arrays.*"), references to a static method or a static field are used to compute completion proposals. Other kind of reference could be used in the future.

Note: This Method only applies to ECMAScript 4 which is not yet supported

Returns:
favorite imports

setFavoriteReferences

public void setFavoriteReferences(java.lang.String[] favoriteImports)
Set the favorite references which will be used to compute some completion proposals. A favorite reference is a qualified reference as it can be seen in an import statement.

Note: This Method only applies to ECMAScript 4 which is not yet supported

Parameters:
favoriteImports -
See Also:
getFavoriteReferences()

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.


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.


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.

Parameters:
problem - the problem object

accept

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

Parameters:
proposal - the completion proposal
Throws:
java.lang.IllegalArgumentException - if the proposal is null

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 accept(CompletionProposal). The default implementation of this method does nothing. Clients may override.

Parameters:
context - the completion context