org.eclipse.jdt/org.eclipse.jdt.core/3.20.0 : org/eclipse/jdt/core/CompletionRequestor.java

CompletionRequestor
http://www.eclipse.org/jdt: Java Development Tools Core (Eclipse Foundation)
Eclipse Public License - v 2.0
Copyright (c) 2004, 2019 IBM Corporation and others.
This program and the accompanying materials
are made available under the terms of the Eclipse Public License 2.0
which accompanies this distribution, and is available at
https://www.eclipse.org/legal/epl-2.0/
SPDX-License-Identifier: EPL-2.0
Contributors:
    IBM Corporation - initial API and implementation
/*******************************************************************************
 * Copyright (c) 2004, 2019 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jdt.core;

import org.eclipse.jdt.core.compiler.IProblem;

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.


The class was introduced in 3.0 as a more evolvable replacement
for the ICompletionRequestor interface.

See Also: ICodeAssist
Since: 3.0/**
 * Abstract base class for a completion requestor which is passed completion
 * proposals as they are generated in response to a code assist request.
 * <p>
 * This class is intended to be subclassed by clients.
 * </p>
 * <p>
 * The code assist engine normally invokes methods on completion
 * requestor in the following sequence:
 * <pre>
 * requestor.beginReporting();
 * requestor.acceptContext(context);
 * requestor.accept(proposal_1);
 * requestor.accept(proposal_2);
 * ...
 * requestor.endReporting();
 * </pre>
 * <p>
 * If, however, the engine is unable to offer completion proposals
 * for whatever reason, <code>completionFailure</code> is called
 * with a problem object describing why completions were unavailable.
 * In this case, the sequence of calls is:
 * <pre>
 * requestor.beginReporting();
 * requestor.acceptContext(context);
 * requestor.completionFailure(problem);
 * requestor.endReporting();
 * </pre>
 * <p>
 * In either case, the bracketing <code>beginReporting</code>
 * <code>endReporting</code> calls are always made as well as
 * <code>acceptContext</code> call.
 * </p>
 * <p>
 * The class was introduced in 3.0 as a more evolvable replacement
 * for the <code>ICompletionRequestor</code> interface.
 * </p>
 *
 * @see ICodeAssist
 * @since 3.0
 */
public abstract class CompletionRequestor {

	The set of CompletionProposal kinds that this requestor
ignores; 0 means the set is empty.
1 << completionProposalKind
/**
	 * The set of CompletionProposal kinds that this requestor
	 * ignores; <code>0</code> means the set is empty.
	 * 1 << completionProposalKind
	 */
	private int ignoreSet = 0;

	private String[] favoriteReferences;

	The set of CompletionProposal kinds that this requestor
allows for required proposals; 0 means the set is empty.
1 << completionProposalKind
/**
	 * The set of CompletionProposal kinds that this requestor
	 * allows for required proposals; <code>0</code> means the set is empty.
	 * 1 << completionProposalKind
	 */
	private int requiredProposalAllowSet[] = null;

	private boolean requireExtendedContext = false;

	Creates a new completion requestor.
The requestor is interested in all kinds of completion
proposals; none will be ignored.
Calls to this constructor are identical to calls to CompletionRequestor(false)
/**
	 * Creates a new completion requestor.
	 * The requestor is interested in all kinds of completion
	 * proposals; none will be ignored.
	 *
	 * Calls to this constructor are identical to calls to <code>CompletionRequestor(false)</code>
	 */
	public CompletionRequestor() {
		this(false);
	}

	Creates a new completion requestor.
If ignoreAll is true the requestor is not interested in
all kinds of completion proposals; all will be ignored. For each kind of completion proposals
that is of interest, setIgnored(kind, false) must be called.
If ignoreAll is false the requestor is interested in
all kinds of completion proposals; none will be ignored.
Params: ignoreAll – true to ignore all kinds of completion proposals,
and false to propose all kinds
Since: 3.4/**
	 * Creates a new completion requestor.
	 * If <code>ignoreAll</code> is <code>true</code> the requestor is not interested in
	 * all kinds of completion proposals; all will be ignored. For each kind of completion proposals
	 * that is of interest, <code>setIgnored(kind, false)</code> must be called.
	 * If <code>ignoreAll</code> is <code>false</code> the requestor is interested in
	 * all kinds of completion proposals; none will be ignored.
	 *
	 * @param ignoreAll <code>true</code> to ignore all kinds of completion proposals,
	 * and <code>false</code> to propose all kinds
	 *
	 * @since 3.4
	 */
	public CompletionRequestor(boolean ignoreAll) {
		this.ignoreSet = ignoreAll ? 0xffffffff : 0x00000000;
	}

