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
23 * requestors in the following sequence:
25 * requestor.beginReporting();
26 * requestor.accept(proposal_1);
27 * requestor.accept(proposal_2);
29 * requestor.endReporting();
31 * If, however, the engine is unable to offer completion proposals
32 * for whatever reason, <code>completionFailure</code> is called
33 * with a problem object describing why completions were unavailable.
34 * In this case, the sequence of calls is:
36 * requestor.beginReporting();
37 * requestor.completionFailure(problem);
38 * requestor.endReporting();
40 * In either case, the bracketing <code>beginReporting</code>
41 * <code>endReporting</code> calls are always made.
44 * The class was introduced in 3.0 as a more evolvable replacement
45 * for the <code>ICompletionRequestor</code> interface.
51 public abstract class CompletionRequestor {
54 * The set of CompletionProposal kinds that this requestor
55 * ignores; <code>0</code> means the set is empty.
56 * 1 << completionProposalKind
58 private int ignoreSet = 0;
61 * Creates a new completion requestor.
62 * The requestor is interested in all kinds of completion
63 * proposals; none will be ignored.
65 public CompletionRequestor() {
70 * Returns whether the given kind of completion proposal is ignored.
72 * @param completionProposalKind one of the kind constants declared
73 * on <code>CompletionProposal</code>
74 * @return <code>true</code> if the given kind of completion proposal
75 * is ignored by this requestor, and <code>false</code> if it is of
77 * @see #setIgnored(int, boolean)
78 * @see CompletionProposal#getKind()
80 public final boolean isIgnored(int completionProposalKind) {
81 if (completionProposalKind < CompletionProposal.ANONYMOUS_CLASS_DECLARATION
82 || completionProposalKind > CompletionProposal.VARIABLE_DECLARATION) {
83 throw new IllegalArgumentException();
85 return 0 != (this.ignoreSet & (1 << completionProposalKind));
89 * Sets whether the given kind of completion proposal is ignored.
91 * @param completionProposalKind one of the kind constants declared
92 * on <code>CompletionProposal</code>
93 * @param ignore <code>true</code> if the given kind of completion proposal
94 * is ignored by this requestor, and <code>false</code> if it is of
96 * @see #isIgnored(int)
97 * @see CompletionProposal#getKind()
99 public final void setIgnored(int completionProposalKind, boolean ignore) {
100 if (completionProposalKind < CompletionProposal.ANONYMOUS_CLASS_DECLARATION
101 || completionProposalKind > CompletionProposal.VARIABLE_DECLARATION) {
102 throw new IllegalArgumentException();
105 this.ignoreSet |= (1 << completionProposalKind);
107 this.ignoreSet &= ~(1 << completionProposalKind);
112 * Pro forma notification sent before reporting a batch of
113 * completion proposals.
115 * The default implementation of this method does nothing.
116 * Clients may override.
119 public void beginReporting() {
124 * Pro forma notification sent after reporting a batch of
125 * completion proposals.
127 * The default implementation of this method does nothing.
128 * Clients may override.
131 public void endReporting() {
136 * Notification of failure to produce any completions.
137 * The problem object explains what prevented completing.
139 * The default implementation of this method does nothing.
140 * Clients may override to receive this kind of notice.
143 * @param problem the problem object
145 public void completionFailure(IProblem problem) {
146 // default behavior is to ignore
150 * Proposes a completion. Has no effect if the kind of proposal
151 * is being ignored by this requestor. Callers should consider
152 * checking {@link #isIgnored(int)} before avoid creating proposal
153 * objects that would only be ignored.
155 * Similarly, implementers should check
156 * {@link #isIgnored(int) isIgnored(proposal.getKind())}
157 * and ignore proposals that have been declared as uninteresting.
158 * The proposal object passed in only valid for the duration of
159 * this call; implementors must not hang on to these objects.
161 * @param proposal the completion proposal
162 * @exception IllegalArgumentException if the proposal is null
164 public abstract void accept(CompletionProposal proposal);