CompletionRequestor


1   /*******************************************************************************
2    * Copyright (c) 2004, 2007 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.jdt.core;
12  
13  import org.eclipse.jdt.core.compiler.IProblem;
14  
15  /**
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.
18   * <p>
19   * This class is intended to be subclassed by clients.
20   * </p>
21   * <p>
22   * The code assist engine normally invokes methods on completion
23   * requestor in the following sequence:
24   * <pre>
25   * requestor.beginReporting();
26   * requestor.acceptContext(context);
27   * requestor.accept(proposal_1);
28   * requestor.accept(proposal_2);
29   * ...
30   * requestor.endReporting();
31   * </pre>
32   * If, however, the engine is unable to offer completion proposals
33   * for whatever reason, <code>completionFailure</code> is called
34   * with a problem object describing why completions were unavailable.
35   * In this case, the sequence of calls is:
36   * <pre>
37   * requestor.beginReporting();
38   * requestor.acceptContext(context);
39   * requestor.completionFailure(problem);
40   * requestor.endReporting();
41   * </pre>
42   * In either case, the bracketing <code>beginReporting</code>
43   * <code>endReporting</code> calls are always made as well as
44   * <code>acceptContext</code> call.
45   * </p>
46   * <p>
47   * The class was introduced in 3.0 as a more evolvable replacement
48   * for the <code>ICompletionRequestor</code> interface.
49   * </p>
50   * 
51   * @see ICodeAssist
52   * @since 3.0
53   */
54  public abstract class CompletionRequestor {
55  
56      /**
57       * The set of CompletionProposal kinds that this requestor
58       * ignores; <code>0</code> means the set is empty.
59       * 1 << completionProposalKind
60       */
61      private int ignoreSet = 0;
62      
63      private String  [] favoriteReferences;
64      
65      /**
66       * The set of CompletionProposal kinds that this requestor
67       * allows for required proposals; <code>0</code> means the set is empty.
68       * 1 << completionProposalKind
69       */
70      private int requiredProposalAllowSet[] = null;
71  
72      /**
73       * Creates a new completion requestor.
74       * The requestor is interested in all kinds of completion
75       * proposals; none will be ignored.
76       */
77      public CompletionRequestor() {
78          // do nothing
79      }
80  
81      /**
82       * Returns whether the given kind of completion proposal is ignored.
83       * 
84       * @param completionProposalKind one of the kind constants declared
85       * on <code>CompletionProposal</code>
86       * @return <code>true</code> if the given kind of completion proposal
87       * is ignored by this requestor, and <code>false</code> if it is of
88       * interest
89       * @see #setIgnored(int, boolean)
90       * @see CompletionProposal#getKind()
91       */
92      public boolean isIgnored(int completionProposalKind) {
93          if (completionProposalKind < CompletionProposal.FIRST_KIND
94              || completionProposalKind > CompletionProposal.LAST_KIND) {
95                  throw new IllegalArgumentException  ("Unknown kind of completion proposal: "+completionProposalKind); //$NON-NLS-1$
96          }
97          return 0 != (this.ignoreSet & (1 << completionProposalKind));
98      }
99      
100     /**
101      * Sets whether the given kind of completion proposal is ignored.
102      * 
103      * @param completionProposalKind one of the kind constants declared
104      * on <code>CompletionProposal</code>
105      * @param ignore <code>true</code> if the given kind of completion proposal
106      * is ignored by this requestor, and <code>false</code> if it is of
107      * interest
108      * @see #isIgnored(int)
109      * @see CompletionProposal#getKind()
110      */
111     public void setIgnored(int completionProposalKind, boolean ignore) {
112         if (completionProposalKind < CompletionProposal.FIRST_KIND
113             || completionProposalKind > CompletionProposal.LAST_KIND) {
114                 throw new IllegalArgumentException  ("Unknown kind of completion proposal: "+completionProposalKind); //$NON-NLS-1$
115         }
116         if (ignore) {
117             this.ignoreSet |= (1 << completionProposalKind);
118         } else {
119             this.ignoreSet &= ~(1 << completionProposalKind);
120         }
121     }
122     
123     /**
124      * Returns whether a proposal of a given kind with a required proposal
125      * of the given kind is allowed.
126      * 
127      * @param proposalKind one of the kind constants declared
128      * @param requiredProposalKind one of the kind constants declared
129      * on <code>CompletionProposal</code>
130      * @return <code>true</code> if a proposal of a given kind with a required proposal
131      * of the given kind is allowed by this requestor, and <code>false</code> 
132      * if it isn't of interest.
133      * <p>
134      * By default, all kinds of required proposals aren't allowed.
135      * </p>
136      * @see #setAllowsRequiredProposals(int, int, boolean)
137      * @see CompletionProposal#getKind()
138      * @see CompletionProposal#getRequiredProposals()
139      * 
140      * @since 3.3
141      */
142     public boolean isAllowingRequiredProposals(int proposalKind, int requiredProposalKind) {
143         if (proposalKind < CompletionProposal.FIRST_KIND
144             || proposalKind > CompletionProposal.LAST_KIND) {
145                 throw new IllegalArgumentException  ("Unknown kind of completion proposal: "+requiredProposalKind); //$NON-NLS-1$
146             }
147         
148         if (requiredProposalKind < CompletionProposal.FIRST_KIND
149             || requiredProposalKind > CompletionProposal.LAST_KIND) {
150                 throw new IllegalArgumentException  ("Unknown required kind of completion proposal: "+requiredProposalKind); //$NON-NLS-1$
151         }
152         if (this.requiredProposalAllowSet == null) return false;
153         
154         return 0 != (this.requiredProposalAllowSet[proposalKind] & (1 << requiredProposalKind));
155     }
156     
157     /**
158      * Sets whether a proposal of a given kind with a required proposal
159      * of the given kind is allowed.
160      * 
161      * Currently only a subset of kinds support required proposals. To see what combinations
162      * are supported you must look at {@link CompletionProposal#getRequiredProposals()}
163      * documentation.
164      * 
165      * @param proposalKind one of the kind constants declared
166      * @param requiredProposalKind one of the kind constants declared
167      * on <code>CompletionProposal</code>
168      * @param allow <code>true</code> if a proposal of a given kind with a required proposal
169      * of the given kind is allowed by this requestor, and <code>false</code> 
170      * if it isn't of interest
171      * @see #isAllowingRequiredProposals(int, int)
172      * @see CompletionProposal#getKind()
173      * @see CompletionProposal#getRequiredProposals()
174      * 
175      * @since 3.3
176      */
177     public void setAllowsRequiredProposals(int proposalKind, int requiredProposalKind, boolean allow) {
178         if (proposalKind < CompletionProposal.FIRST_KIND
179             || proposalKind > CompletionProposal.LAST_KIND) {
180                 throw new IllegalArgumentException  ("Unknown kind of completion proposal: "+requiredProposalKind); //$NON-NLS-1$
181         }
182         if (requiredProposalKind < CompletionProposal.FIRST_KIND
183             || requiredProposalKind > CompletionProposal.LAST_KIND) {
184                 throw new IllegalArgumentException  ("Unknown required kind of completion proposal: "+requiredProposalKind); //$NON-NLS-1$
185         }
186         
187         if (this.requiredProposalAllowSet == null) {
188             this.requiredProposalAllowSet = new int[CompletionProposal.LAST_KIND + 1];
189         }
190         
191         if (allow) {
192             this.requiredProposalAllowSet[proposalKind] |= (1 << requiredProposalKind);
193         } else {
194             this.requiredProposalAllowSet[proposalKind] &= ~(1 << requiredProposalKind);
195         }
196     }
197     
198     /**
199      * Returns the favorite references which are used to compute some completion proposals.
200      * <p>
201      * A favorite reference is a qualified reference as it can be seen in an import statement.<br>
202      * e.g. <code>{"java.util.Arrays"}</code><br>
203      * It can be an on demand reference.<br>
204      * e.g. <code>{"java.util.Arrays.*"}</code>
205      * It can be a reference to a static method or field (as in a static import)<br>
206      * e.g. <code>{"java.util.Arrays.equals"}</code>
207      * </p>
208      * <p>
209      * Currently only on demand type references (<code>"java.util.Arrays.*"</code>),
210      * references to a static method or a static field are used to compute completion proposals.
211      * Other kind of reference could be used in the future.
212      * </p>
213      * @return favorite imports
214      * 
215      * @since 3.3
216      */
217     public String  [] getFavoriteReferences() {
218         return this.favoriteReferences;
219     }
220     
221     /**
222      * Set the favorite references which will be used to compute some completion proposals.
223      * A favorite reference is a qualified reference as it can be seen in an import statement.<br>
224      * 
225      * @param favoriteImports
226      * 
227      * @see #getFavoriteReferences()
228      * 
229      * @since 3.3
230      */
231     public void setFavoriteReferences(String  [] favoriteImports) {
232         this.favoriteReferences = favoriteImports;
233     }
234     
235     /**
236      * Pro forma notification sent before reporting a batch of
237      * completion proposals.
238      * <p>
239      * The default implementation of this method does nothing.
240      * Clients may override.
241      * </p>
242      */
243     public void beginReporting() {
244         // do nothing
245     }
246 
247     /**
248      * Pro forma notification sent after reporting a batch of
249      * completion proposals.
250      * <p>
251      * The default implementation of this method does nothing.
252      * Clients may override.
253      * </p>
254      */
255     public void endReporting() {
256         // do nothing
257     }
258 
259     /**
260      * Notification of failure to produce any completions.
261      * The problem object explains what prevented completing.
262      * <p>
263      * The default implementation of this method does nothing.
264      * Clients may override to receive this kind of notice.
265      * </p>
266      * 
267      * @param problem the problem object
268      */
269     public void completionFailure(IProblem problem) {
270         // default behavior is to ignore
271     }
272 
273     /**
274      * Proposes a completion. Has no effect if the kind of proposal
275      * is being ignored by this requestor. Callers should consider
276      * checking {@link #isIgnored(int)} before avoid creating proposal
277      * objects that would only be ignored.
278      * <p>
279      * Similarly, implementers should check 
280      * {@link #isIgnored(int) isIgnored(proposal.getKind())} 
281      * and ignore proposals that have been declared as uninteresting.
282      * The proposal object passed is only valid for the duration of
283      * completion operation.
284      * 
285      * @param proposal the completion proposal
286      * @exception IllegalArgumentException if the proposal is null
287      */
288     public abstract void accept(CompletionProposal proposal);
289     
290     /**
291      * Propose the context in which the completion occurs.
292      * <p>
293      * This method is called one and only one time before any call to
294      * {@link #accept(CompletionProposal)}.
295      * The default implementation of this method does nothing.
296      * Clients may override.
297      * </p>
298      * @param context the completion context
299      * 
300      * @since 3.1
301      */
302     public void acceptContext(CompletionContext context) {
303         // do nothing
304     }
305 }
306
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags