Fixing the missing sources and javadoc Maven artifacts

[Ariho-Seth]

This draft PR adds the maven-source-plugin in the glassfish-main-aggregator pom file, which generates the sources.jar file

And two plugins ie maven-javadoc-plugin and maven-source-plugin in the glassfish-embedded-all pom file

Fixes #24278

[Ariho-Seth]

Hello @OndroMih, I need some help with this issue.

• When I add the maven-javadoc-plugin in the glassfish-main-aggregator, it fails to build,
• And even the plugins I add in the child modules, as requested in the issue, the target directory is not generated when I try to build

Please, may you help me here on how to continue?

[OndroMih]

Hi, @Ariho-Seth, it wouldn't be this simple. Your changes expect that the root pom.xml is an aggregator but GlassFish's build is a bit more complicated. The aggregate goal expects that all the modules were built already, and then goes through them and aggregates their outputs. And that can't be done with a single maven run, it would have to be another step, e.g. mvn source:aggregate. But it would produce the sources in the root module, which is not what we want. So it's better to revert the changes in the root pom and not touch it anymore.

We want to have sources and javadoc attached to the following artifacts:

• appserver/distributions/glassfish/pom.xml - GlassFish Server Full - we only need javadoc for this one, sources are not very useful
• appserver/distributions/web/pom.xml - GlassFish Server Web - we only need javadoc for this one, sources are not very useful
• appserver/extras/embedded/all/pom.xml - Embedded GlassFish Full
• appserver/extras/embedded/web/pom.xml - Embedded GlassFish Web

For the first 2 options, these are GlassFish server distributions and wouldn't be used as Maven dependencies, so sources are not so useful. However, it still would make sense to save a snapshot of the sources together with the distributed artifacts.

To build the source and javadoc artifacts, it's not enough to run the source and javadoc plugins in those modules. They don't contain sources, we need to extract sources and javadoc from their dependencies.

For javadoc, it should be enough to set includeTransitiveDependencySources property to true. Although it's deprecated, it still does what we need and there's no direct replacement.

            <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-javadoc-plugin</artifactId>
              <version>${maven-javadoc-plugin.version}</version>
              <executions>
                  <execution>
                      <id>attach-javadoc</id>
                      <goals>
                          <goal>jar</goal>
                      </goals>
                      <phase>package</phase>
                      <configuration>
                          <includeTransitiveDependencySources>true</includeTransitiveDependencySources>
                      </configuration>
                  </execution>
              </executions>
          </plugin>
          <plugin>

For sources, it's not so straightforward. The source plugin doesn't support a property similar to includeTransitiveDependencySources. The following approach worked for us in the past:

• use the dependency plugin to unpack sources of dependencies - if the resulting sources JAR is too big, it would be good to include only selected dependencies - e.g. artifacts that start with org.glassfish, jakarta, org.eclipse, and some other specific dependencies like Weld, Hibernate Validator, etc., which are not Eclipse Foundation projects and are not in a package that starts with org.eclipse.
• use the assembly plugin to build the sources JAR with sources of all the dependencies

Here's an example project where this approach worked for us for building sources from dependencies : https://github.com/OmniFish-EE/jnosql-extensions-jakarta-data/blob/5f57e1b5900e61b46e7665024b09fc807fdf2733/jnosql-jakarta-persistence/jnosql-jakarta-persistence-driver-osgi-bundle/pom.xml#L139

[Ariho-Seth]

Hello @OndroMih, Please take a look at the changes I've made, though the target directories are still not being generated, only in the appserver/distributions/glassfish/pom.xml is the target being generated, but still it is generated even without adding the plugin.
Is there any progress? :)

[OndroMih]

@Ariho-Seth , it seems that the maven javadoc plugin doesn't support creating javadoc for non-jar Maven modules. The glassfish server Maven modules are of type ZIP and thus javadoc jar goal will just do nothing.

Can you switch focus to Embedded GlassFish? There it could work.

[OndroMih]

For Embedded GlassFish, he javadoc plugin complains that "No Javadoc in project. Archive not created". And that's true - these modules only aggregate dependencies, they don't have sources or javadoc.

Maybe, in the end, we'll need to resort to calling javadoc directly. The javadoc plugin supports passing options to javadoc, using the additionalJOptions configuration properties. But I'm not sure if we can pass some properties so that the plugin will run even if there are no sources in the maven module. If not, then we'll probably need to execute the javadoc tool directly, using the exec maven plugin.