4.x: Archetypes - update MP Main class javadoc to document the module main class requirement

[romain-grecourt]

#7226 introduced module-info in the archetypes for all flavors.

Since maven-jar-plugin:3.1.2 jar is invoked with -main-class (see usage), which sets the ModuleMainClass module attribute.

However, when the module main class is set, the main class must be in a package that is either exported or opened by the module.

This means that when using the module system we can't reference a built-in main class, instead we have to create one in the module with a simple implementation that calls the built-in one.

#7711 added such Main class to MP archetypes. This issue is about documenting the new requirement in the javadoc of the generated MP main class:

• Tell users that the class is needed when using the module system
• Give a decent explanation of the requirement

See explanations below for the requirements of a module main class.

---

When using jar --main-class, the jar tool creates a binary form ModuleDescriptor that sets the following module attributes:

• ModuleMainClass with the value of --main-class
• ModulePackages with the list of packages exported or opened by the module

The module descriptor is then validated with ModuleDescriptor.read:

This method works exactly as specified by the 2-arg read method with the exception that a package finder is not used to find additional packages when the module descriptor read from the stream does not indicate the set of packages.

The 2-arg ModuleDescriptor.read states:

The set of packages that the packageFinder returns must include all the packages that the module exports, opens, as well as the packages of the service implementations that the module provides, and the package of the main class (if the module has a main class

This effectively means that the module main class must be in a package that is either exported or opened by the module.

If the module is not valid an InvalidModuleDescriptorException is thrown, and the exception message is displayed by jar. See the corresponding jar source code.

E.g.

jar: Package io.helidon missing from ModulePackages class file attribute

---

Some other interesting bits of information:

ModuleDescriptor.packages():

The set of packages includes all exported and open packages, as well as the packages of any service providers, and the package for the main class.

ModulePackages:

The ModulePackages attribute indicates all the packages of a module that are exported or opened by the Module attribute, as well as all the packages of the service implementations recorded in the Module attribute. The ModulePackages attribute may also indicate packages in the module that are neither exported nor opened nor contain service implementations.