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