js4j 0.1.0 → 0.1.2

package/README.md

@@ -33,7 +33,11 @@ A Node.js implementation of [py4j](https://www.py4j.org/) — a bridge between J
     - [createJavaProxy](#createjavaproxy)
     - [CallbackServer](#callbackserver)
     - [ProxyPool](#proxypool)
+  - [launchGateway](#launchgateway)
   - [Errors](#errors)
+- [Known Limitations](#known-limitations)
+  - [Varargs methods](#varargs-methods)
+  - [Fields vs methods](#fields-vs-methods)
 - [TypeScript](#typescript)
 - [Credits](#credits)
 
@@ -642,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.
@@ -668,6 +736,47 @@ const items: any[] = await list.toArray();
 
 ---
 
+### launchGateway
+
+Spawn a Java process that runs a `GatewayServer` and connect a `JavaGateway` to it automatically. Useful when Node.js is responsible for starting the JVM rather than the other way around.
+
+```js
+const { launchGateway } = require('js4j');
+
+const { gateway, kill } = await launchGateway({
+  classpath: '/usr/share/py4j/py4j.jar:java/build',
+  mainClass: 'com.example.MyApp',
+});
+
+const result = await gateway.entry_point.doSomething();
+await kill();
+```
+
+#### Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `classpath` | `string` | *required* | Java classpath string (e.g. `'py4j.jar:.'`). |
+| `mainClass` | `string` | *required* | Fully-qualified main class to launch. |
+| `host` | `string` | `'127.0.0.1'` | Host to connect to after the process starts. |
+| `port` | `number` | `25333` | Port to connect to. |
+| `jvmArgs` | `string[]` | `[]` | Extra JVM flags (e.g. `['-Xmx512m', '-ea']`). |
+| `args` | `string[]` | `[]` | Arguments passed to the main class. |
+| `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
+
+| Property | Type | Description |
+|---|---|---|
+| `gateway` | `JavaGateway` | A connected `JavaGateway` instance. |
+| `process` | `ChildProcess` | The spawned Java child process. |
+| `kill` | `() => Promise<void>` | Shuts down the gateway and kills the Java process. |
+
+---
+
 ## Running Tests
 
 ```bash

package/index.d.ts

@@ -372,6 +372,68 @@ export declare class CallbackServer {
   readonly proxyPool: ProxyPool;
 }
 
+// ---------------------------------------------------------------------------
+// Launcher
+// ---------------------------------------------------------------------------
+
+import { ChildProcess } from 'child_process';
+
+export interface LaunchGatewayOptions {
+  /** Java classpath (e.g. '/path/to/py4j.jar:.') */
+  classpath: string;
+  /** Fully-qualified main class to launch (e.g. 'com.example.MyApp') */
+  mainClass: string;
+  /** Gateway host. Default: '127.0.0.1' */
+  host?: string;
+  /** Gateway port. Default: 25333 */
+  port?: number;
+  /** Extra JVM flags (e.g. ['-Xmx512m']). Default: [] */
+  jvmArgs?: string[];
+  /** Extra arguments passed to the main class. Default: [] */
+  args?: string[];
+  /**
+   * Pattern to match in process stdout that signals the server is ready.
+   * Set to null to skip stdout checking and rely only on port polling.
+   * Default: /GATEWAY_STARTED/
+   */
+  readyPattern?: RegExp | string | null;
+  /** Maximum milliseconds to wait for the server to become ready. Default: 30000 */
+  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 {
+  /** The spawned Java child process. */
+  process: ChildProcess;
+  /** A connected JavaGateway instance. */
+  gateway: JavaGateway;
+  /**
+   * Shut down the gateway and kill the Java process.
+   * Equivalent to calling `gateway.shutdown()` then `process.kill()`.
+   */
+  kill: () => Promise<void>;
+}
+
+/**
+ * Spawn a Java GatewayServer process and connect a JavaGateway to it.
+ *
+ * @example
+ * const { gateway, kill } = await launchGateway({
+ *   classpath: '/usr/share/py4j/py4j.jar:java/build',
+ *   mainClass: 'com.example.MyApp',
+ * });
+ * const result = await gateway.entry_point.doSomething();
+ * await kill();
+ */
+export declare function launchGateway(options: LaunchGatewayOptions): Promise<LaunchGatewayResult>;
+
 // ---------------------------------------------------------------------------
 // Factory functions
 // ---------------------------------------------------------------------------

package/index.js

@@ -40,6 +40,7 @@ const {
   Js4JAuthenticationError,
 } = require('./src/exceptions');
 const protocol = require('./src/protocol');
+const { launchGateway } = require('./src/launcher');
 
 module.exports = {
   // Main gateway classes
@@ -73,6 +74,9 @@ module.exports = {
   Js4JNetworkError,
   Js4JAuthenticationError,
 
+  // Launcher
+  launchGateway,
+
   // Low-level protocol (for advanced use)
   protocol,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js4j",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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/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(() => {