Java Interop

DieselEngine runs on GraalVM, which provides seamless interoperability between JavaScript and Java. You can instantiate Java classes, call static methods, and work with Java collections directly from your scripts.

Java.type()

The primary mechanism for accessing Java classes is Java.type():

const Gson = Java.type('com.google.gson.Gson');
const Random = Java.type('java.util.Random');
const Files = Java.type('java.nio.file.Files');
const Paths = Java.type('java.nio.file.Paths');
const Base64 = Java.type('java.util.Base64');
const ByteArrayInputStream = Java.type('java.io.ByteArrayInputStream');

Once you have a class reference, you can instantiate it or call static methods:

const gson = new Gson();
const json = gson.toJson(someJavaObject);

const random = new Random();
const number = random.nextInt(100);

const path = Paths.get("/tmp/data.txt");
const content = Files.readString(path);

Commonly Used Java Classes

Gson (JSON)

Gson is available for JSON serialization of Java objects. Useful when working with Java objects returned from services:

const Gson = Java.type('com.google.gson.Gson');
const GsonBuilder = Java.type('com.google.gson.GsonBuilder');

// Simple serialization
const gson = new Gson();
const jsonString = gson.toJson(javaObject);

// Pretty printing
const prettyGson = new GsonBuilder().setPrettyPrinting().create();
const pretty = prettyGson.toJson(javaObject);

// Deserialization
const LinkedHashMap = Java.type('java.util.LinkedHashMap');
const parsed = gson.fromJson(jsonString, LinkedHashMap.class);

TIP

For most JSON work, JavaScript's built-in JSON.stringify() and JSON.parse() are simpler and preferred. Use Gson only when you need to serialize/deserialize Java objects that don't convert cleanly.

Random

const Random = Java.type('java.util.Random');
const random = new Random();

const int = random.nextInt(100);       // 0–99
const dbl = random.nextDouble();       // 0.0–1.0
const bool = random.nextBoolean();     // true/false

Files & Paths

const Files = Java.type('java.nio.file.Files');
const Paths = Java.type('java.nio.file.Paths');
const StandardCopyOption = Java.type('java.nio.file.StandardCopyOption');

// Read a file
const path = Paths.get("/tmp/dieselfuse/config.json");
const content = Files.readString(path);

// Write a file
const output = Paths.get("/tmp/dieselfuse/output.txt");
Files.writeString(output, "Hello from DieselEngine");

// Copy a file
Files.copy(source, target, StandardCopyOption.REPLACE_EXISTING);

// Check existence
const exists = Files.exists(Paths.get("/tmp/dieselfuse/data"));

Base64

const Base64 = Java.type('java.util.Base64');

// Encode
const encoded = Base64.getEncoder().encodeToString(byteArray);

// Decode
const decoded = Base64.getDecoder().decode(encodedString);

INFO

The diesel object provides stringToBase64() and base64ToString() convenience methods. Use Java.type for Base64 only when working with byte arrays.

Collections

const ArrayList = Java.type('java.util.ArrayList');
const HashMap = Java.type('java.util.HashMap');
const Arrays = Java.type('java.util.Arrays');

const list = new ArrayList();
list.add("item1");
list.add("item2");
list.size(); // 2

const map = new HashMap();
map.put("key", "value");
map.get("key"); // "value"

Date / Time

const LocalDateTime = Java.type('java.time.LocalDateTime');
const DateTimeFormatter = Java.type('java.time.format.DateTimeFormatter');
const ZoneId = Java.type('java.time.ZoneId');

const now = LocalDateTime.now();
const formatted = now.format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));

Streams

const ByteArrayInputStream = Java.type('java.io.ByteArrayInputStream');
const ByteArrayOutputStream = Java.type('java.io.ByteArrayOutputStream');

// Create an input stream from a string
const bytes = new java.lang.String("hello").getBytes();
const stream = new ByteArrayInputStream(bytes);

Working with Java Arrays

JavaScript arrays and Java arrays are different types. GraalVM handles conversions in many cases, but sometimes you need explicit conversion:

// Create a Java array
const IntArray = Java.type('int[]');
const arr = new IntArray(5);
arr[0] = 10;
arr[1] = 20;

// Convert JS array to Java for API calls
const items = ["a", "b", "c"];
const javaArray = diesel.createArrayOf("text", items);

Accessing DieselEngine Models

You can access DieselEngine's own Java classes for creating model objects:

// Create a Kanban column
const DieselKanbanColumn = Java.type(
  'com.dieselengine.diesel.models.kanban.DieselKanbanColumn'
);
const col = new DieselKanbanColumn();
col.name = "Review";
col.onIdeaAddedNotifyAgent = true;
col.onIdeaAddedSystemPrompt = "Review idea __IDEA_UUID__";

Type Conversion

GraalVM automatically converts between JavaScript and Java types:

JavaScript	Java
string	java.lang.String
number (integer)	int / long / Integer / Long
number (float)	double / Double
boolean	boolean / Boolean
null	null
undefined	null
Array	(not auto-converted — use Java.to())
Object	(accessed as GraalVM proxy)

For explicit conversion:

// JS array to Java List
const list = Java.to(["a", "b", "c"], 'java.util.List');

// JS array to Java String[]
const arr = Java.to(["a", "b", "c"], 'java.lang.String[]');

Best Practices

1. Prefer diesel API methods over raw Java calls when available. They're simpler and handle cleanup.

2. Use JSON.stringify()/JSON.parse() for JSON work. Only use Gson when dealing with complex Java objects.

3. Be careful with Java resources. If you open streams or connections via Java classes, close them in a finally block:

const stream = new ByteArrayInputStream(bytes);
try {
  // use stream
} finally {
  stream.close();
}

4. Watch for type mismatches. When calling Java methods that expect specific types, GraalVM usually handles the conversion, but be explicit with numeric types when needed (e.g., ps.setLong(1, id) vs ps.setInt(1, id)).