Skip to content

Commit dd350ed

Browse files
hgschmiehgschmie
authored
[MJAVADOC-770] Implement legacy mode for Java 9+ (#228)
A lot of existing projects that don't use module descriptors but only automatic module naming have moved past Java 8. However, when trying to build docs, the javadoc plugin assumes that the project is modularized and starts using the module path which leads to problems with documentation generation. This change introduces a new configuration setting `<legacyMode>` which is turned off by default. When turning on, the javadoc plugin will continue to construct just a classpath (and not a module path) for the javadoc tool, even if the jdk version is 9 or greater. Includes integration test and documentation.
1 parent 89316c9 commit dd350ed

File tree

5 files changed

+183
-6
lines changed

5 files changed

+183
-6
lines changed

‎src/it/projects/MJAVADOC-770/invoker.properties

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one
2+
# or more contributor license agreements. See the NOTICE file
3+
# distributed with this work for additional information
4+
# regarding copyright ownership. The ASF licenses this file
5+
# to you under the Apache License, Version 2.0 (the
6+
# "License"); you may not use this file except in compliance
7+
# with the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing,
12+
# software distributed under the License is distributed on an
13+
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
# KIND, either express or implied. See the License for the
15+
# specific language governing permissions and limitations
16+
# under the License.
17+
18+
invoker.goals= package
19+
invoker.java.version = 9+

‎src/it/projects/MJAVADOC-770/pom.xml

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
~ Licensed under the Apache License, Version 2.0 (the "License");
4+
~ you may not use this file except in compliance with the License.
5+
~ You may obtain a copy of the License at
6+
~
7+
~ http://www.apache.org/licenses/LICENSE-2.0
8+
~
9+
~ Unless required by applicable law or agreed to in writing, software
10+
~ distributed under the License is distributed on an "AS IS" BASIS,
11+
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
~ See the License for the specific language governing permissions and
13+
~ limitations under the License.
14+
-->
15+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
16+
<modelVersion>4.0.0</modelVersion>
17+
18+
<groupId>org.apache.maven.plugins.javadoc.it</groupId>
19+
<artifactId>mjavadoc770</artifactId>
20+
<version>1.0-SNAPSHOT</version>
21+
<packaging>jar</packaging>
22+
23+
<url>https://issues.apache.org/jira/browse/MJAVADOC-770</url>
24+
25+
<properties>
26+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
27+
<project.build.targetJdk>9</project.build.targetJdk>
28+
<maven.compiler.source>${project.build.targetJdk}</maven.compiler.source>
29+
<maven.compiler.target>${project.build.targetJdk}</maven.compiler.target>
30+
</properties>
31+
32+
<dependencies>
33+
<dependency>
34+
<groupId>org.apiguardian</groupId>
35+
<artifactId>apiguardian-api</artifactId>
36+
<version>1.1.2</version>
37+
</dependency>
38+
</dependencies>
39+
40+
<build>
41+
<plugins>
42+
<plugin>
43+
<groupId>org.apache.maven.plugins</groupId>
44+
<artifactId>maven-jar-plugin</artifactId>
45+
<version>3.3.0</version>
46+
<executions>
47+
<execution>
48+
<id>default-jar</id>
49+
<!-- add module name to main artifact -->
50+
<configuration>
51+
<archive>
52+
<manifestEntries combine.children="append">
53+
<Automatic-Module-Name>mjavadoc770</Automatic-Module-Name>
54+
</manifestEntries>
55+
</archive>
56+
</configuration>
57+
</execution>
58+
</executions>
59+
</plugin>
60+
<plugin>
61+
<artifactId>maven-javadoc-plugin</artifactId>
62+
<version>@project.version@</version>
63+
<executions>
64+
<execution>
65+
<id>javadoc</id>
66+
<goals>
67+
<goal>jar</goal>
68+
</goals>
69+
<phase>package</phase>
70+
<configuration>
71+
<legacyMode>true</legacyMode>
72+
<release>${project.build.targetJdk}</release>
73+
<skip>false</skip>
74+
<detectJavaApiLink>false</detectJavaApiLink>
75+
<detectOfflineLinks>false</detectOfflineLinks>
76+
<failOnWarnings>true</failOnWarnings>
77+
</configuration>
78+
</execution>
79+
</executions>
80+
</plugin>
81+
</plugins>
82+
</build>
83+
</project>

‎src/it/projects/MJAVADOC-770/src/main/java/mjavadoc770/Main.java

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
20+
package mjavadoc770;
21+
22+
/**
23+
* This is the main class.
24+
*/
25+
public final class Main {
26+
/**
27+
* This is the main method.
28+
*
29+
* @param args The arguments
30+
* @throws Exception if something goes wrong
31+
*/
32+
public static final void main(String ... args) throws Exception {
33+
System.out.println("Hello, World!");
34+
}
35+
}

‎src/it/projects/MJAVADOC-770/verify.groovy

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
20+
// new style javadoc has a module summary. legacy mode has not.
21+
def moduleFile = new File( basedir, 'target/apidocs/mjavadoc770/module-summary.html')
22+
23+
assert !moduleFile.exists()

‎src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -841,6 +841,16 @@ public abstract class AbstractJavadocMojo extends AbstractMojo {
841841
@Parameter(property = "verbose", defaultValue = "false")
842842
private boolean verbose;
843843

844+
/**
845+
* Run the javadoc tool in pre-Java 9 (non-modular) style even if the java version is
846+
* post java 9. This allows non-JPMS projects that have moved to newer Java
847+
* versions to create javadocs without having to use JPMS modules.
848+
*
849+
* @since 3.5.1
850+
*/
851+
@Parameter(property = "legacyMode", defaultValue = "false")
852+
private boolean legacyMode;
853+
844854
// ----------------------------------------------------------------------
845855
// Standard Doclet Options - all alphabetical
846856
// ----------------------------------------------------------------------
@@ -2068,7 +2078,9 @@ protected Map<Path, Collection<String>> getFiles(Collection<Path> sourcePaths) t
20682078
} else if (source != null) {
20692079
autoExclude = JavaVersion.parse(source).isBefore("9");
20702080
} else {
2071-
autoExclude = false;
2081+
// if legacy mode is active, treat it like pre-Java 9 (exclude module-info),
2082+
// otherwise don't auto-exclude anything.
2083+
autoExclude = legacyMode;
20722084
}
20732085

20742086
for (Path sourcePath : sourcePaths) {
@@ -4383,11 +4395,16 @@ private void addJavadocOptions(
43834395

43844396
Map<String, JavaModuleDescriptor> allModuleDescriptors = new HashMap<>();
43854397

4386-
boolean supportModulePath = javadocRuntimeVersion.isAtLeast("9");
4387-
if (release != null) {
4388-
supportModulePath &= JavaVersion.parse(release).isAtLeast("9");
4389-
} else if (source != null) {
4390-
supportModulePath &= JavaVersion.parse(source).isAtLeast("9");
4398+
// do not support the module path in legacy mode
4399+
boolean supportModulePath = !legacyMode;
4400+
4401+
if (supportModulePath) {
4402+
supportModulePath &= javadocRuntimeVersion.isAtLeast("9");
4403+
if (release != null) {
4404+
supportModulePath &= JavaVersion.parse(release).isAtLeast("9");
4405+
} else if (source != null) {
4406+
supportModulePath &= JavaVersion.parse(source).isAtLeast("9");
4407+
}
43914408
}
43924409

43934410
if (supportModulePath) {

0 commit comments

Comments
 (0)