net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/dom/ASTRequestor.java

   1 /*******************************************************************************
   2  * Copyright (c) 2005 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 net.sourceforge.phpdt.core.dom;
  12
  13 import net.sourceforge.phpdt.core.ICompilationUnit;
  14
  15 /**
  16  * An AST requestor handles ASTs for compilation units passed to
  17  * <code>ASTParser.createASTs</code>.
  18  * <p>
  19  * <code>ASTRequestor.acceptAST</code> is called for each of the
  20  * compilation units passed to <code>ASTParser.createASTs</code>.
  21  * After all the compilation units have been processed,
  22  * <code>ASTRequestor.acceptBindings</code> is called for each
  23  * of the binding keys passed to <code>ASTParser.createASTs</code>.
  24  * </p>
  25  * <p>
  26  * This class is intended to be subclassed by clients.
  27  * AST requestors are serially reusable, but neither reentrant nor
  28  * thread-safe.
  29  * </p>
  30  *
  31  * @see ASTParser#createASTs(ICompilationUnit[], String[], ASTRequestor, org.eclipse.core.runtime.IProgressMonitor)
  32  * @since 3.1
  33  */
  34 public abstract class ASTRequestor {
  35
  36         /**
  37          * The compilation unit resolver used to resolve bindings, or
  38          * <code>null</code> if none. Note that this field is non-null
  39          * only within the dynamic scope of a call to
  40          * <code>ASTParser.createASTs</code>.
  41          */
  42         CompilationUnitResolver compilationUnitResolver = null;
  43
  44         /**
  45          * Creates a new instance.
  46          */
  47         protected ASTRequestor() {
  48                 // do nothing
  49         }
  50
  51         /**
  52          * Accepts an AST corresponding to the compilation unit.
  53          * That is, <code>ast</code> is an AST for <code>source</code>.
  54          * <p>
  55          * The default implementation of this method does nothing.
  56          * Clients should override to process the resulting AST.
  57          * </p>
  58          *
  59          * @param source the compilation unit the ast is coming from
  60          * @param ast the requested abtract syntax tree
  61          */
  62         public void acceptAST(ICompilationUnit source, CompilationUnit ast) {
  63                 // do nothing
  64         }
  65
  66         /**
  67          * Accepts a binding corresponding to the binding key.
  68          * That is, <code>binding</code> is the binding for
  69          * <code>bindingKey</code>; <code>binding</code> is <code>null</code>
  70          * if the key cannot be resolved.
  71          * <p>
  72          * The default implementation of this method does nothing.
  73          * Clients should override to process the resulting binding.
  74          * </p>
  75          *
  76          * @param bindingKey the key of the requested binding
  77          * @param binding the requested binding, or <code>null</code> if none
  78          */
  79         public void acceptBinding(String bindingKey, IBinding binding) {
  80                 // do nothing
  81         }
  82
  83         /**
  84          * Resolves bindings for the given binding keys.
  85          * The given binding keys must have been obtained earlier
  86          * using {@link IBinding#getKey()}.
  87          * <p>
  88          * If a binding key cannot be resolved, <code>null</code> is put in the resulting array.
  89          * Bindings can only be resolved in the dynamic scope of a <code>ASTParser.createASTs</code>,
  90          * and only if <code>ASTParser.resolveBindings(true)</code> was specified.
  91          * </p>
  92          * <p>
  93          * Caveat: During an <code>acceptAST</code> callback, there are implementation
  94          * limitations concerning the look up of binding keys representing local elements.
  95          * In some cases, the binding is unavailable, and <code>null</code> will be returned.
  96          * This is only an issue during an <code>acceptAST</code> callback, and only
  97          * when the binding key represents a local element (e.g., local variable,
  98          * local class, method declared in anonymous class). There is no such limitation
  99          * outside of <code>acceptAST</code> callbacks, or for top-level types and their
 100          * members even within <code>acceptAST</code> callbacks.
 101          * </p>
 102          *
 103          * @param bindingKeys the binding keys to look up
 104          * @return a list of bindings paralleling the <code>bindingKeys</code> parameter,
 105          * with <code>null</code> entries for keys that could not be resolved
 106          */
 107         public final IBinding[] createBindings(String[] bindingKeys) {
 108                 int length = bindingKeys.length;
 109                 IBinding[] result = new IBinding[length];
 110                 for (int i = 0; i < length; i++) {
 111                         result[i] = null;
 112                         if (this.compilationUnitResolver != null) {
 113                                 result[i] = this.compilationUnitResolver.createBinding(bindingKeys[i]);
 114                         }
 115                 }
 116                 return result;
 117         }
 118 }