Summary

In the Compiler Tree API, (com.sun.source.**), a new method is added to the DocTrees class, to obtain the characters represented by an instance of EntityTree.

Problem

The com.sun.source.doctree.EntityTree interface provides a representation for the entities that may be found while parsing a documentation comment, but there is no public way to determine the characters represented by the entity. There is support internally within the doclint utility, but this support is not generally available, and it would be convenient if it were.

Solution

Add a new method to the DocTrees utility class to return the characters represented by an entity.

Note that in many cases, entities may represent multiple characters, because of the need for either surrogate pairs or combining characters.

Specification

The following method is added to the DocTrees utility class:

/**
 * Returns a string containing the characters for the entity represented in a given entity tree,
 * or {@code null} if the entity does not represent a series of characters.
 *
 * <p>The interpretation of entities is based on section
 * <a href="https://www.w3.org/TR/html52/syntax.html#character-references">8.1.4. Character references</a>
 * in the HTML 5.2 specification.</p>
 *
 * @returns a string containing the characters
 */
public abstract String getCharacters(EntityTree tree);

The definition of the method specifically references a section within the HTML 5.2 specification. It is expected that this reference may be updated in future releases to newer versions of the HTML specification. This is similar to the way that the specification for java.lang.Character may be updated to refer to newer versions of the Unicode specification.