{"id":15649032,"url":"https://github.com/nvuillam/node-java-caller","last_synced_at":"2025-04-13T07:50:43.839Z","repository":{"id":46283897,"uuid":"286200649","full_name":"nvuillam/node-java-caller","owner":"nvuillam","description":"Lightweight cross-platform javascript module to easily call java from node sources. Automatically install java if not present","archived":false,"fork":false,"pushed_at":"2025-04-13T00:52:18.000Z","size":557,"stargazers_count":41,"open_issues_count":9,"forks_count":11,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-13T01:28:15.560Z","etag":null,"topics":["java","javascript","node","spawn"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nvuillam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["nvuillam"]}},"created_at":"2020-08-09T08:51:14.000Z","updated_at":"2025-04-03T03:18:08.000Z","dependencies_parsed_at":"2023-01-23T11:15:57.519Z","dependency_job_id":"2f5ebc0c-7acf-47a1-b7fa-a1df8d6a4d77","html_url":"https://github.com/nvuillam/node-java-caller","commit_stats":{"total_commits":126,"total_committers":11,"mean_commits":"11.454545454545455","dds":0.4444444444444444,"last_synced_commit":"1de8616a843045c56cb57f34703a637fc7a23c77"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvuillam%2Fnode-java-caller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvuillam%2Fnode-java-caller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvuillam%2Fnode-java-caller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvuillam%2Fnode-java-caller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nvuillam","download_url":"https://codeload.github.com/nvuillam/node-java-caller/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248681494,"owners_count":21144700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","javascript","node","spawn"],"created_at":"2024-10-03T12:27:29.651Z","updated_at":"2025-04-13T07:50:43.813Z","avatar_url":"https://github.com/nvuillam.png","language":"JavaScript","funding_links":["https://github.com/sponsors/nvuillam"],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable MD033 --\u003e\n# Java Caller for Node.js\n\n[![Version](https://img.shields.io/npm/v/java-caller.svg)](https://www.npmjs.com/package/java-caller)\n[![Downloads/week](https://img.shields.io/npm/dw/java-caller.svg)](https://npmjs.org/package/java-caller)\n[![Downloads/total](https://img.shields.io/npm/dt/java-caller.svg)](https://npmjs.org/package/java-caller)\u003c!-- gh-dependents-info-used-by-start --\u003e\n[![Generated by github-dependents-info](https://img.shields.io/static/v1?label=Used%20by\u0026message=106\u0026color=informational\u0026logo=slickpic)](https://github.com/nvuillam/node-java-caller/blob/main/docs/github-dependents-info.md)\u003c!-- gh-dependents-info-used-by-end --\u003e\n[![CircleCI](https://circleci.com/gh/nvuillam/node-java-caller/tree/master.svg?style=shield)](https://circleci.com/gh/nvuillam/node-java-caller/tree/master)\n[![Mega-Linter](https://github.com/nvuillam/node-java-caller/workflows/Mega-Linter/badge.svg)](https://github.com/nvuillam/mega-linter#readme)\n[![codecov](https://codecov.io/gh/nvuillam/node-java-caller/branch/master/graph/badge.svg)](https://codecov.io/gh/nvuillam/node-java-caller)\n[![GitHub contributors](https://img.shields.io/github/contributors/nvuillam/node-java-caller.svg)](https://gitHub.com/nvuillam/node-java-caller/graphs/contributors/)\n[![GitHub stars](https://img.shields.io/github/stars/nvuillam/node-java-caller?label=Star\u0026maxAge=2592000)](https://GitHub.com/nvuillam/node-java-caller/stargazers/)\n[![License](https://img.shields.io/npm/l/java-caller.svg)](https://github.com/nvuillam/node-java-caller/blob/master/LICENSE)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)\n\nLightweight cross-platform javascript module to **easily call java commands from Node.js sources**.\n\n- **Automatically installs required Java version** if not present on the system\n- Compliant with **JDK \u0026 JRE** from **8 to 21**\n- Uses node [spawn](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) method to perform the call\n\nThere are two ways to use java-caller:\n\n- **module**: Manually call JavaCaller in your custom JS/TS code ([example project](https://github.com/nvuillam/node-java-caller/tree/master/examples/module_app))\n- **CLI**: Just define a java-caller-config.json and you can deliver your java executables as your own NPM packages ! ([example project](https://github.com/nvuillam/node-java-caller/tree/master/examples/cli_app), which can be used as starter kit)\n\n## Installation\n\n```shell\nnpm install java-caller --save\n```\n\n## Usage\n\n```javascript\nconst JavaCaller = require('java-caller');\nconst java = new JavaCaller(JAVA_CALLER_OPTIONS);\nconst {status, stdout, stderr} = await java.run(JAVA_ARGUMENTS,JAVA_CALLER_RUN_OPTIONS);\n```\n\n### JAVA_CALLER_OPTIONS\n\n| Parameter             | Description                                                                                                                                                                                                    | Default value        | Example                                  |\n| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ---------------------------------------- |\n| jar                   | Path to executable jar file                                                                                                                                                                                    |                      | `\"myfolder/myjar.jar\"`                   |\n| classPath             | If jar parameter is not set, classpath to use\u003cbr/\u003eUse `:` as separator (it will be converted if runned on Windows), or use a string array.                                                                     | `.` (current folder) | `\"java/myJar.jar:java/myOtherJar.jar\"`   |\n| useAbsoluteClassPaths | Set to true if classpaths should not be based on the rootPath                                                                                                                                                  | `false`              | `true`                                   |\n| mainClass             | If classPath set, main class to call                                                                                                                                                                           |                      | `\"com.example.MyClass\"`                  |\n| rootPath              | If classPath elements are not relative to the current folder, you can define a root path. \u003cbr/\u003e You may use `__dirname` if you classes / jars are in your module folder                                        | `.` (current folder) | `\"/home/my/folder/containing/jars\"`      |\n| minimumJavaVersion    | Minimum java version to be used to call java command.\u003cbr/\u003e If the java version found on machine is lower, java-caller will try to install and use the appropriate one                                          | `8`                  | `11`                                     |\n| maximumJavaVersion    | Maximum java version to be used to call java command.\u003cbr/\u003e If the java version found on machine is upper, java-caller will try to install and use the appropriate one \u003cbr/\u003e Can be equal to minimumJavaVersion |                      | `10`                                     |\n| javaType              | jre or jdk (if not defined and installation is required, jre will be installed)                                                                                                                                |                      | `\"jre\"`                                  |\n| additionalJavaArgs    | Additional parameters for JVM that will be added in every JavaCaller instance runs                                                                                                                             |                      | `[\"-Xms256m\",\"-Xmx2048m\"]`               |\n| 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\"` |\n\n### JAVA_ARGUMENTS\n\nThe list of arguments can contain both arguments types together:\n\n- Java arguments (**-X***, **-D***). ex: `\"-Xms256m\"`, `\"-Xmx2048m\"`\n- Main class arguments (sent to `public static void main method`). ex: `\"--someflag\"` , `\"--someflagwithvalue myVal\"` , `\"-c\"`\n\nExample: `[\"-Xms256m\", \"--someflagwithvalue myVal\", \"-c\"]`\n\n### JAVA_CALLER_RUN_OPTIONS\n\n| Parameter | Description | Default | Example |\n|-----------|-------------|---------|---------|\n| [detached](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) | If set to true, node will node wait for the java command to be completed.\u003cbr/\u003eIn 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`\n| [stdoutEncoding](https://nodejs.org/api/stream.html#readablesetencodingencoding) | Adds control on spawn process stdout | `utf8` | `ucs2` |\n| waitForErrorMs | If detached is true, number of milliseconds to wait to detect an error before exiting JavaCaller run   | `500` | `2000` |\n| [cwd](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) | You can override cwd of spawn called by JavaCaller runner | `process.cwd()` | `some/other/cwd/folder` |\n| javaArgs | List of arguments for JVM only, not the JAR or the class | `[]` | `['--add-opens=java.base/java.lang=ALL-UNNAMED']` |\n| [windowsVerbatimArguments](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) | 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` |\n| [windowless](https://docs.oracle.com/en/java/javase/17/docs/specs/man/java.html#:~:text=main()%20method.-,javaw,information%20if%20a%20launch%20fails.) | 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\n\n## Examples\n\nCall a class located in classpath\n\n```javascript\nconst java = new JavaCaller({\n    classPath: 'test/java/dist',\n    mainClass: 'com.nvuillam.javacaller.JavaCallerTester'\n});\nconst { status, stdout, stderr } = await java.run();\n```\n\nCall a class with multiple folders in the classPath\n\n```javascript\nconst java = new JavaCaller({\n    classPath: ['C:\\\\pathA\\\\test\\\\java\\\\dist', 'C:\\\\pathB\\\\test\\\\java\\\\dist'],\n    mainClass: 'com.nvuillam.javacaller.JavaCallerTester'\n});\nconst { status, stdout, stderr } = await java.run();\n```\n\nCall a class located in classpath with java and custom arguments\n\n```javascript\nconst java = new JavaCaller({\n    classPath: 'test/java/dist',\n    mainClass: 'com.nvuillam.javacaller.JavaCallerTester'\n});\nconst { status, stdout, stderr } = await java.run(['-Xms256m', '-Xmx2048m', '--customarg nico']);\n```\n\nCall a class in jar located in classpath\n\n```javascript\nconst java = new JavaCaller({\n    classPath: 'test/java/jar/JavaCallerTester.jar',\n    mainClass: 'com.nvuillam.javacaller.JavaCallerTester'\n});\nconst { status, stdout, stderr } = await java.run();\n```\n\nCall a runnable jar\n\n```javascript\nconst java = new JavaCaller({\n    jar: 'test/java/jar/JavaCallerTesterRunnable.jar',\n});\nconst { status, stdout, stderr } = await java.run();\n```\n\nCall a detached java process\n\n```javascript\nconst java = new JavaCaller({\n    classPath: 'test/java/dist',\n    mainClass: 'com.nvuillam.javacaller.JavaCallerTester'\n});\nconst { status, stdout, stderr, childJavaProcess } = await java.run(['--sleep'], { detached: true });\n\n// Kill later the java process if necessary\nchildJavaProcess.kill('SIGINT');\n```\n\nCall a windowless java process\n\n```javascript\nconst java = new JavaCaller({\n    classPath: 'test/java/dist',\n    mainClass: 'com.nvuillam.javacaller.JavaCallerTester'\n});\nconst { status, stdout, stderr } = await java.run(['--sleep'], { windowless: true });\n```\n\nYou can see **more examples in** [**test methods**](https://github.com/nvuillam/node-java-caller/blob/master/test/java-caller.test.js)\n\n## TROUBLESHOOTING\n\nSet environment variable `DEBUG=java-caller` before calling your code using java-caller module, and you will see the java commands executed.\n\nExample debug log:\n\n```shell\njava-caller Found Java version 1.80131 +1s\njava-caller Java command: java -Xms256m -Xmx2048m -cp C:\\Work\\gitPerso\\node-java-caller\\test\\java\\dist com.nvuillam.javacaller.JavaCallerTester -customarg nico +1ms\n```\n\n## CONTRIBUTE\n\nContributions are very welcome !\n\nPlease follow [Contribution instructions](CONTRIBUTING.md)\n\n## RELEASE NOTES\n\nSee complete [CHANGELOG](CHANGELOG.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnvuillam%2Fnode-java-caller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnvuillam%2Fnode-java-caller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnvuillam%2Fnode-java-caller/lists"}