	Returns whether the given kind of completion proposal is ignored.
Params: completionProposalKind – one of the kind constants declared
on CompletionProposal
See Also: setIgnored(int, boolean)
CompletionProposal.getKind()
Returns: true if the given kind of completion proposal
is ignored by this requestor, and false if it is of
interest/**
	 * Returns whether the given kind of completion proposal is ignored.
	 *
	 * @param completionProposalKind one of the kind constants declared
	 * on <code>CompletionProposal</code>
	 * @return <code>true</code> if the given kind of completion proposal
	 * is ignored by this requestor, and <code>false</code> if it is of
	 * interest
	 * @see #setIgnored(int, boolean)
	 * @see CompletionProposal#getKind()
	 */
	public boolean isIgnored(int completionProposalKind) {
		if (completionProposalKind < CompletionProposal.FIRST_KIND
			|| completionProposalKind > CompletionProposal.LAST_KIND) {
				throw new IllegalArgumentException("Unknown kind of completion proposal: "+completionProposalKind); //$NON-NLS-1$
		}
		return 0 != (this.ignoreSet & (1 << completionProposalKind));
	}

	Sets whether the given kind of completion proposal is ignored.
Params: 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()/**
	 * Sets whether the given kind of completion proposal is ignored.
	 *
	 * @param completionProposalKind one of the kind constants declared
	 * on <code>CompletionProposal</code>
	 * @param ignore <code>true</code> if the given kind of completion proposal
	 * is ignored by this requestor, and <code>false</code> if it is of
	 * interest
	 * @see #isIgnored(int)
	 * @see CompletionProposal#getKind()
	 */
	public void setIgnored(int completionProposalKind, boolean ignore) {
		if (completionProposalKind < CompletionProposal.FIRST_KIND
			|| completionProposalKind > CompletionProposal.LAST_KIND) {
				throw new IllegalArgumentException("Unknown kind of completion proposal: "+completionProposalKind); //$NON-NLS-1$
		}
		if (ignore) {
			this.ignoreSet |= (1 << completionProposalKind);
		} else {
			this.ignoreSet &= ~(1 << completionProposalKind);
		}
	}

	Returns whether a proposal of a given kind with a required proposal
of the given kind is allowed.
Params: proposalKind – one of the kind constants declared
requiredProposalKind – one of the kind constants declared
on CompletionProposal
See Also: setAllowsRequiredProposals(int, int, boolean)
CompletionProposal.getKind()
CompletionProposal.getRequiredProposals()
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.
Since: 3.3/**
	 * Returns whether a proposal of a given kind with a required proposal
	 * of the given kind is allowed.
	 *
	 * @param proposalKind one of the kind constants declared
	 * @param requiredProposalKind one of the kind constants declared
	 * on <code>CompletionProposal</code>
	 * @return <code>true</code> if a proposal of a given kind with a required proposal
	 * of the given kind is allowed by this requestor, and <code>false</code>
	 * if it isn't of interest.
	 * <p>
	 * By default, all kinds of required proposals aren't allowed.
	 * </p>
	 * @see #setAllowsRequiredProposals(int, int, boolean)
	 * @see CompletionProposal#getKind()
	 * @see CompletionProposal#getRequiredProposals()
	 *
	 * @since 3.3
	 */
	public boolean isAllowingRequiredProposals(int proposalKind, int requiredProposalKind) {
		if (proposalKind < CompletionProposal.FIRST_KIND
			|| proposalKind > CompletionProposal.LAST_KIND) {
				throw new IllegalArgumentException("Unknown kind of completion proposal: "+requiredProposalKind); //$NON-NLS-1$
			}

		if (requiredProposalKind < CompletionProposal.FIRST_KIND
			|| requiredProposalKind > CompletionProposal.LAST_KIND) {
				throw new IllegalArgumentException("Unknown required kind of completion proposal: "+requiredProposalKind); //$NON-NLS-1$
		}
		if (this.requiredProposalAllowSet == null) return false;

		return 0 != (this.requiredProposalAllowSet[proposalKind] & (1 << requiredProposalKind));
	}

