ElementVisitor.java revision 3895:4a937fde7b91
1214571Sdim/* 2214571Sdim * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved. 3214571Sdim * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4214571Sdim * 5214571Sdim * This code is free software; you can redistribute it and/or modify it 6214571Sdim * under the terms of the GNU General Public License version 2 only, as 7214571Sdim * published by the Free Software Foundation. Oracle designates this 8214571Sdim * particular file as subject to the "Classpath" exception as provided 9214571Sdim * by Oracle in the LICENSE file that accompanied this code. 10214571Sdim * 11214571Sdim * This code is distributed in the hope that it will be useful, but WITHOUT 12214571Sdim * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13214571Sdim * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14214571Sdim * version 2 for more details (a copy is included in the LICENSE file that 15214571Sdim * accompanied this code). 16214571Sdim * 17214571Sdim * You should have received a copy of the GNU General Public License version 18214571Sdim * 2 along with this work; if not, write to the Free Software Foundation, 19214571Sdim * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20214571Sdim * 21214571Sdim * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22214571Sdim * or visit www.oracle.com if you need additional information or have any 23214571Sdim * questions. 24214571Sdim */ 25214571Sdim 26214571Sdimpackage javax.lang.model.element; 27214571Sdim 28214571Sdimimport javax.lang.model.util.*; 29214571Sdim 30214571Sdim/** 31214571Sdim * A visitor of program elements, in the style of the visitor design 32214571Sdim * pattern. Classes implementing this interface are used to operate 33214571Sdim * on an element when the kind of element is unknown at compile time. 34214571Sdim * When a visitor is passed to an element's {@link Element#accept 35214571Sdim * accept} method, the <code>visit<i>Xyz</i></code> method most applicable 36214571Sdim * to that element is invoked. 37214571Sdim * 38214571Sdim * <p> Classes implementing this interface may or may not throw a 39214571Sdim * {@code NullPointerException} if the additional parameter {@code p} 40214571Sdim * is {@code null}; see documentation of the implementing class for 41214571Sdim * details. 42214571Sdim * 43214571Sdim * <p> <b>WARNING:</b> It is possible that methods will be added to 44214571Sdim * this interface to accommodate new, currently unknown, language 45214571Sdim * structures added to future versions of the Java™ programming 46214571Sdim * language. Therefore, visitor classes directly implementing this 47214571Sdim * interface may be source incompatible with future versions of the 48214571Sdim * platform. To avoid this source incompatibility, visitor 49214571Sdim * implementations are encouraged to instead extend the appropriate 50214571Sdim * abstract visitor class that implements this interface. However, an 51214571Sdim * API should generally use this visitor interface as the type for 52214571Sdim * parameters, return type, etc. rather than one of the abstract 53214571Sdim * classes. 54214571Sdim * 55214571Sdim * <p>Note that methods to accommodate new language constructs could 56214571Sdim * be added in a source <em>compatible</em> way if they were added as 57214571Sdim * <em>default methods</em>. However, default methods are only 58214571Sdim * available on Java SE 8 and higher releases and the {@code 59214571Sdim * javax.lang.model.*} packages bundled in Java SE 8 were required to 60214571Sdim * also be runnable on Java SE 7. Therefore, default methods 61214571Sdim * were <em>not</em> used when extending {@code javax.lang.model.*} 62214571Sdim * to cover Java SE 8 language features. However, default methods 63214571Sdim * are used in subsequent revisions of the {@code javax.lang.model.*} 64214571Sdim * packages that are only required to run on Java SE 8 and higher 65214571Sdim * platform versions. 66214571Sdim * 67214571Sdim * @param <R> the return type of this visitor's methods. Use {@link 68214571Sdim * Void} for visitors that do not need to return results. 69214571Sdim * @param <P> the type of the additional parameter to this visitor's 70214571Sdim * methods. Use {@code Void} for visitors that do not need an 71214571Sdim * additional parameter. 72214571Sdim * 73214571Sdim * @author Joseph D. Darcy 74214571Sdim * @author Scott Seligman 75214571Sdim * @author Peter von der Ahé 76214571Sdim * @since 1.6 77214571Sdim */ 78214571Sdimpublic interface ElementVisitor<R, P> { 79214571Sdim /** 80214571Sdim * Visits an element. 81214571Sdim * @param e the element to visit 82214571Sdim * @param p a visitor-specified parameter 83214571Sdim * @return a visitor-specified result 84214571Sdim */ 85214571Sdim R visit(Element e, P p); 86214571Sdim 87214571Sdim /** 88214571Sdim * A convenience method equivalent to {@code visit(e, null)}. 89214571Sdim * 90214571Sdim * @implSpec The default implementation is {@code visit(e, null)}. 91214571Sdim * 92214571Sdim * @param e the element to visit 93214571Sdim * @return a visitor-specified result 94214571Sdim */ 95214571Sdim default R visit(Element e) { 96214571Sdim return visit(e, null); 97214571Sdim } 98214571Sdim 99214571Sdim /** 100214571Sdim * Visits a package element. 101214571Sdim * @param e the element to visit 102214571Sdim * @param p a visitor-specified parameter 103214571Sdim * @return a visitor-specified result 104214571Sdim */ 105214571Sdim R visitPackage(PackageElement e, P p); 106214571Sdim 107214571Sdim /** 108214571Sdim * Visits a type element. 109214571Sdim * @param e the element to visit 110214571Sdim * @param p a visitor-specified parameter 111214571Sdim * @return a visitor-specified result 112214571Sdim */ 113214571Sdim R visitType(TypeElement e, P p); 114214571Sdim 115214571Sdim /** 116214571Sdim * Visits a variable element. 117214571Sdim * @param e the element to visit 118214571Sdim * @param p a visitor-specified parameter 119214571Sdim * @return a visitor-specified result 120214571Sdim */ 121214571Sdim R visitVariable(VariableElement e, P p); 122214571Sdim 123214571Sdim /** 124214571Sdim * Visits an executable element. 125214571Sdim * @param e the element to visit 126214571Sdim * @param p a visitor-specified parameter 127214571Sdim * @return a visitor-specified result 128214571Sdim */ 129214571Sdim R visitExecutable(ExecutableElement e, P p); 130214571Sdim 131214571Sdim /** 132214571Sdim * Visits a type parameter element. 133214571Sdim * @param e the element to visit 134214571Sdim * @param p a visitor-specified parameter 135214571Sdim * @return a visitor-specified result 136214571Sdim */ 137214571Sdim R visitTypeParameter(TypeParameterElement e, P p); 138214571Sdim 139214571Sdim /** 140214571Sdim * Visits an unknown kind of element. 141214571Sdim * This can occur if the language evolves and new kinds 142214571Sdim * of elements are added to the {@code Element} hierarchy. 143214571Sdim * 144214571Sdim * @param e the element to visit 145214571Sdim * @param p a visitor-specified parameter 146214571Sdim * @return a visitor-specified result 147214571Sdim * @throws UnknownElementException 148214571Sdim * a visitor implementation may optionally throw this exception 149214571Sdim */ 150214571Sdim R visitUnknown(Element e, P p); 151214571Sdim 152214571Sdim /** 153214571Sdim * Visits a module element. 154214571Sdim * 155214571Sdim * @implSpec Visits a {@code ModuleElement} by calling {@code 156214571Sdim * visitUnknown(e, p)}. 157214571Sdim * 158214571Sdim * @param e the element to visit 159214571Sdim * @param p a visitor-specified parameter 160214571Sdim * @return a visitor-specified result 161214571Sdim * @since 9 162214571Sdim */ 163214571Sdim default R visitModule(ModuleElement e, P p) { 164214571Sdim return visitUnknown(e, p); 165214571Sdim } 166214571Sdim} 167214571Sdim