JinwooHwang commented on code in PR #7926:
URL: https://github.com/apache/geode/pull/7926#discussion_r2382877931
##########
geode-assembly/build.gradle:
##########
@@ -387,24 +408,78 @@ tasks.register('gfshDepsJar', Jar) {
}
}
+// Extract legacy Tomcat 6 jars needed only to satisfy Javadoc for old session
manager classes
+// (LifecycleSupport, SerializablePrincipal) without altering runtime
dependencies.
+def legacyTomcatDir = "$buildDir/legacyTomcat"
+tasks.register('extractLegacyTomcatForJavadoc') {
+ description = 'Extracts legacy Tomcat catalina jars for Javadoc symbol
resolution.'
+ outputs.dir(legacyTomcatDir)
+ dependsOn configurations.webServerTomcat6
+ doLast {
+ delete legacyTomcatDir
+ copy {
+ from { zipTree(configurations.webServerTomcat6.singleFile) }
+ // Include the full Tomcat 6 lib set so packages like
org.apache.catalina.ha.session
Review Comment:
Hi @sboorlagadda,
Thanks for pointing that out—excellent observation. Your thoughtful feedback
is much appreciated.
### We need all three layers because they solve different, mutually
exclusive problems:
- Modern Tomcat 9 dependencies
- Extracted legacy Tomcat 6 JARs
- A very small set of stubs
**The stubs DON'T work alone. Here is the evidence:**
- Only 5 stub classes exist in java
- But 30+ different org.apache.catalina.* imports were found across the
codebase
- The stub for SerializablePrincipal has a clear comment: "Only the minimal
surface required by DeltaSession is implemented"
**Legacy JARs provide the bulk coverage:**
- The geode-modules directory extensively uses Tomcat classes that only
exist in older versions
- Classes like org.apache.catalina.session.ManagerBase,
org.apache.catalina.security.SecurityUtil are referenced but not stubbed
- The legacy extraction covers ~26+ classes that would otherwise require
individual stub maintenance
**Stubs provide surgical fixes:**
- The SerializablePrincipal stub shows this clearly—it provides only the
methods needed by DeltaSession
- The comment explicitly states it's a minimal implementation for Javadoc
generation only
- Stubs avoid pulling in the full complexity of legacy classes where only
type presence is needed
**Why not "just stubs"?** Because creating and maintaining 30+ accurate
stubs would be error-prone and high-maintenance.
**Why not "just legacy JARs"?** Because newer modules (like
geode-modules-tomcat9) need modern Tomcat 9 APIs that don't exist in Tomcat 6.
Each layer reduces a different failure mode. Removing any single layer
breaks some subset of symbols.
### The current configuration implicitly tests and tolerates that scenario.
The build succeeds with exit code 0 for :geode-assembly:docs, which would fail
immediately on a binary or signature mismatch if resolution were ambiguous in a
harmful way.
**Evidence of the conflict:**
- There IS a SerializablePrincipal stub at SerializablePrincipal.java
- There IS also a SerializablePrincipal class in the extracted Tomcat 6 JARs
- The Javadoc task successfully completes with exit code 0
**How the conflict is resolved:**
The classpath order in the docs task is:
```
classpath = configurations.javadocOnly + // (1) Tomcat 9 JARs
files(docProjects.collect { proj -> proj.sourceSets.main.output }) + //
(2) Project outputs
legacyCatalinaJars + // (3) Extracted Tomcat 6 JARs
sourceSets.javadocStubs.output // (4) Stub classes (LAST)
```
Because stubs are last, any class present in both a JAR and the stubs is
resolved from the earlier entry (the real Tomcat class). The stub then becomes
an inert fallback. That ordering is deliberate and safe.
**Why this is safe:**
- The stub's comment confirms it's designed as a fallback: "minimal surface
required by DeltaSession"
- The successful Javadoc build proves there are no signature conflicts
between the two versions
- If there were incompatible method signatures, Javadoc compilation would
fail immediately
### The Tomcat APIs ARE incompatible—that's exactly WHY both versions are
needed.
**Evidence of version-specific needs:**
**Modern code needs Tomcat 9:**
- Files in geode-modules-tomcat9 are designed for current Tomcat APIs
- Modern session management uses updated interfaces and packages
- Without Tomcat 9 deps, these modules' Javadoc would fail with missing
symbols
**Legacy code needs Tomcat 6:**
- DeltaSession.java specifically imports
org.apache.catalina.ha.session.SerializablePrincipal
- This class exists in Tomcat 6 but was removed/changed in later versions
- Tomcat6CommitSessionValve.java explicitly targets Tomcat 6 APIs
- Classes like org.apache.catalina.security.SecurityUtil changed interfaces
between versions
**Safe mixing strategy:**
- Scope isolation: Both are only used for Javadoc generation, never in
runtime distribution
- Package exclusion: exclude 'org/apache/catalina/**' ensures no Tomcat
classes leak into published docs
- Quarantined classpath: Legacy JARs are never added to lib/ or any runtime
configuration
- Classpath ordering: Modern takes precedence where available, legacy fills
gaps
Please let me know if I’ve misunderstood anything. As I’m still new to the
community, I may not be as familiar with certain nuances. Your thoughtful
guidance and seasoned experience would be greatly appreciated as I continue to
get up to speed. Thank you so much for your help, @sboorlagadda .
--
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]
