Skip to content

Commit a760db9

Browse files
zspitzerzspitzer
committed
improve recipes
1 parent 28ea452 commit a760db9

File tree

9 files changed

+346
-724
lines changed

9 files changed

+346
-724
lines changed

‎docs/recipes/event-gateways.md‎

Lines changed: 17 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -23,59 +23,39 @@
2323

2424
# Event Gateways
2525

26-
First of all, it is necessary to explain how Event Gateways (EG) are working in the first place. EG's are another way to communicate with your Lucee server and are kind of a service running on Lucee, reacting to certain events. These kinds of events could be something along the lines of:
26+
Event Gateways are services running on Lucee that react to events such as:
2727

28-
- SMS sent to a certain receiver
29-
- File change happening in a directory
30-
- Mail received on a mail server
31-
- Slack notification received
28+
- SMS received
29+
- File change in a directory
30+
- Mail received
31+
- Slack notification
3232

33-
What then can be done with these events is to trigger some actions that react to these events. For instance, if an SMS is sent to the server asking for the current heap memory space, the server could respond with an SMS returning the details. So you basically have an event producer and an event consumer.
33+
In Lucee, Event Gateways can be written in CFML (not just Java), making them much more accessible.
3434

35-
Event Gateways have for a long time lived a quiet life in CFML for several reasons. The main reasons were the lack of diversity and implementations, which were due to the fact that EG's had to be written in Java and not every CFML developer is very familiar with Java. Given this downside, it is understandable that there are such few available event gateways available.
35+
## Components
3636

37-
## Lucee's approach
37+
- **Gateway driver** - CFC that manages lifecycle, always running
38+
- **Event Gateway** - The actual event handling implementation
3839

39-
In Lucee, EG's can be written in CFML, and this is what this description is all about, which now makes it way more attractive to write the decisive parts with your favorite language. Some parts sometimes still need perhaps a Java library, but coding around that normally is not really a problem. Just use the according JAR solution available for the specific event (like SMS or others).
40-
41-
## What are the involved components in Lucee?
42-
43-
There are 2 components that are important for writing an event gateway:
44-
45-
- Gateway driver
46-
- Event Gateway
47-
48-
The gateway driver is a CFC that is always instantiated and running. It is responsible for managing the lifecycle of the event gateway. The event gateway is the actual implementation of the event handling logic.
49-
50-
## Testing the Event Gateway
51-
52-
I have created a template called testGateway.cfm and use the following code to test the result.
40+
## Example
5341

5442
```lucee
5543
<cfset sMessage = "something I need to log.">
5644
<cfset sendGatewayMessage("logMe", {})>
5745
```
5846

59-
<img src="/uploads/default/original/1X/a127ee6bf8b4df77c6956ba2cada99ab4642e7ff.jpg" width="593" height="163">
60-
61-
Now the sanity checks kick in and prevent faulty data from being sent to the Gateway. So once we change the code to this:
47+
Sanity checks prevent faulty data. With valid data:
6248

6349
```lucee
6450
<cfset sMessage = "something I need to log.">
6551
<cfset sendGatewayMessage("logMe", {message:sMessage, type:"error"})>
6652
```
6753

68-
We receive the expected blank page. In the background, the message has been passed to the Gateway through the sendGateway() method and the data will be written by the start() endless loop into the logfile with the help of the method \_log().
69-
70-
How you actually write your EG is totally up to you. But now, do it in CFML!
71-
72-
## Further examples for Event Gateway implementations
73-
74-
Above we have introduced the possibility to asynchronously log some data to a log file. There are additional other Event Gateways you can think of or use:
54+
The message passes to the Gateway via `sendGatewayMessage()` and gets written to the log.
7555

76-
- ICQ watcher
77-
- Slack Channel inspector
78-
- Listen to a socket
79-
- On incoming email
56+
## Use Cases
8057

81-
The possibilities are huge and we expect several new event gateways to emerge in the next few months. Have fun with Lucee.
58+
- Bluesky/social media integration
59+
- Slack channel monitoring
60+
- Socket listeners
61+
- Incoming email handlers

‎docs/recipes/java-scripting.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,15 @@
2020