	Sets whether a proposal of a given kind with a required proposal of the given kind is allowed. A required proposal of a given kind is proposed even if isIgnored(int) return true for that kind. Currently only a subset of kinds support required proposals. To see what combinations are supported you must look at CompletionProposal.getRequiredProposals() documentation. 
Params: 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()
Since: 3.3/**
	 * Sets whether a proposal of a given kind with a required proposal
	 * of the given kind is allowed.
	 *
	 * A required proposal of a given kind is proposed even if {@link #isIgnored(int)}
	 * return <code>true</code> for that kind.
	 *
	 * Currently only a subset of kinds support required proposals. To see what combinations
	 * are supported you must look at {@link CompletionProposal#getRequiredProposals()}
	 * documentation.
	 *
	 * @param proposalKind one of the kind constants declared
	 * @param requiredProposalKind one of the kind constants declared
	 * on <code>CompletionProposal</code>
	 * @param allow <code>true</code> if a proposal of a given kind with a required proposal
	 * of the given kind is allowed by this requestor, and <code>false</code>
	 * if it isn't of interest
	 * @see #isAllowingRequiredProposals(int, int)
	 * @see CompletionProposal#getKind()
	 * @see CompletionProposal#getRequiredProposals()
	 *
	 * @since 3.3
	 */
	public void setAllowsRequiredProposals(int proposalKind, int requiredProposalKind, boolean allow) {
		if (proposalKind < CompletionProposal.FIRST_KIND
			|| proposalKind > CompletionProposal.LAST_KIND) {
				throw new IllegalArgumentException("Unknown kind of completion proposal: "+requiredProposalKind); //$NON-NLS-1$
		}
		if (requiredProposalKind < CompletionProposal.FIRST_KIND
			|| requiredProposalKind > CompletionProposal.LAST_KIND) {
				throw new IllegalArgumentException("Unknown required kind of completion proposal: "+requiredProposalKind); //$NON-NLS-1$
		}

		if (this.requiredProposalAllowSet == null) {
			this.requiredProposalAllowSet = new int[CompletionProposal.LAST_KIND + 1];
		}

		if (allow) {
			this.requiredProposalAllowSet[proposalKind] |= (1 << requiredProposalKind);
		} else {
			this.requiredProposalAllowSet[proposalKind] &= ~(1 << requiredProposalKind);
		}
	}

	Returns the favorite references which are used to compute some completion proposals.

A favorite reference is a qualified reference as it can be seen in an import statement.

e.g. {"java.util.Arrays"}

It can be an on demand reference.

e.g. {"java.util.Arrays.*"}
It can be a reference to a static method or field (as in a static import)

e.g. {"java.util.Arrays.equals"}


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.

Returns: favorite imports
Since: 3.3/**
	 * Returns the favorite references which are used to compute some completion proposals.
	 * <p>
	 * A favorite reference is a qualified reference as it can be seen in an import statement.<br>
	 * e.g. <code>{"java.util.Arrays"}</code><br>
	 * It can be an on demand reference.<br>
	 * e.g. <code>{"java.util.Arrays.*"}</code>
	 * It can be a reference to a static method or field (as in a static import)<br>
	 * e.g. <code>{"java.util.Arrays.equals"}</code>
	 * </p>
	 * <p>
	 * Currently only on demand type references (<code>"java.util.Arrays.*"</code>),
	 * 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.
	 * </p>
	 * @return favorite imports
	 *
	 * @since 3.3
	 */
	public String[] getFavoriteReferences() {
		return this.favoriteReferences;
	}

	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.

Params: favoriteImports – 
See Also: getFavoriteReferences()
Since: 3.3/**
	 * 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.<br>
	 *
	 * @param favoriteImports
	 *
	 * @see #getFavoriteReferences()
	 *
	 * @since 3.3
	 */
	public void setFavoriteReferences(String[] favoriteImports) {
		this.favoriteReferences = favoriteImports;
	}

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

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

/**
	 * Pro forma notification sent before reporting a batch of
	 * completion proposals.
	 * <p>
	 * The default implementation of this method does nothing.
	 * Clients may override.
	 * </p>
	 */
	public void beginReporting() {
		// do nothing
	}

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

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

/**
	 * Pro forma notification sent after reporting a batch of
	 * completion proposals.
	 * <p>
	 * The default implementation of this method does nothing.
	 * Clients may override.
	 * </p>
	 */
	public void endReporting() {
		// do nothing
	}

	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.

Params: problem – the problem object/**
	 * Notification of failure to produce any completions.
	 * The problem object explains what prevented completing.
	 * <p>
	 * The default implementation of this method does nothing.
	 * Clients may override to receive this kind of notice.
	 * </p>
	 *
	 * @param problem the problem object
	 */
	public void completionFailure(IProblem problem) {
		// default behavior is to ignore
	}

	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. 
Params: proposal – the completion proposal
Throws: IllegalArgumentException – if the proposal is null/**
	 * Proposes a completion. Has no effect if the kind of proposal
	 * is being ignored by this requestor. Callers should consider
	 * checking {@link #isIgnored(int)} before avoid creating proposal
	 * objects that would only be ignored.
	 * <p>
	 * Similarly, implementers should check
	 * {@link #isIgnored(int) 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.
	 *
	 * @param proposal the completion proposal
	 * @exception IllegalArgumentException if the proposal is null
	 */
	public abstract void accept(CompletionProposal proposal);

	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. 
Params: context – the completion context
Since: 3.1/**
	 * Propose the context in which the completion occurs.
	 * <p>
	 * This method is called one and only one time before any call to
	 * {@link #accept(CompletionProposal)}.
	 * The default implementation of this method does nothing.
	 * Clients may override.
	 * </p>
	 * @param context the completion context
	 *
	 * @since 3.1
	 */
	public void acceptContext(CompletionContext context) {
		// do nothing
	}

