1 /* 2 * Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.lang.model.util; 27 28 import javax.lang.model.element.*; 29 import javax.annotation.processing.SupportedSourceVersion; 30 import javax.lang.model.SourceVersion; 31 import static javax.lang.model.SourceVersion.*; 32 33 34 /** 35 * A scanning visitor of program elements with default behavior 36 * appropriate for the {@link SourceVersion#RELEASE_6 RELEASE_6} 37 * source version. The <code>visit<i>Xyz</i></code> methods in this 38 * class scan their component elements by calling {@code scan} on 39 * their {@linkplain Element#getEnclosedElements enclosed elements}, 40 * {@linkplain ExecutableElement#getParameters parameters}, etc., as 41 * indicated in the individual method specifications. A subclass can 42 * control the order elements are visited by overriding the 43 * <code>visit<i>Xyz</i></code> methods. Note that clients of a scanner 44 * may get the desired behavior be invoking {@code v.scan(e, p)} rather 45 * than {@code v.visit(e, p)} on the root objects of interest. 46 * 47 * <p>When a subclass overrides a <code>visit<i>Xyz</i></code> method, the 48 * new method can cause the enclosed elements to be scanned in the 49 * default way by calling <code>super.visit<i>Xyz</i></code>. In this 50 * fashion, the concrete visitor can control the ordering of traversal 51 * over the component elements with respect to the additional 52 * processing; for example, consistently calling 53 * <code>super.visit<i>Xyz</i></code> at the start of the overridden 54 * methods will yield a preorder traversal, etc. If the component 55 * elements should be traversed in some other order, instead of 56 * calling <code>super.visit<i>Xyz</i></code>, an overriding visit method 57 * should call {@code scan} with the elements in the desired order. 58 * 59 * @apiNote 60 * Methods in this class may be overridden subject to their general 61 * contract. 62 * 63 * <p id=note_for_subclasses><strong>WARNING:</strong> The {@code ElementVisitor} interface 64 * implemented by this class may have methods added to it in the 65 * future to accommodate new, currently unknown, language structures 66 * added to future versions of the Java programming language. 67 * Therefore, methods whose names begin with {@code "visit"} may be 68 * added to this class in the future; to avoid incompatibilities, 69 * classes which extend this class should not declare any instance 70 * methods with names beginning with {@code "visit"}.</p> 71 * 72 * <p>When such a new visit method is added, the default 73 * implementation in this class will be to directly or indirectly call the {@link 74 * #visitUnknown visitUnknown} method. A new element scanner visitor 75 * class will also be introduced to correspond to the new language 76 * level; this visitor will have different default behavior for the 77 * visit method in question. When a new visitor is introduced, 78 * portions of this visitor class may be deprecated, including its constructors. 79 * 80 * @param <R> the return type of this visitor's methods. Use {@link 81 * Void} for visitors that do not need to return results. 82 * @param <P> the type of the additional parameter to this visitor's 83 * methods. Use {@code Void} for visitors that do not need an 84 * additional parameter. 85 * 86 * @author Joseph D. Darcy 87 * @author Scott Seligman 88 * @author Peter von der Ahé 89 * 90 * @see ElementScanner7 91 * @see ElementScanner8 92 * @see ElementScanner9 93 * @see ElementScanner14 94 * @since 1.6 95 */ 96 @SupportedSourceVersion(RELEASE_6) 97 public class ElementScanner6<R, P> extends AbstractElementVisitor6<R, P> { 98 /** 99 * The specified default value. 100 */ 101 protected final R DEFAULT_VALUE; 102 103 /** 104 * Constructor for concrete subclasses; uses {@code null} for the 105 * default value. 106 * @deprecated Release 6 is obsolete; update to a visitor for a newer 107 * release level. 108 */ 109 @Deprecated(since="9") 110 protected ElementScanner6(){ 111 DEFAULT_VALUE = null; 112 } 113 114 /** 115 * Constructor for concrete subclasses; uses the argument for the 116 * default value. 117 * 118 * @param defaultValue the default value 119 * @deprecated Release 6 is obsolete; update to a visitor for a newer 120 * release level. 121 */ 122 @Deprecated(since="9") 123 protected ElementScanner6(R defaultValue){ 124 DEFAULT_VALUE = defaultValue; 125 } 126 127 /** 128 * Iterates over the given elements and calls {@link 129 * #scan(Element, Object) scan(Element, P)} on each one. Returns 130 * the result of the last call to {@code scan} or {@code 131 * DEFAULT_VALUE} for an empty iterable. 132 * 133 * @param iterable the elements to scan 134 * @param p additional parameter 135 * @return the scan of the last element or {@code DEFAULT_VALUE} if no elements 136 */ 137 public final R scan(Iterable<? extends Element> iterable, P p) { 138 R result = DEFAULT_VALUE; 139 for(Element e : iterable) 140 result = scan(e, p); 141 return result; 142 } 143 144 /** 145 * Processes an element by calling {@code e.accept(this, p)}; 146 * this method may be overridden by subclasses. 147 * 148 * @param e the element to scan 149 * @param p a scanner-specified parameter 150 * @return the result of visiting {@code e}. 151 */ 152 public R scan(Element e, P p) { 153 return e.accept(this, p); 154 } 155 156 /** 157 * Convenience method equivalent to {@code v.scan(e, null)}. 158 * 159 * @param e the element to scan 160 * @return the result of scanning {@code e}. 161 */ 162 public final R scan(Element e) { 163 return scan(e, null); 164 } 165 166 /** 167 * {@inheritDoc} 168 * 169 * @implSpec This implementation scans the enclosed elements. 170 * 171 * @param e {@inheritDoc} 172 * @param p {@inheritDoc} 173 * @return the result of scanning 174 */ 175 public R visitPackage(PackageElement e, P p) { 176 return scan(e.getEnclosedElements(), p); 177 } 178 179 /** 180 * {@inheritDoc} 181 * 182 * @implSpec This implementation scans the enclosed elements. 183 * Note that type parameters are <em>not</em> scanned by this 184 * implementation since type parameters are not considered to be 185 * {@linkplain TypeElement#getEnclosedElements enclosed elements 186 * of a type}. 187 * 188 * @param e {@inheritDoc} 189 * @param p {@inheritDoc} 190 * @return the result of scanning 191 */ 192 public R visitType(TypeElement e, P p) { 193 return scan(e.getEnclosedElements(), p); 194 } 195 196 /** 197 * {@inheritDoc} 198 * 199 * @implSpec This implementation scans the enclosed elements, unless the 200 * element is a {@code RESOURCE_VARIABLE} in which case {@code 201 * visitUnknown} is called. 202 * 203 * @param e {@inheritDoc} 204 * @param p {@inheritDoc} 205 * @return the result of scanning 206 */ 207 public R visitVariable(VariableElement e, P p) { 208 if (e.getKind() != ElementKind.RESOURCE_VARIABLE) 209 return scan(e.getEnclosedElements(), p); 210 else 211 return visitUnknown(e, p); 212 } 213 214 /** 215 * {@inheritDoc} 216 * 217 * @implSpec This implementation scans the parameters. 218 * Note that type parameters are <em>not</em> scanned by this 219 * implementation. 220 * 221 * @param e {@inheritDoc} 222 * @param p {@inheritDoc} 223 * @return the result of scanning 224 */ 225 public R visitExecutable(ExecutableElement e, P p) { 226 return scan(e.getParameters(), p); 227 } 228 229 /** 230 * {@inheritDoc} 231 * 232 * @implSpec This implementation scans the enclosed elements. 233 * 234 * @param e {@inheritDoc} 235 * @param p {@inheritDoc} 236 * @return the result of scanning 237 */ 238 public R visitTypeParameter(TypeParameterElement e, P p) { 239 return scan(e.getEnclosedElements(), p); 240 } 241 }