net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/CompletionRequestor.java

   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
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  *******************************************************************************/
  11 package net.sourceforge.phpdt.core;
  12
  13 import net.sourceforge.phpdt.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  * requestors in the following sequence:
  24  * <pre>
  25  * requestor.beginReporting();
  26  * requestor.accept(proposal_1);
  27  * requestor.accept(proposal_2);
  28  * ...
  29  * requestor.endReporting();
  30  * </pre>
  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:
  35  * <pre>
  36  * requestor.beginReporting();
  37  * requestor.completionFailure(problem);
  38  * requestor.endReporting();
  39  * </pre>
  40  * In either case, the bracketing <code>beginReporting</code>
  41  * <code>endReporting</code> calls are always made.
  42  * </p>
  43  * <p>
  44  * The class was introduced in 3.0 as a more evolvable replacement
  45  * for the <code>ICompletionRequestor</code> interface.
  46  * </p>
  47  *
  48  * @see ICodeAssist
  49  * @since 3.0
  50  */
  51 public abstract class CompletionRequestor {
  52
  53         /**
  54          * The set of CompletionProposal kinds that this requestor
  55          * ignores; <code>0</code> means the set is empty.
  56          * 1 << completionProposalKind
  57          */
  58         private int ignoreSet = 0;
  59
  60         /**
  61          * Creates a new completion requestor.
  62          * The requestor is interested in all kinds of completion
  63          * proposals; none will be ignored.
  64          */
  65         public CompletionRequestor() {
  66                 // do nothing
  67         }
  68
  69         /**
  70          * Returns whether the given kind of completion proposal is ignored.
  71          *
  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
  76          * interest
  77          * @see #setIgnored(int, boolean)
  78          * @see CompletionProposal#getKind()
  79          */
  80         public final boolean isIgnored(int completionProposalKind) {
  81                 if (completionProposalKind < CompletionProposal.ANONYMOUS_CLASS_DECLARATION
  82                         || completionProposalKind > CompletionProposal.VARIABLE_DECLARATION) {
  83                                 throw new IllegalArgumentException();
  84                 }
  85                 return 0 != (this.ignoreSet & (1 << completionProposalKind));
  86         }
  87
  88         /**
  89          * Sets whether the given kind of completion proposal is ignored.
  90          *
  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
  95          * interest
  96          * @see #isIgnored(int)
  97          * @see CompletionProposal#getKind()
  98          */
  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();
 103                 }
 104                 if (ignore) {
 105                         this.ignoreSet |= (1 << completionProposalKind);
 106                 } else {
 107                         this.ignoreSet &= ~(1 << completionProposalKind);
 108                 }
 109         }
 110
 111         /**
 112          * Pro forma notification sent before reporting a batch of
 113          * completion proposals.
 114          * <p>
 115          * The default implementation of this method does nothing.
 116          * Clients may override.
 117          * </p>
 118          */
 119         public void beginReporting() {
 120                 // do nothing
 121         }
 122
 123         /**
 124          * Pro forma notification sent after reporting a batch of
 125          * completion proposals.
 126          * <p>
 127          * The default implementation of this method does nothing.
 128          * Clients may override.
 129          * </p>
 130          */
 131         public void endReporting() {
 132                 // do nothing
 133         }
 134
 135         /**
 136          * Notification of failure to produce any completions.
 137          * The problem object explains what prevented completing.
 138          * <p>
 139          * The default implementation of this method does nothing.
 140          * Clients may override to receive this kind of notice.
 141          * </p>
 142          *
 143          * @param problem the problem object
 144          */
 145         public void completionFailure(IProblem problem) {
 146                 // default behavior is to ignore
 147         }
 148
 149         /**
 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.
 154          * <p>
 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.
 160          *
 161          * @param proposal the completion proposal
 162          * @exception IllegalArgumentException if the proposal is null
 163          */
 164         public abstract void accept(CompletionProposal proposal);
 165 }