Wheels 4.0: Engine adapter modules (Lucee, Adobe, BoxLang) Issue #1968

[bpamiri]

Summary

Engine-specific adapter modules for consistent cross-engine behavior.

Details

• wheels-lucee-adapter — Lucee-specific optimizations
• wheels-adobe-adapter — Adobe ColdFusion compatibility
• wheels-boxlang-adapter — BoxLang native features
• Adapter pattern ensures consistent behavior across all supported engines
• Part of Wheels 4.0 epic (Plugin system → Service Provider model (Wheels 4.0) #1917)

Source

design_docs/architecture/wheels-4-architecture-guide.md

[bpamiri]

Analysis

Synopsis

This issue proposes extracting engine-specific code into separate adapter modules (wheels-lucee-adapter, wheels-adobe-adapter, wheels-boxlang-adapter) so the Wheels core contains only engine-agnostic code and each adapter handles engine quirks via a consistent adapter pattern.

Merit Assessment

Recommendation: Proceed

• The problem is quantifiable. There are ~98 engine-specific conditional branches (structKeyExists(server, "boxlang"), structKeyExists(server, "lucee"), server.coldfusion.*) scattered across 47 files in vendor/wheels/. The heaviest offenders: Global.cfc (15 occurrences), onapplicationstart.cfc (6), Plugins.cfc (4), Dispatch.cfc (4), and various model/ files. Each engine branch is a maintenance burden and a cross-engine bug vector.
• BoxLang compatibility is driving significant complexity. Recent additions include BoxLang-specific date parsing workarounds (Global.cfc lines 2395-2505), image handling ($image() lines 34-51), SQL Server index query fixes (line 210), and component path construction workarounds in Plugins.cfc (lines 53-88). This will only grow as BoxLang matures.
• Database adapter pattern already proves the concept. vendor/wheels/databaseAdapters/ has 7 database-specific subdirectories (MySQL, PostgreSQL, SQLServer, H2, Oracle, SQLite, CockroachDB) extending Abstract.cfc. Engine adapters would follow the same proven pattern.
• CI matrix already tests all engines. The test workflow (.github/workflows/tests.yml) runs 8 engines (lucee5, lucee6, lucee7, adobe2018, adobe2021, adobe2023, adobe2025, boxlang). Engine adapters would not change CI coverage — they would make failures more targeted and debuggable.

Implementation Plan

1. Catalog all engine-specific branches — Systematically go through the 47 files / 98 occurrences and categorize each branch:

   • Image handling (Global.cfc $image()) — BoxLang uses ImageRead/ImageInfo vs cfimage
   • Date parsing (Global.cfc lines 2338-2505) — BoxLang date format ambiguities
   • Component path construction (Plugins.cfc lines 53-88) — BoxLang leading slash behavior
   • Server detection/version checking (onapplicationstart.cfc lines 36-68) — Engine name/version resolution
   • SSE streaming (controller/sse.cfc) — Engine-specific output flushing
   • Query execution (databaseAdapters/Base.cfc) — Already adapter-based
   • Mixin initialization (Plugins.cfc line 242-244) — BoxLang variables.this workaround

2. Define EngineAdapterInterface.cfc — Create vendor/wheels/interfaces/EngineAdapterInterface.cfc with methods for each category:

   • imageInfo(source), imageProcess(action, args)
   • parseDate(value), formatTimestamp(value)
   • resolveComponentPath(basePath, folder, file)
   • getEngineName(), getEngineVersion(), checkMinimumVersion()
   • flushOutput(), getRequestTimeout()
   • canonicalize(input) (Lucee 5 null workaround, Global.cfc line 2320)

3. Implement three adapters — Create vendor/wheels/engine/:

   • LuceeAdapter.cfc — Native Lucee optimizations (e.g., direct server.lucee.version access, cfimage support)
   • AdobeAdapter.cfc — ACF-specific handling (e.g., server.coldfusion.productVersion, CreateObject("java", "coldfusion.runtime.RequestMonitor") for request timeout on line 2120)
   • BoxLangAdapter.cfc — BoxLang workarounds (image handling, date parsing, component paths)

4. Wire adapter selection into bootstrap — In onapplicationstart.cfc (around lines 36-46), detect the engine once and store the adapter instance: application.$wheels.engineAdapter = new wheels.engine.LuceeAdapter(). Replace all structKeyExists(server, "boxlang") branches with adapter method calls.

5. Extract adapters into installable modules — Once the module system (Wheels 4.0: Module system and package format #1966) lands, each adapter becomes a standalone module that declares provides: "engineAdapter" in its box.json. Core ships with all three bundled for backward compatibility.

Estimated complexity: Medium. Interface + 3 adapter implementations = ~1-2 weeks. Refactoring 47 files to use adapter calls = ~2 weeks. High test confidence due to existing CI matrix.

Dependencies & Risks

• Soft prerequisite: Wheels 4.0: Interface-driven design contracts Issue #1967 #1967 (interface contracts) provides the EngineAdapterInterface pattern, but this issue can proceed independently with a local interface definition.
• Soft prerequisite: Wheels 4.0: Module system and package format #1966 (module system) for the final packaging as installable modules. The adapters can live in-tree initially at vendor/wheels/engine/ and be extracted later.
• Breaking change risk: Low if the adapter is selected automatically at boot time. No public API changes — this is a pure internal refactor.
• Risk: incomplete extraction. Some engine branches are deeply embedded in query building or model initialization. The database adapter layer (vendor/wheels/databaseAdapters/Base.cfc) already has engine-specific code mixed with database-specific code. Cleanly separating engine vs database concerns requires care.
• Test strategy: Each adapter must pass the full test suite on its target engine. The existing CI matrix (8 engines x 5+ databases) already validates this — no new test infrastructure needed.

---

Automated analysis by @claude — review and adjust as needed.