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.element; 27 28 import javax.lang.model.util.*; 29 30 /** 31 * A visitor of program elements, in the style of the visitor design 32 * pattern. Classes implementing this interface are used to operate 33 * on an element when the kind of element is unknown at compile time. 34 * When a visitor is passed to an element's {@link Element#accept 35 * accept} method, the <code>visit<i>Xyz</i></code> method most applicable 36 * to that element is invoked. 37 * 38 * <p> Classes implementing this interface may or may not throw a 39 * {@code NullPointerException} if the additional parameter {@code p} 40 * is {@code null}; see documentation of the implementing class for 41 * details. 42 * 43 * @apiNote 44 * 45 * WARNING: It is possible that methods will be added to 46 * this interface to accommodate new, currently unknown, language 47 * structures added to future versions of the Java™ programming 48 * language. 49 * 50 * Such additions have already occurred to support language features 51 * added after this API was introduced. 52 * 53 * Visitor classes directly implementing this 54 * interface may be source incompatible with future versions of the 55 * platform. To avoid this source incompatibility, visitor 56 * implementations are encouraged to instead extend the appropriate 57 * abstract visitor class that implements this interface. However, an 58 * API should generally use this visitor interface as the type for 59 * parameters, return type, etc. rather than one of the abstract 60 * classes. 61 * 62 * <p>Methods to accommodate new language constructs are expected to 63 * be added as default methods to provide strong source compatibility, 64 * as done for {@link visitModule visitModule}. The implementations of 65 * the default methods will in turn call {@link visitUnknown 66 * visitUnknown}, behavior that will be overridden in concrete 67 * visitors supporting the source version with the new language 68 * construct. 69 * 70 * <p>There are several families of classes implementing this visitor 71 * interface in the {@linkplain javax.lang.model.util util 72 * package}. The families follow a naming pattern along the lines of 73 * {@code FooVisitor}<i>N</i> where <i>N</i> indicates the 74 * {@linkplain javax.lang.model.SourceVersion source version} the 75 * visitor is appropriate for. 76 * 77 * In particular, a {@code FooVisitor}<i>N</i> is expected to handle 78 * all language constructs present in source version <i>N</i>. If 79 * there are no new language constructs added in version 80 * <i>N</i> + 1 (or subsequent releases), {@code 81 * FooVisitor}<i>N</i> may also handle that later source version; in 82 * that case, the {@link 83 * javax.annotation.processing.SupportedSourceVersion 84 * SupportedSourceVersion} annotation on the {@code 85 * FooVisitor}<i>N</i> class will indicate a later version. 86 * 87 * When visiting an element representing a language construct 88 * introduced <strong>after</strong> source version <i>N</i>, a {@code 89 * FooVisitor}<i>N</i> will throw an {@link UnknownElementException} 90 * unless that behavior is overridden. 91 * 92 * <p>When choosing which member of a visitor family to subclass, 93 * subclassing the most recent one increases the range of source 94 * versions covered. When choosing which visitor family to subclass, 95 * consider their built-in capabilities: 96 * 97 * <ul> 98 * 99 * <li>{@link AbstractElementVisitor6 AbstractElementVisitor}s: 100 * Skeletal visitor implementations. 101 * 102 * <li>{@link SimpleElementVisitor6 SimpleElementVisitor}s: Support 103 * default actions and a default return value. 104 * 105 * <li>{@link ElementKindVisitor6 ElementKindVisitor}s: Visit methods 106 * provided on a {@linkplain Element#getKind per-kind} granularity as 107 * some categories of elements can have more than one kind. 108 * 109 * <li>{@link ElementScanner6 ElementScanner}s: Scanners are visitors 110 * which traverse an element and the elements {@linkplain 111 * Element#getEnclosedElements enclosed} by it and associated with it. 112 * 113 * </ul> 114 * 115 * @param <R> the return type of this visitor's methods. Use {@link 116 * Void} for visitors that do not need to return results. 117 * @param <P> the type of the additional parameter to this visitor's 118 * methods. Use {@code Void} for visitors that do not need an 119 * additional parameter. 120 * 121 * @author Joseph D. Darcy 122 * @author Scott Seligman 123 * @author Peter von der Ahé 124 * @since 1.6 125 */ 126 public interface ElementVisitor<R, P> { 127 /** 128 * Visits an element. 129 * @param e the element to visit 130 * @param p a visitor-specified parameter 131 * @return a visitor-specified result 132 */ 133 R visit(Element e, P p); 134 135 /** 136 * A convenience method equivalent to {@code visit(e, null)}. 137 * 138 * @implSpec The default implementation is {@code visit(e, null)}. 139 * 140 * @param e the element to visit 141 * @return a visitor-specified result 142 */ 143 default R visit(Element e) { 144 return visit(e, null); 145 } 146 147 /** 148 * Visits a package element. 149 * @param e the element to visit 150 * @param p a visitor-specified parameter 151 * @return a visitor-specified result 152 */ 153 R visitPackage(PackageElement e, P p); 154 155 /** 156 * Visits a type element. 157 * @param e the element to visit 158 * @param p a visitor-specified parameter 159 * @return a visitor-specified result 160 */ 161 R visitType(TypeElement e, P p); 162 163 /** 164 * Visits a variable element. 165 * @param e the element to visit 166 * @param p a visitor-specified parameter 167 * @return a visitor-specified result 168 */ 169 R visitVariable(VariableElement e, P p); 170 171 /** 172 * Visits an executable element. 173 * @param e the element to visit 174 * @param p a visitor-specified parameter 175 * @return a visitor-specified result 176 */ 177 R visitExecutable(ExecutableElement e, P p); 178 179 /** 180 * Visits a type parameter element. 181 * @param e the element to visit 182 * @param p a visitor-specified parameter 183 * @return a visitor-specified result 184 */ 185 R visitTypeParameter(TypeParameterElement e, P p); 186 187 /** 188 * Visits an unknown kind of element. 189 * This can occur if the language evolves and new kinds 190 * of elements are added to the {@code Element} hierarchy. 191 * 192 * @param e the element to visit 193 * @param p a visitor-specified parameter 194 * @return a visitor-specified result 195 * @throws UnknownElementException 196 * a visitor implementation may optionally throw this exception 197 */ 198 R visitUnknown(Element e, P p); 199 200 /** 201 * Visits a module element. 202 * 203 * @implSpec The default implementation visits a {@code 204 * ModuleElement} by calling {@code visitUnknown(e, p)}. 205 * 206 * @param e the element to visit 207 * @param p a visitor-specified parameter 208 * @return a visitor-specified result 209 * @since 9 210 * @spec JPMS 211 */ 212 default R visitModule(ModuleElement e, P p) { 213 return visitUnknown(e, p); 214 } 215 216 /** 217 * {@preview Associated with records, a preview feature of the Java language. 218 * 219 * This method is associated with <i>records</i>, a preview 220 * feature of the Java language. Preview features 221 * may be removed in a future release, or upgraded to permanent 222 * features of the Java language.} 223 * 224 * Visits a record component element. 225 * 226 * @implSpec The default implementation visits a {@code 227 * RecordComponentElement} by calling {@code visitUnknown(e, p)}. 228 * 229 * @param e the element to visit 230 * @param p a visitor-specified parameter 231 * @return a visitor-specified result 232 * @since 14 233 */ 234 @jdk.internal.PreviewFeature(feature=jdk.internal.PreviewFeature.Feature.RECORDS, 235 essentialAPI=false) 236 @SuppressWarnings("preview") 237 default R visitRecordComponent(RecordComponentElement e, P p) { 238 return visitUnknown(e, p); 239 } 240 }