	Returns whether this requestor requires an extended context.
By default this method return false.
See Also: CompletionContext.isExtended()
Returns: true if this requestor requires an extended context.
Since: 3.4/**
	 * Returns whether this requestor requires an extended context.
	 *
	 * By default this method return <code>false</code>.
	 *
	 * @return <code>true</code> if this requestor requires an extended context.
	 *
	 * @see CompletionContext#isExtended()
	 *
	 * @since 3.4
	 */
	public boolean isExtendedContextRequired() {
		return this.requireExtendedContext;
	}


	Sets whether this requestor requires an extended context.
Params: require – true if this requestor requires an extended context.
See Also: CompletionContext.isExtended()
Since: 3.4/**
	 * Sets whether this requestor requires an extended context.
	 *
	 * @param require <code>true</code> if this requestor requires an extended context.
	 *
	 * @see CompletionContext#isExtended()
	 *
	 * @since 3.4
	 */
	public void setRequireExtendedContext(boolean require) {
		this.requireExtendedContext = require;
	}

	If this returns true, exclude test sources and dependencies.
See Also: IClasspathAttribute.TEST
Returns: true if this requestor does not want to get any completions from test code.
Since: 3.14/**
	 * If this returns true, exclude test sources and dependencies.
	 * 
	 * @return <code>true</code> if this requestor does not want to get any completions from test code.
	 * @see IClasspathAttribute#TEST
	 * @since 3.14
	 */
	public boolean isTestCodeExcluded() {
		return false;
	}
}
Params:	ignoreAll – `true` to ignore all kinds of completion proposals, and `false` to propose all kinds
Since:	3.4
Params:	completionProposalKind – one of the kind constants declared on `CompletionProposal`
See Also:	setIgnored(int, boolean) CompletionProposal.getKind()
Returns:	`true` if the given kind of completion proposal is ignored by this requestor, and `false` if it is of interest
Params:	proposalKind – one of the kind constants declared requiredProposalKind – one of the kind constants declared on `CompletionProposal`
See Also:	setAllowsRequiredProposals(int, int, boolean) CompletionProposal.getKind() CompletionProposal.getRequiredProposals()
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.
Since:	3.3
Params:	favoriteImports –
See Also:	getFavoriteReferences()
Since:	3.3
Params:	proposal – the completion proposal
Throws:	IllegalArgumentException – if the proposal is null
See Also:	CompletionContext.isExtended()
Returns:	`true` if this requestor requires an extended context.
Since:	3.4
Params:	require – `true` if this requestor requires an extended context.
See Also:	CompletionContext.isExtended()
Since:	3.4
See Also:	IClasspathAttribute.TEST
Returns:	`true` if this requestor does not want to get any completions from test code.
Since:	3.14
/

org.eclipse.jdt/ org.eclipse.jdt.core/ 3.20.0/ org/eclipse/jdt/core/CompletionRequestor.java
