core/plugins/org.eclipse.dltk.core/model/org/eclipse/dltk/core/CompletionRequestor.java

/*******************************************************************************
 * Copyright (c) 2004, 2007 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 
 *******************************************************************************/
package org.eclipse.dltk.core;

import org.eclipse.core.runtime.Assert;
import org.eclipse.dltk.codeassist.RelevanceConstants;
import org.eclipse.dltk.compiler.problem.IProblem;

/**
 * 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 requestors in
 * the following sequence:
 * 
 * <pre>
 * requestor.beginReporting();
 * requestor.acceptContext(context);
 * requestor.accept(proposal_1);
 * requestor.accept(proposal_2);
 * ...
 * requestor.endReporting();
 * </pre>
 * 
 * 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>
 * 
 * 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
 * 
 */
public abstract class CompletionRequestor {

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

	/**
	 * Creates a new completion requestor. The requestor is interested in all
	 * kinds of completion proposals; none will be ignored.
	 */
	public CompletionRequestor() {
		// do nothing
	}

	public static final int ALL = 1 << 31;
	private static final int ALL_BITSET = Integer.MAX_VALUE;

	/**
	 * Returns whether the given kind of completion proposal is ignored.
	 * 
	 * @param completionProposalKind
	 *            one of the kind constants declared on
	 *            <code>CompletionProposal</code> or {@link #ALL}
	 * @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 final boolean isIgnored(int completionProposalKind) {
		if (completionProposalKind == ALL) {
			return this.ignoreSet == ALL_BITSET;
		}
		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.
	 * 
	 * @param completionProposalKind
	 *            one of the kind constants declared on
	 *            <code>CompletionProposal</code> or {@link #ALL}
	 * @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 final void setIgnored(int completionProposalKind, boolean ignore) {
		if (completionProposalKind == ALL) {
			this.ignoreSet = ignore ? ALL_BITSET : 0;
			return;
		}
		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);
		}
	}

	/**
	 * 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.
	 * <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.
	 * <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
	 * {@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.
	 * <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
	 * 
	 * 
	 */
	public void acceptContext(CompletionContext context) {
		// do nothing
	}

	/**
	 * Checks if the current call is made to display context information.
	 * 
	 * @return
	 */
	public boolean isContextInformationMode() {
		return false;
	}

	/**
	 * Interface for the filtering out or changing the relevance of the
	 * completion proposals.
	 * 
	 * @since 4.1
	 */
	public static interface CompletionProposalFilter {
		int DEFAULT = 0;
		int IGNORE = -1000;
		int DISCOURAGED = -50;

		/**
		 * Evaluates the relevance of specified proposal. Possible return values
		 * are:
		 * <ul>
		 * <li>{@link #DEFAULT} to continue without any changes
		 * <li>{@link #IGNORE} to skip the proposal
		 * <li>{@link #DISCOURAGED} to mark the proposal as
		 * <em>not recommended</em>
		 * <li>constants from {@link RelevanceConstants} to increase the
		 * relevance of the proposal
		 * </ul>
		 */
		int evaluate(CompletionProposal proposal);
	}

	private CompletionProposalFilter[] filters;

	/**
	 * Adds the given filter to this requestor.
	 * 
	 * @since 4.1
	 */
	public void addFilter(CompletionProposalFilter filter) {
		Assert.isNotNull(filter);
		if (filters == null) {
			filters = new CompletionProposalFilter[] { filter };
		} else {
			final CompletionProposalFilter[] newFilters = new CompletionProposalFilter[filters.length + 1];
			System.arraycopy(filters, 0, newFilters, 0, filters.length);
			newFilters[filters.length] = filter;
			filters = newFilters;
		}
	}

	/**
	 * Returns the result of filtering for the given completion proposal.
	 * 
	 * @see #addFilter(CompletionProposalFilter)
	 * @since 4.1
	 */
	protected int evaluateFilters(CompletionProposal completionProposal) {
		int result = CompletionProposalFilter.DEFAULT;
		if (filters != null) {
			try {
				for (CompletionProposalFilter filter : filters) {
					int value = filter.evaluate(completionProposal);
					if (value == CompletionProposalFilter.IGNORE) {
						return value;
					}
					if (value > 0 && value > result || value < 0
							&& value < result) {
						result = value;
					}
				}
			} catch (RuntimeException e) {
				DLTKCore.error(
						"Error while evaluating CompletionProposalFilter, continue without filters",
						e);
				filters = null;
				result = CompletionProposalFilter.DEFAULT;
			}
		}
		return result;
	}
}