2121
# Java Scripting with Lucee
2222

23-
Lucee provides comprehensive support for JSR-223 (Java Scripting API), enabling CFML to be used as a scripting language in any environment that supports the Java platform. This opens up powerful integration scenarios where you can leverage CFML's expressive syntax and built-in functions across diverse technology stacks, build tools, serverless platforms, and automation frameworks.
23+
Lucee provides comprehensive support for JSR-223 (Java Scripting API), enabling CFML to be used as a scripting language in any environment that supports the Java platform.
24+
25+
This opens up powerful integration scenarios where you can leverage CFML's expressive syntax and built-in functions across diverse technology stacks, build tools, serverless platforms, and automation frameworks.
2426

2527
## Overview
2628

27-
Through JSR-223 support, Lucee can be used as a scripting engine in any environment that runs on the Java platform. This includes build tools like Ant and Maven, serverless platforms like AWS Lambda, CI/CD pipelines, data processing workflows, and standalone scripts. The integration requires only adding Lucee JAR files to your classpath - no complex setup or application server needed.
29+
Through JSR-223 support, Lucee can be used as a scripting engine in any environment that runs on the Java platform. This includes build tools like Ant and Maven, serverless platforms like AWS Lambda, CI/CD pipelines, data processing workflows, and standalone scripts.
30+
31+
The integration requires only adding Lucee JAR files to your classpath - no complex setup or application server needed.
2832

2933
## AI-Optimized Technical Reference
3034

‎docs/recipes/java-settings.md‎

Lines changed: 81 additions & 139 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
21
<!--
32
{
43
"title": "JavaSettings in Application.cfc, Components and CFConfig.json",
@@ -23,192 +22,135 @@
2322
}
2423
-->
2524

26-
# Java Settings in Application.cfc (Now with Maven Support)
27-
28-
This document provides information about configuring Java settings in Lucee using `Application.cfc`, and other new places like `.CFConfig.json`, `createObject`, and components.
29-
30-
## Introduction
25+
# Java Settings
3126

32-
The `this.javasettings` settings in `Application.cfc` allow you to define Java library paths, OSGi bundle paths, Maven libraries, and other Java-related configurations. These settings cannot be configured through the Lucee admin or environment variables.
27+
The `javasettings` configuration tells Lucee where to find Java libraries. You can load JARs from local paths, pull dependencies from Maven automatically, or use OSGi bundles for advanced modular deployments.
3328

34-
Starting with Lucee 6.2, we’ve extended Java settings to support Maven libraries and expanded their use in additional contexts, including `.CFConfig.json`, `createObject`, and individual components.
29+
Configure it in `Application.cfc` (app-wide), on individual components (isolated), in `.CFConfig.json` (server-wide), or inline with `createObject`.
3530

36-
## Configuring Java Settings
31+
## Application.cfc
3732

38-
You can configure Java settings in `Application.cfc`, `.CFConfig.json`, within components, or using the `createObject` function.
39-
40-
### Load Paths
41-
42-
You can define regular JARs (not OSGi) by specifying the path to a directory or the JAR file itself.
33+
The most common approach - makes libraries available to your entire application:
4334

4435
```cfml
45-
this.javasettings.loadPaths = [
46-
"/my/local/path/to/whatever/lib/",
47-
"/my/local/path/to/whatever/lib/xyz.jar"
48-
];
36+
this.javasettings = {
37+
"maven": [
38+
{
39+
"groupId": "org.quartz-scheduler",
40+
"artifactId": "quartz",
41+
"version": "2.3.2"
42+
}
43+
],
44+
"loadPaths": [
45+
"/my/local/path/to/libs/",
46+
"/my/local/path/to/libs/example.jar"
47+
],
48+
"reloadOnChange": true,
49+
"watchInterval": 60,
50+
"watchExtensions": ["jar", "class"]
51+
};
4952
```
5053

51-
### Bundle Paths
54+
## Maven Dependencies (6.2+)
5255

53-
You can load local OSGi bundles in a similar way.
56+
Pull libraries from Maven Central automatically - no manual JAR management:
5457

