[MJAVADOC-609] Include jars for which module name cannot be determined on the classpath

• Type: Bug
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Affects Version/s: 3.1.0
• Fix Version/s: 3.2.0
• Component/s: javadoc
• Assignee: Robert Scholte
• Reporter: Phil Clay
• Created: 12/Jun/19 16:56
• Updated: 02/Dec/19 22:44
• Resolved: 02/Dec/19 22:44

Description

In maven-javadoc-plugin v3.1.0, dependency jars for which the module name cannot be determined are not included on the classpath when running the javadoc command.  This leads to ClassNotFoundExceptions when running javadoc.

Here is a concrete example:

When developing features on feature branches, some developers include jira issue names in the version of artifacts... e.g. ABC-1234-SNAPSHOT.   This leads to jar file names in the form foo-ABC-1234-SNAPSHOT.jar.  Unfortunately, an automatic module name cannot be determined from the filename of this jar according to the rules of ModuleFinder. When attempting to determine the module name of this jar, the following exception is encountered:

java.lang.module.FindException: Unable to derive module descriptor for C:\Users\foo\.m2\repository\com\bar\foo\ABC-1234-SNAPSHOT\foo-ABC-1234-SNAPSHOT.jar
	at java.base/jdk.internal.module.ModulePath.readJar(ModulePath.java:647)
	at java.base/jdk.internal.module.ModulePath.readModule(ModulePath.java:330)
	at java.base/jdk.internal.module.ModulePath.scan(ModulePath.java:236)
	at java.base/jdk.internal.module.ModulePath.scanNextEntry(ModulePath.java:189)
	at java.base/jdk.internal.module.ModulePath.findAll(ModulePath.java:165)
	at ModuleTest.test(ModuleTest.java:14)
	... snip
Caused by: java.lang.IllegalArgumentException: foo.ABC.1234.SNAPSHOT: Invalid module name: '1234' is not a Java identifier
	at java.base/jdk.internal.module.Checks.requireModuleName(Checks.java:52)
	at java.base/java.lang.module.ModuleDescriptor$Builder.<init>(ModuleDescriptor.java:1550)
	at java.base/java.lang.module.ModuleDescriptor.newAutomaticModule(ModuleDescriptor.java:2438)
	at java.base/jdk.internal.module.ModulePath.deriveModuleDescriptor(ModulePath.java:507)
	at java.base/jdk.internal.module.ModulePath.readJar(ModulePath.java:643)
	... 44 more

The maven-javadoc-plugin will swallow this exception (without logging), and won't include the jar on the classpath.

More specifically:

1. AbstractJavadocMojo calls locationManager.resolvePaths(request)
2. The returned ResolvePathsResult<File> result contains the swallowed exception in result.getPathExceptions(). The result does not include the file in getModulepathElements() or getClasspathElements()
3. The AbstractJavadocMojo ignores the path exceptions
4. Therefore, the files that have path exceptions do not get included in the classpath or module path
5. Later, this results in ClassNotFoundExceptions when running javadoc

One workaround is to not use the jira issue name in the version. However, this practice is extremely baked into our workflow (there is automation around it), and therefore would be very difficult to change.

I would like the maven-javadoc-plugin to include jars for which the automatic module name cannot be determined on the classpath.

Potential solutions:

This could potentially be solved in plexus-java, by having LocationManager.resolvePaths return jars for which the automatic module name cannot be determined as part of result.getClasspathElements()

Or, it could be solved it maven-javadoc-plugin by having AbstractJavadocMojo include any files from result.getPathExceptions() on the classpath by default.

Regardless of what is done, result.getPathExceptions() should not be totally swallowed by maven-javadoc-plugin. They should at least be logged to the debug logs. I had to remote debug in order to figure out why the jar was not being included on the classpath.

Issue Links

• is superceded by: MJAVADOC-620 Maven Javadoc Plugin fails to resolve the dependencies when used with Java 11