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 com.sun.source.util;
  27 
  28 import com.sun.source.doctree.*;
  29 
  30 /**
  31  * A simple visitor for tree nodes.
  32  *
  33  * @param <R> the return type of this visitor's methods.  Use {@link
  34  *            Void} for visitors that do not need to return results.
  35  * @param <P> the type of the additional parameter to this visitor's
  36  *            methods.  Use {@code Void} for visitors that do not need an
  37  *            additional parameter.
  38  *
  39  * @since 1.8
  40  */
  41 public class SimpleDocTreeVisitor<R,P> implements DocTreeVisitor<R, P> {
  42     /**
  43      * The default value, returned by the {@link #defaultAction default action}.
  44      */
  45     protected final R DEFAULT_VALUE;
  46 
  47     /**
  48      * Creates a visitor, with a DEFAULT_VALUE of {@code null}.
  49      */
  50     protected SimpleDocTreeVisitor() {
  51         DEFAULT_VALUE = null;
  52     }
  53 
  54     /**
  55      * Creates a visitor, with a specified DEFAULT_VALUE.
  56      * @param defaultValue the default value to be returned by the default action.
  57      */
  58     protected SimpleDocTreeVisitor(R defaultValue) {
  59         DEFAULT_VALUE = defaultValue;
  60     }
  61 
  62     /**
  63      * The default action, used by all visit methods that are not overridden.
  64      * @param node the node being visited
  65      * @param p the parameter value passed to the visit method
  66      * @return the result value to be returned from the visit method
  67      */
  68     protected R defaultAction(DocTree node, P p) {
  69         return DEFAULT_VALUE;
  70     }
  71 
  72     /**
  73      * Invokes the appropriate visit method specific to the type of the node.
  74      * @param node the node on which to dispatch
  75      * @param p a parameter to be passed to the appropriate visit method
  76      * @return the value returns from the appropriate visit method
  77      */
  78     public final R visit(DocTree node, P p) {
  79         return (node == null) ? null : node.accept(this, p);
  80     }
  81 
  82     /**
  83      * Invokes the appropriate visit method on each of a sequence of nodes.
  84      * @param nodes the nodes on which to dispatch
  85      * @param p a parameter value to be passed to each appropriate visit method
  86      * @return the value return from the last of the visit methods, or null
  87      *      if none were called.
  88      */
  89     public final R visit(Iterable<? extends DocTree> nodes, P p) {
  90         R r = null;
  91         if (nodes != null) {
  92             for (DocTree node : nodes)
  93                 r = visit(node, p);
  94         }
  95         return r;
  96     }
  97 
  98     /**
  99      * {@inheritDoc} This implementation calls {@code defaultAction}.
 100      *
 101      * @param node {@inheritDoc}
 102      * @param p {@inheritDoc}
 103      * @return  the result of {@code defaultAction}
 104      */
 105     @Override
 106     public R visitAttribute(AttributeTree node, P p) {
 107         return defaultAction(node, p);
 108     }
 109 
 110     /**
 111      * {@inheritDoc} This implementation calls {@code defaultAction}.
 112      *
 113      * @param node {@inheritDoc}
 114      * @param p {@inheritDoc}
 115      * @return  the result of {@code defaultAction}
 116      */
 117     @Override
 118     public R visitAuthor(AuthorTree node, P p) {
 119         return defaultAction(node, p);
 120     }
 121 
 122     /**
 123      * {@inheritDoc} This implementation calls {@code defaultAction}.
 124      *
 125      * @param node {@inheritDoc}
 126      * @param p {@inheritDoc}
 127      * @return  the result of {@code defaultAction}
 128      */
 129     @Override
 130     public R visitComment(CommentTree node, P p) {
 131         return defaultAction(node, p);
 132     }
 133 
 134     /**
 135      * {@inheritDoc} This implementation calls {@code defaultAction}.
 136      *
 137      * @param node {@inheritDoc}
 138      * @param p {@inheritDoc}
 139      * @return  the result of {@code defaultAction}
 140      */
 141     @Override
 142     public R visitDeprecated(DeprecatedTree node, P p) {
 143         return defaultAction(node, p);
 144     }
 145 
 146     /**
 147      * {@inheritDoc} This implementation calls {@code defaultAction}.
 148      *
 149      * @param node {@inheritDoc}
 150      * @param p {@inheritDoc}
 151      * @return  the result of {@code defaultAction}
 152      */
 153     @Override
 154     public R visitDocComment(DocCommentTree node, P p) {
 155         return defaultAction(node, p);
 156     }
 157 
 158     /**
 159      * {@inheritDoc} This implementation calls {@code defaultAction}.
 160      *
 161      * @param node {@inheritDoc}
 162      * @param p {@inheritDoc}
 163      * @return  the result of {@code defaultAction}
 164      */
 165     @Override
 166     public R visitDocRoot(DocRootTree node, P p) {
 167         return defaultAction(node, p);
 168     }
 169 
 170     /**
 171      * {@inheritDoc}
 172      *
 173      * @implSpec This implementation calls {@code defaultAction}.
 174      *
 175      * @param node {@inheritDoc}
 176      * @param p {@inheritDoc}
 177      * @return  the result of {@code defaultAction}
 178      * @since 10
 179      */
 180     @Override
 181     public R visitDocType(DocTypeTree node, P p) { return defaultAction(node, p); }
 182 
 183     /**
 184      * {@inheritDoc} This implementation calls {@code defaultAction}.
 185      *
 186      * @param node {@inheritDoc}
 187      * @param p {@inheritDoc}
 188      * @return  the result of {@code defaultAction}
 189      */
 190     @Override
 191     public R visitEndElement(EndElementTree node, P p) { return defaultAction(node, p);}
 192 
 193     /**
 194      * {@inheritDoc} This implementation calls {@code defaultAction}.
 195      *
 196      * @param node {@inheritDoc}
 197      * @param p {@inheritDoc}
 198      * @return  the result of {@code defaultAction}
 199      */
 200     @Override
 201     public R visitEntity(EntityTree node, P p) {
 202         return defaultAction(node, p);
 203     }
 204 
 205     /**
 206      * {@inheritDoc} This implementation calls {@code defaultAction}.
 207      *
 208      * @param node {@inheritDoc}
 209      * @param p {@inheritDoc}
 210      * @return  the result of {@code defaultAction}
 211      */
 212     @Override
 213     public R visitErroneous(ErroneousTree node, P p) {
 214         return defaultAction(node, p);
 215     }
 216 
 217     /**
 218      * {@inheritDoc} This implementation calls {@code defaultAction}.
 219      *
 220      * @param node {@inheritDoc}
 221      * @param p {@inheritDoc}
 222      * @return the result of {@code defaultAction}
 223      *
 224      * @since 9
 225      */
 226     @Override
 227     public R visitHidden(HiddenTree node, P p) {
 228         return defaultAction(node, p);
 229     }
 230 
 231     /**
 232      * {@inheritDoc} This implementation calls {@code defaultAction}.
 233      *
 234      * @param node {@inheritDoc}
 235      * @param p {@inheritDoc}
 236      * @return  the result of {@code defaultAction}
 237      */
 238     @Override
 239     public R visitIdentifier(IdentifierTree node, P p) {
 240         return defaultAction(node, p);
 241     }
 242 
 243     /**
 244      * {@inheritDoc} This implementation calls {@code defaultAction}.
 245      *
 246      * @param node {@inheritDoc}
 247      * @param p {@inheritDoc}
 248      * @return  the result of {@code defaultAction}
 249      *
 250      * @since 9
 251      */
 252     @Override
 253     public R visitIndex(IndexTree node, P p) {
 254         return defaultAction(node, p);
 255     }
 256 
 257     /**
 258      * {@inheritDoc} This implementation calls {@code defaultAction}.
 259      *
 260      * @param node {@inheritDoc}
 261      * @param p {@inheritDoc}
 262      * @return  the result of {@code defaultAction}
 263      */
 264     @Override
 265     public R visitInheritDoc(InheritDocTree node, P p) {
 266         return defaultAction(node, p);
 267     }
 268 
 269     /**
 270      * {@inheritDoc} This implementation calls {@code defaultAction}.
 271      *
 272      * @param node {@inheritDoc}
 273      * @param p {@inheritDoc}
 274      * @return  the result of {@code defaultAction}
 275      */
 276     @Override
 277     public R visitLink(LinkTree node, P p) {
 278         return defaultAction(node, p);
 279     }
 280 
 281     /**
 282      * {@inheritDoc} This implementation calls {@code defaultAction}.
 283      *
 284      * @param node {@inheritDoc}
 285      * @param p {@inheritDoc}
 286      * @return  the result of {@code defaultAction}
 287      */
 288     @Override
 289     public R visitLiteral(LiteralTree node, P p) {
 290         return defaultAction(node, p);
 291     }
 292 
 293     /**
 294      * {@inheritDoc} This implementation calls {@code defaultAction}.
 295      *
 296      * @param node {@inheritDoc}
 297      * @param p {@inheritDoc}
 298      * @return  the result of {@code defaultAction}
 299      */
 300     @Override
 301     public R visitAccessor(AccessorTree node, P p) {
 302         return defaultAction(node, p);
 303     }
 304 
 305     /**
 306      * {@inheritDoc} This implementation calls {@code defaultAction}.
 307      *
 308      * @param node {@inheritDoc}
 309      * @param p {@inheritDoc}
 310      * @return  the result of {@code defaultAction}
 311      */
 312     @Override
 313     public R visitParam(ParamTree node, P p) {
 314         return defaultAction(node, p);
 315     }
 316 
 317     /**
 318      * {@inheritDoc} This implementation calls {@code defaultAction}.
 319      *
 320      * @param node {@inheritDoc}
 321      * @param p {@inheritDoc}
 322      * @return  the result of {@code defaultAction}
 323      *
 324      * @since 9
 325      */
 326     @Override
 327     public R visitProvides(ProvidesTree node, P p) {
 328         return defaultAction(node, p);
 329     }
 330 
 331     /**
 332      * {@inheritDoc} This implementation calls {@code defaultAction}.
 333      *
 334      * @param node {@inheritDoc}
 335      * @param p {@inheritDoc}
 336      * @return  the result of {@code defaultAction}
 337      */
 338     @Override
 339     public R visitReference(ReferenceTree node, P p) {
 340         return defaultAction(node, p);
 341     }
 342 
 343     /**
 344      * {@inheritDoc} This implementation calls {@code defaultAction}.
 345      *
 346      * @param node {@inheritDoc}
 347      * @param p {@inheritDoc}
 348      * @return  the result of {@code defaultAction}
 349      */
 350     @Override
 351     public R visitReturn(ReturnTree node, P p) {
 352         return defaultAction(node, p);
 353     }
 354 
 355     /**
 356      * {@inheritDoc} This implementation calls {@code defaultAction}.
 357      *
 358      * @param node {@inheritDoc}
 359      * @param p {@inheritDoc}
 360      * @return  the result of {@code defaultAction}
 361      */
 362     @Override
 363     public R visitSee(SeeTree node, P p) {
 364         return defaultAction(node, p);
 365     }
 366 
 367     /**
 368      * {@inheritDoc} This implementation calls {@code defaultAction}.
 369      *
 370      * @param node {@inheritDoc}
 371      * @param p {@inheritDoc}
 372      * @return  the result of {@code defaultAction}
 373      */
 374     @Override
 375     public R visitSerial(SerialTree node, P p) {
 376         return defaultAction(node, p);
 377     }
 378 
 379     /**
 380      * {@inheritDoc} This implementation calls {@code defaultAction}.
 381      *
 382      * @param node {@inheritDoc}
 383      * @param p {@inheritDoc}
 384      * @return  the result of {@code defaultAction}
 385      */
 386     @Override
 387     public R visitSerialData(SerialDataTree node, P p) {
 388         return defaultAction(node, p);
 389     }
 390 
 391     /**
 392      * {@inheritDoc} This implementation calls {@code defaultAction}.
 393      *
 394      * @param node {@inheritDoc}
 395      * @param p {@inheritDoc}
 396      * @return  the result of {@code defaultAction}
 397      */
 398     @Override
 399     public R visitSerialField(SerialFieldTree node, P p) {
 400         return defaultAction(node, p);
 401     }
 402 
 403     /**
 404      * {@inheritDoc} This implementation calls {@code defaultAction}.
 405      *
 406      * @param node {@inheritDoc}
 407      * @param p {@inheritDoc}
 408      * @return  the result of {@code defaultAction}
 409      */
 410     @Override
 411     public R visitSince(SinceTree node, P p) {
 412         return defaultAction(node, p);
 413     }
 414 
 415     /**
 416      * {@inheritDoc} This implementation calls {@code defaultAction}.
 417      *
 418      * @param node {@inheritDoc}
 419      * @param p {@inheritDoc}
 420      * @return  the result of {@code defaultAction}
 421      */
 422     @Override
 423     public R visitStartElement(StartElementTree node, P p) {
 424         return defaultAction(node, p);
 425     }
 426 
 427     /**
 428      * {@inheritDoc} This implementation calls {@code defaultAction}.
 429      *
 430      * @param node {@inheritDoc}
 431      * @param p {@inheritDoc}
 432      * @return  the result of {@code defaultAction}
 433      * @since 10
 434      */
 435     @Override
 436     public R visitSummary(SummaryTree node, P p) {
 437         return defaultAction(node, p);
 438     }
 439 
 440     /**
 441      * {@inheritDoc} This implementation calls {@code defaultAction}.
 442      *
 443      * @param node {@inheritDoc}
 444      * @param p {@inheritDoc}
 445      * @return  the result of {@code defaultAction}
 446      * @since 12
 447      */
 448     @Override
 449     public R visitSystemProperty(SystemPropertyTree node, P p) {
 450         return defaultAction(node, p);
 451     }
 452 
 453     /**
 454      * {@inheritDoc} This implementation calls {@code defaultAction}.
 455      *
 456      * @param node {@inheritDoc}
 457      * @param p {@inheritDoc}
 458      * @return  the result of {@code defaultAction}
 459      */
 460     @Override
 461     public R visitText(TextTree node, P p) {
 462         return defaultAction(node, p);
 463     }
 464 
 465     /**
 466      * {@inheritDoc} This implementation calls {@code defaultAction}.
 467      *
 468      * @param node {@inheritDoc}
 469      * @param p {@inheritDoc}
 470      * @return  the result of {@code defaultAction}
 471      */
 472     @Override
 473     public R visitThrows(ThrowsTree node, P p) {
 474         return defaultAction(node, p);
 475     }
 476 
 477     /**
 478      * {@inheritDoc} This implementation calls {@code defaultAction}.
 479      *
 480      * @param node {@inheritDoc}
 481      * @param p {@inheritDoc}
 482      * @return  the result of {@code defaultAction}
 483      */
 484     @Override
 485     public R visitUnknownBlockTag(UnknownBlockTagTree node, P p) {
 486         return defaultAction(node, p);
 487     }
 488 
 489     /**
 490      * {@inheritDoc} This implementation calls {@code defaultAction}.
 491      *
 492      * @param node {@inheritDoc}
 493      * @param p {@inheritDoc}
 494      * @return  the result of {@code defaultAction}
 495      */
 496     @Override
 497     public R visitUnknownInlineTag(UnknownInlineTagTree node, P p) {
 498         return defaultAction(node, p);
 499     }
 500 
 501     /**
 502      * {@inheritDoc} This implementation calls {@code defaultAction}.
 503      *
 504      * @param node {@inheritDoc}
 505      * @param p {@inheritDoc}
 506      * @return  the result of {@code defaultAction}
 507      *
 508      * @since 9
 509      */
 510     @Override
 511     public R visitUses(UsesTree node, P p) {
 512         return defaultAction(node, p);
 513     }
 514 
 515     /**
 516      * {@inheritDoc} This implementation calls {@code defaultAction}.
 517      *
 518      * @param node {@inheritDoc}
 519      * @param p {@inheritDoc}
 520      * @return  the result of {@code defaultAction}
 521      */
 522     @Override
 523     public R visitValue(ValueTree node, P p) {
 524         return defaultAction(node, p);
 525     }
 526 
 527     /**
 528      * {@inheritDoc} This implementation calls {@code defaultAction}.
 529      *
 530      * @param node {@inheritDoc}
 531      * @param p {@inheritDoc}
 532      * @return  the result of {@code defaultAction}
 533      */
 534     @Override
 535     public R visitVersion(VersionTree node, P p) {
 536         return defaultAction(node, p);
 537     }
 538 
 539     /**
 540      * {@inheritDoc} This implementation calls {@code defaultAction}.
 541      *
 542      * @param node {@inheritDoc}
 543      * @param p {@inheritDoc}
 544      * @return  the result of {@code defaultAction}
 545      */
 546     @Override
 547     public R visitOther(DocTree node, P p) {
 548         return defaultAction(node, p);
 549     }
 550 
 551 }