1 /******************************************************************************* 2 * Copyright (c) 2010 IBM Corporation and others. 3 * 4 * This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License 2.0 6 * which accompanies this distribution, and is available at 7 * https://www.eclipse.org/legal/epl-2.0/ 8 * 9 * SPDX-License-Identifier: EPL-2.0 10 * 11 * Contributors: 12 * IBM Corporation - initial API and implementation 13 *******************************************************************************/ 14 package org.eclipse.jdt.core.dom; 15 16 /** 17 * An AST requestor handles ASTs for compilation units passed to 18 * {@link ASTParser#createASTs(String[], String[], String[], FileASTRequestor, org.eclipse.core.runtime.IProgressMonitor) ASTParser.createASTs}. 19 * <p> 20 * {@link FileASTRequestor#acceptAST(String, CompilationUnit) FileASTRequestor.acceptAST} is called for each of the 21 * compilation units passed to {@link ASTParser#createASTs(String[], String[], String[], FileASTRequestor, org.eclipse.core.runtime.IProgressMonitor) ASTParser.createASTs}. 22 * After all the compilation units have been processed, 23 * {@link #acceptBinding(String, IBinding) FileASTRequestor.acceptBinding} is called for each 24 * of the binding keys passed to {@link ASTParser#createASTs(String[], String[], String[], FileASTRequestor, org.eclipse.core.runtime.IProgressMonitor) ASTParser.createASTs}. 25 * </p> 26 * <p> 27 * This class is intended to be subclassed by clients. 28 * AST requestors are serially reusable, but neither reentrant nor thread-safe. 29 * </p> 30 * 31 * @see ASTParser#createASTs(String[], String[], String[], FileASTRequestor, org.eclipse.core.runtime.IProgressMonitor) 32 * @since 3.6 33 */ 34 public abstract class FileASTRequestor { 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 * Accepts an AST corresponding to the compilation unit. 46 * That is, <code>ast</code> is an AST for <code>source</code>. 47 * <p> 48 * The default implementation of this method does nothing. 49 * Clients should override to process the resulting AST. 50 * </p> 51 * 52 * @param sourceFilePath the compilation unit the given ast is coming from 53 * @param ast the requested abstract syntax tree 54 */ acceptAST(String sourceFilePath, CompilationUnit ast)55 public void acceptAST(String sourceFilePath, CompilationUnit ast) { 56 // do nothing 57 } 58 59 /** 60 * Accepts a binding corresponding to the binding key. 61 * That is, <code>binding</code> is the binding for 62 * <code>bindingKey</code>; <code>binding</code> is <code>null</code> 63 * if the key cannot be resolved. 64 * <p> 65 * The default implementation of this method does nothing. 66 * Clients should override to process the resulting binding. 67 * </p> 68 * 69 * @param bindingKey the key of the requested binding 70 * @param binding the requested binding, or <code>null</code> if none 71 */ acceptBinding(String bindingKey, IBinding binding)72 public void acceptBinding(String bindingKey, IBinding binding) { 73 // do nothing 74 } 75 76 /** 77 * Resolves bindings for the given binding keys. 78 * The given binding keys must have been obtained earlier 79 * using {@link IBinding#getKey()}. 80 * <p> 81 * If a binding key cannot be resolved, <code>null</code> is put in the resulting array. 82 * Bindings can only be resolved in the dynamic scope of a <code>ASTParser.createASTs</code>, 83 * and only if <code>ASTParser.resolveBindings(true)</code> was specified. 84 * </p> 85 * <p> 86 * Caveat: During an <code>acceptAST</code> callback, there are implementation 87 * limitations concerning the look up of binding keys representing local elements. 88 * In some cases, the binding is unavailable, and <code>null</code> will be returned. 89 * This is only an issue during an <code>acceptAST</code> callback, and only 90 * when the binding key represents a local element (e.g., local variable, 91 * local class, method declared in anonymous class). There is no such limitation 92 * outside of <code>acceptAST</code> callbacks, or for top-level types and their 93 * members even within <code>acceptAST</code> callbacks. 94 * </p> 95 * 96 * @param bindingKeys the binding keys to look up 97 * @return a list of bindings paralleling the <code>bindingKeys</code> parameter, 98 * with <code>null</code> entries for keys that could not be resolved 99 */ createBindings(String[] bindingKeys)100 public final IBinding[] createBindings(String[] bindingKeys) { 101 int length = bindingKeys.length; 102 IBinding[] result = new IBinding[length]; 103 for (int i = 0; i < length; i++) { 104 result[i] = null; 105 if (this.compilationUnitResolver != null) { 106 result[i] = this.compilationUnitResolver.createBinding(bindingKeys[i]); 107 } 108 } 109 return result; 110 } 111 } 112