DocTreeFactory.java revision 4278:a6cee0419f93 
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
26package com.sun.source.util;
27
28import java.util.List;
29
30import javax.lang.model.element.Name;
31import javax.tools.Diagnostic;
32import javax.tools.JavaFileObject;
33
34import com.sun.source.doctree.AttributeTree;
35import com.sun.source.doctree.AttributeTree.ValueKind;
36import com.sun.source.doctree.AuthorTree;
37import com.sun.source.doctree.CommentTree;
38import com.sun.source.doctree.DeprecatedTree;
39import com.sun.source.doctree.DocCommentTree;
40import com.sun.source.doctree.DocRootTree;
41import com.sun.source.doctree.DocTree;
42import com.sun.source.doctree.EndElementTree;
43import com.sun.source.doctree.EntityTree;
44import com.sun.source.doctree.ErroneousTree;
45import com.sun.source.doctree.HiddenTree;
46import com.sun.source.doctree.IdentifierTree;
47import com.sun.source.doctree.IndexTree;
48import com.sun.source.doctree.InheritDocTree;
49import com.sun.source.doctree.LinkTree;
50import com.sun.source.doctree.LiteralTree;
51import com.sun.source.doctree.ParamTree;
52import com.sun.source.doctree.ProvidesTree;
53import com.sun.source.doctree.ReferenceTree;
54import com.sun.source.doctree.ReturnTree;
55import com.sun.source.doctree.SeeTree;
56import com.sun.source.doctree.SerialDataTree;
57import com.sun.source.doctree.SerialFieldTree;
58import com.sun.source.doctree.SerialTree;
59import com.sun.source.doctree.SinceTree;
60import com.sun.source.doctree.StartElementTree;
61import com.sun.source.doctree.SummaryTree;
62import com.sun.source.doctree.TextTree;
63import com.sun.source.doctree.ThrowsTree;
64import com.sun.source.doctree.UnknownBlockTagTree;
65import com.sun.source.doctree.UnknownInlineTagTree;
66import com.sun.source.doctree.UsesTree;
67import com.sun.source.doctree.ValueTree;
68import com.sun.source.doctree.VersionTree;
69
70/**
71 *  Factory for creating {@code DocTree} nodes.
72 *
73 *  @implNote The methods in an implementation of this interface may only accept {@code DocTree}
74 *  nodes that have been created by the same implementation.
75 *
76 *  @since 9
77 */
78public interface DocTreeFactory {
79    /**
80     * Create a new {@code AttributeTree} object, to represent an HTML attribute in an HTML tag.
81     * @param name  the name of the attribute
82     * @param vkind the kind of attribute value
83     * @param value the value, if any, of the attribute
84     * @return an {@code AttributeTree} object
85     */
86    AttributeTree newAttributeTree(Name name, ValueKind vkind, List<? extends DocTree> value);
87
88    /**
89     * Create a new {@code AuthorTree} object, to represent an {@code {@author } } tag.
90     * @param name the name of the author
91     * @return an {@code AuthorTree} object
92     */
93    AuthorTree newAuthorTree(List<? extends DocTree> name);
94
95    /**
96     * Create a new {@code CodeTree} object, to represent a {@code {@code } } tag.
97     * @param text the content of the tag
98     * @return a {@code CodeTree} object
99     */
100    LiteralTree newCodeTree(TextTree text);
101
102    /**
103     * Create a new {@code CommentTree}, to represent an HTML comment.
104     * @param text the content of the comment
105     * @return a {@code CommentTree} object
106     */
107    CommentTree newCommentTree(String text);
108
109    /**
110     * Create a new {@code DeprecatedTree} object, to represent an {@code {@deprecated } } tag.
111     * @param text the content of the tag
112     * @return a {@code DeprecatedTree} object
113     */
114    DeprecatedTree newDeprecatedTree(List<? extends DocTree> text);
115
116    /**
117     * Create a new {@code DocCommentTree} object, to represent a complete doc comment.
118     * @param fullBody the entire body of the doc comment
119     * @param tags the block tags in the doc comment
120     * @return a {@code DocCommentTree} object
121     */
122    DocCommentTree newDocCommentTree(List<? extends DocTree> fullBody, List<? extends DocTree> tags);
123
124    /**
125     * Create a new {@code DocRootTree} object, to represent an {@code {@docroot} } tag.
126     * @return a {@code DocRootTree} object
127     */
128    DocRootTree newDocRootTree();
129
130    /**
131     * Create a new {@code EndElement} object, to represent the end of an HTML element.
132     * @param name the name of the HTML element
133     * @return an {@code EndElementTree} object
134     */
135    EndElementTree newEndElementTree(Name name);
136
137    /**
138     * Create a new {@code EntityTree} object, to represent an HTML entity.
139     * @param name the name of the entity, representing the characters between '&lt;' and ';'
140     * in the representation of the entity in an HTML document
141     * @return an {@code EntityTree} object
142     */
143    EntityTree newEntityTree(Name name);
144
145    /**
146     * Create a new {@code ErroneousTree} object, to represent some unparseable input.
147     * @param text the unparseable text
148     * @param diag a diagnostic associated with the unparseable text, or null
149     * @return an {@code ErroneousTree} object
150     */
151    ErroneousTree newErroneousTree(String text, Diagnostic<JavaFileObject> diag);
152
153    /**
154     * Create a new {@code ExceptionTree} object, to represent an {@code @exception } tag.
155     * @param name the name of the exception
156     * @param description a description of why the exception might be thrown
157     * @return an {@code ExceptionTree} object
158     */
159    ThrowsTree newExceptionTree(ReferenceTree name, List<? extends DocTree> description);
160
161    /**
162     * Create a new {@code HiddenTree} object, to represent an {@code {@hidden } } tag.
163     * @param text the content of the tag
164     * @return a {@code HiddenTree} object
165     */
166    HiddenTree newHiddenTree(List<? extends DocTree> text);
167
168    /**
169     * Create a new {@code IdentifierTree} object, to represent an identifier, such as in a
170     * {@code @param } tag.
171     * @param name the name of the identifier
172     * @return an {@code IdentifierTree} object
173     */
174    IdentifierTree newIdentifierTree(Name name);
175
176    /**
177     * Create a new {@code IndexTree} object, to represent an {@code {@index } } tag.
178     * @param term the search term
179     * @param description an optional description of the search term
180     * @return an {@code IndexTree} object
181     */
182    IndexTree newIndexTree(DocTree term, List<? extends DocTree> description);
183
184    /**
185     * Create a new {@code InheritDocTree} object, to represent an {@code {@inheritDoc} } tag.
186     * @return an {@code InheritDocTree} object
187     */
188    InheritDocTree newInheritDocTree();
189
190    /**
191     * Create a new {@code LinkTree} object, to represent a {@code {@link } } tag.
192     * @param ref the API element being referenced
193     * @param label an optional label for the link
194     * @return a {@code LinkTree} object
195     */
196    LinkTree newLinkTree(ReferenceTree ref, List<? extends DocTree> label);
197
198    /**
199     * Create a new {@code LinkPlainTree} object, to represent a {@code {@linkplain } } tag.
200     * @param ref the API element being referenced
201     * @param label an optional label for the link
202     * @return a {@code LinkPlainTree} object
203     */
204    LinkTree newLinkPlainTree(ReferenceTree ref, List<? extends DocTree> label);
205
206    /**
207     * Create a new {@code LiteralTree} object, to represent a {@code {@literal } } tag.
208     * @param text the content of the tag
209     * @return a {@code LiteralTree} object
210     */
211    LiteralTree newLiteralTree(TextTree text);
212
213    /**
214     * Create a new {@code ParamTree} object, to represent a {@code @param } tag.
215     * @param isTypeParameter true if this is a type parameter, and false otherwise
216     * @param name the parameter being described
217     * @param description the description of the parameter
218     * @return a {@code ParamTree} object
219     */
220    ParamTree newParamTree(boolean isTypeParameter, IdentifierTree name, List<? extends DocTree> description);
221
222    /**
223     * Create a new {@code ProvidesTree} object, to represent a {@code @provides } tag.
224     * @param name the name of the service type
225     * @param description a description of the service being provided
226     * @return a {@code ProvidesTree} object
227     */
228    ProvidesTree newProvidesTree(ReferenceTree name, List<? extends DocTree> description);
229
230    /**
231     * Create a new {@code ReferenceTree} object, to represent a reference to an API element.
232     *
233     * @param signature the doc comment signature of the reference
234     * @return a {@code ReferenceTree} object
235     */
236    ReferenceTree newReferenceTree(String signature);
237
238    /**
239     * Create a new {@code ReturnTree} object, to represent a {@code @return } tag.
240     * @param description the description of the return value of a method
241     * @return a {@code ReturnTree} object
242     */
243    ReturnTree newReturnTree(List<? extends DocTree> description);
244
245    /**
246     * Create a new {@code SeeTree} object, to represent a {@code @see } tag.
247     * @param reference the reference
248     * @return a {@code SeeTree} object
249     */
250    SeeTree newSeeTree(List<? extends DocTree> reference);
251
252    /**
253     * Create a new {@code SerialTree} object, to represent a {@code @serial } tag.
254     * @param description the description for the tag
255     * @return a {@code SerialTree} object
256     */
257    SerialTree newSerialTree(List<? extends DocTree> description);
258
259    /**
260     * Create a new {@code SerialDataTree} object, to represent a {@code @serialData } tag.
261     * @param description the description for the tag
262     * @return a {@code SerialDataTree} object
263     */
264    SerialDataTree newSerialDataTree(List<? extends DocTree> description);
265
266    /**
267     * Create a new {@code SerialFieldTree} object, to represent a {@code @serialField } tag.
268     * @param name the name of the field
269     * @param type the type of the field
270     * @param description the description of the field
271     * @return a {@code SerialFieldTree} object
272     */
273    SerialFieldTree newSerialFieldTree(IdentifierTree name, ReferenceTree type, List<? extends DocTree> description);
274
275    /**
276     * Create a new {@code SinceTree} object, to represent a {@code @since } tag.
277     * @param text the content of the tag
278     * @return a {@code SinceTree} object
279     */
280    SinceTree newSinceTree(List<? extends DocTree> text);
281
282    /**
283     * Create a new {@code StartElementTree} object, to represent the start of an HTML element.
284     * @param name the name of the HTML element
285     * @param attrs the attributes
286     * @param selfClosing true if the start element is marked as self-closing; otherwise false
287     * @return a {@code StartElementTree} object
288     */
289    StartElementTree newStartElementTree(Name name, List<? extends DocTree> attrs, boolean selfClosing);
290
291    /**
292     * Create a new {@code SummaryTree} object, to represent a {@code @summary } tag.
293     *
294     * @implSpec This implementation throws {@code UnsupportedOperationException}.
295     *
296     * @param summary the content of the tag
297     * @return a {@code SummaryTree} object
298     * @since 10
299     */
300    default SummaryTree newSummaryTree(List<? extends DocTree> summary) {
301        throw new UnsupportedOperationException("not implemented");
302    }
303
304    /**
305     * Create a new {@code TextTree} object, to represent some plain text.
306     * @param text the text
307     * @return a {@code TextTree} object
308     */
309    TextTree newTextTree(String text);
310
311    /**
312     * Create a new {@code ThrowsTree} object, to represent a {@code @throws } tag.
313     * @param name the name of the exception
314     * @param description a description of why the exception might be thrown
315     * @return a {@code ThrowsTree} object
316     */
317    ThrowsTree newThrowsTree(ReferenceTree name, List<? extends DocTree> description);
318
319    /**
320     * Create a new {@code UnknownBlockTagTree} object, to represent an unrecognized block tag.
321     * @param name the name of the block tag
322     * @param content the content
323     * @return an {@code UnknownBlockTagTree} object
324     */
325    UnknownBlockTagTree newUnknownBlockTagTree(Name name, List<? extends DocTree> content);
326
327    /**
328     * Create a new {@code UnknownInlineTagTree} object, to represent an unrecognized inline tag.
329     * @param name the name of the inline tag
330     * @param content the content
331     * @return an {@code UnknownInlineTagTree} object
332     */
333    UnknownInlineTagTree newUnknownInlineTagTree(Name name, List<? extends DocTree> content);
334
335    /**
336     * Create a new {@code UsesTree} object, to represent a {@code @uses } tag.
337     * @param name the name of the service type
338     * @param description a description of how the service will be used
339     * @return a {@code UsesTree} object
340     */
341    UsesTree newUsesTree(ReferenceTree name, List<? extends DocTree> description);
342
343    /**
344     * Create a new {@code ValueTree} object, to represent a {@code {@value } } tag.
345     * @param ref a reference to the value
346     * @return a {@code ValueTree} object
347     */
348    ValueTree newValueTree(ReferenceTree ref);
349
350    /**
351     * Create a new {@code VersionTree} object, to represent a {@code {@version } } tag.
352     * @param text the content of the tag
353     * @return a {@code VersionTree} object
354     */
355    VersionTree newVersionTree(List<? extends DocTree> text);
356
357    /**
358     * Set the position to be recorded in subsequent tree nodes created by this factory.
359     * The position should be a character offset relative to the beginning of the source file
360     * or {@link javax.tools.Diagnostic#NOPOS NOPOS}.
361     * @param pos the position
362     * @return this object, to facilitate method chaining
363     */
364    DocTreeFactory at(int pos);
365
366    /**
367     * Get the first sentence contained in a list of content.
368     * The determination of the first sentence is implementation specific, and may
369     * involve the use of a locale-specific {@link java.text.BreakIterator BreakIterator}
370     * and other heuristics.
371     * The resulting list may share a common set of initial items with the input list.
372     * @param list the list
373     * @return a list containing the first sentence of the list.
374     */
375    List<DocTree> getFirstSentence(List<? extends DocTree> list);
376
377}
378