[
https://issues.apache.org/jira/browse/GEODE-10516?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Jinwoo Hwang updated GEODE-10516:
---------------------------------
Description:
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
was:
h2. Summary
Add input validation and filtering capabilities to the Geode session management
module. This enhancement introduces a validation framework based on
industry-standard security practices (ysoserial, OWASP) while maintaining full
backward compatibility.
h3. Blocklist Methodology
The blocklist is based on authoritative security research:
*Primary Sources:*
# [ysoserial|https://github.com/frohoff/ysoserial] - Canonical gadget chain
database (40+ exploits)
# [OWASP Deserialization Cheat
Sheet|https://cheatsheetseries.owasp.org/cheatsheets/Deserialization_Cheat_Sheet.html]
- Industry best practices
# CVE Database - Known vulnerabilities with proof-of-concept exploits
# Security advisories from Apache, Spring, Oracle
*Blocked Categories:*
|Category|Examples|Reason|CVE References|
|Commons Collections|InvokerTransformer, ChainedTransformer|Arbitrary method
invocation|CVE-2015-7501|
|Spring Internals|ObjectFactory, BeanFactory|Bean instantiation
exploits|CVE-2016-1000027|
|JDK Classes|TemplatesImpl, Proxy|Bytecode loading, dynamic
proxies|CVE-2015-4852|
|Scripting Engines|Groovy closures, JavaScript|Script execution
capabilities|Various|
|Connection Pools|C3P0, DBCP|JNDI injection vectors|CVE-2019-5427|
|RMI/JNDI|UnicastRef, ReferenceWrapper|Remote object lookups|CVE-2016-3427|
h3. Allowlist Methodology
The allowlist includes classes proven safe for deserialization:
*Included Categories:*
# Standard Java types (String, primitives, Collections)
# Immutable data structures (UUID, LocalDate, Optional)
# Geode internal classes (PDX, Region, etc.)
# Framework classes with no gadget chains
*NOT Included (and why):*
{*}Jackson ({{{}com.fasterxml..jackson.{}}}{*}):*
* *Should NOT be blocked* - Jackson is not a gadget chain
* Different vulnerability domain (JSON parsing vs Java serialization)
* Extensively used in Geode (96+ usages in core, GFSH, management API)
* Zero entries in ysoserial's 40+ exploit payloads
* Blocking would break legitimate functionality
h2. Security Research References
h3. Primary Sources
*ysoserial Project:*
* URL: [https://github.com/frohoff/ysoserial]
* Description: Canonical collection of Java deserialization exploits
* Content: 40+ proven gadget chain payloads
* Usage: Defines our blocklist of dangerous classes
*OWASP Deserialization Cheat Sheet:*
* URL:
[https://cheatsheetseries.owasp.org/cheatsheets/Deserialization_Cheat_Sheet.html]
* Description: Industry best practices for secure deserialization
* Guidance: Defense-in-depth, allowlisting, monitoring
*OWASP Top 10:*
* URL:
[https://owasp.org/www-project-top-ten/2017/A8_2017-Insecure_Deserialization]
* Status: A8:2017 - Insecure Deserialization
* Severity: Critical
h3. CVE References
|CVE ID|Component|Description|Exploitability|
|CVE-2015-7501|Commons Collections|InvokerTransformer RCE|Widely exploited|
|CVE-2015-4852|WebLogic/TemplatesImpl|Bytecode injection RCE|Active
exploitation|
|CVE-2016-1000027|Spring Framework|JtaTransactionManager RCE|Known exploits|
|CVE-2019-5427|C3P0|JNDI injection RCE|Proof-of-concept available|
|CVE-2017-5638|Apache Struts|OGNL deserialization|Equifax breach (2017)|
h3. Academic Research
*"Marshalling Pickles" (Black Hat 2017):*
* Comprehensive analysis of serialization vulnerabilities
* Surveyed 30+ libraries for gadget chains
* Established classification framework
*"Serial Killer" (Code White Security):*
* Open-source deserialization firewall
* Reference implementation for filtering
* URL: [https://github.com/ikkisoft/SerialKiller]
*Foxglove Security Research:*
* Original disclosure of Commons Collections exploit
* Real-world impact analysis
* URL:
[https://foxglovesecurity.com/2015/11/06/what-do-weblogic-websphere-jboss-jenkins-opennms-and-your-application-have-in-common-this-vulnerability/]
h3. Risk of Implementing
*Compatibility Risk: LOW*
* Fully backward compatible design
* No API changes required
* Comprehensive test coverage
*Performance Risk: LOW*
* Measured overhead < 2ms
* Negligible impact on session operations
* One-time initialization cost
*Operational Risk: LOW*
* Secure defaults require no configuration
* Clear documentation and examples
* Monitoring capabilities included
*Overall Implementation Risk: LOW*
h2. Compliance and Standards
h3. Security Frameworks
*OWASP Compliance:*
* Addresses A8:2017 - Insecure Deserialization
* Implements recommended defense-in-depth
* Follows input validation best practices
*NIST Cybersecurity Framework:*
* Identify: Recognizes deserialization as attack vector
* Protect: Implements filtering controls
* Detect: Provides logging and monitoring
* Respond: Enables security incident investigation
*CWE Mitigation:*
* CWE-502: Deserialization of Untrusted Data
* Implements recommended safeguards
* Defense-in-depth approach
h3. Industry Standards
*PCI-DSS 3.2.1:*
* Requirement 6.5.8: Secure coding practices
* Input validation on untrusted data
* Protection against common vulnerabilities
*SOC 2 Type II:*
* CC6.1: Logical and physical access controls
* CC7.2: System monitoring and detection
* CC9.2: Risk mitigation procedures
h3. Estimated Timeline
* Code review completion: 1-2 weeks
* Merge to develop: Immediately after approval
* Next release: According to Geode release schedule
* Backporting: Consider for supported versions (if critical)
h2. Related Work
* GEODE-10466: Jakarta EE 10 migration (related PR #7940)
> 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)
