[GEODE-10516] Java Documentation Modernization: Stable Aggregation, Legacy Tomcat Neutralization, and Compliance Readiness

[JinwooHwang]

Java Documentation Modernization: Stable Aggregation, Legacy Tomcat Neutralization, and Compliance Readiness

Summary

This pull request restores and stabilizes the aggregate Javadoc build (:geode-assembly:docs) under Gradle 7 by:

• Adding an isolated javadocStubs source set containing minimal legacy Tomcat API placeholders.
• Replacing earlier brittle workarounds (class exclusions, legacy extraction reliance) with a stable classpath-only symbol resolution strategy.
• Resolving missing symbols (LifecycleSupport, SerializablePrincipal, etc.) without bundling obsolete Tomcat 6/7 artifacts.

Result: The aggregate Javadoc builds cleanly, includes intended Geode modules, excludes unwanted external Tomcat API docs, and is positioned for later enforcement hardening.

Motivation

Previously the aggregate Javadoc failed due to unresolved Tomcat 6/7 symbols after refactoring. Pulling the Tomcat 6 distribution to recover those types was brittle and noisy. Excluding affected Geode sources reduced failures but degraded documentation coverage.

Goals addressed:

1. Eliminate cross-project configuration resolution warnings.
2. Avoid globally disabling Javadoc error handling (failOnError=false).
3. Keep session-related sources in the docs.
4. Prevent Tomcat API packages from appearing in published output.
5. Preserve a path to future strict -Xwerror enforcement.
6. Remain RAT (license header) compliant.

Key Changes

Build (geode-assembly/build.gradle)

• Added sourceSets { javadocStubs { ... } }.
• Added stub output to the Javadoc classpath only (not published, not runtime).
• Added exclusion: exclude 'org/apache/catalina/**'.
• Retained combined option: options.addStringOption('Xwerror','-quiet').

Stub Classes (with ASF headers)

Located under:
geode-assembly/src/javadocStubs/java/

• org.apache.catalina.util.LifecycleSupport
• org.apache.catalina.ha.session.SerializablePrincipal
• Supporting minimal placeholders:
  • org.apache.catalina.LifecycleListener
  • org.apache.catalina.Realm
  • org.apache.catalina.realm.GenericPrincipal

They intentionally contain only the signatures required for symbol resolution.

Javadoc Assembly

• Aggregates sources from all javadocOnly dependency projects.
• Uses modern Tomcat 9 + annotations for compilation context.
• Excludes third-party Tomcat API docs while keeping Geode integration code visible.

Rationale

Concern	Decision	Reason
Legacy Tomcat symbols missing	Provide minimal stubs	Avoid shipping/maintaining obsolete binaries
Third-party API leakage	Exclude org.apache.catalina.*	Keep published API surface focused
Future strictness	Keep structural -Xwerror	Simple toggle later
License compliance	ASF headers on new sources	RAT passes cleanly

Verification

Performed:

1. Ran :geode-assembly:docs.
2. Confirmed generated HTML javadocs.
3. RAT task succeeded.
4. Session-related classes referencing Tomcat types appear in docs without unresolved symbol warnings.

For all changes:

• Is there a JIRA ticket associated with this PR? Is it referenced in the commit message?

• Has your PR been rebased against the latest commit within the target branch (typically develop)?

• Is your initial contribution a single, squashed commit?

• Does gradlew build run cleanly?

• Have you written or updated unit tests to verify your changes?

• If adding new dependencies to the code, are these dependencies licensed in a way that is compatible for inclusion under ASF 2.0?