Java-caller NPM

Java Caller for Node.js

Lightweight cross-platform javascript module to easily call java commands from Node.js sources.

Automatically installs required Java version if not present on the system
Compliant with JDK & JRE from 8 to 20
Uses node spawn method to perform the call

There are two ways to use java-caller:

module: Manually call JavaCaller in your custom JS/TS code (example project)
CLI: Just define a java-caller-config.json and you can deliver your java executables as your own NPM packages ! (example project, which can be used as starter kit)

Installation

npm install java-caller --save

Usage

const JavaCaller = require('java-caller');
const java = new JavaCaller(JAVA_CALLER_OPTIONS);
const {status, stdout, stderr} = java.run(JAVA_ARGUMENTS,JAVA_CALLER_RUN_OPTIONS);

JAVA_CALLER_OPTIONS

Parameter	Description	Default value	Example
jar	Path to executable jar file		`"myfolder/myjar.jar"`
classPath	If jar parameter is not set, classpath to useUse `:` as separator (it will be converted if runned on Windows), or use a string array.	`.` (current folder)	`"java/myJar.jar:java/myOtherJar.jar"`
useAbsoluteClassPaths	Set to true if classpaths should not be based on the rootPath	`false`	`true`
mainClass	If classPath set, main class to call		`"com.example.MyClass"`
rootPath	If classPath elements are not relative to the current folder, you can define a root path. You may use `__dirname` if you classes / jars are in your module folder	`.` (current folder)	`"/home/my/folder/containing/jars"`
minimumJavaVersion	Minimum java version to be used to call java command. If the java version found on machine is lower, java-caller will try to install and use the appropriate one	`8`	`11`
maximumJavaVersion	Maximum java version to be used to call java command. If the java version found on machine is upper, java-caller will try to install and use the appropriate one Can be equal to minimumJavaVersion		`10`
javaType	jre or jdk (if not defined and installation is required, jre will be installed)		`"jre"`
additionalJavaArgs	Additional parameters for JVM that will be added in every JavaCaller instance runs		`["-Xms256m","-Xmx2048m"]`
javaExecutable	You can force to use a defined java executable, instead of letting java-caller find/install one. Can also be defined with env var `JAVA_CALLER_JAVA_EXECUTABLE`		`"/home/some-java-version/bin/java.exe"`

JAVA_ARGUMENTS

The list of arguments can contain both arguments types together:

Java arguments (-X*, -D*). ex: "-Xms256m", "-Xmx2048m"
Main class arguments (sent to public static void main method). ex: "--someflag" , "--someflagwithvalue myVal" , "-c"

Example: ["-Xms256m", "--someflagwithvalue myVal", "-c"]

JAVA_CALLER_RUN_OPTIONS

Parameter	Description	Default	Example
detached	If set to true, node will node wait for the java command to be completed.In that case, `childJavaProcess` property will be returned, but `stdout` and `stderr` may be empty, except if an error is triggered at command execution	`false`	`true`
stdoutEncoding	Adds control on spawn process stdout	`utf8`	`ucs2`
waitForErrorMs	If detached is true, number of milliseconds to wait to detect an error before exiting JavaCaller run	`500`	`2000`
cwd	You can override cwd of spawn called by JavaCaller runner	`process.cwd()`	`some/other/cwd/folder`
javaArgs	List of arguments for JVM only, not the JAR or the class	`[]`	`['--add-opens=java.base/java.lang=ALL-UNNAMED']`
windowsVerbatimArguments	No quoting or escaping of arguments is done on Windows. Ignored on Unix. This is set to true automatically when shell is specified and is CMD.	`true`	`false`
windowless	If windowless is true, JavaCaller calls javaw instead of java to not create any windows, useful when using detached on Windows. Ignored on Unix.	false	true

Examples

Call a class located in classpath

const java = new JavaCaller({
    classPath: 'test/java/dist',
    mainClass: 'com.nvuillam.javacaller.JavaCallerTester'
});
const { status, stdout, stderr } = await java.run();

Call a class with multiple folders in the classPath

const java = new JavaCaller({
    classPath: ['C:\\pathA\\test\\java\\dist', 'C:\\pathB\\test\\java\\dist'],
    mainClass: 'com.nvuillam.javacaller.JavaCallerTester'
});
const { status, stdout, stderr } = await java.run();

Call a class located in classpath with java and custom arguments

const java = new JavaCaller({
    classPath: 'test/java/dist',
    mainClass: 'com.nvuillam.javacaller.JavaCallerTester'
});
const { status, stdout, stderr } = await java.run(['-Xms256m', '-Xmx2048m', '--customarg nico']);

Call a class in jar located in classpath

const java = new JavaCaller({
    classPath: 'test/java/jar/JavaCallerTester.jar',
    mainClass: 'com.nvuillam.javacaller.JavaCallerTester'
});
const { status, stdout, stderr } = await java.run();

Call a runnable jar

const java = new JavaCaller({
    jar: 'test/java/jar/JavaCallerTesterRunnable.jar',
});
const { status, stdout, stderr } = await java.run();

Call a detached java process

const java = new JavaCaller({
    classPath: 'test/java/dist',
    mainClass: 'com.nvuillam.javacaller.JavaCallerTester'
});
const { status, stdout, stderr, childJavaProcess } = await java.run(['--sleep'], { detached: true });

// Kill later the java process if necessary
childJavaProcess.kill('SIGINT');

Call a windowless java process

const java = new JavaCaller({
    classPath: 'test/java/dist',
    mainClass: 'com.nvuillam.javacaller.JavaCallerTester'
});
const { status, stdout, stderr } = await java.run(['--sleep'], { windowless: true });

You can see more examples in test methods

TROUBLESHOOTING

Set environment variable DEBUG=java-caller before calling your code using java-caller module, and you will see the java commands executed.

Example debug log:

java-caller Found Java version 1.80131 +1s
java-caller Java command: java -Xms256m -Xmx2048m -cp C:\Work\gitPerso\node-java-caller\test\java\dist com.nvuillam.javacaller.JavaCallerTester -customarg nico +1ms