Jinwoo Hwang created GEODE-10517:
------------------------------------
Summary: Execution Optimization Enablement via Explicit
Cross‑Module Test Result Dependency Modeling
Key: GEODE-10517
URL: https://issues.apache.org/jira/browse/GEODE-10517
Project: Geode
Issue Type: Improvement
Reporter: Jinwoo Hwang
Assignee: Jinwoo Hwang
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)
