Summary

Introduce a new method that returns the best candidate for a main method of the given target class.

Problem

With the introduction of JEP 463 Implicitly Declared Classes and Instance Main Methods the determination of class's main method is no longer a simple algorithm.

Solution

Introduce a new method in java.lang.Class that encompasses the main method determining algorithm. Having a common method ensures that all use cases employ the same algorithm.

Specification

   /**
     * Return the first method that meets the requirements of an application main method
     * {@jls 12.1.4}. The method must:
     * <ul>
     * <li>be declared in this class's hierarchy</li>
     * <li>have the name "main"</li>
     * <li>have a single argument of type {@code String[]}, {@code String...} or no argument</li>
     * <li>have the return type of void</li>
     * <li>be public, protected or package private</li>
     * <li>not be abstract</li>
     *</ul>
     *
     * Searching continues until a main method is found or the search is exhausted. The
     * primary search occurs in two phases, once for a main method with a {@code
     * String[]} or {@code String...} argument and failing that, once for a main method
     * with a no arguments. The search itself uses recursion to first look at methods
     * in this class, then default methods in this class's interface hierarchy and
     * then repeating these steps with the class's super class.
     *
     * @apiNote The method returned may be declared in this class, a super class
     * or as a default method of an interface that the class or super class
     * implements.
     * <p>It is not possible to declare a static main method and instance main
     * method with the same signature in the same class. {@jls 8.4.2} states that
     * "It is a compile-time error to declare two methods with override-equivalent
     * signatures in a class."
     * <p>{@link SecurityException SecurityExceptions} can halt
     * the search. In this case, a null is returned.
     *
     * @return the main method if a method found or null if no method is found
     *
     * @jls 8.2 Class Members
     * @jls 8.4 Method Declarations
     * @jls 8.4.2 Method Signature
     * @jls 12.1.4 Invoke a main method
     * @since 22
     */
    @PreviewFeature(feature=PreviewFeature.Feature.IMPLICIT_CLASSES)
    @CallerSensitive
    public Method findMainMethod() {