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 }