[
https://issues.apache.org/jira/browse/GEODE-10516?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18117827#comment-18117827
]
ASF subversion and git services commented on GEODE-10516:
---------------------------------------------------------
Commit 7e2204560968683c3019bc36327a248065427894 in geode's branch
refs/heads/develop from Jinwoo Hwang
[ https://gitbox.apache.org/repos/asf?p=geode.git;h=7e22045609 ]
[GEODE-10516] Java Documentation Modernization: Stable Aggregation, Legacy
Tomcat Neutralization, and Compliance Readiness (#7926)
* Execution optimizations
* Cross-project runtimeClasspath resolution
* geode-assembly-docs
* geode-assembly-docs
* Revert "Execution optimizations"
This reverts commit 5de4fb5f01f4545139d9bcd52b77fe7f33aefad3.
* Revert "Cross-project runtimeClasspath resolution"
This reverts commit e899ebcaa51e9334413e61145d26ff8432be14af.
* remove exclude examples/security
* addressed format
* added impl
> Java Documentation Modernization: Stable Aggregation, Legacy Tomcat
> Neutralization, and Compliance Readiness
> ------------------------------------------------------------------------------------------------------------
>
> Key: GEODE-10516
> URL: https://issues.apache.org/jira/browse/GEODE-10516
> Project: Geode
> Issue Type: Improvement
> Reporter: Jinwoo Hwang
> Assignee: Jinwoo Hwang
> Priority: Major
> Fix For: 2.1.0
>
>
> h2. Summary
> Restore and stabilize the aggregate Javadoc build
> ({{{}:geode-assembly:docs{}}}) under Gradle 7 by implementing a three-layered
> approach: minimal stub classes for surgical symbol resolution, legacy Tomcat
> 6 JARs for broad coverage, and modern Tomcat 9 dependencies for current APIs.
> This eliminates unresolved symbol errors while preventing third-party API
> documentation leakage.
> h2. Description
> h3. Problem Statement
> The aggregate Javadoc build task ({{{}:geode-assembly:docs{}}}) fails under
> Gradle 7 due to unresolved Tomcat 6/7 API symbols. Geode's session management
> modules reference legacy Tomcat classes ({{{}LifecycleSupport{}}},
> {{{}SerializablePrincipal{}}}, etc.) that no longer exist in modern Tomcat
> versions, causing Javadoc compilation to fail with "symbol not found" errors.
> *Current Failure:*
> {noformat}
> Task :geode-assembly:docs FAILED
> error: cannot find symbol
> [javadoc] import org.apache.catalina.ha.session.SerializablePrincipal;
> [javadoc] ^
> [javadoc] symbol: class SerializablePrincipal
> [javadoc] location: package org.apache.catalina.ha.session
> error: cannot find symbol
> [javadoc] import org.apache.catalina.util.LifecycleSupport;
> [javadoc] ^
> [javadoc] symbol: class LifecycleSupport
> [javadoc] location: package org.apache.catalina.util
> ... (30+ similar unresolved symbols)
> {noformat}
> h3. Historical Context
> h4. Previous State
> *Before Refactoring:*
> * Aggregate Javadoc task worked with older Gradle versions
> * Dependencies implicitly resolved Tomcat symbols
> * No explicit version conflicts managed
> *After Gradle 7 Migration:*
> * Stricter classpath resolution broke implicit dependencies
> * Legacy Tomcat symbols no longer automatically available
> * Build failures blocking documentation generation
> h4. Previous Workaround Attempts
> |Approach|Implementation|Problem|
> |Global {{failOnError=false}}|Disable all Javadoc error checking|Masks real
> documentation issues, defeats purpose|
> |Class exclusions|{{exclude 'org/apache/geode/modules/session/**'}}|Removes
> session management from documentation|
> |Legacy extraction only|Extract Tomcat 6 distribution JARs|Brittle, noisy,
> conflicts with modern APIs|
> |Stubs only|Create minimal placeholders|Insufficient coverage (30+ classes
> needed)|
> *None of these approaches were satisfactory:*
> * Quality compromise (ignoring errors or excluding content)
> * Maintenance burden (extensive stub creation)
> * Brittle dependencies (full legacy distribution extraction)
> h3. Current Behavior
> *Build Failure:*
> {code:bash}
> ./gradlew :geode-assembly:docs
> # Result: FAILED
> # Reason: Unresolved symbols from legacy Tomcat APIs
> # Impact: No aggregate Javadoc generated
> {code}
> *Specific Symbol Resolution Failures:*
> |Symbol|Package|Usage in Geode|Tomcat Version|
> |LifecycleSupport|org.apache.catalina.util|Session lifecycle
> management|Tomcat 6/7 only|
> |SerializablePrincipal|org.apache.catalina.ha.session|Delta session
> replication|Tomcat 6/7 only|
> |ManagerBase|org.apache.catalina.session|Session manager base class|Removed
> in Tomcat 9|
> |SecurityUtil|org.apache.catalina.security|Security utilities|Changed in
> Tomcat 9|
> |GenericPrincipal|org.apache.catalina.realm|Authentication
> principal|Signature changed|
>
> *Code Example (DeltaSession.java):*
> {code:java}
> package org.apache.geode.modules.session.internal.filter;
> import org.apache.catalina.ha.session.SerializablePrincipal; // NOT FOUND
> import org.apache.catalina.util.LifecycleSupport; // NOT FOUND
> public class DeltaSession extends Session {
> private SerializablePrincipal principal; // Compilation fails
> private LifecycleSupport lifecycle; // Compilation fails
> }
> {code}
> h3. Scope of Issue
> h4. Affected Modules
> {noformat}
> geode-assembly/
> ├── build.gradle (Javadoc task configuration)
> └── src/javadocStubs/java/ (NEW - stub classes)
> └── org/apache/catalina/
> ├── util/LifecycleSupport.java
> ├── ha/session/SerializablePrincipal.java
> ├── LifecycleListener.java
> ├── Realm.java
> └── realm/GenericPrincipal.java
> geode-modules/
> ├── geode-modules-session-internal/ (Uses legacy Tomcat 6 APIs)
> ├── geode-modules-tomcat7/ (Uses Tomcat 7 APIs)
> ├── geode-modules-tomcat8/ (Uses Tomcat 8 APIs)
> └── geode-modules-tomcat9/ (Uses modern Tomcat 9 APIs)
> {noformat}
> h4. Symbol Count Analysis
> *Tomcat Class References in Geode:*
> * Total {{org.apache.catalina.*}} imports: 30+ unique classes
> * Legacy-only classes (Tomcat 6/7): 26+ classes
> * Modern-only classes (Tomcat 9+): 8+ classes
> * Classes with API changes between versions: 4+ classes
> *Coverage Breakdown:*
> * Stub classes created: 5 (surgical fixes)
> * Legacy JAR coverage: 26+ classes (broad coverage)
> * Modern dependencies: 8+ classes (current API support)
> h3. Root Cause Analysis
> h4. Multi-Version Tomcat Support Challenge
> Geode supports multiple Tomcat versions simultaneously:
> {noformat}
> geode-modules-tomcat7 → Tomcat 7.x APIs
> geode-modules-tomcat8 → Tomcat 8.x APIs
> geode-modules-tomcat9 → Tomcat 9.x APIs
> geode-modules-session → Legacy Tomcat 6/7 APIs
> {noformat}
> *The Fundamental Problem:*
> * Legacy code requires Tomcat 6/7 classes (removed in Tomcat 9)
> * Modern code requires Tomcat 9 classes (different from Tomcat 6)
> * Aggregate Javadoc must compile ALL modules together
> * No single Tomcat version satisfies all requirements
> h4. Gradle 7 Strictness
> *What Changed:*
> * Gradle 7+ enforces stricter classpath validation
> * Unresolved symbols cause immediate build failure
> * {{-Xwerror}} flag enforced by default for quality
> * Previous implicit dependency resolution no longer works
> *Impact:*
> * Build that worked in Gradle 6 now fails
> * Cannot ignore errors without compromising quality
> * Must explicitly resolve ALL symbol dependencies
> h3. API Leakage Prevention
> *Problem:* Don't want Tomcat internal APIs in published Javadoc
> *Solution:*
> {code:groovy}
> task docs(type: Javadoc) {
> // Exclude all Tomcat packages from generated documentation
> exclude 'org/apache/catalina/**'
> exclude 'org/apache/tomcat/**'
> exclude 'org/apache/coyote/**'
> }
> {code}
> *Result:*
> * Tomcat classes used for compilation/type checking only
> * No Tomcat packages appear in published Javadoc HTML
> * Only Geode classes documented
> h2. Benefits of This Enhancement
> h3. Build Stability
> * *Complete symbol resolution* - All 30+ Tomcat references resolved
> * *No error suppression* - {{-Xwerror}} remains enabled for quality
> * *Gradle 7+ compatible* - Works with strict validation
> * *Deterministic builds* - Consistent results across environments
> h3. Documentation Quality
> * *Full coverage* - Session management included in documentation
> * *No content loss* - All Geode modules documented
> * *Clean output* - No third-party API leakage
> * *Professional appearance* - Complete, error-free Javadoc
> h3. Maintainability
> * *Layered approach* - Each layer has clear purpose
> * *Minimal custom code* - Only 5 stub classes needed
> * *Low maintenance* - Stubs are minimal, unlikely to change
> * *Clear intent* - Each layer documented and justified
> h3. Compliance and Quality
> * *RAT compliant* - All stub files have ASF license headers
> * *Quality gates enabled* - {{-Xwerror}} catches real issues
> * *Future-proof* - Ready for stricter enforcement
> * *Best practices* - Follows Gradle documentation patterns
> h2. Success Criteria
> When this enhancement is implemented, the following should be true:
> # *Build Success:* {{:geode-assembly:docs}} completes with exit code 0
> # *Symbol Resolution:* All 30+ Tomcat references resolve without errors
> # *Quality Gates:* {{-Xwerror}} remains enabled, catching real issues
> # *Content Coverage:* Session management modules included in documentation
> # *API Isolation:* No Tomcat packages appear in published Javadoc
> # *License Compliance:* All stub files pass RAT checks with ASF headers
> # *No Regressions:* All 15 CI checks passing
> h2. Risk Assessment
> h3. Risk of NOT Fixing
> *Documentation Risk: HIGH*
> * Aggregate Javadoc cannot be generated
> * Session management undocumented
> * API documentation incomplete
> * User/developer confusion
> *Quality Risk: MEDIUM*
> * Cannot enable strict error checking
> * Real documentation issues masked
> * Professional appearance compromised
> *Maintenance Risk: MEDIUM*
> * Workarounds accumulate over time
> * Technical debt increases
> * Future Gradle versions may break completely
> h3. Risk of Fixing
> *Implementation Risk: LOW*
> * Pure build configuration changes
> * No runtime code modifications
> * Well-tested approach
> *Compatibility Risk: VERY LOW*
> * Only affects Javadoc generation
> * No published artifact changes
> * No API modifications
> *Maintenance Risk: LOW*
> * 5 minimal stub files (unlikely to change)
> * Clear documentation of approach
> * Layered strategy easy to understand
> *Overall Risk: LOW*
> * High benefit (documentation restored)
> * Minimal risk (build infrastructure only)
> * Reversible (can revert if issues arise)
> h2. Compliance and Standards
> h3. Apache License Compliance
> *RAT (Release Audit Tool) Validation:*
> * All 5 stub files include full ASF license headers
> * Copyright notices present
> * License references correct
> * {{./gradlew rat}} passes cleanly
> *Stub File Header Example:*
> {code:java}
> /*
> * Licensed to the Apache Software Foundation (ASF) under one or more
> * contributor license agreements. See the NOTICE file distributed with
> * this work for additional information regarding copyright ownership.
> * The ASF licenses this file to You under the Apache License, Version 2.0
> * (the "License"); you may not use this file except in compliance with
> * the License. You may obtain a copy of the License at
> *
> * http://www.apache.org/licenses/LICENSE-2.0
> *
> * Unless required by applicable law or agreed to in writing, software
> * distributed under the License is distributed on an "AS IS" BASIS,
> * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
> * See the License for the specific language governing permissions and
> * limitations under the License.
> */
> {code}
> h3. Documentation Standards
> *Javadoc Quality:*
> * {{-Xwerror}} flag enabled (strict mode)
> * All documentation warnings treated as errors
> * Real issues caught during build
> * Professional output quality
> *API Surface Control:*
> * Third-party APIs excluded from published docs
> * Only Geode public APIs documented
> * Clear separation of internal vs external
> * User-facing documentation clean
>
> h2. Related Work
> * Gradle 7 migration efforts
> * Documentation infrastructure modernization
> * Tomcat version support strategy
> * Build system quality improvements
>
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
