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 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 AttributeTree node. 61 * @param node the node being visited 62 * @param p a parameter value 63 * @return a result value 64 */ 65 R visitAttribute(AttributeTree node, P p); 66 67 /** 68 * Visits an AuthorTree node. 69 * @param node the node being visited 70 * @param p a parameter value 71 * @return a result value 72 */ 73 R visitAuthor(AuthorTree node, P p); 74 75 /** 76 * Visits a CommentTree node. 77 * @param node the node being visited 78 * @param p a parameter value 79 * @return a result value 80 */ 81 R visitComment(CommentTree node, P p); 82 83 /** 84 * Visits a DeprecatedTree node. 85 * @param node the node being visited 86 * @param p a parameter value 87 * @return a result value 88 */ 89 R visitDeprecated(DeprecatedTree node, P p); 90 91 /** 92 * Visits a DocCommentTree node. 93 * @param node the node being visited 94 * @param p a parameter value 95 * @return a result value 96 */ 97 R visitDocComment(DocCommentTree node, P p); 98 99 /** 100 * Visits a DocRootTree node. 101 * @param node the node being visited 102 * @param p a parameter value 103 * @return a result value 104 */ 105 R visitDocRoot(DocRootTree node, P p); 106 107 /** 108 * Visits a DocTypeTree node. 109 * 110 * @implSpec Visits a {@code DocTypeTree} node 111 * by calling {@code visitOther(node, p)}. 112 * 113 * @param node the node being visited 114 * @param p a parameter value 115 * @return a result value 116 * @since 10 117 */ 118 default R visitDocType(DocTypeTree node, P p) { 119 return visitOther(node, p); 120 } 121 122 /** 123 * Visits an EndElementTree node. 124 * @param node the node being visited 125 * @param p a parameter value 126 * @return a result value 127 */ 128 R visitEndElement(EndElementTree node, P p); 129 130 /** 131 * Visits an EntityTree node. 132 * @param node the node being visited 133 * @param p a parameter value 134 * @return a result value 135 */ 136 R visitEntity(EntityTree node, P p); 137 138 /** 139 * Visits an ErroneousTree node. 140 * @param node the node being visited 141 * @param p a parameter value 142 * @return a result value 143 */ 144 R visitErroneous(ErroneousTree node, P p); 145 146 /** 147 * Visits a HiddenTree node. 148 * 149 * @implSpec Visits a {@code HiddenTree} node 150 * by calling {@code visitOther(node, p)}. 151 * 152 * @param node the node being visited 153 * @param p a parameter value 154 * @return a result value 155 * 156 * @since 9 157 */ 158 default R visitHidden(HiddenTree node, P p) { 159 return visitOther(node, p); 160 } 161 162 /** 163 * Visits an IdentifierTree node. 164 * @param node the node being visited 165 * @param p a parameter value 166 * @return a result value 167 */ 168 R visitIdentifier(IdentifierTree node, P p); 169 170 /** 171 * Visits an IndexTree node. 172 * 173 * @implSpec Visits an {@code IndexTree} node 174 * by calling {@code visitOther(node, p)}. 175 * 176 * @param node the node being visited 177 * @param p a parameter value 178 * @return a result value 179 * 180 * @since 9 181 */ 182 default R visitIndex(IndexTree node, P p) { 183 return visitOther(node, p); 184 } 185 186 /** 187 * Visits an InheritDocTree node. 188 * @param node the node being visited 189 * @param p a parameter value 190 * @return a result value 191 */ 192 R visitInheritDoc(InheritDocTree node, P p); 193 194 /** 195 * Visits a LinkTree node. 196 * @param node the node being visited 197 * @param p a parameter value 198 * @return a result value 199 */ 200 R visitLink(LinkTree node, P p); 201 202 /** 203 * Visits an LiteralTree node. 204 * @param node the node being visited 205 * @param p a parameter value 206 * @return a result value 207 */ 208 R visitLiteral(LiteralTree node, P p); 209 210 /** 211 * Visits a ParamTree node. 212 * @param node the node being visited 213 * @param p a parameter value 214 * @return a result value 215 */ 216 R visitParam(ParamTree node, P p); 217 218 /** 219 * Visits a ProvidesTree node. 220 * 221 * @implSpec Visits a {@code ProvidesTree} node 222 * by calling {@code visitOther(node, p)}. 223 * 224 * @param node the node being visited 225 * @param p a parameter value 226 * @return a result value 227 * 228 * @since 9 229 */ 230 default R visitProvides(ProvidesTree node, P p) { 231 return visitOther(node, p); 232 } 233 234 /** 235 * Visits a ReferenceTree node. 236 * @param node the node being visited 237 * @param p a parameter value 238 * @return a result value 239 */ 240 R visitReference(ReferenceTree node, P p); 241 242 /** 243 * Visits a ReturnTree node. 244 * @param node the node being visited 245 * @param p a parameter value 246 * @return a result value 247 */ 248 R visitReturn(ReturnTree node, P p); 249 250 /** 251 * Visits a SeeTree node. 252 * @param node the node being visited 253 * @param p a parameter value 254 * @return a result value 255 */ 256 R visitSee(SeeTree node, P p); 257 258 /** 259 * Visits a SerialTree node. 260 * @param node the node being visited 261 * @param p a parameter value 262 * @return a result value 263 */ 264 R visitSerial(SerialTree node, P p); 265 266 /** 267 * Visits a SerialDataTree node. 268 * @param node the node being visited 269 * @param p a parameter value 270 * @return a result value 271 */ 272 R visitSerialData(SerialDataTree node, P p); 273 274 /** 275 * Visits a SerialFieldTree node. 276 * @param node the node being visited 277 * @param p a parameter value 278 * @return a result value 279 */ 280 R visitSerialField(SerialFieldTree node, P p); 281 282 /** 283 * Visits a SinceTree node. 284 * @param node the node being visited 285 * @param p a parameter value 286 * @return a result value 287 */ 288 R visitSince(SinceTree node, P p); 289 290 /** 291 * Visits a StartElementTree node. 292 * @param node the node being visited 293 * @param p a parameter value 294 * @return a result value 295 */ 296 R visitStartElement(StartElementTree node, P p); 297 298 /** 299 * Visits a SummaryTree node. 300 * 301 * @implSpec Visits a {@code SummaryTree} node 302 * by calling {@code visitOther(node, p)}. 303 * 304 * @param node the node being visited 305 * @param p a parameter value 306 * @return a result value 307 * @since 10 308 */ 309 default R visitSummary(SummaryTree node, P p) { 310 return visitOther(node, p); 311 } 312 313 /** 314 * Visits a SystemPropertyTree node. 315 * 316 * @implSpec Visits a {@code SystemPropertyTree} node 317 * by calling {@code visitOther(node, p)}. 318 * 319 * @param node the node being visited 320 * @param p a parameter value 321 * @return a result value 322 * @since 12 323 */ 324 default R visitSystemProperty(SystemPropertyTree node, P p) { 325 return visitOther(node, p); 326 } 327 328 /** 329 * Visits a TextTree node. 330 * @param node the node being visited 331 * @param p a parameter value 332 * @return a result value 333 */ 334 R visitText(TextTree node, P p); 335 336 /** 337 * Visits a ThrowsTree node. 338 * @param node the node being visited 339 * @param p a parameter value 340 * @return a result value 341 */ 342 R visitThrows(ThrowsTree node, P p); 343 344 /** 345 * Visits an UnknownBlockTagTree node. 346 * @param node the node being visited 347 * @param p a parameter value 348 * @return a result value 349 */ 350 R visitUnknownBlockTag(UnknownBlockTagTree node, P p); 351 352 /** 353 * Visits an UnknownInlineTagTree node. 354 * @param node the node being visited 355 * @param p a parameter value 356 * @return a result value 357 */ 358 R visitUnknownInlineTag(UnknownInlineTagTree node, P p); 359 360 /** 361 * Visits a UsesTree node. 362 * 363 * @implSpec Visits a {@code UsesTree} node 364 * by calling {@code visitOther(node, p)}. 365 * 366 * @param node the node being visited 367 * @param p a parameter value 368 * @return a result value 369 * 370 * @since 9 371 */ 372 default R visitUses(UsesTree node, P p) { 373 return visitOther(node, p); 374 } 375 376 /** 377 * Visits a ValueTree node. 378 * @param node the node being visited 379 * @param p a parameter value 380 * @return a result value 381 */ 382 R visitValue(ValueTree node, P p); 383 384 /** 385 * Visits a VersionTreeTree node. 386 * @param node the node being visited 387 * @param p a parameter value 388 * @return a result value 389 */ 390 R visitVersion(VersionTree node, P p); 391 392 /** 393 * Visits an unknown type of DocTree node. 394 * This can occur if the set of tags evolves and new kinds 395 * of nodes are added to the {@code DocTree} hierarchy. 396 * @param node the node being visited 397 * @param p a parameter value 398 * @return a result value 399 */ 400 R visitOther(DocTree node, P p); 401 }