1 /*
   2  * Copyright (c) 2011, 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.doctree;
  27 
  28 
  29 /**
  30  * A visitor of trees, in the style of the visitor design pattern.
  31  * Classes implementing this interface are used to operate
  32  * on a tree when the kind of tree is unknown at compile time.
  33  * When a visitor is passed to an tree's {@link DocTree#accept
  34  * accept} method, the <code>visit<i>Xyz</i></code> method most applicable
  35  * to that tree is invoked.
  36  *
  37  * <p> Classes implementing this interface may or may not throw a
  38  * {@code NullPointerException} if the additional parameter {@code p}
  39  * is {@code null}; see documentation of the implementing class for
  40  * details.
  41  *
  42  * <p> <b>WARNING:</b> It is possible that methods will be added to
  43  * this interface to accommodate new, currently unknown, doc comment
  44  * structures added to future versions of the Java&trade; programming
  45  * language.  Therefore, visitor classes directly implementing this
  46  * interface may be source incompatible with future versions of the
  47  * platform.
  48  *
  49  * @param <R> the return type of this visitor's methods.  Use {@link
  50  *            Void} for visitors that do not need to return results.
  51  * @param <P> the type of the additional parameter to this visitor's
  52  *            methods.  Use {@code Void} for visitors that do not need an
  53  *            additional parameter.
  54  *
  55  * @since 1.8
  56  */
  57 public interface DocTreeVisitor<R,P> {
  58 
  59     /**
  60      * Visits an AaccessorTree node.
  61      * @param node the node being visited
  62      * @param p a parameter value
  63      * @return a result value
  64      */
  65     R visitAccessor(AccessorTree node, P p);
  66 
  67     /**
  68      * Visits an AttributeTree node.
  69      * @param node the node being visited
  70      * @param p a parameter value
  71      * @return a result value
  72      */
  73     R visitAttribute(AttributeTree node, P p);
  74 
  75     /**
  76      * Visits an AuthorTree node.
  77      * @param node the node being visited
  78      * @param p a parameter value
  79      * @return a result value
  80      */
  81     R visitAuthor(AuthorTree node, P p);
  82 
  83     /**
  84      * Visits a CommentTree node.
  85      * @param node the node being visited
  86      * @param p a parameter value
  87      * @return a result value
  88      */
  89     R visitComment(CommentTree node, P p);
  90 
  91     /**
  92      * Visits a DeprecatedTree node.
  93      * @param node the node being visited
  94      * @param p a parameter value
  95      * @return a result value
  96      */
  97     R visitDeprecated(DeprecatedTree node, P p);
  98 
  99     /**
 100      * Visits a DocCommentTree node.
 101      * @param node the node being visited
 102      * @param p a parameter value
 103      * @return a result value
 104      */
 105     R visitDocComment(DocCommentTree node, P p);
 106 
 107     /**
 108      * Visits a DocRootTree node.
 109      * @param node the node being visited
 110      * @param p a parameter value
 111      * @return a result value
 112      */
 113     R visitDocRoot(DocRootTree node, P p);
 114 
 115     /**
 116      * Visits a DocTypeTree node.
 117      *
 118      * @implSpec Visits a {@code DocTypeTree} node
 119      * by calling {@code visitOther(node, p)}.
 120      *
 121      * @param node the node being visited
 122      * @param p    a parameter value
 123      * @return a result value
 124      * @since 10
 125      */
 126     default R visitDocType(DocTypeTree node, P p) {
 127         return visitOther(node, p);
 128     }
 129 
 130     /**
 131      * Visits an EndElementTree node.
 132      * @param node the node being visited
 133      * @param p a parameter value
 134      * @return a result value
 135      */
 136     R visitEndElement(EndElementTree node, P p);
 137 
 138     /**
 139      * Visits an EntityTree node.
 140      * @param node the node being visited
 141      * @param p a parameter value
 142      * @return a result value
 143      */
 144     R visitEntity(EntityTree node, P p);
 145 
 146     /**
 147      * Visits an ErroneousTree node.
 148      * @param node the node being visited
 149      * @param p a parameter value
 150      * @return a result value
 151      */
 152     R visitErroneous(ErroneousTree node, P p);
 153 
 154     /**
 155      * Visits a HiddenTree node.
 156      *
 157      * @implSpec Visits a {@code HiddenTree} node
 158      * by calling {@code visitOther(node, p)}.
 159      *
 160      * @param node the node being visited
 161      * @param p a parameter value
 162      * @return a result value
 163      *
 164      * @since 9
 165      */
 166     default R visitHidden(HiddenTree node, P p)  {
 167         return visitOther(node, p);
 168     }
 169 
 170     /**
 171      * Visits an IdentifierTree node.
 172      * @param node the node being visited
 173      * @param p a parameter value
 174      * @return a result value
 175      */
 176     R visitIdentifier(IdentifierTree node, P p);
 177 
 178     /**
 179      * Visits an IndexTree node.
 180      *
 181      * @implSpec Visits an {@code IndexTree} node
 182      * by calling {@code visitOther(node, p)}.
 183      *
 184      * @param node the node being visited
 185      * @param p a parameter value
 186      * @return a result value
 187      *
 188      * @since 9
 189      */
 190     default R visitIndex(IndexTree node, P p) {
 191         return visitOther(node, p);
 192     }
 193 
 194     /**
 195      * Visits an InheritDocTree node.
 196      * @param node the node being visited
 197      * @param p a parameter value
 198      * @return a result value
 199      */
 200     R visitInheritDoc(InheritDocTree node, P p);
 201 
 202     /**
 203      * Visits a LinkTree node.
 204      * @param node the node being visited
 205      * @param p a parameter value
 206      * @return a result value
 207      */
 208     R visitLink(LinkTree node, P p);
 209 
 210     /**
 211      * Visits an LiteralTree node.
 212      * @param node the node being visited
 213      * @param p a parameter value
 214      * @return a result value
 215      */
 216     R visitLiteral(LiteralTree node, P p);
 217 
 218     /**
 219      * Visits a ParamTree node.
 220      * @param node the node being visited
 221      * @param p a parameter value
 222      * @return a result value
 223      */
 224     R visitParam(ParamTree node, P p);
 225 
 226     /**
 227      * Visits a ProvidesTree node.
 228      *
 229      * @implSpec Visits a {@code ProvidesTree} node
 230      * by calling {@code visitOther(node, p)}.
 231      *
 232      * @param node the node being visited
 233      * @param p a parameter value
 234      * @return a result value
 235      *
 236      * @since 9
 237      */
 238     default R visitProvides(ProvidesTree node, P p) {
 239         return visitOther(node, p);
 240     }
 241 
 242     /**
 243      * Visits a ReferenceTree node.
 244      * @param node the node being visited
 245      * @param p a parameter value
 246      * @return a result value
 247      */
 248     R visitReference(ReferenceTree node, P p);
 249 
 250     /**
 251      * Visits a ReturnTree node.
 252      * @param node the node being visited
 253      * @param p a parameter value
 254      * @return a result value
 255      */
 256     R visitReturn(ReturnTree node, P p);
 257 
 258     /**
 259      * Visits a SeeTree node.
 260      * @param node the node being visited
 261      * @param p a parameter value
 262      * @return a result value
 263      */
 264     R visitSee(SeeTree node, P p);
 265 
 266     /**
 267      * Visits a SerialTree node.
 268      * @param node the node being visited
 269      * @param p a parameter value
 270      * @return a result value
 271      */
 272     R visitSerial(SerialTree node, P p);
 273 
 274     /**
 275      * Visits a SerialDataTree node.
 276      * @param node the node being visited
 277      * @param p a parameter value
 278      * @return a result value
 279      */
 280     R visitSerialData(SerialDataTree node, P p);
 281 
 282     /**
 283      * Visits a SerialFieldTree node.
 284      * @param node the node being visited
 285      * @param p a parameter value
 286      * @return a result value
 287      */
 288     R visitSerialField(SerialFieldTree node, P p);
 289 
 290     /**
 291      * Visits a SinceTree node.
 292      * @param node the node being visited
 293      * @param p a parameter value
 294      * @return a result value
 295      */
 296     R visitSince(SinceTree node, P p);
 297 
 298     /**
 299      * Visits a StartElementTree node.
 300      * @param node the node being visited
 301      * @param p a parameter value
 302      * @return a result value
 303      */
 304     R visitStartElement(StartElementTree node, P p);
 305 
 306     /**
 307      * Visits a SummaryTree node.
 308      *
 309      * @implSpec Visits a {@code SummaryTree} node
 310      * by calling {@code visitOther(node, p)}.
 311      *
 312      * @param node the node being visited
 313      * @param p a parameter value
 314      * @return a result value
 315      * @since 10
 316      */
 317     default R visitSummary(SummaryTree node, P p) {
 318         return visitOther(node, p);
 319     }
 320 
 321     /**
 322      * Visits a SystemPropertyTree node.
 323      *
 324      * @implSpec Visits a {@code SystemPropertyTree} node
 325      * by calling {@code visitOther(node, p)}.
 326      *
 327      * @param node the node being visited
 328      * @param p a parameter value
 329      * @return a result value
 330      * @since 12
 331      */
 332     default R visitSystemProperty(SystemPropertyTree node, P p) {
 333         return visitOther(node, p);
 334     }
 335 
 336     /**
 337      * Visits a TextTree node.
 338      * @param node the node being visited
 339      * @param p a parameter value
 340      * @return a result value
 341      */
 342     R visitText(TextTree node, P p);
 343 
 344     /**
 345      * Visits a ThrowsTree node.
 346      * @param node the node being visited
 347      * @param p a parameter value
 348      * @return a result value
 349      */
 350     R visitThrows(ThrowsTree node, P p);
 351 
 352     /**
 353      * Visits an UnknownBlockTagTree node.
 354      * @param node the node being visited
 355      * @param p a parameter value
 356      * @return a result value
 357      */
 358     R visitUnknownBlockTag(UnknownBlockTagTree node, P p);
 359 
 360     /**
 361      * Visits an UnknownInlineTagTree node.
 362      * @param node the node being visited
 363      * @param p a parameter value
 364      * @return a result value
 365      */
 366     R visitUnknownInlineTag(UnknownInlineTagTree node, P p);
 367 
 368     /**
 369      * Visits a UsesTree node.
 370      *
 371      * @implSpec Visits a {@code UsesTree} node
 372      * by calling {@code visitOther(node, p)}.
 373      *
 374      * @param node the node being visited
 375      * @param p a parameter value
 376      * @return a result value
 377      *
 378      * @since 9
 379      */
 380     default R visitUses(UsesTree node, P p) {
 381         return visitOther(node, p);
 382     }
 383 
 384     /**
 385      * Visits a ValueTree node.
 386      * @param node the node being visited
 387      * @param p a parameter value
 388      * @return a result value
 389      */
 390     R visitValue(ValueTree node, P p);
 391 
 392     /**
 393      * Visits a VersionTreeTree node.
 394      * @param node the node being visited
 395      * @param p a parameter value
 396      * @return a result value
 397      */
 398     R visitVersion(VersionTree node, P p);
 399 
 400     /**
 401      * Visits an unknown type of DocTree node.
 402      * This can occur if the set of tags evolves and new kinds
 403      * of nodes are added to the {@code DocTree} hierarchy.
 404      * @param node the node being visited
 405      * @param p a parameter value
 406      * @return a result value
 407      */
 408     R visitOther(DocTree node, P p);
 409 }