5558
```cfml
56-
this.javasettings.bundlePaths = [
57-
"/my/local/path/to/whatever/lib/",
58-
"/my/local/path/to/whatever/lib/xyz.jar"
59+
this.javasettings.maven = [
60+
{
61+
"groupId": "org.quartz-scheduler",
62+
"artifactId": "quartz",
63+
"version": "2.3.2"
64+
},
65+
{
66+
"groupId": "commons-beanutils",
67+
"artifactId": "commons-beanutils",
68+
"version": "1.9.4"
69+
}
5970
];
6071
```
6172

62-
### Maven Support
73+
### Shorthand Syntax
6374

64-
Starting in Lucee 6.2, Maven support has been added to `this.javasettings`, allowing you to define Maven dependencies directly. Maven manages libraries by automatically handling their retrieval and versioning.
75+
Use `group:artifact:version` strings for brevity:
6576

6677
```cfml
6778
this.javasettings.maven = [
68-
{
69-
"groupId": "org.quartz-scheduler",
70-
"artifactId": "quartz",
71-
"version": "2.3.2"
72-
},
73-
{
74-
"groupId": "commons-beanutils",
75-
"artifactId": "commons-beanutils",
76-
"version": "1.9.4"
77-
}
79+
"org.quartz-scheduler:quartz:2.3.2",
80+
"commons-beanutils:commons-beanutils:1.9.4"
7881
];
7982
```
8083

81-
If the `version` is omitted, Lucee will use the latest available version of the Maven artifact.
84+
Omit `version` for latest (e.g., `"commons-beanutils:commons-beanutils"`).
8285

83-
## Java Settings in `.CFConfig.json`
86+
## Load Paths
8487

85-
You can also define Java settings globally for all applications through the `.CFConfig.json` configuration file. This is especially useful when managing Docker environments.
88+
Point to local JAR files or directories containing JARs:
8689

