use javax or jakarta jars based on version

Author: zspitzer

.gitignore

@@ -4,3 +4,5 @@ bin
 logs
 /temp-unique
 /agent-tests
+/.claude
+/test-output

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+
 - **Local JAR Support**: Added `luceeJar` parameter to test locally built Lucee JARs without publishing
   - Accepts full path to a local JAR file
   - Overrides both `luceeVersion` and `luceeVersionQuery`
@@ -18,45 +19,106 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Custom path: Uses specified directory path
 - **Concurrent Execution Support**: Multiple script-runner instances can now run simultaneously without conflicts
 - **Race Condition Detection**: Automatic detection and prevention of directory conflicts
-- **Improved JFR Logging**: 
+- **Improved JFR Logging**:
   - JFR files now output to organized `logs/` directory
   - Descriptive filenames: `timestamp-lucee-version-webroot-script-javaversion.jfr`
   - Added `logs/` to `.gitignore`
-- **Enhanced Error Messages**: 
+- **Enhanced Error Messages**:
   - Git Bash path conversion detection with specific solutions
   - Execute script validation with exact file path shown
   - Windows trailing backslash validation
 - **Cross-Platform Path Handling**: Robust path concatenation logic for Windows and Unix systems
+- **Version Detection & Servlet API Handling**:
+  - Automatic detection of Lucee 5/6 vs 7+ to select correct servlet dependencies
+  - New `detect-version-type` target inspects version strings and JAR filenames
+  - Split Maven pom files: `pom-javax.xml` (Lucee 5/6) and `pom-jakarta.xml` (Lucee 7+)
+  - Seamless handling of javax to jakarta servlet API transition
+  - Build target reordering so version detection happens before dependency resolution
+- **Java Agent Support**:
+  - `-DjavaAgent=` - Path to Java agent JAR (profilers, debuggers like luceedebug)
+  - `-DjavaAgentArgs=` - Arguments passed to the agent
+  - `-Djdwp=` - Enable JDWP debugging agent with suspend=n (default: false)
+  - `-DjdwpPort=` - JDWP port configuration (default: 9999)
+  - Automatic `--add-opens=java.base/java.lang=ALL-UNNAMED` when using agents
+- **Advanced JVM Options**:
+  - `-DjvmArgs=` - Raw JVM arguments string for custom configurations
+  - `-DFlightRecordingSettings=` - JFR settings profile (default/profile/custom.jfc)
+  - `-DPrintInlining=` - JVM compilation diagnostics (PrintInlining, PrintCompilation, UnlockDiagnosticVMOptions)
+  - `-DPrintGCDetails=` - Detailed garbage collection logging
+  - `-DUseEpsilonGC=` - Epsilon no-op garbage collector with AlwaysPreTouch for testing
+- **Version Query Format Enhancement**:
+  - `luceeVersion` now accepts version query format (e.g., `7.0/stable/light`)
+  - Maintains backward compatibility with `luceeVersionQuery` parameter
+  - Unified version handling logic across both parameters
 
 ### Changed
-- **Updated Lucee Version**: Standardized all references to version 6.2.2.91 across codebase
+
+- **Updated Lucee Version**: Standardized all references to version 7.0.1.100 across codebase
 - **JFR Filename Format**: Changed from `lucee-version.jar-javaversion.jfr` to descriptive format with timestamp and context
 - **Documentation**: Updated README.md with comprehensive working directory behavior explanations
+- **Build Process**:
+  - Uncommented `include template` execution path in build-run-cfml.xml
+  - Build target dependencies reordered: `detect-version-type` now runs before `setEnv`
+  - Enhanced conditional property checking for javaAgent, jvmProperties, jvmArgs
+  - Echo statements now show which servlet type is selected (javax vs jakarta)
+- **Error Handling**:
+  - `_internalRequest` now captures and validates HTTP status codes
+  - Non-200 status codes throw descriptive errors with LDEV-6086 reference
+  - Better debugging information for script execution failures
 
 ### Fixed
+
 - **File Path Validation Bug**: Fixed concatenation logic for execute script validation
 - **Git Bash Path Conversion Issues**: Added detection and helpful error messages for MSYS path conversion problems
 - **Build Script Path Resolution**: Fixed relative path issues when using unique working directories
+- **Request Timeout Detection**: Internal requests now properly detect and report non-200 status codes (LDEV-6086)
 
 ### Technical Details
 
 #### New Ant Properties
+
 - `uniqueWorkingDir`: Controls working directory behavior
 - `webroot.name`: Extracted basename of webroot for JFR filenames
 - `execute.clean`: Cleaned execute path (removes leading slashes) for JFR filenames
 - `execute.fullpath`: Properly concatenated full path for file validation
