js4j 0.1.0

package/src/collections.js

@@ -0,0 +1,325 @@
+'use strict';
+
+const {
+  LIST_COMMAND_NAME,
+  LIST_SORT_SUBCOMMAND_NAME,
+  LIST_REVERSE_SUBCOMMAND_NAME,
+  LIST_SLICE_SUBCOMMAND_NAME,
+  LIST_CONCAT_SUBCOMMAND_NAME,
+  LIST_MULT_SUBCOMMAND_NAME,
+  LIST_IMULT_SUBCOMMAND_NAME,
+  LIST_COUNT_SUBCOMMAND_NAME,
+  ARRAY_COMMAND_NAME,
+  ARRAY_GET_SUB_COMMAND_NAME,
+  ARRAY_SET_SUB_COMMAND_NAME,
+  ARRAY_SLICE_SUB_COMMAND_NAME,
+  ARRAY_LEN_SUB_COMMAND_NAME,
+  CALL_COMMAND_NAME,
+  END,
+  END_COMMAND_PART,
+  INTEGER_TYPE,
+  encodeCommandPart,
+  decodeReturnValue,
+} = require('./protocol');
+
+function buildListCommand(subCmd, targetId, ...parts) {
+  let cmd = LIST_COMMAND_NAME + subCmd + targetId + END_COMMAND_PART;
+  for (const p of parts) { cmd += p; }
+  cmd += END + END_COMMAND_PART;
+  return cmd;
+}
+
+function buildCallCommand(targetId, method, args, gatewayClient) {
+  const { buildArgsCommand } = require('./javaObject');
+  const argsStr = buildArgsCommand(args, gatewayClient._proxyPool);
+  return (
+    CALL_COMMAND_NAME +
+    targetId + END_COMMAND_PART +
+    method + END_COMMAND_PART +
+    argsStr +
+    END + END_COMMAND_PART
+  );
+}
+
+// ---------------------------------------------------------------------------
+// JavaList — wraps java.util.List
+// ---------------------------------------------------------------------------
+
+function createJavaList(targetId, gatewayClient) {
+  const obj = {
+    _targetId: targetId,
+    _gatewayClient: gatewayClient,
+    _isJavaList: true,
+
+    async size() { return gatewayClient.callMethod(targetId, 'size', []); },
+    async get(index) { return gatewayClient.callMethod(targetId, 'get', [index]); },
+    async add(element) { return gatewayClient.callMethod(targetId, 'add', [element]); },
+    async addAt(index, element) { return gatewayClient.callMethod(targetId, 'add', [index, element]); },
+    async remove(indexOrValue) { return gatewayClient.callMethod(targetId, 'remove', [indexOrValue]); },
+    async set(index, element) { return gatewayClient.callMethod(targetId, 'set', [index, element]); },
+    async clear() { return gatewayClient.callMethod(targetId, 'clear', []); },
+    async contains(value) { return gatewayClient.callMethod(targetId, 'contains', [value]); },
+    async indexOf(value) { return gatewayClient.callMethod(targetId, 'indexOf', [value]); },
+
+    async subList(fromIndex, toIndex) {
+      const answer = await gatewayClient._sendCommand(
+        buildListCommand(
+          LIST_SLICE_SUBCOMMAND_NAME, targetId,
+          INTEGER_TYPE + fromIndex + END_COMMAND_PART,
+          INTEGER_TYPE + toIndex + END_COMMAND_PART
+        )
+      );
+      return decodeReturnValue(answer, gatewayClient);
+    },
+
+    async sort() {
+      const answer = await gatewayClient._sendCommand(buildListCommand(LIST_SORT_SUBCOMMAND_NAME, targetId));
+      return decodeReturnValue(answer, gatewayClient);
+    },
+
+    async reverse() {
+      const answer = await gatewayClient._sendCommand(buildListCommand(LIST_REVERSE_SUBCOMMAND_NAME, targetId));
+      return decodeReturnValue(answer, gatewayClient);
+    },
+
+    async count(value) {
+      const answer = await gatewayClient._sendCommand(
+        buildListCommand(LIST_COUNT_SUBCOMMAND_NAME, targetId, encodeCommandPart(value, gatewayClient._proxyPool))
+      );
+      return decodeReturnValue(answer, gatewayClient);
+    },
+
+    async *[Symbol.asyncIterator]() {
+      const size = await this.size();
+      for (let i = 0; i < size; i++) { yield await this.get(i); }
+    },
+
+    async toArray() {
+      const size = await this.size();
+      const result = [];
+      for (let i = 0; i < size; i++) { result.push(await this.get(i)); }
+      return result;
+    },
+
+    async call(method, ...args) { return gatewayClient.callMethod(targetId, method, args); },
+  };
+
+  return new Proxy(obj, {
+    get(target, prop) {
+      if (typeof prop === 'symbol') return target[prop];
+      if (Object.prototype.hasOwnProperty.call(target, prop)) return target[prop];
+      if (prop === 'then') return undefined;
+      return (...args) => gatewayClient.callMethod(targetId, prop, args);
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// JavaSet — wraps java.util.Set
+// ---------------------------------------------------------------------------
+
+function createJavaSet(targetId, gatewayClient) {
+  const obj = {
+    _targetId: targetId,
+    _gatewayClient: gatewayClient,
+    _isJavaSet: true,
+
+    async size() { return gatewayClient.callMethod(targetId, 'size', []); },
+    async add(element) { return gatewayClient.callMethod(targetId, 'add', [element]); },
+    async remove(element) { return gatewayClient.callMethod(targetId, 'remove', [element]); },
+    async contains(element) { return gatewayClient.callMethod(targetId, 'contains', [element]); },
+    async clear() { return gatewayClient.callMethod(targetId, 'clear', []); },
+
+    async toArray() {
+      const iter = await gatewayClient.callMethod(targetId, 'iterator', []);
+      const result = [];
+      while (await iter.hasNext()) { result.push(await iter.next()); }
+      return result;
+    },
+
+    async toSet() {
+      const iter = await gatewayClient.callMethod(targetId, 'iterator', []);
+      const result = new Set();
+      while (await iter.hasNext()) { result.add(await iter.next()); }
+      return result;
+    },
+
+    async *[Symbol.asyncIterator]() {
+      const iter = await gatewayClient.callMethod(targetId, 'iterator', []);
+      while (await iter.hasNext()) { yield await iter.next(); }
+    },
+
+    async call(method, ...args) { return gatewayClient.callMethod(targetId, method, args); },
+  };
+
+  return new Proxy(obj, {
+    get(target, prop) {
+      if (typeof prop === 'symbol') return target[prop];
+      if (Object.prototype.hasOwnProperty.call(target, prop)) return target[prop];
+      if (prop === 'then') return undefined;
+      return (...args) => gatewayClient.callMethod(targetId, prop, args);
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// JavaMap — wraps java.util.Map
+// ---------------------------------------------------------------------------
+
+function createJavaMap(targetId, gatewayClient) {
+  const obj = {
+    _targetId: targetId,
+    _gatewayClient: gatewayClient,
+    _isJavaMap: true,
+
+    async size() { return gatewayClient.callMethod(targetId, 'size', []); },
+    async get(key) { return gatewayClient.callMethod(targetId, 'get', [key]); },
+    async put(key, value) { return gatewayClient.callMethod(targetId, 'put', [key, value]); },
+    async remove(key) { return gatewayClient.callMethod(targetId, 'remove', [key]); },
+    async containsKey(key) { return gatewayClient.callMethod(targetId, 'containsKey', [key]); },
+    async containsValue(value) { return gatewayClient.callMethod(targetId, 'containsValue', [value]); },
+    async clear() { return gatewayClient.callMethod(targetId, 'clear', []); },
+    async keySet() { return gatewayClient.callMethod(targetId, 'keySet', []); },
+    async values() { return gatewayClient.callMethod(targetId, 'values', []); },
+    async entrySet() { return gatewayClient.callMethod(targetId, 'entrySet', []); },
+
+    async toMap() {
+      const result = new Map();
+      const entries = await this.entrySet();
+      for await (const entry of entries) {
+        const key = await entry.getKey();
+        const val = await entry.getValue();
+        result.set(key, val);
+      }
+      return result;
+    },
+
+    async toObject() {
+      const result = {};
+      const keys = await this.keySet();
+      for await (const key of keys) { result[key] = await this.get(key); }
+      return result;
+    },
+
+    async call(method, ...args) { return gatewayClient.callMethod(targetId, method, args); },
+  };
+
+  return new Proxy(obj, {
+    get(target, prop) {
+      if (typeof prop === 'symbol') return target[prop];
+      if (Object.prototype.hasOwnProperty.call(target, prop)) return target[prop];
+      if (prop === 'then') return undefined;
+      return (...args) => gatewayClient.callMethod(targetId, prop, args);
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// JavaArray — wraps Java arrays (fixed length)
+// ---------------------------------------------------------------------------
+
+function createJavaArray(targetId, gatewayClient) {
+  function arrayCmd(subCmd, ...parts) {
+    let cmd = ARRAY_COMMAND_NAME + subCmd + targetId + END_COMMAND_PART;
+    for (const p of parts) cmd += p;
+    cmd += END + END_COMMAND_PART;
+    return cmd;
+  }
+
+  const obj = {
+    _targetId: targetId,
+    _gatewayClient: gatewayClient,
+    _isJavaArray: true,
+
+    async get(index) {
+      const answer = await gatewayClient._sendCommand(
+        arrayCmd(ARRAY_GET_SUB_COMMAND_NAME, INTEGER_TYPE + index + END_COMMAND_PART)
+      );
+      return decodeReturnValue(answer, gatewayClient);
+    },
+
+    async set(index, value) {
+      const answer = await gatewayClient._sendCommand(
+        arrayCmd(ARRAY_SET_SUB_COMMAND_NAME,
+          INTEGER_TYPE + index + END_COMMAND_PART,
+          encodeCommandPart(value, gatewayClient._proxyPool))
+      );
+      return decodeReturnValue(answer, gatewayClient);
+    },
+
+    async length() {
+      const answer = await gatewayClient._sendCommand(arrayCmd(ARRAY_LEN_SUB_COMMAND_NAME));
+      return decodeReturnValue(answer, gatewayClient);
+    },
+
+    async slice(fromIndex, toIndex) {
+      const answer = await gatewayClient._sendCommand(
+        arrayCmd(ARRAY_SLICE_SUB_COMMAND_NAME,
+          INTEGER_TYPE + fromIndex + END_COMMAND_PART,
+          INTEGER_TYPE + toIndex + END_COMMAND_PART)
+      );
+      return decodeReturnValue(answer, gatewayClient);
+    },
+
+    async toArray() {
+      const len = await this.length();
+      const result = [];
+      for (let i = 0; i < len; i++) { result.push(await this.get(i)); }
+      return result;
+    },
+
+    async *[Symbol.asyncIterator]() {
+      const len = await this.length();
+      for (let i = 0; i < len; i++) { yield await this.get(i); }
+    },
+
+    async call(method, ...args) { return gatewayClient.callMethod(targetId, method, args); },
+  };
+
+  return obj;
+}
+
+// ---------------------------------------------------------------------------
+// JavaIterator — wraps java.util.Iterator
+// ---------------------------------------------------------------------------
+
+function createJavaIterator(targetId, gatewayClient) {
+  const obj = {
+    _targetId: targetId,
+    _gatewayClient: gatewayClient,
+    _isJavaIterator: true,
+
+    async hasNext() { return gatewayClient.callMethod(targetId, 'hasNext', []); },
+    async next() { return gatewayClient.callMethod(targetId, 'next', []); },
+    async remove() { return gatewayClient.callMethod(targetId, 'remove', []); },
+
+    async *[Symbol.asyncIterator]() {
+      while (await this.hasNext()) { yield await this.next(); }
+    },
+
+    async toArray() {
+      const result = [];
+      while (await this.hasNext()) { result.push(await this.next()); }
+      return result;
+    },
+
+    async call(method, ...args) { return gatewayClient.callMethod(targetId, method, args); },
+  };
+
+  return new Proxy(obj, {
+    get(target, prop) {
+      if (typeof prop === 'symbol') return target[prop];
+      if (Object.prototype.hasOwnProperty.call(target, prop)) return target[prop];
+      if (prop === 'then') return undefined;
+      return (...args) => gatewayClient.callMethod(targetId, prop, args);
+    },
+  });
+}
+
+module.exports = {
+  createJavaList,
+  createJavaSet,
+  createJavaMap,
+  createJavaArray,
+  createJavaIterator,
+};

package/src/connection.js

@@ -0,0 +1,253 @@
+'use strict';
+
+const net = require('net');
+const { Js4JNetworkError, Js4JAuthenticationError } = require('./exceptions');
+const {
+  AUTH_COMMAND_NAME,
+  END,
+  END_COMMAND_PART,
+  SUCCESS,
+} = require('./protocol');
+
+/**
+ * Serialises concurrent requests so that only one in-flight command exists on
+ * the socket at a time — matching py4j's synchronous request/response model.
+ */
+class RequestQueue {
+  constructor() {
+    this._queue = [];
+    this._running = false;
+  }
+
+  /** Enqueue an async task function and return its result as a Promise. */
+  run(task) {
+    return new Promise((resolve, reject) => {
+      this._queue.push({ task, resolve, reject });
+      this._flush();
+    });
+  }
+
+  async _flush() {
+    if (this._running) return;
+    this._running = true;
+    while (this._queue.length > 0) {
+      const { task, resolve, reject } = this._queue.shift();
+      try {
+        resolve(await task());
+      } catch (err) {
+        reject(err);
+      }
+    }
+    this._running = false;
+  }
+}
+
+/**
+ * A single TCP connection to a py4j-compatible GatewayServer.
+ *
+ * Handles buffered line-by-line reading and serialises commands through a
+ * RequestQueue so the socket is never used concurrently.
+ */
+class GatewayConnection {
+  constructor(options = {}) {
+    this.host = options.host || '127.0.0.1';
+    this.port = options.port || 25333;
+    this.authToken = options.authToken || null;
+    this._socket = null;
+    this._buffer = '';
+    this._readResolve = null;
+    this._readReject = null;
+    this._queue = new RequestQueue();
+    this._closed = false;
+  }
+
+  /** Open the TCP connection (and optionally authenticate). */
+  connect() {
+    return new Promise((resolve, reject) => {
+      const sock = new net.Socket();
+      sock.setEncoding('utf8');
+      sock.setNoDelay(true);
+
+      sock.on('data', (chunk) => {
+        this._buffer += chunk;
+        this._drainBuffer();
+      });
+
+      sock.on('error', (err) => {
+        this._closed = true;
+        if (this._readReject) {
+          this._readReject(new Js4JNetworkError('Socket error: ' + err.message));
+          this._readReject = null;
+          this._readResolve = null;
+        }
+      });
+
+      sock.on('close', () => {
+        this._closed = true;
+        if (this._readReject) {
+          this._readReject(new Js4JNetworkError('Connection closed by remote host'));
+          this._readReject = null;
+          this._readResolve = null;
+        }
+      });
+
+      sock.connect(this.port, this.host, async () => {
+        this._socket = sock;
+        try {
+          if (this.authToken) {
+            await this._authenticate();
+          }
+          resolve(this);
+        } catch (err) {
+          sock.destroy();
+          reject(err);
+        }
+      });
+
+      sock.on('error', (err) => {
+        if (!this._socket) {
+          // Connection-phase error
+          reject(new Js4JNetworkError('Could not connect to gateway: ' + err.message));
+        }
+      });
+    });
+  }
+
+  /** Send an authentication command and verify the response. */
+  async _authenticate() {
+    const cmd = AUTH_COMMAND_NAME + this.authToken + END_COMMAND_PART + END + END_COMMAND_PART;
+    const resp = await this._rawSend(cmd);
+    if (!resp.startsWith(SUCCESS)) {
+      throw new Js4JAuthenticationError('Gateway authentication failed');
+    }
+  }
+
+  /**
+   * Send a py4j command string and return the single-line response.
+   * Requests are queued; only one is in flight at a time.
+   */
+  sendCommand(command) {
+    if (this._closed) {
+      return Promise.reject(new Js4JNetworkError('Connection is closed'));
+    }
+    return this._queue.run(() => this._rawSend(command));
+  }
+
+  /** Internal: write to socket and wait for one line of response. */
+  _rawSend(command) {
+    return new Promise((resolve, reject) => {
+      this._readResolve = resolve;
+      this._readReject = reject;
+      this._socket.write(command, 'utf8', (err) => {
+        if (err) {
+          this._readResolve = null;
+          this._readReject = null;
+          reject(new Js4JNetworkError('Write failed: ' + err.message));
+        }
+      });
+    });
+  }
+
+  /** Drain the internal buffer, resolving the pending read on a complete line. */
+  _drainBuffer() {
+    const idx = this._buffer.indexOf('\n');
+    if (idx !== -1 && this._readResolve) {
+      const line = this._buffer.substring(0, idx);
+      this._buffer = this._buffer.substring(idx + 1);
+      const resolve = this._readResolve;
+      this._readResolve = null;
+      this._readReject = null;
+      resolve(line);
+    }
+  }
+
+  /** Close this connection. */
+  close() {
+    this._closed = true;
+    if (this._socket) {
+      this._socket.destroy();
+      this._socket = null;
+    }
+  }
+
+  get isConnected() {
+    return !this._closed && this._socket !== null;
+  }
+}
+
+/**
+ * A pool of GatewayConnections.
+ * py4j gives each thread its own connection; in Node.js we hand out
+ * connections from the pool (creating new ones as needed) and return them
+ * when the request is done.
+ *
+ * For simplicity the default pool size is 1 (sequential behaviour matching
+ * py4j's single-threaded usage), but you can raise maxConnections for
+ * concurrent callers.
+ */
+class ConnectionPool {
+  constructor(options = {}, maxConnections = 4) {
+    this._options = options;
+    this._maxConnections = maxConnections;
+    this._idle = []; // available connections
+    this._active = 0;
+    this._waiters = [];
+  }
+
+  /** Borrow a connection from the pool (creates one if needed). */
+  async acquire() {
+    if (this._idle.length > 0) {
+      const conn = this._idle.pop();
+      if (conn.isConnected) {
+        this._active++;
+        return conn;
+      }
+    }
+
+    if (this._active < this._maxConnections) {
+      const conn = new GatewayConnection(this._options);
+      await conn.connect();
+      this._active++;
+      return conn;
+    }
+
+    // Wait for a connection to become available
+    return new Promise((resolve, reject) => {
+      this._waiters.push({ resolve, reject });
+    });
+  }
+
+  /** Return a connection to the pool. */
+  release(conn) {
+    this._active--;
+    if (this._waiters.length > 0) {
+      const { resolve } = this._waiters.shift();
+      this._active++;
+      resolve(conn);
+      return;
+    }
+    if (conn.isConnected) {
+      this._idle.push(conn);
+    }
+  }
+
+  /** Run a function with a borrowed connection, then release it. */
+  async withConnection(fn) {
+    const conn = await this.acquire();
+    try {
+      return await fn(conn);
+    } finally {
+      this.release(conn);
+    }
+  }
+
+  /** Close all connections in the pool. */
+  closeAll() {
+    for (const conn of this._idle) {
+      conn.close();
+    }
+    this._idle = [];
+  }
+}
+
+module.exports = { GatewayConnection, ConnectionPool, RequestQueue };

package/src/exceptions.js

@@ -0,0 +1,68 @@
+'use strict';
+
+/**
+ * Base error class for all js4j errors.
+ * Mirrors py4j's Py4JError.
+ */
+class Js4JError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'Js4JError';
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+/**
+ * Raised when a Java-side exception occurs during method invocation.
+ * Contains the full Java exception message and optional stack trace.
+ * Mirrors py4j's Py4JJavaError.
+ */
+class Js4JJavaError extends Js4JError {
+  /**
+   * @param {string} message             - Human-readable error message
+   * @param {string} javaExceptionMessage - Raw protocol payload (e.g. "ro0")
+   * @param {object} [javaException]     - Decoded Java Throwable as a JavaObject;
+   *                                       call await err.javaException.getMessage() etc.
+   */
+  constructor(message, javaExceptionMessage, javaException) {
+    super(message);
+    this.name = 'Js4JJavaError';
+    this.javaExceptionMessage = javaExceptionMessage || '';
+    this.javaException = javaException || null;
+  }
+
+  toString() {
+    return `${this.name}: ${this.message}\n  Java exception payload: ${this.javaExceptionMessage}`;
+  }
+}
+
+/**
+ * Raised when a network error occurs during communication with the Java gateway.
+ * Mirrors py4j's Py4JNetworkError.
+ */
+class Js4JNetworkError extends Js4JError {
+  constructor(message) {
+    super(message);
+    this.name = 'Js4JNetworkError';
+  }
+}
+
+/**
+ * Raised when authentication with the Java gateway fails.
+ * Mirrors py4j's Py4JAuthenticationError.
+ */
+class Js4JAuthenticationError extends Js4JError {
+  constructor(message) {
+    super(message || 'Authentication failed');
+    this.name = 'Js4JAuthenticationError';
+  }
+}
+
+module.exports = {
+  Js4JError,
+  Js4JJavaError,
+  Js4JNetworkError,
+  Js4JAuthenticationError,
+};