87-
```json
88-
{
89-
"javasettings": {
90-
"maven": [
91-
{
92-
"groupId": "org.quartz-scheduler",
93-
"artifactId": "quartz",
94-
"version": "2.3.2"
95-
},
96-
{
97-
"groupId": "commons-beanutils",
98-
"artifactId": "commons-beanutils",
99-
"version": "1.9.4"
100-
}
101-
],
102-
"loadPaths": [
103-
"/my/local/path/to/whatever/lib/",
104-
"/my/local/path/to/whatever/lib/xyz.jar"
105-
],
106-
"bundlePaths": [
107-
"/my/local/path/to/whatever/lib/",
108-
"/my/local/path/to/whatever/lib/xyz.jar"
109-
]
110-
}
111-
}
90+
```cfml
91+
this.javasettings.loadPaths = [
92+
"/my/local/path/to/whatever/lib/",
93+
"/my/local/path/to/whatever/lib/xyz.jar"
94+
];
11295
```
11396

114-
### Using Java Settings in `Application.cfc`
115-
116-
In your [[tag-Application]], you can define or override Java settings specific to your application.
97+
## Bundle Paths
11798

118-
This is the primary way to configure Java dependencies at the application level.
99+
For OSGi bundles (modular JARs with explicit dependency metadata). Most applications don't need this - use `loadPaths` for regular JARs:
119100

120101
```cfml
121-
this.javasettings = {
122-
"maven": [
123-
{
124-
"groupid": "commons-beanutils",
125-
"artifactid": "commons-beanutils",
126-
"version": "1.9.4"
127-
}
128-
],
129-
"loadPaths": [
130-
"/my/local/path/to/libs/",
131-
"/my/local/path/to/libs/example.jar"
132-
],
133-
"bundlePaths": [
134-
"/my/local/path/to/bundles/"
135-
],
136-
"reloadOnChange": true,
137-
"watchInterval": 60,
138-
"watchExtensions": ["jar", "class"]
139-
};
102+
this.javasettings.bundlePaths = [
103+
"/my/local/path/to/whatever/lib/",
104+
"/my/local/path/to/whatever/lib/xyz.jar"
105+
];
140106
```
141107

142-
This method gives you flexibility to handle specific Java dependencies within each application, ensuring that classloaders are configured per application.
143-
144-
### Using Java Settings in a Component
108+
## Component-Level
145109

146-
Maven dependencies and other Java settings can also be defined as part of a [[tag-component]].
147-
148-
This ensures that only the classes loaded within that component will use the specified settings, isolating it from the rest of the application and avoiding conflicts.
110+
Isolate libraries to a single component. The attribute value must be a JSON string:
149111

150112
```cfml
151-
component javaSettings = '{
152-
"maven": [
153-
{
154-
"groupId": "commons-beanutils",
155-
"artifactId": "commons-beanutils",
156-
"version": "1.9.4"
157-
}
158-
]
113+
component javasettings='{
114+
"maven": ["commons-beanutils:commons-beanutils:1.9.4"]
159115
}' {
160-
// Component logic
116+
// Only this component has access to beanutils
161117
}
162118
```
163119

164-
This method is useful for encapsulating components with specific versions of libraries, preventing conflicts with other parts of the application.
120+
See [[java-libraries]] for more on using Maven dependencies in components.
165121

166-
### Using Java Settings in `createObject`
122+
## createObject
167123

168-
Java settings can also be defined dynamically when creating Java objects using the [[function-createObject]] function.
124+
Load a library inline when creating a Java object:
169125

170126
```cfml
171-
createObject("java", "org.apache.commons.beanutils.BeanUtils", {
172-
"maven": [
173-
{
174-
"groupId": "commons-beanutils",
175-
"artifactId": "commons-beanutils",
176-
"version": "1.9.4"
177-
}
178-
]
127+
obj = createObject( "java", "org.apache.commons.beanutils.BeanUtils", {
128+
"maven": ["commons-beanutils:commons-beanutils:1.9.4"]
179129
});
180130
```
181131

182-
This approach provides the flexibility to load Java classes and dependencies at runtime.
183-
184-
## Classloader Recycling
185-
186-
Lucee automatically generates a unique hash based on the defined Java settings and maintains a pool of corresponding classloaders. This means that classloaders are reused efficiently, reducing resource consumption and improving performance.
187-
188-
## Reload On Change
189-
190-
The setting `this.javasettings.reloadOnChange` indicates whether to reload updated classes and JARs dynamically, without restarting Lucee. The default value is `false`.
191-
192-
```cfml
193-
this.javasettings.reloadOnChange = false;
194-
```
195-
196-
## Watch Interval
132+
## .CFConfig.json
197133

198-
The setting `this.javasettings.watchInterval` defines the interval in seconds that Lucee looks for changes. The default value is `60`.
134+
Server-wide settings in your CFConfig file:
199135

200-
```cfml
201-
this.javasettings.watchInterval = 60;
136+
```json
137+
{
138+
"javasettings": {
139+
"maven": [
140+
"org.quartz-scheduler:quartz:2.3.2",
141+
"commons-beanutils:commons-beanutils:1.9.4"
142+
],
143+
"loadPaths": [
144+
"/my/local/path/to/libs/"
145+
]
146+
}
147+
}
202148
```
203149

204-
## Watch Extensions
205-
206-
The setting `this.javasettings.watchExtensions` defines the extensions Lucee looks for when you list a directory with `loadPaths` or `bundlePaths`. The default value is `["jar", "class"]`.
207-
208-
```cfml
209-
this.javasettings.watchExtensions = ["jar", "class"];
210-
```
150+
## Additional Settings
211151

212-
## Conclusion
152+
- `reloadOnChange` - Reload updated classes/JARs without restart (default: `false`)
153+
- `watchInterval` - Seconds between change checks (default: `60`)
154+
- `watchExtensions` - Extensions to watch (default: `["jar", "class"]`)
213155

214-
With the introduction of Maven support and the ability to define Java settings in multiple contexts such as `.CFConfig.json`, `Application.cfc`, components, and `createObject`, Lucee provides enhanced flexibility for integrating and managing Java libraries. These features help avoid conflicts and ensure that your Java dependencies are managed efficiently across various parts of your application.
156+
Lucee pools classloaders based on settings hash for efficient reuse.

0 commit comments

Comments
 (0)