+- `javaAgent`: Path to Java agent JAR file
+- `javaAgentArgs`: Arguments passed to Java agent
+- `jdwp`: Enable JDWP debugging agent (suspend=n)
+- `jdwpPort`: JDWP port configuration (default: 9999)
+- `jvmArgs`: Raw JVM arguments string
+- `FlightRecordingSettings`: JFR settings profile configuration
+- `PrintInlining`: JVM compilation diagnostics flag
+- `PrintGCDetails`: Garbage collection logging flag
+- `UseEpsilonGC`: Epsilon no-op GC flag
+- `pom.file`: Dynamically selected pom file (pom-javax.xml or pom-jakarta.xml)
+- `version.major.extracted`: Extracted major version number for servlet API detection
+- `usesJavax`: Boolean flag indicating if javax servlet API is used (vs jakarta)
+- `servlet.type`: Servlet API type in use (javax or jakarta)
 
 #### Build Process Improvements
+
 - Added `set-unique-working-dir` target with timestamp generation and race condition checks
 - Enhanced `run-cfml` target with improved validation and path handling
 - Updated GitHub Actions workflow with concurrent execution tests
+- New `detect-version-type` target for automatic servlet API detection:
+  - Parses version strings from `luceeVersion`, `luceeVersionQuery`, or `luceeJar` filename
+  - Extracts major version number using regex
+  - Selects appropriate pom file before dependency resolution
+  - Supports various version formats: `7.0.0.1`, `lucee-7.0.jar`, `7/snapshot/zero`, file paths
+- Internal request result validation with status code checking
 
 #### Error Handling
+
 - Early validation of execute script existence under webroot
 - Specific error messages for common Git Bash issues
 - Clear guidance on workarounds and solutions
+- HTTP status code validation for internal requests (detects timeouts and failures)
 
 ### Migration Notes
-- Existing usage remains unchanged (backward compatible)
+
+- Existing usage remains unchanged (fully backward compatible)
 - New JFR files will appear in `logs/` directory instead of project root
-- Git users should add `logs/` to their `.gitignore` if not already present
+- Git users should add `logs/` to their `.gitignore` if not already present
+- Lucee 5/6 and 7+ now use different servlet dependencies automatically (javax vs jakarta)
+- Version query format can now be used with `luceeVersion` parameter directly
+- All new parameters are optional and have sensible defaults

EXAMPLES.md

@@ -208,7 +208,7 @@ ant -DpreCleanup=false -DpostCleanup=false -Dwebroot=. -Dexecute=test.cfm
 ```bash
 # Install extension from dist/ directory and run tests
 ant -buildfile=script-runner/build.xml \
-    -DluceeVersion="6.2.2.91" \
+    -DluceeVersion="7.0.1.100" \
     -Dwebroot="$BITBUCKET_CLONE_DIR/lucee/test" \
     -DextensionDir="$BITBUCKET_CLONE_DIR/dist" \
     -Dexecute="bootstrap-tests.cfm" \
@@ -300,5 +300,5 @@ pipelines:
           - git clone https://github.com/lucee/lucee
           - export testLabels="PDF"
           - echo $testLabels
-          - ant -buildfile script-runner/build.xml -DluceeVersion="light-6.2.2.91" -Dwebroot="$BITBUCKET_CLONE_DIR/lucee/test" -DextensionDir="$BITBUCKET_CLONE_DIR/dist" -Dexecute="bootstrap-tests.cfm" -DtestAdditional="$BITBUCKET_CLONE_DIR/tests"
+          - ant -buildfile script-runner/build.xml -DluceeVersion="light-7.0.1.100" -Dwebroot="$BITBUCKET_CLONE_DIR/lucee/test" -DextensionDir="$BITBUCKET_CLONE_DIR/dist" -Dexecute="bootstrap-tests.cfm" -DtestAdditional="$BITBUCKET_CLONE_DIR/tests"
 ```

README.md

@@ -37,7 +37,7 @@ ant -buildfile "C:\tools\script-runner\build.xml" -Dwebroot="C:\work\myproject"
 
 - `-buildfile` specifies where script-runner is installed
 - `-Dwebroot` is the directory containing your CFML code (can be relative to current directory)
-- `-Dexecute` is the CFML script to run (relative to webroot)
+- `-Dexecute` is the CFML script to run (relative to webroot, no leading slash required)
 - **Note:** The script-runner always normalizes the webroot to an absolute path internally, regardless of whether you pass a relative or absolute path. All output and script execution will use this normalized absolute path.
 
 ### Basic Usage
