1 /*******************************************************************************
2 * Copyright (c) 2004 IBM Corporation and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Common Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/cpl-v10.html
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11 package net.sourceforge.phpdt.core;
13 import net.sourceforge.phpdt.core.compiler.IProblem;
16 * Abstract base class for a completion requestor which is passed completion
17 * proposals as they are generated in response to a code assist request.
19 * This class is intended to be subclassed by clients.
22 * The code assist engine normally invokes methods on completion requestors in
23 * the following sequence:
26 * requestor.beginReporting();
27 * requestor.accept(proposal_1);
28 * requestor.accept(proposal_2);
30 * requestor.endReporting();
33 * If, however, the engine is unable to offer completion proposals for whatever
34 * reason, <code>completionFailure</code> is called with a problem object
35 * describing why completions were unavailable. In this case, the sequence of
39 * requestor.beginReporting();
40 * requestor.completionFailure(problem);
41 * requestor.endReporting();
44 * In either case, the bracketing <code>beginReporting</code>
45 * <code>endReporting</code>
46 * calls are always made.
49 * The class was introduced in 3.0 as a more evolvable replacement for the
50 * <code>ICompletionRequestor</code> interface.
56 public abstract class CompletionRequestor {
59 * The set of CompletionProposal kinds that this requestor ignores;
60 * <code>0</code> means the set is empty. 1 << completionProposalKind
62 private int ignoreSet = 0;
65 * Creates a new completion requestor. The requestor is interested in all
66 * kinds of completion proposals; none will be ignored.
68 public CompletionRequestor() {
73 * Returns whether the given kind of completion proposal is ignored.
75 * @param completionProposalKind
76 * one of the kind constants declared on
77 * <code>CompletionProposal</code>
78 * @return <code>true</code> if the given kind of completion proposal is
79 * ignored by this requestor, and <code>false</code> if it is of
81 * @see #setIgnored(int, boolean)
82 * @see CompletionProposal#getKind()
84 public final boolean isIgnored(int completionProposalKind) {
85 if (completionProposalKind < CompletionProposal.ANONYMOUS_CLASS_DECLARATION
86 || completionProposalKind > CompletionProposal.VARIABLE_DECLARATION) {
87 throw new IllegalArgumentException();
89 return 0 != (this.ignoreSet & (1 << completionProposalKind));
93 * Sets whether the given kind of completion proposal is ignored.
95 * @param completionProposalKind
96 * one of the kind constants declared on
97 * <code>CompletionProposal</code>
99 * <code>true</code> if the given kind of completion proposal
100 * is ignored by this requestor, and <code>false</code> if it
102 * @see #isIgnored(int)
103 * @see CompletionProposal#getKind()
105 public final void setIgnored(int completionProposalKind, boolean ignore) {
106 if (completionProposalKind < CompletionProposal.ANONYMOUS_CLASS_DECLARATION
107 || completionProposalKind > CompletionProposal.VARIABLE_DECLARATION) {
108 throw new IllegalArgumentException();
111 this.ignoreSet |= (1 << completionProposalKind);
113 this.ignoreSet &= ~(1 << completionProposalKind);
118 * Pro forma notification sent before reporting a batch of completion
121 * The default implementation of this method does nothing. Clients may
125 public void beginReporting() {
130 * Pro forma notification sent after reporting a batch of completion
133 * The default implementation of this method does nothing. Clients may
137 public void endReporting() {
142 * Notification of failure to produce any completions. The problem object
143 * explains what prevented completing.
145 * The default implementation of this method does nothing. Clients may
146 * override to receive this kind of notice.
152 public void completionFailure(IProblem problem) {
153 // default behavior is to ignore
157 * Proposes a completion. Has no effect if the kind of proposal is being
158 * ignored by this requestor. Callers should consider checking
159 * {@link #isIgnored(int)} before avoid creating proposal objects that would
162 * Similarly, implementers should check
163 * {@link #isIgnored(int) isIgnored(proposal.getKind())} and ignore
164 * proposals that have been declared as uninteresting. The proposal object
165 * passed in only valid for the duration of this call; implementors must not
166 * hang on to these objects.
169 * the completion proposal
170 * @exception IllegalArgumentException
171 * if the proposal is null
173 public abstract void accept(CompletionProposal proposal);