src/share/classes/javax/lang/model/element/ElementVisitor.java

Wed, 23 Jan 2013 20:11:07 -0800

author
darcy
date
Wed, 23 Jan 2013 20:11:07 -0800
changeset 1522
09f65aad4759
parent 798
4868a36f6fd8
child 2525
2eb010b6cb22
permissions
-rw-r--r--

8006264: Add explanation of why default methods cannot be used in JDK 8 javax.lang.model
Reviewed-by: jjg

duke@1 1 /*
darcy@1522 2 * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
duke@1 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
duke@1 4 *
duke@1 5 * This code is free software; you can redistribute it and/or modify it
duke@1 6 * under the terms of the GNU General Public License version 2 only, as
ohair@554 7 * published by the Free Software Foundation. Oracle designates this
duke@1 8 * particular file as subject to the "Classpath" exception as provided
ohair@554 9 * by Oracle in the LICENSE file that accompanied this code.
duke@1 10 *
duke@1 11 * This code is distributed in the hope that it will be useful, but WITHOUT
duke@1 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
duke@1 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
duke@1 14 * version 2 for more details (a copy is included in the LICENSE file that
duke@1 15 * accompanied this code).
duke@1 16 *
duke@1 17 * You should have received a copy of the GNU General Public License version
duke@1 18 * 2 along with this work; if not, write to the Free Software Foundation,
duke@1 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
duke@1 20 *
ohair@554 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
ohair@554 22 * or visit www.oracle.com if you need additional information or have any
ohair@554 23 * questions.
duke@1 24 */
duke@1 25
duke@1 26 package javax.lang.model.element;
duke@1 27
duke@1 28 import javax.lang.model.util.*;
duke@1 29
duke@1 30 /**
duke@1 31 * A visitor of program elements, in the style of the visitor design
duke@1 32 * pattern. Classes implementing this interface are used to operate
duke@1 33 * on an element when the kind of element is unknown at compile time.
duke@1 34 * When a visitor is passed to an element's {@link Element#accept
duke@1 35 * accept} method, the <tt>visit<i>XYZ</i></tt> method most applicable
duke@1 36 * to that element is invoked.
duke@1 37 *
duke@1 38 * <p> Classes implementing this interface may or may not throw a
duke@1 39 * {@code NullPointerException} if the additional parameter {@code p}
duke@1 40 * is {@code null}; see documentation of the implementing class for
duke@1 41 * details.
duke@1 42 *
duke@1 43 * <p> <b>WARNING:</b> It is possible that methods will be added to
duke@1 44 * this interface to accommodate new, currently unknown, language
duke@1 45 * structures added to future versions of the Java&trade; programming
duke@1 46 * language. Therefore, visitor classes directly implementing this
duke@1 47 * interface may be source incompatible with future versions of the
duke@1 48 * platform. To avoid this source incompatibility, visitor
duke@1 49 * implementations are encouraged to instead extend the appropriate
duke@1 50 * abstract visitor class that implements this interface. However, an
duke@1 51 * API should generally use this visitor interface as the type for
duke@1 52 * parameters, return type, etc. rather than one of the abstract
duke@1 53 * classes.
duke@1 54 *
darcy@1522 55 * <p>Note that methods to accommodate new language constructs could
darcy@1522 56 * be added in a source <em>compatible</em> way if they were added as
darcy@1522 57 * <em>default methods</em>. However, default methods are only
darcy@1522 58 * available on Java SE 8 and higher releases and the {@code
darcy@1522 59 * javax.lang.model.*} packages bundled in Java SE 8 are required to
darcy@1522 60 * also be runnable on Java SE 7. Therefore, default methods
darcy@1522 61 * <em>cannot</em> be used when extending {@code javax.lang.model.*}
darcy@1522 62 * to cover Java SE 8 language features. However, default methods may
darcy@1522 63 * be used in subsequent revisions of the {@code javax.lang.model.*}
darcy@1522 64 * packages that are only required to run on Java SE 8 and higher
darcy@1522 65 * platform versions.
darcy@1522 66 *
duke@1 67 * @param <R> the return type of this visitor's methods. Use {@link
duke@1 68 * Void} for visitors that do not need to return results.
duke@1 69 * @param <P> the type of the additional parameter to this visitor's
duke@1 70 * methods. Use {@code Void} for visitors that do not need an
duke@1 71 * additional parameter.
duke@1 72 *
duke@1 73 * @author Joseph D. Darcy
duke@1 74 * @author Scott Seligman
duke@1 75 * @author Peter von der Ah&eacute;
duke@1 76 * @see AbstractElementVisitor6
darcy@575 77 * @see AbstractElementVisitor7
duke@1 78 * @since 1.6
duke@1 79 */
duke@1 80 public interface ElementVisitor<R, P> {
duke@1 81 /**
duke@1 82 * Visits an element.
duke@1 83 * @param e the element to visit
duke@1 84 * @param p a visitor-specified parameter
duke@1 85 * @return a visitor-specified result
duke@1 86 */
duke@1 87 R visit(Element e, P p);
duke@1 88
duke@1 89 /**
duke@1 90 * A convenience method equivalent to {@code v.visit(e, null)}.
duke@1 91 * @param e the element to visit
duke@1 92 * @return a visitor-specified result
duke@1 93 */
duke@1 94 R visit(Element e);
duke@1 95
duke@1 96 /**
duke@1 97 * Visits a package element.
duke@1 98 * @param e the element to visit
duke@1 99 * @param p a visitor-specified parameter
duke@1 100 * @return a visitor-specified result
duke@1 101 */
duke@1 102 R visitPackage(PackageElement e, P p);
duke@1 103
duke@1 104 /**
duke@1 105 * Visits a type element.
duke@1 106 * @param e the element to visit
duke@1 107 * @param p a visitor-specified parameter
duke@1 108 * @return a visitor-specified result
duke@1 109 */
duke@1 110 R visitType(TypeElement e, P p);
duke@1 111
duke@1 112 /**
duke@1 113 * Visits a variable element.
duke@1 114 * @param e the element to visit
duke@1 115 * @param p a visitor-specified parameter
duke@1 116 * @return a visitor-specified result
duke@1 117 */
duke@1 118 R visitVariable(VariableElement e, P p);
duke@1 119
duke@1 120 /**
duke@1 121 * Visits an executable element.
duke@1 122 * @param e the element to visit
duke@1 123 * @param p a visitor-specified parameter
duke@1 124 * @return a visitor-specified result
duke@1 125 */
duke@1 126 R visitExecutable(ExecutableElement e, P p);
duke@1 127
duke@1 128 /**
duke@1 129 * Visits a type parameter element.
duke@1 130 * @param e the element to visit
duke@1 131 * @param p a visitor-specified parameter
duke@1 132 * @return a visitor-specified result
duke@1 133 */
duke@1 134 R visitTypeParameter(TypeParameterElement e, P p);
duke@1 135
duke@1 136 /**
duke@1 137 * Visits an unknown kind of element.
duke@1 138 * This can occur if the language evolves and new kinds
duke@1 139 * of elements are added to the {@code Element} hierarchy.
duke@1 140 *
duke@1 141 * @param e the element to visit
duke@1 142 * @param p a visitor-specified parameter
duke@1 143 * @return a visitor-specified result
duke@1 144 * @throws UnknownElementException
duke@1 145 * a visitor implementation may optionally throw this exception
duke@1 146 */
duke@1 147 R visitUnknown(Element e, P p);
duke@1 148 }

mercurial