Summary

Add a getOutermostTypeElement convenience method to javax.lang.model.util.Elements.

Problem

The javax.lang.model API does not have a convenient way to access the outermost class or interface that may contain an element.

Solution

Add the method in question to the convenience interface intended to host such methods. A functional default implementation is included as part of the interface update.

Specification

/**
 * {@return the outermost type element an element is contained in
 * if such a containing element exists; otherwise returns {@code
 * null}}
 *
 * {@linkplain ModuleElement Modules} and {@linkplain
 * PackageElement packages} do <em>not</em> have a containing type
 * element and therefore {@code null} is returned for those kinds
 * of elements.
 *
 * A {@link NestingKind#TOP_LEVEL top-level} class or
 * interface is its own outermost type element.
 *
 * @implSpec
 * The default implementation of this method first checks the kind
 * of the argument. For elements of kind {@code PACKAGE}, {@code
 * MODULE}, and {@code OTHER}, {@code null} is returned. For
 * elements of other kinds, the element is examined to see if it
 * is a top-level class or interface. If so, that element is
 * returned; otherwise, the {@linkplain
 * Element#getEnclosingElement enclosing element} chain is
 * followed until a top-level class or interface is found. The
 * element for the eventual top-level class or interface is
 * returned.
 *
 * @param e the element being examined
 * @see Element#getEnclosingElement
 * @since 18
 */
default TypeElement getOutermostTypeElement(Element e)