Every long-running software platform eventually has to update its core runtime dependencies to remain maintainable. For Wikantik—our open-source knowledge platform forked from Apache JSPWiki—that baseline update began at version 2.12.3. Before adding Model Context Protocol (MCP) servers, PostgreSQL vector indexing, or a decoupled React frontend, the codebase had to complete the transition from the legacy javax. namespace to Jakarta EE 10 (jakarta.).
In late 2024, the codebase reflected two decades of incremental Java EE development. It was stable in production, but its core dependencies were pinned to older servlet and utility specifications.
The Legacy Baseline: Apache JSPWiki at 2.12.3
Examining the dependency tree at commit 5ed33a488b (the immediate post-2.12.3 release baseline) shows the pre-migration dependency profile:
- Java Runtime & Compiler: Configured for legacy Java 8 and Java 11 bytecode compatibility.
- Servlet & Web Tier: Bound strictly to
javax.servlet:javax.servlet-api:3.1.0,javax.servlet.jsp:javax.servlet.jsp-api:2.3.3, and Apache Standard Taglibs (JSTL 1.2). - Auxiliary Enterprise APIs: Tied to
com.sun.mail:javax.mail:1.6.2for SMTP notifications, Java Architecture for XML Binding (JAXB 2.x), and Apache XML-RPC 2.0.1 (a protocol specification dating back to 2005). - File Upload Engine: Dependent on the original
commons-fileupload:commons-fileupload:1.5, which tightly coupled multipart parsing tojavax.servlet.http.HttpServletRequest. - Test Infrastructure: Anchored to
net.sourceforge.stripes:stripes:1.6.0—an older presentation framework retained primarily for its HTTP servlet request and session mock classes in unit tests.
Because of these dependencies, the application was restricted to Apache Tomcat 9 and earlier servlet containers.
Why Migrate: The javax to jakarta Transition
When Oracle transferred stewardship of Java EE to the Eclipse Foundation in 2017, the trademark agreement required renaming the root package namespace from javax.* to jakarta.*.
Starting with Jakarta EE 9 and Jakarta EE 10 (Servlet 6.0), current application servers—including Apache Tomcat 10/11, Eclipse Jetty 12, and WildFly 27+—dropped native support for javax.servlet. Remaining on the older namespace carried clear operational drawbacks:
- Container Incompatibility: Inability to deploy to modern, secure, lightweight container runtimes.
- Outdated Dependencies: Inability to upgrade web libraries, multipart parsers, and authentication filters that now target Jakarta EE APIs.
- Runtime Constraints: Slower adoption of newer JDK features, updated HTTP/2 container connectors, and current testing libraries.
Rather than relying on bytecode translation layers at deployment time, we migrated the source tree directly to Jakarta EE 10.
Source-Level Migration: Commit 19e12e277d
On September 6, 2024, commit 19e12e277d ("javax to jakarta") updated 261 files (1,083 insertions and 748 deletions) across the project's submodules.
The changes covered four main areas:
- Core Web Tier: Every servlet, filter, and lifecycle listener—including
WikiServletFilter,RPCServlet,AttachmentServlet, andWikiBootstrapServletContextListener—was migrated fromjavax.servlet.*tojakarta.servlet.*. - Context and Session DSLs: Core SPI interfaces (
ContextDSL,EngineDSL,SessionDSL) were decoupled from old container types and rewired to Jakarta interfaces. - Enterprise Messaging & XML:
MailUtilwas refactored to consumejakarta.mail:jakarta.mail-api:2.1.3, while data serialisation was upgraded tojakarta.xml.bind-api:4.0.x. - Deployment Descriptors (Commit
95cc3c1543): Allweb.xmland Tag Library Descriptor (TLD) schemas were updated from the JCP namespace to Jakarta EE 10 schemas:<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd" version="6.0">
Some Jakarta migrations use bytecode rewriting tools such as Eclipse Transformer or Tomcat's migration utility at deployment time. While useful as a temporary bridge, bytecode translation complicates debugging when reflection, service loaders, and custom classloaders are involved. Updating imports, build descriptors, and test fixtures directly in source control kept stack traces and IDE tooling consistent.
Downstream Dependency Updates
Updating package imports exposed several third-party libraries that still referenced javax.servlet types at runtime. Resolving those incompatibilities required four follow-up changes:
1. Migrating to Commons FileUpload 2.0 (Commit c9ce381fde)
Apache Commons FileUpload 1.x depended directly on javax.servlet. To restore attachment handling, AttachmentServlet was updated to Apache Commons FileUpload 2.0 (commons-fileupload2-jakarta-servlet6:2.0.0-M2), adopting its builder API (DiskFileItemFactory.builder().get()) and JakartaServletFileUpload.isMultipartContent(req).
2. Replacing Stripes Test Mocks with Mockito (Commit 84028cb5e3)
The test suite historically used net.sourceforge.stripes to mock servlet requests and sessions. Because Stripes predated Jakarta EE, its mock objects did not implement jakarta.servlet.http.HttpServletRequest. We replaced Stripes with an internal Mockito-based HttpMockFactory across more than 30 test classes, including WikiSessionTest and AuthenticationManagerTest.
3. Isolating XML-RPC and Updating Container Tests (Commits b65b0b9eaf, 4e5b9e81c9)
Apache XML-RPC 2.0 lacked Jakarta EE support. Rather than blocking the servlet upgrade, XML-RPC was moved out of the core module into an isolated web fragment prior to deprecation, and older embedded Jetty test harnesses were replaced with Cargo-managed container tests.
4. Container Baseline & Modern JDK Constructs (Commits e122d23c05, d2e13b71e6)
With the core modernized, the infrastructure was updated to match. The project Dockerfile was upgraded to FROM tomcat:10.1 (and subsequently Tomcat 11.0.14 via Cargo). Concurrently, commit d2e13b71e6 elevated the baseline compiler to Java 17, replacing verbose boilerplate across JSPWikiMarkupParser and security handlers with modern switch expressions, var declarations, and pattern matching.
The Foundation for an Agentic Future
Tagged as milestone 3.0.0-git-01 (commit 44ac9175be), the Jakarta EE 10 upgrade established the container baseline for the subsequent fork to Wikantik.
With modern servlets and clean HTTP abstractions in place, the team could subsequently extract lightweight manager interfaces into wikantik-api, replace legacy wiki syntax with native CommonMark rendering, and embed the Model Context Protocol (MCP) server that allows AI coding assistants to interact directly with the wiki. Modernizing the enterprise foundation wasn't glamorous work, but it was the prerequisite that made everything else possible. For the full Phase I–V timeline and a side-by-side comparison with upstream Apache JSPWiki, see History and Evolution: From Apache JSPWiki to Wikantik on the wiki.
1 comment
Is this really an interesting project?