ElementVisitor.java revision 3976:65d446c80cdf
133965Sjdp/* 2130561Sobrien * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved. 3130561Sobrien * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4218822Sdim * 5130561Sobrien * This code is free software; you can redistribute it and/or modify it 633965Sjdp * under the terms of the GNU General Public License version 2 only, as 733965Sjdp * published by the Free Software Foundation. Oracle designates this 833965Sjdp * particular file as subject to the "Classpath" exception as provided 933965Sjdp * by Oracle in the LICENSE file that accompanied this code. 1033965Sjdp * 1133965Sjdp * This code is distributed in the hope that it will be useful, but WITHOUT 1233965Sjdp * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1333965Sjdp * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1433965Sjdp * version 2 for more details (a copy is included in the LICENSE file that 1533965Sjdp * accompanied this code). 1633965Sjdp * 1733965Sjdp * You should have received a copy of the GNU General Public License version 1833965Sjdp * 2 along with this work; if not, write to the Free Software Foundation, 1933965Sjdp * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2033965Sjdp * 2133965Sjdp * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22218822Sdim * or visit www.oracle.com if you need additional information or have any 2333965Sjdp * questions. 2433965Sjdp */ 2533965Sjdp 2633965Sjdppackage javax.lang.model.element; 2733965Sjdp 2833965Sjdpimport javax.lang.model.util.*; 2933965Sjdp 3033965Sjdp/** 3133965Sjdp * A visitor of program elements, in the style of the visitor design 3233965Sjdp * pattern. Classes implementing this interface are used to operate 3333965Sjdp * on an element when the kind of element is unknown at compile time. 3433965Sjdp * When a visitor is passed to an element's {@link Element#accept 3533965Sjdp * accept} method, the <code>visit<i>Xyz</i></code> method most applicable 3633965Sjdp * to that element is invoked. 3777298Sobrien * 3833965Sjdp * <p> Classes implementing this interface may or may not throw a 39218822Sdim * {@code NullPointerException} if the additional parameter {@code p} 40218822Sdim * is {@code null}; see documentation of the implementing class for 4133965Sjdp * details. 4233965Sjdp * 43218822Sdim * <p> <b>WARNING:</b> It is possible that methods will be added to 4433965Sjdp * this interface to accommodate new, currently unknown, language 4533965Sjdp * structures added to future versions of the Java™ programming 46218822Sdim * language. Therefore, visitor classes directly implementing this 4733965Sjdp * interface may be source incompatible with future versions of the 48218822Sdim * platform. To avoid this source incompatibility, visitor 49218822Sdim * implementations are encouraged to instead extend the appropriate 50218822Sdim * abstract visitor class that implements this interface. However, an 51218822Sdim * API should generally use this visitor interface as the type for 52218822Sdim * parameters, return type, etc. rather than one of the abstract 53218822Sdim * classes. 54218822Sdim * 55218822Sdim * <p>Note that methods to accommodate new language constructs could 56218822Sdim * be added in a source <em>compatible</em> way if they were added as 57218822Sdim * <em>default methods</em>. However, default methods are only 58218822Sdim * available on Java SE 8 and higher releases and the {@code 59218822Sdim * javax.lang.model.*} packages bundled in Java SE 8 were required to 60218822Sdim * also be runnable on Java SE 7. Therefore, default methods 61218822Sdim * were <em>not</em> used when extending {@code javax.lang.model.*} 6233965Sjdp * to cover Java SE 8 language features. However, default methods 63218822Sdim * are used in subsequent revisions of the {@code javax.lang.model.*} 64218822Sdim * packages that are only required to run on Java SE 8 and higher 6533965Sjdp * platform versions. 66218822Sdim * 6733965Sjdp * @param <R> the return type of this visitor's methods. Use {@link 6833965Sjdp * Void} for visitors that do not need to return results. 6933965Sjdp * @param <P> the type of the additional parameter to this visitor's 7033965Sjdp * methods. Use {@code Void} for visitors that do not need an 7133965Sjdp * additional parameter. 72218822Sdim * 73218822Sdim * @author Joseph D. Darcy 74218822Sdim * @author Scott Seligman 7533965Sjdp * @author Peter von der Ahé 76218822Sdim * @since 1.6 7733965Sjdp */ 7833965Sjdppublic interface ElementVisitor<R, P> { 7933965Sjdp /** 80130561Sobrien * Visits an element. 81130561Sobrien * @param e the element to visit 8233965Sjdp * @param p a visitor-specified parameter 8333965Sjdp * @return a visitor-specified result 8433965Sjdp */ 8533965Sjdp R visit(Element e, P p); 8633965Sjdp 8733965Sjdp /** 8833965Sjdp * A convenience method equivalent to {@code visit(e, null)}. 8933965Sjdp * 9033965Sjdp * @implSpec The default implementation is {@code visit(e, null)}. 9133965Sjdp * 9233965Sjdp * @param e the element to visit 9333965Sjdp * @return a visitor-specified result 9433965Sjdp */ 9533965Sjdp default R visit(Element e) { 9633965Sjdp return visit(e, null); 9733965Sjdp } 9833965Sjdp 9933965Sjdp /** 100130561Sobrien * Visits a package element. 101130561Sobrien * @param e the element to visit 10233965Sjdp * @param p a visitor-specified parameter 10333965Sjdp * @return a visitor-specified result 10433965Sjdp */ 10533965Sjdp R visitPackage(PackageElement e, P p); 10633965Sjdp 10733965Sjdp /** 10833965Sjdp * Visits a type element. 10933965Sjdp * @param e the element to visit 11033965Sjdp * @param p a visitor-specified parameter 11133965Sjdp * @return a visitor-specified result 11233965Sjdp */ 113218822Sdim R visitType(TypeElement e, P p); 114218822Sdim 115218822Sdim /** 116218822Sdim * Visits a variable element. 117218822Sdim * @param e the element to visit 118218822Sdim * @param p a visitor-specified parameter 119218822Sdim * @return a visitor-specified result 120218822Sdim */ 121218822Sdim R visitVariable(VariableElement e, P p); 122218822Sdim 123218822Sdim /** 124218822Sdim * Visits an executable element. 125218822Sdim * @param e the element to visit 126218822Sdim * @param p a visitor-specified parameter 127218822Sdim * @return a visitor-specified result 128218822Sdim */ 129218822Sdim R visitExecutable(ExecutableElement e, P p); 130218822Sdim 131218822Sdim /** 132218822Sdim * Visits a type parameter element. 133218822Sdim * @param e the element to visit 134218822Sdim * @param p a visitor-specified parameter 135218822Sdim * @return a visitor-specified result 13633965Sjdp */ 13733965Sjdp R visitTypeParameter(TypeParameterElement e, P p); 13833965Sjdp 139130561Sobrien /** 140130561Sobrien * Visits an unknown kind of element. 14133965Sjdp * This can occur if the language evolves and new kinds 14233965Sjdp * of elements are added to the {@code Element} hierarchy. 14333965Sjdp * 14433965Sjdp * @param e the element to visit 14533965Sjdp * @param p a visitor-specified parameter 14633965Sjdp * @return a visitor-specified result 14733965Sjdp * @throws UnknownElementException 14833965Sjdp * a visitor implementation may optionally throw this exception 14933965Sjdp */ 15033965Sjdp R visitUnknown(Element e, P p); 15133965Sjdp 15233965Sjdp /** 15333965Sjdp * Visits a module element. 15433965Sjdp * 15533965Sjdp * @implSpec Visits a {@code ModuleElement} by calling {@code 15633965Sjdp * visitUnknown(e, p)}. 15733965Sjdp * 15833965Sjdp * @param e the element to visit 15933965Sjdp * @param p a visitor-specified parameter 16033965Sjdp * @return a visitor-specified result 16133965Sjdp * @since 9 16233965Sjdp * @spec JPMS 163130561Sobrien */ 16433965Sjdp default R visitModule(ModuleElement e, P p) { 16533965Sjdp return visitUnknown(e, p); 166130561Sobrien } 16733965Sjdp} 168218822Sdim