js4j 0.1.0

package/java/TestEntryPoint.java

@@ -0,0 +1,262 @@
+import java.util.*;
+import py4j.GatewayServer;
+
+/**
+ * TestEntryPoint — the Java-side entry point object exposed to both py4j and js4j clients.
+ *
+ * All methods here are exercised by both the Python and JavaScript comparison tests.
+ * Results must be identical between the two client implementations.
+ */
+public class TestEntryPoint {
+
+    // ------------------------------------------------------------------
+    // Arithmetic
+    // ------------------------------------------------------------------
+
+    public int add(int a, int b) {
+        return a + b;
+    }
+
+    public double addDoubles(double a, double b) {
+        return a + b;
+    }
+
+    public long addLongs(long a, long b) {
+        return a + b;
+    }
+
+    public int multiply(int a, int b) {
+        return a * b;
+    }
+
+    public double divide(double a, double b) {
+        return a / b;
+    }
+
+    // ------------------------------------------------------------------
+    // Strings
+    // ------------------------------------------------------------------
+
+    public String greet(String name) {
+        return "Hello, " + name + "!";
+    }
+
+    public String concatenate(String a, String b) {
+        return a + b;
+    }
+
+    public int stringLength(String s) {
+        return s.length();
+    }
+
+    public String toUpperCase(String s) {
+        return s.toUpperCase();
+    }
+
+    public boolean containsSubstring(String haystack, String needle) {
+        return haystack.contains(needle);
+    }
+
+    public String repeatString(String s, int times) {
+        StringBuilder sb = new StringBuilder();
+        for (int i = 0; i < times; i++) sb.append(s);
+        return sb.toString();
+    }
+
+    // ------------------------------------------------------------------
+    // Booleans
+    // ------------------------------------------------------------------
+
+    public boolean andBool(boolean a, boolean b) {
+        return a && b;
+    }
+
+    public boolean orBool(boolean a, boolean b) {
+        return a || b;
+    }
+
+    public boolean notBool(boolean a) {
+        return !a;
+    }
+
+    // ------------------------------------------------------------------
+    // Null handling
+    // ------------------------------------------------------------------
+
+    public String maybeNull(boolean returnNull) {
+        return returnNull ? null : "not null";
+    }
+
+    public boolean isNull(Object obj) {
+        return obj == null;
+    }
+
+    // ------------------------------------------------------------------
+    // Collections — returns wrapped Java collections
+    // ------------------------------------------------------------------
+
+    public List<String> getStringList() {
+        List<String> list = new ArrayList<>();
+        list.add("alpha");
+        list.add("beta");
+        list.add("gamma");
+        return list;
+    }
+
+    public List<Integer> getIntList() {
+        List<Integer> list = new ArrayList<>();
+        list.add(1);
+        list.add(2);
+        list.add(3);
+        list.add(4);
+        list.add(5);
+        return list;
+    }
+
+    public Set<String> getStringSet() {
+        Set<String> set = new LinkedHashSet<>();
+        set.add("one");
+        set.add("two");
+        set.add("three");
+        return set;
+    }
+
+    public Map<String, Integer> getStringIntMap() {
+        Map<String, Integer> map = new LinkedHashMap<>();
+        map.put("a", 1);
+        map.put("b", 2);
+        map.put("c", 3);
+        return map;
+    }
+
+    public int sumList(List<Integer> list) {
+        int total = 0;
+        for (int v : list) total += v;
+        return total;
+    }
+
+    public int listSize(List<?> list) {
+        return list.size();
+    }
+
+    // ------------------------------------------------------------------
+    // Arrays
+    // ------------------------------------------------------------------
+
+    public int[] getIntArray() {
+        return new int[]{10, 20, 30, 40, 50};
+    }
+
+    public String[] getStringArray() {
+        return new String[]{"x", "y", "z"};
+    }
+
+    public int sumArray(int[] arr) {
+        int total = 0;
+        for (int v : arr) total += v;
+        return total;
+    }
+
+    // ------------------------------------------------------------------
+    // Exceptions
+    // ------------------------------------------------------------------
+
+    public void throwException(String message) {
+        throw new RuntimeException(message);
+    }
+
+    public int divideInts(int a, int b) {
+        return a / b;  // throws ArithmeticException on b=0
+    }
+
+    // ------------------------------------------------------------------
+    // Object creation (returns instances of inner classes)
+    // ------------------------------------------------------------------
+
+    public Counter createCounter(int initial) {
+        return new Counter(initial);
+    }
+
+    public static class Counter {
+        private int value;
+
+        public Counter(int initial) {
+            this.value = initial;
+        }
+
+        public void increment() { value++; }
+        public void decrement() { value--; }
+        public void add(int n) { value += n; }
+        public int getValue() { return value; }
+        public void reset() { value = 0; }
+
+        @Override
+        public String toString() {
+            return "Counter(" + value + ")";
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // StringBuilder (tests creating Java objects from the client side)
+    // ------------------------------------------------------------------
+
+    public String buildString(String initial, String[] parts) {
+        StringBuilder sb = new StringBuilder(initial);
+        for (String p : parts) sb.append(p);
+        return sb.toString();
+    }
+
+    // ------------------------------------------------------------------
+    // Type round-trips (verify encoding/decoding symmetry)
+    // ------------------------------------------------------------------
+
+    public int echoInt(int v) { return v; }
+    public long echoLong(long v) { return v; }
+    public double echoDouble(double v) { return v; }
+    public boolean echoBool(boolean v) { return v; }
+    public String echoString(String v) { return v; }
+    public byte[] echoBytes(byte[] v) { return v; }
+
+    // ------------------------------------------------------------------
+    // Varargs
+    // ------------------------------------------------------------------
+
+    public int sumVarargs(int... values) {
+        int total = 0;
+        for (int v : values) total += v;
+        return total;
+    }
+
+    public String joinStrings(String sep, String... parts) {
+        return String.join(sep, parts);
+    }
+
+    // ------------------------------------------------------------------
+    // Static access demo (via jvm namespace)
+    // ------------------------------------------------------------------
+
+    // These are tested via gateway.jvm.java.lang.Math.abs(-5) etc.
+    // Nothing needed here; tests exercise the JVM directly.
+
+    // ------------------------------------------------------------------
+    // Main — starts the GatewayServer
+    // ------------------------------------------------------------------
+
+    public static void main(String[] args) throws Exception {
+        int port = args.length > 0 ? Integer.parseInt(args[0]) : 25333;
+        TestEntryPoint entryPoint = new TestEntryPoint();
+        GatewayServer server = new GatewayServer(entryPoint, port);
+        server.start();
+        // Signal readiness to the test harness
+        System.out.println("GATEWAY_STARTED:" + server.getListeningPort());
+        System.out.flush();
+
+        // Keep alive until stdin is closed (test harness closes it on teardown)
+        try {
+            while (System.in.read() != -1) {}
+        } catch (Exception e) {
+            // ignore
+        }
+        server.shutdown();
+    }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "js4j",
+  "version": "0.1.0",
+  "description": "A Node.js implementation of py4j — bridge between JavaScript and Java via the Py4J gateway protocol",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "test": "jest --testPathPattern='tests/(unit|integration)' --forceExit",
+    "test:unit": "jest --testPathPattern='tests/unit' --forceExit",
+    "test:integration": "jest --testPathPattern='tests/integration' --forceExit --runInBand",
+    "test:comparison": "node tests/comparison/run_comparison.js",
+    "test:all": "npm test && npm run test:comparison"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/theo-kim/js4j"
+  },
+  "keywords": ["java", "bridge", "py4j", "jvm", "gateway"],
+  "author": "Theodore Kim",
+  "license": "MIT",
+  "dependencies": {},
+  "devDependencies": {
+    "jest": "^29.0.0"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "testTimeout": 30000
+  }
+}

package/src/callbackServer.js

@@ -0,0 +1,269 @@
+'use strict';
+
+const net = require('net');
+const { EventEmitter } = require('events');
+const { Js4JNetworkError, Js4JError } = require('./exceptions');
+const {
+  CALL_COMMAND_NAME,
+  SUCCESS,
+  ERROR,
+  END,
+  END_COMMAND_PART,
+  NULL_TYPE,
+  VOID_TYPE,
+  encodeCommandPart,
+  decodeReturnValue,
+  decodeTypedValue,
+} = require('./protocol');
+
+/**
+ * A pool of JS objects that are exposed to Java as "Python proxies".
+ * When a JS object is passed as an argument to a Java method, and that
+ * Java method expects a Java interface, we register the JS object here.
+ * Java can then call methods on it via the CallbackServer.
+ *
+ * Mirrors py4j's PythonProxyPool.
+ */
+class ProxyPool extends EventEmitter {
+  constructor() {
+    super();
+    this._pool = new Map();
+    this._counter = 0;
+  }
+
+  /** Register a JS proxy object and return its ID. */
+  register(obj) {
+    const id = 'p' + this._counter++;
+    this._pool.set(id, obj);
+    return id;
+  }
+
+  /** Look up a proxy by ID. */
+  get(id) {
+    return this._pool.get(id) || null;
+  }
+
+  /** Remove a proxy from the pool. */
+  remove(id) {
+    this._pool.delete(id);
+  }
+
+  /** Check if a proxy is registered. */
+  has(id) {
+    return this._pool.has(id);
+  }
+}
+
+/**
+ * Handles a single callback connection from Java.
+ * Reads py4j-protocol commands and dispatches them to JS proxy objects.
+ */
+class CallbackConnection {
+  constructor(socket, proxyPool, gatewayClient) {
+    this._socket = socket;
+    this._proxyPool = proxyPool;
+    this._gatewayClient = gatewayClient;
+    this._buffer = '';
+
+    socket.setEncoding('utf8');
+    socket.setNoDelay(true);
+
+    socket.on('data', (chunk) => {
+      this._buffer += chunk;
+      this._processBuffer();
+    });
+
+    socket.on('error', () => {});
+    socket.on('close', () => {});
+  }
+
+  _processBuffer() {
+    // Commands are newline-delimited sequences ending with "e\n"
+    // Read lines until we have a full command
+    const lines = [];
+    let remaining = this._buffer;
+
+    while (true) {
+      const idx = remaining.indexOf('\n');
+      if (idx === -1) break;
+      const line = remaining.substring(0, idx);
+      remaining = remaining.substring(idx + 1);
+      lines.push(line);
+      if (line === END) {
+        this._buffer = remaining;
+        this._handleCommand(lines);
+        return;
+      }
+    }
+    this._buffer = remaining;
+  }
+
+  async _handleCommand(lines) {
+    if (lines.length === 0) return;
+
+    const commandType = lines[0];
+
+    if (commandType === 'c') {
+      // Call command: c, proxy_id, method_name, [args...], e
+      const proxyId = lines[1];
+      const methodName = lines[2];
+      const argLines = lines.slice(3, lines.length - 1); // exclude trailing 'e'
+
+      const proxy = this._proxyPool.get(proxyId);
+      if (!proxy) {
+        this._sendError(`No proxy found with id: ${proxyId}`);
+        return;
+      }
+
+      const method = proxy[methodName];
+      if (typeof method !== 'function') {
+        this._sendError(`Method '${methodName}' not found on proxy`);
+        return;
+      }
+
+      try {
+        const args = this._decodeArgs(argLines);
+        const result = await method.apply(proxy, args);
+        this._sendSuccess(result);
+      } catch (err) {
+        this._sendError(err.message || String(err));
+      }
+    } else if (commandType === 'g') {
+      // Garbage-collect a proxy
+      const proxyId = lines[1];
+      this._proxyPool.remove(proxyId);
+      this._sendSuccessVoid();
+    }
+  }
+
+  _decodeArgs(argLines) {
+    const args = [];
+    for (const line of argLines) {
+      if (line.length === 0) continue;
+      const typePrefix = line[0];
+      const value = line.slice(1);
+      args.push(decodeTypedValue(typePrefix, value, this._gatewayClient));
+    }
+    return args;
+  }
+
+  _sendSuccess(value) {
+    let response;
+    if (value === null || value === undefined) {
+      response = '!' + SUCCESS + VOID_TYPE + '\n';
+    } else {
+      try {
+        const encoded = encodeCommandPart(value, this._proxyPool);
+        // encodeCommandPart returns "type+value\n"; wrap in return+success code
+        response = '!' + SUCCESS + encoded;
+      } catch (_) {
+        response = '!' + SUCCESS + VOID_TYPE + '\n';
+      }
+    }
+    this._socket.write(response);
+  }
+
+  _sendSuccessVoid() {
+    this._socket.write('!' + SUCCESS + VOID_TYPE + '\n');
+  }
+
+  _sendError(message) {
+    this._socket.write('!' + ERROR + message + '\n');
+  }
+}
+
+/**
+ * CallbackServer — listens for Java → JS callback connections.
+ *
+ * When a JS object is passed to Java as a proxy (implementing a Java
+ * interface), Java connects back here to invoke methods on that object.
+ *
+ * Mirrors py4j's CallbackServer.
+ */
+class CallbackServer extends EventEmitter {
+  /**
+   * @param {object} options
+   * @param {string} [options.host='127.0.0.1']
+   * @param {number} [options.port=25334]
+   * @param {ProxyPool} options.proxyPool
+   * @param {object} options.gatewayClient
+   */
+  constructor(options = {}) {
+    super();
+    this.host = options.host || '127.0.0.1';
+    this.port = options.port || 25334;
+    this._proxyPool = options.proxyPool || new ProxyPool();
+    this._gatewayClient = options.gatewayClient;
+    this._server = null;
+    this._connections = new Set();
+    this.listening = false;
+  }
+
+  /** Start listening for Java callback connections. */
+  start() {
+    return new Promise((resolve, reject) => {
+      this._server = net.createServer((socket) => {
+        const conn = new CallbackConnection(socket, this._proxyPool, this._gatewayClient);
+        this._connections.add(conn);
+        socket.on('close', () => this._connections.delete(conn));
+        this.emit('connection', conn);
+      });
+
+      this._server.on('error', reject);
+
+      this._server.listen(this.port, this.host, () => {
+        this.listening = true;
+        this.port = this._server.address().port; // capture actual port (useful if port=0)
+        this.emit('listening');
+        resolve(this);
+      });
+    });
+  }
+
+  /** Stop the callback server and close all connections. */
+  stop() {
+    return new Promise((resolve) => {
+      for (const conn of this._connections) {
+        try { conn._socket.destroy(); } catch (_) {}
+      }
+      this._connections.clear();
+
+      if (this._server) {
+        this._server.close(() => {
+          this.listening = false;
+          resolve();
+        });
+        this._server = null;
+      } else {
+        resolve();
+      }
+    });
+  }
+
+  get proxyPool() {
+    return this._proxyPool;
+  }
+}
+
+/**
+ * Helper to create a JS object that can be passed to Java as a callback proxy.
+ *
+ * @param {string[]} interfaces - Java interface FQNs this object implements
+ * @param {object} impl - Object with method implementations
+ * @returns {object} A proxy-tagged object ready to pass to Java
+ *
+ * @example
+ * const handler = createJavaProxy(
+ *   ['java.lang.Runnable'],
+ *   { run: () => console.log('Java called run!') }
+ * );
+ * await gateway.jvm.java.lang.Thread(handler).start();
+ */
+function createJavaProxy(interfaces, impl) {
+  return Object.assign({}, impl, {
+    _js4jProxy: true,
+    _interfaces: interfaces,
+  });
+}
+
+module.exports = { CallbackServer, ProxyPool, CallbackConnection, createJavaProxy };

package/src/clientServer.js

@@ -0,0 +1,81 @@
+'use strict';
+
+/**
+ * ClientServer — bidirectional, pinned-thread communication model.
+ *
+ * In py4j, ClientServer ensures that callbacks from Java arrive on the
+ * same thread that made the original call into Java, enabling recursive
+ * Java → Python → Java call chains without deadlocks.
+ *
+ * In Node.js there is only one thread and the event loop handles
+ * concurrency, so the pinning behaviour is not required.  This module
+ * wraps JavaGateway + CallbackServer with the same API surface as
+ * py4j's ClientServer for compatibility.
+ *
+ * Mirrors py4j's ClientServer class.
+ */
+
+const { JavaGateway, GatewayParameters, CallbackServerParameters } = require('./gateway');
+const { createJavaProxy } = require('./callbackServer');
+
+class ClientServer {
+  /**
+   * @param {GatewayParameters|object}        [javaParameters]
+   * @param {CallbackServerParameters|object} [pythonParameters]
+   */
+  constructor(javaParameters, pythonParameters) {
+    this._gateway = new JavaGateway(javaParameters, pythonParameters);
+  }
+
+  /**
+   * Connect to the Java gateway AND start the callback server.
+   * @returns {Promise<ClientServer>}
+   */
+  async connect() {
+    await this._gateway.connect();
+    await this._gateway.startCallbackServer();
+    return this;
+  }
+
+  /**
+   * Shut down the gateway and the callback server.
+   */
+  async shutdown() {
+    await this._gateway.shutdown();
+  }
+
+  /** The jvm namespace (same as gateway.jvm). */
+  get jvm() {
+    return this._gateway.jvm;
+  }
+
+  /** The entry point object (same as gateway.entry_point). */
+  get entry_point() {
+    return this._gateway.entry_point;
+  }
+
+  /** The underlying JavaGateway. */
+  get gateway() {
+    return this._gateway;
+  }
+
+  /** The callback server. */
+  get callbackServer() {
+    return this._gateway._callbackServer;
+  }
+
+  // Delegate convenience methods
+  getField(obj, name) { return this._gateway.getField(obj, name); }
+  setField(obj, name, val) { return this._gateway.setField(obj, name, val); }
+  newArray(cls, ...dims) { return this._gateway.newArray(cls, ...dims); }
+  newJvmView(name) { return this._gateway.newJvmView(name); }
+  getMethods(obj) { return this._gateway.getMethods(obj); }
+  getFields(obj) { return this._gateway.getFields(obj); }
+  getStaticMembers(cls) { return this._gateway.getStaticMembers(cls); }
+  javaImport(fqn) { return this._gateway.javaImport(fqn); }
+  help(target) { return this._gateway.help(target); }
+  releaseObject(obj) { return this._gateway.releaseObject(obj); }
+  detach(obj) { return this._gateway.detach(obj); }
+}
+
+module.exports = { ClientServer, createJavaProxy };