1 /*
   2  * Copyright (c) 2005, 2017, 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 static javax.lang.model.element.ElementKind.*;
  30 import javax.annotation.processing.SupportedSourceVersion;
  31 import static javax.lang.model.SourceVersion.*;
  32 import javax.lang.model.SourceVersion;
  33 
  34 
  35 /**
  36  * A visitor of program elements based on their {@linkplain
  37  * ElementKind kind} with default behavior appropriate for the {@link
  38  * SourceVersion#RELEASE_6 RELEASE_6} source version.  For {@linkplain
  39  * Element elements} <code><i>Xyz</i></code> that may have more than one
  40  * kind, the <code>visit<i>Xyz</i></code> methods in this class delegate
  41  * to the <code>visit<i>Xyz</i>As<i>Kind</i></code> method corresponding to the
  42  * first argument's kind.  The <code>visit<i>Xyz</i>As<i>Kind</i></code> methods
  43  * call {@link #defaultAction defaultAction}, passing their arguments
  44  * to {@code defaultAction}'s corresponding parameters.
  45  *
  46  * <p> Methods in this class may be overridden subject to their
  47  * general contract.  Note that annotating methods in concrete
  48  * subclasses with {@link java.lang.Override @Override} will help
  49  * ensure that methods are overridden as intended.
  50  *
  51  * <p> <b>WARNING:</b> The {@code ElementVisitor} interface
  52  * implemented by this class may have methods added to it or the
  53  * {@code ElementKind} {@code enum} used in this case may have
  54  * constants added to it in the future to accommodate new, currently
  55  * unknown, language structures added to future versions of the
  56  * Java&trade; programming language.  Therefore, methods whose names
  57  * begin with {@code "visit"} may be added to this class in the
  58  * future; to avoid incompatibilities, classes which extend this class
  59  * should not declare any instance methods with names beginning with
  60  * {@code "visit"}.
  61  *
  62  * <p>When such a new visit method is added, the default
  63  * implementation in this class will be to call the {@link
  64  * #visitUnknown visitUnknown} method.  A new abstract element kind
  65  * visitor class will also be introduced to correspond to the new
  66  * language level; this visitor will have different default behavior
  67  * for the visit method in question.  When the new visitor is
  68  * introduced, all or portions of this visitor may be deprecated.
  69  *
  70  * @param <R> the return type of this visitor's methods.  Use {@link
  71  *            Void} for visitors that do not need to return results.
  72  * @param <P> the type of the additional parameter to this visitor's
  73  *            methods.  Use {@code Void} for visitors that do not need an
  74  *            additional parameter.
  75  *
  76  * @author Joseph D. Darcy
  77  * @author Scott Seligman
  78  * @author Peter von der Ah&eacute;
  79  *
  80  * @see ElementKindVisitor7
  81  * @see ElementKindVisitor8
  82  * @see ElementKindVisitor9
  83  * @since 1.6
  84  */
  85 @SupportedSourceVersion(RELEASE_6)
  86 public class ElementKindVisitor6<R, P>
  87                   extends SimpleElementVisitor6<R, P> {
  88     /**
  89      * Constructor for concrete subclasses; uses {@code null} for the
  90      * default value.
  91      * @deprecated Release 6 is obsolete; update to a visitor for a newer
  92      * release level.
  93      */
  94     @Deprecated(since="9")
  95     protected ElementKindVisitor6() {
  96         super(null);
  97     }
  98 
  99     /**
 100      * Constructor for concrete subclasses; uses the argument for the
 101      * default value.
 102      *
 103      * @param defaultValue the value to assign to {@link #DEFAULT_VALUE}
 104      * @deprecated Release 6 is obsolete; update to a visitor for a newer
 105      * release level.
 106      */
 107     @Deprecated(since="9")
 108     protected ElementKindVisitor6(R defaultValue) {
 109         super(defaultValue);
 110     }
 111 
 112     /**
 113      * {@inheritDoc}
 114      *
 115      * The element argument has kind {@code PACKAGE}.
 116      *
 117      * @implSpec This implementation calls {@code defaultAction}.
 118      *
 119      * @param e {@inheritDoc}
 120      * @param p {@inheritDoc}
 121      * @return  {@inheritDoc}
 122      */
 123     @Override
 124     public R visitPackage(PackageElement e, P p) {
 125         assert e.getKind() == PACKAGE: "Bad kind on PackageElement";
 126         return defaultAction(e, p);
 127     }
 128 
 129     /**
 130      * {@inheritDoc}
 131      *
 132      * @implSpec This implementation dispatches to the visit method for the
 133      * specific {@linkplain ElementKind kind} of type, {@code
 134      * ANNOTATION_TYPE}, {@code CLASS}, {@code ENUM}, or {@code
 135      * INTERFACE}.
 136      *
 137      * @param e {@inheritDoc}
 138      * @param p {@inheritDoc}
 139      * @return  the result of the kind-specific visit method
 140      */
 141     @Override
 142     public R visitType(TypeElement e, P p) {
 143         ElementKind k = e.getKind();
 144         switch(k) {
 145         case ANNOTATION_TYPE:
 146             return visitTypeAsAnnotationType(e, p);
 147 
 148         case CLASS:
 149             return visitTypeAsClass(e, p);
 150 
 151         case ENUM:
 152             return visitTypeAsEnum(e, p);
 153 
 154         case INTERFACE:
 155             return visitTypeAsInterface(e, p);
 156 
 157         case RECORD:
 158             return visitTypeAsRecord(e, p);
 159 
 160         default:
 161             throw new AssertionError("Bad kind " + k + " for TypeElement" + e);
 162         }
 163     }
 164 
 165     /**
 166      * Visits an {@code ANNOTATION_TYPE} type element.
 167      *
 168      * @implSpec This implementation calls {@code defaultAction}.
 169      *
 170      * @param e the element to visit
 171      * @param p a visitor-specified parameter
 172      * @return  the result of {@code defaultAction}
 173      */
 174     public R visitTypeAsAnnotationType(TypeElement e, P p) {
 175         return defaultAction(e, p);
 176     }
 177 
 178     /**
 179      * Visits a {@code CLASS} type element.
 180      *
 181      * @implSpec This implementation calls {@code defaultAction}.
 182      *
 183      * @param e the element to visit
 184      * @param p a visitor-specified parameter
 185      * @return  the result of {@code defaultAction}
 186      */
 187     public R visitTypeAsClass(TypeElement e, P p) {
 188         return defaultAction(e, p);
 189     }
 190 
 191     /**
 192      * Visits an {@code ENUM} type element.
 193      *
 194      * @implSpec This implementation calls {@code defaultAction}.
 195      *
 196      * @param e the element to visit
 197      * @param p a visitor-specified parameter
 198      * @return  the result of {@code defaultAction}
 199      */
 200     public R visitTypeAsEnum(TypeElement e, P p) {
 201         return defaultAction(e, p);
 202     }
 203 
 204     /**
 205      * Visits an {@code INTERFACE} type element.
 206      *
 207      * @implSpec This implementation calls {@code defaultAction}.
 208      *.
 209      * @param e the element to visit
 210      * @param p a visitor-specified parameter
 211      * @return  the result of {@code defaultAction}
 212      */
 213     public R visitTypeAsInterface(TypeElement e, P p) {
 214         return defaultAction(e, p);
 215     }
 216 
 217     /**
 218      * Visits a {@code RECORD} type element.
 219      *
 220      * @implSpec This implementation calls {@code visitUnknown}.
 221      *.
 222      * @param e the element to visit
 223      * @param p a visitor-specified parameter
 224      * @return  the result of {@code visitUnknown}
 225      *
 226      * @since amber
 227      */
 228     public R visitTypeAsRecord(TypeElement e, P p) {
 229         return visitUnknown(e, p);
 230     }
 231 
 232     /**
 233      * Visits a variable element
 234      *
 235      * @implSpec This implementation dispatches to the visit method for
 236      * the specific {@linkplain ElementKind kind} of variable, {@code
 237      * ENUM_CONSTANT}, {@code EXCEPTION_PARAMETER}, {@code FIELD},
 238      * {@code LOCAL_VARIABLE}, {@code PARAMETER}, {@code RESOURCE_VARIABLE},
 239      * or {@code STATE_COMPONENT}.
 240      *
 241      * @param e {@inheritDoc}
 242      * @param p {@inheritDoc}
 243      * @return  the result of the kind-specific visit method
 244      */
 245     @Override
 246     public R visitVariable(VariableElement e, P p) {
 247         ElementKind k = e.getKind();
 248         switch(k) {
 249         case ENUM_CONSTANT:
 250             return visitVariableAsEnumConstant(e, p);
 251 
 252         case EXCEPTION_PARAMETER:
 253             return visitVariableAsExceptionParameter(e, p);
 254 
 255         case FIELD:
 256             return visitVariableAsField(e, p);
 257 
 258         case LOCAL_VARIABLE:
 259             return visitVariableAsLocalVariable(e, p);
 260 
 261         case PARAMETER:
 262             return visitVariableAsParameter(e, p);
 263 
 264         case RESOURCE_VARIABLE:
 265             return visitVariableAsResourceVariable(e, p);
 266 
 267         case STATE_COMPONENT:
 268             return visitVariableAsStateComponent(e, p);
 269 
 270         default:
 271             throw new AssertionError("Bad kind " + k + " for VariableElement" + e);
 272         }
 273     }
 274 
 275     /**
 276      * Visits an {@code ENUM_CONSTANT} variable element.
 277      *
 278      * @implSpec This implementation calls {@code defaultAction}.
 279      *.
 280      * @param e the element to visit
 281      * @param p a visitor-specified parameter
 282      * @return  the result of {@code defaultAction}
 283      */
 284     public R visitVariableAsEnumConstant(VariableElement e, P p) {
 285         return defaultAction(e, p);
 286     }
 287 
 288     /**
 289      * Visits an {@code EXCEPTION_PARAMETER} variable element.
 290      *
 291      * @implSpec This implementation calls {@code defaultAction}.
 292      *.
 293      * @param e the element to visit
 294      * @param p a visitor-specified parameter
 295      * @return  the result of {@code defaultAction}
 296      */
 297     public R visitVariableAsExceptionParameter(VariableElement e, P p) {
 298         return defaultAction(e, p);
 299     }
 300 
 301     /**
 302      * Visits a {@code FIELD} variable element.
 303      *
 304      * @implSpec This implementation calls {@code defaultAction}.
 305      *.
 306      * @param e the element to visit
 307      * @param p a visitor-specified parameter
 308      * @return  the result of {@code defaultAction}
 309      */
 310     public R visitVariableAsField(VariableElement e, P p) {
 311         return defaultAction(e, p);
 312     }
 313 
 314     /**
 315      * Visits a {@code LOCAL_VARIABLE} variable element.
 316      *
 317      * @implSpec This implementation calls {@code defaultAction}.
 318      *
 319      * @param e the element to visit
 320      * @param p a visitor-specified parameter
 321      * @return  the result of {@code defaultAction}
 322      */
 323     public R visitVariableAsLocalVariable(VariableElement e, P p) {
 324         return defaultAction(e, p);
 325     }
 326 
 327     /**
 328      * Visits a {@code PARAMETER} variable element.
 329      *
 330      * @implSpec This implementation calls {@code defaultAction}.
 331      *
 332      * @param e the element to visit
 333      * @param p a visitor-specified parameter
 334      * @return  the result of {@code defaultAction}
 335      */
 336     public R visitVariableAsParameter(VariableElement e, P p) {
 337         return defaultAction(e, p);
 338     }
 339 
 340     /**
 341      * Visits a {@code RESOURCE_VARIABLE} variable element.
 342      *
 343      * @implSpec This implementation calls {@code visitUnknown}.
 344      *
 345      * @param e the element to visit
 346      * @param p a visitor-specified parameter
 347      * @return  the result of {@code visitUnknown}
 348      *
 349      * @since 1.7
 350      */
 351     public R visitVariableAsResourceVariable(VariableElement e, P p) {
 352         return visitUnknown(e, p);
 353     }
 354 
 355     /**
 356      * Visits a {@code STATE_COMPONENT} variable element.
 357      *
 358      * @implSpec This implementation calls {@code visitUnknown}.
 359      *
 360      * @param e the element to visit
 361      * @param p a visitor-specified parameter
 362      * @return  the result of {@code visitUnknown}
 363      *
 364      * @since amber
 365      */
 366     public R visitVariableAsStateComponent(VariableElement e, P p) {
 367         return visitUnknown(e, p);
 368     }
 369 
 370     /**
 371      * {@inheritDoc}
 372      *
 373      * @implSpec This implementation dispatches to the visit method
 374      * for the specific {@linkplain ElementKind kind} of executable,
 375      * {@code CONSTRUCTOR}, {@code INSTANCE_INIT}, {@code METHOD}, or
 376      * {@code STATIC_INIT}.
 377      *
 378      * @param e {@inheritDoc}
 379      * @param p {@inheritDoc}
 380      * @return  the result of the kind-specific visit method
 381      */
 382     @Override
 383     public R visitExecutable(ExecutableElement e, P p) {
 384         ElementKind k = e.getKind();
 385         switch(k) {
 386         case CONSTRUCTOR:
 387             return visitExecutableAsConstructor(e, p);
 388 
 389         case INSTANCE_INIT:
 390             return visitExecutableAsInstanceInit(e, p);
 391 
 392         case METHOD:
 393             return visitExecutableAsMethod(e, p);
 394 
 395         case STATIC_INIT:
 396             return visitExecutableAsStaticInit(e, p);
 397 
 398         default:
 399             throw new AssertionError("Bad kind " + k + " for ExecutableElement" + e);
 400         }
 401     }
 402 
 403     /**
 404      * Visits a {@code CONSTRUCTOR} executable element.
 405      *
 406      * @implSpec This implementation calls {@code defaultAction}.
 407      *
 408      * @param e the element to visit
 409      * @param p a visitor-specified parameter
 410      * @return  the result of {@code defaultAction}
 411      */
 412     public R visitExecutableAsConstructor(ExecutableElement e, P p) {
 413         return defaultAction(e, p);
 414     }
 415 
 416     /**
 417      * Visits an {@code INSTANCE_INIT} executable element.
 418      *
 419      * @implSpec This implementation calls {@code defaultAction}.
 420      *
 421      * @param e the element to visit
 422      * @param p a visitor-specified parameter
 423      * @return  the result of {@code defaultAction}
 424      */
 425     public R visitExecutableAsInstanceInit(ExecutableElement e, P p) {
 426         return defaultAction(e, p);
 427     }
 428 
 429     /**
 430      * Visits a {@code METHOD} executable element.
 431      *
 432      * @implSpec This implementation calls {@code defaultAction}.
 433      *
 434      * @param e the element to visit
 435      * @param p a visitor-specified parameter
 436      * @return  the result of {@code defaultAction}
 437      */
 438     public R visitExecutableAsMethod(ExecutableElement e, P p) {
 439         return defaultAction(e, p);
 440     }
 441 
 442     /**
 443      * Visits a {@code STATIC_INIT} executable element.
 444      *
 445      * @implSpec This implementation calls {@code defaultAction}.
 446      *
 447      * @param e the element to visit
 448      * @param p a visitor-specified parameter
 449      * @return  the result of {@code defaultAction}
 450      */
 451     public R visitExecutableAsStaticInit(ExecutableElement e, P p) {
 452         return defaultAction(e, p);
 453     }
 454 
 455     /**
 456      * {@inheritDoc}
 457      *
 458      * The element argument has kind {@code TYPE_PARAMETER}.
 459      *
 460      * @implSpec This implementation calls {@code defaultAction}.
 461      *
 462      * @param e {@inheritDoc}
 463      * @param p {@inheritDoc}
 464      * @return  {@inheritDoc}
 465      */
 466     @Override
 467     public R visitTypeParameter(TypeParameterElement e, P p) {
 468         assert e.getKind() == TYPE_PARAMETER: "Bad kind on TypeParameterElement";
 469         return defaultAction(e, p);
 470     }
 471 }