You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/copilot-instructions.md
+8-4Lines changed: 8 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,6 +3,7 @@
3
3
## What this project is
4
4
5
5
- A ColdBox module that embeds and exposes the JavaLoader library so CFML apps can dynamically load/compile Java classes and JARs.
6
+
- On BoxLang 1.8.0+ the public loader facade uses BoxLang's native request class loader for dynamic class loading instead of instantiating the bundled JavaLoader.
- WireBox DSL: `ModuleConfig.cfc` registers a custom DSL `javaloader` via `wireBox.registerDSL(...)`. Use inject="javaloader:ClassName" for DSL injections.
28
29
- Main WireBox mappings: `binder.map("jl@cbjavaloader")` (internal JavaLoader) and `loader@cbjavaloader` (public module proxy, see `models/Loader.cfc`). Use `getWireBox().getInstance("loader@cbjavaloader")` in tests or handlers.
29
-
- Persistent loader instance: `models/Loader.cfc` stores the JavaLoader instance in `server` scope under a hashed static key and uses `lock` for safe init/re-init — avoid re-instantiating directly; call `Loader.setup(moduleSettings)` or `Loader.getJavaLoader()`.
30
+
- Runtime split: `models/Loader.cfc` branches by runtime. On BoxLang it loads configured paths with `getRequestClassLoader().addPaths(...)` and resolves classes via `createObject( "java", className, getRequestClassLoader() )`. On Adobe CF/Lucee it stores the JavaLoader instance in `server` scope under a hashed static key and uses `lock` for safe init/re-init.
31
+
- Module startup expands configured `loadPaths` into concrete files in `ModuleConfig.cfc`; `cfcdynamicproxy.jar` is prepended only for non-BoxLang runtimes.
30
32
- Java compilation: `models/javaloader/JavaCompiler.cfc` expects a JVM `tools.jar` compiler on the classpath; compiled jars are placed by default in `models/javaloader/tmp` (see module `settings.compileDirectory`).
31
33
32
34
## Important files to consult (fast path)
33
35
34
36
-`ModuleConfig.cfc` — module settings defaults and DSL registration.
35
-
-`models/Loader.cfc` — public API that other apps use (`create`, `appendPath`, `getLoadedURLs`).
37
+
-`models/Loader.cfc` — public API that other apps use (`create`, `appendPaths`, `getLoadedURLs`) and the BoxLang/native-vs-JavaLoader branching.
-`models/javaloader/JavaCompiler.cfc` — dynamic compilation logic and compiler discovery.
38
40
-`build/Build.cfc` and `box.json` — packaging, test runner URL and build scripts used by CI.
@@ -45,7 +47,9 @@
45
47
46
48
## Safety, edge cases, and constraints agents must respect
47
49
48
-
- Do not remove or replace the `server`-scoped loader without using the `Loader` API — other code/tests expect the single instance.
50
+
- Do not remove or replace the `server`-scoped loader without using the `Loader` API on Adobe CF/Lucee — other code/tests expect the single instance there.
51
+
- Do not assume a JavaLoader instance exists in `server` scope on BoxLang; the native path bypasses JavaLoader setup entirely.
52
+
- When changing runtime-sensitive behavior, preserve the BoxLang vs Adobe CF/Lucee differences in `getLoadedURLs()`: BoxLang only reports configured app paths, while Adobe CF/Lucee also includes `cfcdynamicproxy.jar`.
49
53
- Java compilation may fail when the JVM compiler is not available; surface clear errors and point to `JavaCompiler.cfc` and `tools.jar` classpath as remediation.
50
54
51
55
## Examples (from repo)
@@ -60,7 +64,7 @@
60
64
61
65
## What to do next when editing code
62
66
63
-
- When changing public behavior in `Loader.cfc` or DSL registration in `ModuleConfig.cfc`, update `test-harness/tests/specs/LoaderTest.cfc` or add a spec demonstrating the change.
67
+
- When changing public behavior in `Loader.cfc` or DSL registration in `ModuleConfig.cfc`, update `test-harness/tests/specs/LoaderTest.cfc` or add a spec demonstrating the change, including runtime-specific expectations when BoxLang behavior differs from Adobe CF/Lucee.
64
68
- Run `box testbox ...` after edits and ensure `test-harness` runner URL in `box.json` matches `build/Build.cfc` test runner if you rely on build tasks.
65
69
66
70
Please review and tell me if you'd like added examples (e.g., a minimal handler that uses the loader), or if I should fold in more lines from the module-template instructions.
This module will allow your ColdBox applications to class load different Java classes and libraries at runtime via the JavaLoader project. It also registers a WireBox DSL so you can easily inject Java classes into your objects using WireBox.
20
+
This module allows your ColdBox applications to class load different Java classes and libraries at runtime. On Adobe ColdFusion and Lucee it uses the bundled JavaLoader project. On BoxLang 1.8.0+ it uses BoxLang's native request class loader while keeping the same `loader@cbjavaloader` facade and `javaloader:` WireBox DSL.
25
21
26
22
## License
27
23
@@ -36,9 +32,9 @@ Apache License, Version 2.0.
36
32
37
33
## System Requirements
38
34
39
-
- BoxLang 1+
35
+
- BoxLang 1.8.0+
40
36
- Lucee 5+
41
-
- ColdFusion 2021+
37
+
-Adobe ColdFusion 2023+
42
38
43
39
## Instructions
44
40
@@ -48,13 +44,22 @@ Just drop into your **modules** folder or use the box-cli to install
48
44
49
45
The module has a default folder called `lib` where any jars you drop there will be class loaded automatically. However, we recommend using the `loadpaths` setting for selecting an array of locations to class load, so when the module updates you won't lose those files.
50
46
51
-
## Models
47
+
On BoxLang 1.8.0+ those configured paths are added to the native request class loader. On Adobe ColdFusion and Lucee they continue to be loaded through JavaLoader.
48
+
49
+
## Loader API
52
50
53
-
The module registers the following mapping in WireBox: `loader@cbjavaloader`. Which is the class you will use to class load, append paths and much more. Check out the included API Docs for much more information. The main methods of importance of the java loader are:
51
+
The module registers the following mapping in WireBox: `loader@cbjavaloader`. This is the facade you will use to class load, append paths, and inspect the active class loader. The main methods are:
54
52
55
53
-`create( class )` - Create a loaded Java class
56
-
-`appendPath( dirPath, filter)` - Appends a directory path of *.jar's,*.classes to the current loaded class loader.
54
+
-`appendPaths( dirPath, filter)` - Appends a directory path of `*.jar` or `*.class` files to the current class loader.
57
55
-`getLoadedURLs()` - Get all the loaded URLs
56
+
-`getURLClassLoader()` - Get the active class loader implementation
57
+
58
+
## Runtime Behavior
59
+
60
+
- BoxLang 1.8.0+: `loader@cbjavaloader` uses the native request class loader. `setup()` and `appendPaths()` call `addPaths()`, and `create()` resolves classes with `createObject( "java", className, getRequestClassLoader() )`.
61
+
- Adobe ColdFusion and Lucee: the module keeps using the bundled JavaLoader instance stored in server scope, including the legacy `cfcdynamicproxy.jar` support jar.
62
+
- Because of that runtime split, `getLoadedURLs()` will usually report fewer entries on BoxLang than on Adobe ColdFusion or Lucee for the same configuration.
Here are the module settings you can place in your `ColdBox.cfc` under an `moduleSettings.cbJavaLoader` structure:
72
77
73
78
```js
74
-
75
79
moduleSettings = {
76
80
cbJavaLoader = {
77
81
// A single path, and array of paths or a single Jar
78
82
loadPaths = [],
79
-
// Load ColdFusion classes with loader
83
+
// Load ColdFusion classes with loader (JavaLoader runtimes only)
80
84
loadColdFusionClassPath =false,
81
-
// Attach a custom class loader as a parent
85
+
// Attach a custom class loader as a parent (JavaLoader runtimes only)
82
86
parentClassLoader ="",
83
-
// Directories that contain Java source code that are to be dynamically compiled
87
+
// Directories that contain Java source code that are to be dynamically compiled (JavaLoader runtimes only)
84
88
sourceDirectories = [],
85
-
// the directory to build the .jar file for dynamic compilation in, defaults to ./tmp
89
+
// the directory to build the .jar file for dynamic compilation in, defaults to ./tmp (JavaLoader runtimes only)
86
90
compileDirectory ="models/javaloader/tmp",
87
-
// Whether or not the source is trusted, i.e. it is going to change? Defaults to false, so changes will be recompiled and loaded
91
+
// Whether or not the source is trusted, i.e. it is going to change? Defaults to false, so changes will be recompiled and loaded (JavaLoader runtimes only)
88
92
trustedSource =false
89
93
}
90
94
};
91
95
92
96
```
93
97
98
+
In BoxLang native mode, `loadPaths` is the primary setting used by the loader facade. The remaining compilation and parent-loader settings continue to apply to the JavaLoader-backed Adobe ColdFusion and Lucee path.
0 commit comments