1 /*
2 * Copyright (c) 2011, 2013, 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 /**
32 * A TreeVisitor that visits all the child tree nodes.
33 * To visit nodes of a particular type, just override the
34 * corresponding visitXYZ method.
35 * Inside your method, call super.visitXYZ to visit descendant
36 * nodes.
37 *
38 * <p>The default implementation of the visitXYZ methods will determine
39 * a result as follows:
40 * <ul>
41 * <li>If the node being visited has no children, the result will be null.
42 * <li>If the node being visited has one child, the result will be the
43 * result of calling {@code scan} on that child. The child may be a simple node
44 * or itself a list of nodes.
45 * <li> If the node being visited has more than one child, the result will
46 * be determined by calling {@code scan} each child in turn, and then combining the
47 * result of each scan after the first with the cumulative result
48 * so far, as determined by the {@link #reduce} method. Each child may be either
49 * a simple node of a list of nodes. The default behavior of the {@code reduce}
50 * method is such that the result of the visitXYZ method will be the result of
51 * the last child scanned.
52 * </ul>
53 *
54 * <p>Here is an example to count the number of erroneous nodes in a tree:
55 * <pre>
56 * class CountErrors extends DocTreeScanner<Integer,Void> {
57 * {@literal @}Override
58 * public Integer visitErroneous(ErroneousTree node, Void p) {
59 * return 1;
60 * }
61 * {@literal @}Override
62 * public Integer reduce(Integer r1, Integer r2) {
63 * return (r1 == null ? 0 : r1) + (r2 == null ? 0 : r2);
64 * }
65 * }
66 * </pre>
67 *
68 * @since 1.8
69 */
70 @jdk.Exported
71 public class DocTreeScanner<R,P> implements DocTreeVisitor<R,P> {
72
73 /**
74 * Scan a single node.
75 */
76 public R scan(DocTree node, P p) {
77 return (node == null) ? null : node.accept(this, p);
78 }
79
80 private R scanAndReduce(DocTree node, P p, R r) {
81 return reduce(scan(node, p), r);
82 }
83
84 /**
85 * Scan a list of nodes.
86 */
87 public R scan(Iterable<? extends DocTree> nodes, P p) {
88 R r = null;
89 if (nodes != null) {
90 boolean first = true;
91 for (DocTree node : nodes) {
92 r = (first ? scan(node, p) : scanAndReduce(node, p, r));
93 first = false;
94 }
95 }
96 return r;
97 }
98
99 private R scanAndReduce(Iterable<? extends DocTree> nodes, P p, R r) {
100 return reduce(scan(nodes, p), r);
101 }
102
103 /**
104 * Reduces two results into a combined result.
105 * The default implementation is to return the first parameter.
106 * The general contract of the method is that it may take any action whatsoever.
107 */
108 public R reduce(R r1, R r2) {
109 return r1;
110 }
111
112
113 /* ***************************************************************************
114 * Visitor methods
115 ****************************************************************************/
116
117 @Override
118 public R visitAttribute(AttributeTree node, P p) {
119 return null;
120 }
121
122 @Override
123 public R visitAuthor(AuthorTree node, P p) {
124 return scan(node.getName(), p);
125 }
126
127 @Override
128 public R visitComment(CommentTree node, P p) {
129 return null;
130 }
131
132 @Override
133 public R visitDeprecated(DeprecatedTree node, P p) {
134 return scan(node.getBody(), p);
135 }
136
137 @Override
138 public R visitDocComment(DocCommentTree node, P p) {
139 R r = scan(node.getFirstSentence(), p);
140 r = scanAndReduce(node.getBody(), p, r);
141 r = scanAndReduce(node.getBlockTags(), p, r);
142 return r;
143 }
144
145 @Override
146 public R visitDocRoot(DocRootTree node, P p) {
147 return null;
148 }
149
150 @Override
151 public R visitEndElement(EndElementTree node, P p) {
152 return null;
153 }
154
155 @Override
156 public R visitEntity(EntityTree node, P p) {
157 return null;
158 }
159
160 @Override
161 public R visitErroneous(ErroneousTree node, P p) {
162 return null;
163 }
164
165 @Override
166 public R visitIdentifier(IdentifierTree node, P p) {
167 return null;
168 }
169
170 @Override
171 public R visitInheritDoc(InheritDocTree node, P p) {
172 return null;
173 }
174
175 @Override
176 public R visitLink(LinkTree node, P p) {
177 R r = scan(node.getReference(), p);
178 r = scanAndReduce(node.getLabel(), p, r);
179 return r;
180 }
181
182 @Override
183 public R visitLiteral(LiteralTree node, P p) {
184 return null;
185 }
186
187 @Override
188 public R visitParam(ParamTree node, P p) {
189 R r = scan(node.getName(), p);
190 r = scanAndReduce(node.getDescription(), p, r);
191 return r;
192 }
193
194 @Override
195 public R visitReference(ReferenceTree node, P p) {
196 return null;
197 }
198
199 @Override
200 public R visitReturn(ReturnTree node, P p) {
201 return scan(node.getDescription(), p);
202 }
203
204 @Override
205 public R visitSee(SeeTree node, P p) {
206 return scan(node.getReference(), p);
207 }
208
209 @Override
210 public R visitSerial(SerialTree node, P p) {
211 return scan(node.getDescription(), p);
212 }
213
214 @Override
215 public R visitSerialData(SerialDataTree node, P p) {
216 return scan(node.getDescription(), p);
217 }
218
219 @Override
220 public R visitSerialField(SerialFieldTree node, P p) {
221 R r = scan(node.getName(), p);
222 r = scanAndReduce(node.getType(), p, r);
223 r = scanAndReduce(node.getDescription(), p, r);
224 return r;
225 }
226
227 @Override
228 public R visitSince(SinceTree node, P p) {
229 return scan(node.getBody(), p);
230 }
231
232 @Override
233 public R visitStartElement(StartElementTree node, P p) {
234 return scan(node.getAttributes(), p);
235 }
236
237 @Override
238 public R visitText(TextTree node, P p) {
239 return null;
240 }
241
242 @Override
243 public R visitThrows(ThrowsTree node, P p) {
244 R r = scan(node.getExceptionName(), p);
245 r = scanAndReduce(node.getDescription(), p, r);
246 return r;
247 }
248
249 @Override
250 public R visitUnknownBlockTag(UnknownBlockTagTree node, P p) {
251 return scan(node.getContent(), p);
252 }
253
254 @Override
255 public R visitUnknownInlineTag(UnknownInlineTagTree node, P p) {
256 return scan(node.getContent(), p);
257 }
258
259 @Override
260 public R visitValue(ValueTree node, P p) {
261 return scan(node.getReference(), p);
262 }
263
264 @Override
265 public R visitVersion(VersionTree node, P p) {
266 return scan(node.getBody(), p);
267 }
268
269 @Override
270 public R visitOther(DocTree node, P p) {
271 return null;
272 }
273
274 }