js4j 0.1.1 → 0.1.3

package/README.md

@@ -35,6 +35,9 @@ A Node.js implementation of [py4j](https://www.py4j.org/) — a bridge between J
     - [ProxyPool](#proxypool)
   - [launchGateway](#launchgateway)
   - [Errors](#errors)
+- [Known Limitations](#known-limitations)
+  - [Varargs methods](#varargs-methods)
+  - [Fields vs methods](#fields-vs-methods)
 - [TypeScript](#typescript)
 - [Credits](#credits)
 
@@ -643,6 +646,70 @@ try {
 
 ---
 
+## Known Limitations
+
+### Varargs methods
+
+Java compiles `T... args` varargs parameters to `T[]` in bytecode. When js4j forwards multiple bare JavaScript arguments, the Java reflection engine looks for a method with that exact number of parameters and fails with "method not found".
+
+**Rule: pack all varargs arguments into a Java array created with `gateway.newArray()`.**
+
+```js
+// Java signature: Paths.get(String first, String... more)
+
+// WRONG — Java looks for get(String, String, String), which doesn't exist
+const path = await Paths.get('/tmp', 'subdir', 'file.txt');
+
+// CORRECT — single-argument call (empty varargs), works fine
+const path = await Paths.get('/tmp/subdir/file.txt');
+
+// CORRECT — varargs passed as a String array
+const more = await gateway.newArray(gateway.jvm.java.lang.String, 2);
+await more.set(0, 'subdir');
+await more.set(1, 'file.txt');
+const path = await Paths.get('/tmp', more);
+```
+
+The same pattern applies to any varargs method:
+
+```js
+// Java signature: String.format(String format, Object... args)
+const fmtArgs = await gateway.newArray(gateway.jvm.java.lang.Object, 2);
+await fmtArgs.set(0, 'World');
+await fmtArgs.set(1, 42);
+const result = await gateway.jvm.java.lang.String.format('Hello %s, you are number %d', fmtArgs);
+```
+
+For simple cases it is often easier to avoid varargs entirely by building the value in JavaScript first:
+
+```js
+// Build the path string in JS rather than using multi-part Paths.get
+const path = await Paths.get(`${baseDir}/subdir/file.txt`);
+```
+
+### Fields vs methods
+
+Property access on a `JavaObject` or `JavaClass` is reserved for **method calls**. Directly reading or writing a public Java field with `obj.fieldName` or `obj.fieldName = value` will only affect the local JavaScript proxy object — it will not communicate with the JVM.
+
+Always use `getField` / `setField`:
+
+```js
+// WRONG — only sets a JS property, Java never sees it
+obj.count = 10;
+
+// CORRECT
+await gateway.setField(obj, 'count', 10);
+const count = await gateway.getField(obj, 'count');
+```
+
+This applies to static fields too:
+
+```js
+const pi = await gateway.getField(gateway.jvm.java.lang.Math, 'PI');
+```
+
+---
+
 ## TypeScript
 
 Full type definitions are included. No `@types/` package is needed.
@@ -698,6 +765,7 @@ await kill();
 | `readyPattern` | `RegExp \| string \| null` | `/GATEWAY_STARTED/` | Pattern matched against stdout to detect when the server is ready. Set to `null` to skip stdout checking and rely only on port polling. |
 | `timeout` | `number` | `30000` | Maximum milliseconds to wait for the server to become ready. |
 | `gatewayOptions` | `GatewayParametersOptions` | `{}` | Extra options forwarded to `GatewayParameters` (e.g. `authToken`). |
+| `killConflict` | `boolean` | `false` | If `true`, detect any process already listening on the target port and kill it before launching. Throws if the port cannot be freed within 5 seconds. |
 
 #### Return value
 

package/index.d.ts

@@ -401,6 +401,12 @@ export interface LaunchGatewayOptions {
   timeout?: number;
   /** Extra options forwarded to GatewayParameters. */
   gatewayOptions?: GatewayParametersOptions;
+  /**
+   * If true, detect any process already listening on the target port and send
+   * it SIGTERM before launching. An error is thrown if the port cannot be
+   * freed within 5 seconds. Default: false.
+   */
+  killConflict?: boolean;
 }
 
 export interface LaunchGatewayResult {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js4j",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "A Node.js implementation of py4j — bridge between JavaScript and Java via the Py4J gateway protocol",
   "main": "index.js",
   "types": "index.d.ts",

package/src/exceptions.js

@@ -33,6 +33,21 @@ class Js4JJavaError extends Js4JError {
     this.javaException = javaException || null;
   }
 
+  /**
+   * Fetch the human-readable Java exception message by calling getMessage()
+   * on the Java Throwable object.  Falls back to the raw protocol payload
+   * (javaExceptionMessage) if the Java call fails or javaException is null.
+   * @returns {Promise<string>}
+   */
+  async getJavaMessage() {
+    if (!this.javaException) return this.javaExceptionMessage || this.message;
+    try {
+      return await this.javaException.getMessage();
+    } catch (_) {
+      return this.javaExceptionMessage || this.message;
+    }
+  }
+
   toString() {
     return `${this.name}: ${this.message}\n  Java exception payload: ${this.javaExceptionMessage}`;
   }

package/src/launcher.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { spawn } = require('child_process');
+const { spawn, execSync } = require('child_process');
 const net = require('net');
 const { JavaGateway, GatewayParameters } = require('./gateway');
 
@@ -20,6 +20,8 @@ const { JavaGateway, GatewayParameters } = require('./gateway');
  *                                                                   and rely only on port polling.
  * @param {number}   [options.timeout=30000]    - Max ms to wait for the server to be ready
  * @param {object}   [options.gatewayOptions]   - Extra options forwarded to GatewayParameters
+ * @param {boolean}  [options.killConflict=false] - If true, detect and kill any process already
+ *                                                  listening on the target port before launching.
  *
  * @returns {Promise<{ process: ChildProcess, gateway: JavaGateway, kill: Function }>}
  *
@@ -47,11 +49,16 @@ async function launchGateway(options = {}) {
     readyPattern = /GATEWAY_STARTED/,
     timeout = 30000,
     gatewayOptions = {},
+    killConflict = false,
   } = options;
 
   if (!classpath) throw new Error('launchGateway: options.classpath is required');
   if (!mainClass) throw new Error('launchGateway: options.mainClass is required');
 
+  if (killConflict) {
+    await _checkAndKillConflict(host, port);
+  }
+
   // Build the java command: java [jvmArgs] -cp <classpath> <mainClass> [args]
   const javaArgs = [...jvmArgs, '-cp', classpath, mainClass, ...args];
 
@@ -83,6 +90,105 @@ async function launchGateway(options = {}) {
 // Internal helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * If something is already listening on host:port, find its PID(s) and kill them,
+ * then wait for the port to become free.
+ */
+async function _checkAndKillConflict(host, port) {
+  const inUse = await _isPortInUse(host, port);
+  if (!inUse) return;
+
+  const pids = _getPidsOnPort(port);
+  if (pids.length === 0) {
+    throw new Error(
+      `launchGateway: port ${port} is already in use but no owning process could be found. ` +
+      `Free the port manually and retry.`
+    );
+  }
+
+  for (const pid of pids) {
+    try {
+      process.kill(pid, 'SIGTERM');
+    } catch (_) {
+      // process may have already exited
+    }
+  }
+
+  await _waitForPortFree(host, port, 5000);
+}
+
+/**
+ * Return true if something is already accepting connections on host:port.
+ */
+function _isPortInUse(host, port) {
+  return new Promise((resolve) => {
+    const sock = new net.Socket();
+    sock.setTimeout(500);
+    sock.on('connect', () => { sock.destroy(); resolve(true); });
+    sock.on('error',   () => { sock.destroy(); resolve(false); });
+    sock.on('timeout', () => { sock.destroy(); resolve(false); });
+    sock.connect(port, host);
+  });
+}
+
+/**
+ * Find the PID(s) of whatever is listening on the given port.
+ * Uses lsof on Linux/macOS and netstat on Windows.
+ * Returns an array of integer PIDs (may be empty if detection fails).
+ */
+function _getPidsOnPort(port) {
+  try {
+    if (process.platform === 'win32') {
+      // netstat -ano lists active connections; parse LISTENING lines for the port
+      const out = execSync(`netstat -ano`, { encoding: 'utf8', stdio: 'pipe' });
+      const pids = new Set();
+      for (const line of out.split('\n')) {
+        // Format: "  TCP  0.0.0.0:25333  0.0.0.0:0  LISTENING  1234"
+        if (!line.includes('LISTENING')) continue;
+        if (!line.includes(`:${port}`)) continue;
+        const parts = line.trim().split(/\s+/);
+        const pid = parseInt(parts[parts.length - 1], 10);
+        if (!isNaN(pid) && pid > 0) pids.add(pid);
+      }
+      return [...pids];
+    } else {
+      // lsof -ti :<port> prints one PID per line
+      const out = execSync(`lsof -ti :${port}`, { encoding: 'utf8', stdio: 'pipe' }).trim();
+      return out
+        .split('\n')
+        .map((s) => parseInt(s.trim(), 10))
+        .filter((n) => !isNaN(n) && n > 0);
+    }
+  } catch (_) {
+    // lsof/netstat not available, or returned non-zero (no matches)
+    return [];
+  }
+}
+
+/**
+ * Poll until nothing is listening on host:port, or reject after timeout ms.
+ */
+function _waitForPortFree(host, port, timeout) {
+  return new Promise((resolve, reject) => {
+    const deadline = Date.now() + timeout;
+    function check() {
+      if (Date.now() > deadline) {
+        reject(new Error(
+          `launchGateway: port ${port} was still occupied after ${timeout}ms`
+        ));
+        return;
+      }
+      const sock = new net.Socket();
+      sock.setTimeout(300);
+      sock.on('connect', () => { sock.destroy(); setTimeout(check, 200); });
+      sock.on('error',   () => { sock.destroy(); resolve(); });
+      sock.on('timeout', () => { sock.destroy(); resolve(); });
+      sock.connect(port, host);
+    }
+    check();
+  });
+}
+
 function _waitForReady(child, host, port, readyPattern, timeout) {
   return new Promise((resolve, reject) => {
     const deadline = setTimeout(() => {