zhtttylz opened a new pull request, #8038:
URL: https://github.com/apache/hadoop/pull/8038
### Description of PR
This PR restores the ability to generate JDiff API XML on **JDK 17** by
porting Hadoop’s in‑tree doclets to the modern **JDK 9+ Doclet API
(`jdk.javadoc.doclet`)**, while preserving the legacy command‑line surface and
XML output contract used in our release process.
**Background.** The original JDiff tool and its legacy doclet APIs predate
JPMS and JDK 9; the upstream artifact (`jdiff:1.0.9`) is from 2005 and does not
support JDK 9+ doclet APIs. Hadoop’s release process, however, still depends on
JDiff XML to publish API diffs between releases.
**Why now.** Since **JEP 221** (JDK 9), the standard `com.sun.javadoc`
doclet path was superseded by `jdk.javadoc.doclet.*`, and the old doclet was
eventually removed/replaced in modern JDKs. To run on **JDK 17**, we need
doclets implemented against the new API.
### How was this patch tested?
Built with JDK 17 and the docs profile to ensure JDiff XML is emitted.
```
mvn -T 1C clean package \
-Pnative -Pdocs \
-Drequire.snappy -Drequire.zstd -Drequire.openssl \
-Djdiff.version=1.1.1-jdk17 \
-DskipTests -Denforcer.skip=true
```
This produces JDiff XML for each module. For example, HDFS:
[Apache_Hadoop_HDFS_3.5.0-SNAPSHOT.xml](https://github.com/user-attachments/files/22904594/Apache_Hadoop_HDFS_3.5.0-SNAPSHOT.xml)
### For code changes:
All changes are scoped to the **hadoop-annotations** module and only affect
build-time doclet code.
1. **Add a JDK‑specific source set and Maven profile**
- Introduce `src/main/java17` under
`hadoop-common-project/hadoop-annotations`.
- Add a Maven profile `jdk17` (activated on JDK ≥ 17) that:
- Adds the `java17` sources via `build-helper-maven-plugin`.
- Compiles them with `maven-compiler-plugin` at `-release 17` and
`-add-modules jdk.javadoc`.
- This keeps JDK 8/11 builds unchanged and makes JDK 17 builds
self‑contained.
2. **Port / re‑implement the doclets on the new Doclet API (under `java17`)**
- `ExcludePrivateAnnotationsJDiffDoclet`
- `IncludePublicAnnotationsJDiffDoclet`
- `ExcludePrivateAnnotationsStandardDoclet`
- `IncludePublicAnnotationsStandardDoclet`
- The JDiff doclets delegate to the (forked) JDiff implementation and
run via `Doclet#run(DocletEnvironment)`.
- The Standard doclets wrap `jdk.javadoc.doclet.StandardDoclet` to keep
the same inclusion/exclusion semantics when producing regular Javadoc.
3. **Port the processing utilities to JDK 17**
- Provide `RootDocProcessor` and `StabilityOptions` variants that
operate on `DocletEnvironment`, preserving:
- audience filtering (exclude `@InterfaceAudience.Private` /
`LimitedPrivate`)
- “public‑only” mode (`IncludePublic*` doclets)
- stability flags such as `unstable`, `evolving`, etc.
4. **No changes to runtime or public APIs**
- Everything here runs at **doc generation time** only.
- No new third‑party runtime dependencies are introduced.
**Related JDiff changes (temporary local test build; JDK 17 adaptation
implemented)**
I implemented the JDK 17 adaptation in JDiff (port to the`
jdk.javadoc.doclet` API) and validated Hadoop’s docs build using a **temporary,
locally installed** artifact: `jdiff:1.1.1-jdk17`. This build is not published
to Maven Central and is provided only so reviewers can reproduce JDiff XML
generation on JDK 17. The implementation is available in zhtttylz/jdiff#4.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