@@ -50,10 +50,22 @@ Default `ant` will run the `sample/index.cfm` file
 
 #### Lucee Version
 
-- `-DluceeVersion=` - Lucee version (default: `6.2.2.91`). Examples: `6.2.2.91`, `light-6.2.2.91`, `zero-6.2.2.91`
-- `-DluceeVersionQuery=` - Query-based version (optional, overrides luceeVersion). Format: `(version)/(stable/rc/snapshot)/(jar/light/zero)`. Example: `5.4/stable/light`
+Version Query Format: `(version)/(stable/rc/snapshot/lpha)/(jar/light/zero)`.
+
+Examples:
+
+- `7.0/stable/light`
+- `0/stable/jar`
+- `7.0.2/snapshot/zero`
+
 - `-DluceeJar=` - Path to custom Lucee JAR (optional, overrides both luceeVersion and luceeVersionQuery). Example: `/full-path/to/lucee.jar`, but make sure you use the exact filename for the jar.
 
+- `-DluceeVersion=` - Lucee version (default: `6.2.2.91`). Examples: `6.2.2.91`, `light-6.2.2.91`, `zero-6.2.2.91` or `7.0/stable/light`
+
+**New** LuceeVersion now also handles Version Query format, `luceeVersionQuery` is still supported for backwards compat
+
+- `-DluceeVersionQuery=` - Query-based version (optional, overrides luceeVersion).
+
 #### Paths and Execution
 
 - `-Dwebroot=` - Directory containing CFML code (default: `tests/`). On Windows, trailing backslashes (`\`) will be rejected with an error
@@ -85,8 +97,24 @@ These options are good for inspecting after a run, or setting up the `/lucee-ser
 - `-Ddebugger=` - Enable Java debugger on port 5000 with suspend=y (default: false)
 - `-DFlightRecording=` - Enable Java Flight Recorder profiling (default: false). Saves `.jfr` files to `logs/` directory
 - `-DFlightRecordingFilename=` - Custom output path for JFR recording file
+- `-DFlightRecordingSettings=` - JFR settings profile (default: `profile`). Options: `default`, `profile`, or path to custom `.jfc` file
 - `-DjfrExports=` - Add JFR module exports for Lucee JFR API access (default: false)
 
+#### Java Agent Support
+
+- `-DjavaAgent=` - Path to a Java agent JAR file (e.g., profilers, debuggers like luceedebug)
+- `-DjavaAgentArgs=` - Arguments passed to the agent (the part after `=` in `-javaagent:path=args`)
+- `-Djdwp=` - Enable JDWP debugging agent with suspend=n (default: false). Required for agents like luceedebug
+- `-DjdwpPort=` - JDWP port (default: 9999)
+
+#### Advanced JVM Options
+
+- `-DjvmProperties=` - Path to Java properties file to load additional JVM properties
+- `-DjvmArgs=` - Raw JVM arguments string (e.g., `"-Xmx64m -Xms32m"`)
+- `-DPrintGCDetails=` - Enable detailed garbage collection logging (default: false)
+- `-DUseEpsilonGC=` - Enable Epsilon no-op garbage collector for testing (default: false). Also enables AlwaysPreTouch
+- `-DPrintInlining=` - Enable JVM compilation diagnostics (default: false). Enables PrintInlining, PrintCompilation, and UnlockDiagnosticVMOptions
+
 ### Java Flight Recorder (JFR) Profiling
 
 Enable JFR to capture detailed performance data during script execution:
@@ -136,6 +164,35 @@ jfr print --json logs/250101-120530-j21.jfr > output.json
 
 The `jfr` command-line tool is included in the JDK bin directory. For visual analysis, use JDK Mission Control (JMC) or import into profiling tools.
 
+### Java Agent Example (luceedebug)
+
+To run with a Java agent like [luceedebug](https://github.com/softwareCobbler/luceedebug):
+
+```bash
+ant -buildfile "D:\work\script-runner" ^
+    -Djdwp="true" ^
+    -DjdwpPort="9999" ^
+    -DjavaAgent="D:\path\to\luceedebug-2.0.15.jar" ^
+    -DjavaAgentArgs="jdwpHost=localhost,jdwpPort=9999,debugHost=0.0.0.0,debugPort=10000,jarPath=D:\path\to\luceedebug-2.0.15.jar" ^
+    -Dwebroot="D:\my\cfml\app" ^
+    -Dexecute="index.cfm"
+```
+
+**Note:** The agent's `jarPath` argument must match the `-DjavaAgent` path exactly.
+
+To profile luceedebug overhead with JFR:
+
+```bash
+ant -buildfile "D:\work\script-runner" ^
+    -Djdwp="true" ^
+    -DjavaAgent="D:\path\to\luceedebug.jar" ^
+    -DjavaAgentArgs="jdwpHost=localhost,jdwpPort=9999,debugHost=0.0.0.0,debugPort=10000,jarPath=D:\path\to\luceedebug.jar" ^
+    -DFlightRecording="true" ^
+    -DFlightRecordingFilename="D:\output\luceedebug-profile.jfr" ^
+    -Dwebroot="." ^
+    -Dexecute="benchmark.cfm"
+```
+
 ### TL;DR: Quoting & Paths (Stop Overthinking It)
 
 **If your path has spaces, use quotes. If not, don’t.**
@@ -342,6 +399,19 @@ To use as a GitHub Action, to run the PDF tests after building the PDF Extension
         preCleanup: true (purges Lucee working directory before starting)
         postCleanup: true (purges Lucee working directory after finishing)
         uniqueWorkingDir: true (optional) uses unique working directory for concurrent execution
+        FlightRecording: true (optional) enables Java Flight Recorder profiling
+        FlightRecordingFilename: /path/to/output.jfr (optional) custom JFR output path
+        FlightRecordingSettings: profile (optional) JFR settings profile (default/profile/custom.jfc)
+        jfrExports: true (optional) adds JFR module exports for Lucee JFR API access
+        javaAgent: /path/to/agent.jar (optional) Java agent JAR path
+        javaAgentArgs: agent=args (optional) Java agent arguments
+        jdwp: true (optional) enables JDWP debugging agent (suspend=n)
+        jdwpPort: 9999 (optional) JDWP port (default: 9999)
+        jvmProperties: /path/to/jvm.properties (optional) Java properties file path
+        jvmArgs: "-Xmx64m -Xms32m" (optional) raw JVM arguments
+        PrintGCDetails: true (optional) enables detailed GC logging
+        UseEpsilonGC: true (optional) enables Epsilon no-op garbage collector
+        PrintInlining: true (optional) enables JVM compilation diagnostics
       env:
         testLabels: pdf
         testAdditional: ${{ github.workspace }}/tests

action.yml

@@ -2,10 +2,10 @@ name: 'Lucee Script Runner'
 description: 'Run Lucee via the command line'
 inputs:
   luceeVersion:
-    description: Lucee Version to run, i.e. "light-6.2.2.91", "5.4.6.9", "zero-6.2.2.91"
+    description: Lucee Version to run, i.e. "light-7.0.1.100", "5.4.6.9", "zero-6.2.4.24" or "7.0/snapshot/jar"
     required: true
   luceeVersionQuery:
-    description: Lucee Version Query to run (overrides luceeVersion, i.e. "5.4/stable/light", "6.1/snapshot/jar", "6/stable/zero" )
+    description: Lucee Version Query to run (overrides luceeVersion, i.e. "5.4/stable/light", "7.0/snapshot/jar", "6/stable/zero" ) for backwards compat, use luceeVersion instead
     default: ""
   luceeJar:
     description: Full path to a local Lucee JAR file (overrides both luceeVersion and luceeVersionQuery)

build-run-cfml.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project default="all" basedir="." name="run-cfml">
-	
+
 	<!-- Protection: This file should only be called from build.xml -->
 	<fail message="ERROR: build-run-cfml.xml should not be run directly! Use build.xml instead.">
 		<condition>
@@ -9,7 +9,7 @@
 			</not>
 		</condition>
 	</fail>
-	
+
 	<macrodef name="echots">
 		<attribute name="message"/>
 		<sequential>
@@ -173,12 +173,18 @@
 
 					try {
 						if ( executeScriptByInclude eq "true"){
-							//include template="#execute#";
+							include template="#execute#";
 						} else {
-							_internalRequest(
+							result = _internalRequest(
 								template = execute,
 								url = passedVariables
-							 ); // using internal request runs the Application.cfc, pass any simple variables in as URLs
+							); // using internal request runs the Application.cfc, pass any simple variables in as URLs
+
+							if (result.status_code != 200){
+								failedRequest = "Error: Script threw [#result.status_code#], expected [200], possible request timeout? see LDEV-6086";
+								systemOuput( failedRequest, true, true);
+								throw "Error: Script threw [#result.status_code#], expected [200], possible request timeout? see LDEV-6086";
+							}
 						}
 					} catch (e){
 						request.errorThrown = true;