js4j 0.1.0

package/tests/unit/exceptions.test.js

@@ -0,0 +1,104 @@
+'use strict';
+
+const {
+  Js4JError,
+  Js4JJavaError,
+  Js4JNetworkError,
+  Js4JAuthenticationError,
+} = require('../../src/exceptions');
+
+describe('Js4JError', () => {
+  test('is an instance of Error', () => {
+    const err = new Js4JError('test');
+    expect(err).toBeInstanceOf(Error);
+  });
+
+  test('has correct name', () => {
+    expect(new Js4JError('x').name).toBe('Js4JError');
+  });
+
+  test('has correct message', () => {
+    expect(new Js4JError('something went wrong').message).toBe('something went wrong');
+  });
+
+  test('instanceof Js4JError', () => {
+    expect(new Js4JError('x')).toBeInstanceOf(Js4JError);
+  });
+});
+
+describe('Js4JJavaError', () => {
+  test('extends Js4JError', () => {
+    expect(new Js4JJavaError('msg', 'java trace')).toBeInstanceOf(Js4JError);
+  });
+
+  test('has correct name', () => {
+    expect(new Js4JJavaError('m', 't').name).toBe('Js4JJavaError');
+  });
+
+  test('stores javaExceptionMessage', () => {
+    const err = new Js4JJavaError('A occurred', 'java.lang.RuntimeException: A');
+    expect(err.javaExceptionMessage).toBe('java.lang.RuntimeException: A');
+  });
+
+  test('toString includes Java trace', () => {
+    const err = new Js4JJavaError('msg', 'trace here');
+    expect(err.toString()).toContain('trace here');
+  });
+
+  test('javaExceptionMessage defaults to empty string', () => {
+    const err = new Js4JJavaError('msg');
+    expect(err.javaExceptionMessage).toBe('');
+  });
+});
+
+describe('Js4JNetworkError', () => {
+  test('extends Js4JError', () => {
+    expect(new Js4JNetworkError('net')).toBeInstanceOf(Js4JError);
+  });
+
+  test('has correct name', () => {
+    expect(new Js4JNetworkError('net').name).toBe('Js4JNetworkError');
+  });
+});
+
+describe('Js4JAuthenticationError', () => {
+  test('extends Js4JError', () => {
+    expect(new Js4JAuthenticationError()).toBeInstanceOf(Js4JError);
+  });
+
+  test('has correct name', () => {
+    expect(new Js4JAuthenticationError().name).toBe('Js4JAuthenticationError');
+  });
+
+  test('default message', () => {
+    expect(new Js4JAuthenticationError().message).toBe('Authentication failed');
+  });
+
+  test('custom message', () => {
+    expect(new Js4JAuthenticationError('bad token').message).toBe('bad token');
+  });
+});
+
+describe('Error hierarchy', () => {
+  test('all errors are instanceof Error', () => {
+    expect(new Js4JError('x')).toBeInstanceOf(Error);
+    expect(new Js4JJavaError('x', 'y')).toBeInstanceOf(Error);
+    expect(new Js4JNetworkError('x')).toBeInstanceOf(Error);
+    expect(new Js4JAuthenticationError()).toBeInstanceOf(Error);
+  });
+
+  test('Js4JJavaError is NOT instanceof Js4JNetworkError', () => {
+    expect(new Js4JJavaError('x', 'y')).not.toBeInstanceOf(Js4JNetworkError);
+  });
+
+  test('can be caught as Js4JError', () => {
+    function throwIt() { throw new Js4JJavaError('boom', 'trace'); }
+    expect(throwIt).toThrow(Js4JError);
+  });
+
+  test('stack trace is available', () => {
+    const err = new Js4JError('oops');
+    expect(typeof err.stack).toBe('string');
+    expect(err.stack).toContain('Js4JError');
+  });
+});

package/tests/unit/gateway.test.js

@@ -0,0 +1,178 @@
+'use strict';
+
+/**
+ * Unit tests for gateway-level functionality that can be tested without a
+ * live Java server (using mocked connections).
+ */
+
+const { GatewayParameters, CallbackServerParameters } = require('../../src/gateway');
+const { ProxyPool, createJavaProxy } = require('../../src/callbackServer');
+const { createJavaObject } = require('../../src/javaObject');
+
+// ---------------------------------------------------------------------------
+// GatewayParameters
+// ---------------------------------------------------------------------------
+
+describe('GatewayParameters', () => {
+  test('defaults', () => {
+    const p = new GatewayParameters();
+    expect(p.host).toBe('127.0.0.1');
+    expect(p.port).toBe(25333);
+    expect(p.authToken).toBeNull();
+    expect(p.autoField).toBe(false);
+    expect(p.autoConvert).toBe(false);
+    expect(p.enableMemoryManagement).toBe(false);
+    expect(p.poolSize).toBe(4);
+  });
+
+  test('custom values', () => {
+    const p = new GatewayParameters({
+      host: '0.0.0.0',
+      port: 9999,
+      authToken: 'secret',
+      autoField: true,
+      autoConvert: true,
+      enableMemoryManagement: true,
+      poolSize: 8,
+    });
+    expect(p.host).toBe('0.0.0.0');
+    expect(p.port).toBe(9999);
+    expect(p.authToken).toBe('secret');
+    expect(p.autoField).toBe(true);
+    expect(p.autoConvert).toBe(true);
+    expect(p.enableMemoryManagement).toBe(true);
+    expect(p.poolSize).toBe(8);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// CallbackServerParameters
+// ---------------------------------------------------------------------------
+
+describe('CallbackServerParameters', () => {
+  test('defaults', () => {
+    const p = new CallbackServerParameters();
+    expect(p.host).toBe('127.0.0.1');
+    expect(p.port).toBe(25334);
+    expect(p.daemonize).toBe(true);
+    expect(p.propagateException).toBe(false);
+  });
+
+  test('custom values', () => {
+    const p = new CallbackServerParameters({
+      host: '0.0.0.0',
+      port: 25335,
+      daemonize: false,
+      propagateException: true,
+    });
+    expect(p.host).toBe('0.0.0.0');
+    expect(p.port).toBe(25335);
+    expect(p.daemonize).toBe(false);
+    expect(p.propagateException).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ProxyPool
+// ---------------------------------------------------------------------------
+
+describe('ProxyPool', () => {
+  test('register returns unique IDs', () => {
+    const pool = new ProxyPool();
+    const a = {};
+    const b = {};
+    const idA = pool.register(a);
+    const idB = pool.register(b);
+    expect(idA).not.toBe(idB);
+    expect(idA).toMatch(/^p\d+$/);
+  });
+
+  test('get returns registered object', () => {
+    const pool = new ProxyPool();
+    const obj = { method: () => 42 };
+    const id = pool.register(obj);
+    expect(pool.get(id)).toBe(obj);
+  });
+
+  test('remove deletes the entry', () => {
+    const pool = new ProxyPool();
+    const id = pool.register({});
+    pool.remove(id);
+    expect(pool.get(id)).toBeNull();
+  });
+
+  test('has() returns correct boolean', () => {
+    const pool = new ProxyPool();
+    const id = pool.register({});
+    expect(pool.has(id)).toBe(true);
+    pool.remove(id);
+    expect(pool.has(id)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createJavaProxy
+// ---------------------------------------------------------------------------
+
+describe('createJavaProxy', () => {
+  test('creates an object with _js4jProxy flag', () => {
+    const proxy = createJavaProxy(['java.lang.Runnable'], { run: () => {} });
+    expect(proxy._js4jProxy).toBe(true);
+  });
+
+  test('stores interfaces', () => {
+    const proxy = createJavaProxy(['java.lang.Runnable', 'java.lang.Comparable'], {});
+    expect(proxy._interfaces).toEqual(['java.lang.Runnable', 'java.lang.Comparable']);
+  });
+
+  test('includes implementation methods', () => {
+    const proxy = createJavaProxy(['java.lang.Runnable'], {
+      run: () => 'ran',
+    });
+    expect(typeof proxy.run).toBe('function');
+    expect(proxy.run()).toBe('ran');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createJavaObject
+// ---------------------------------------------------------------------------
+
+describe('createJavaObject', () => {
+  const mockClient = {
+    async callMethod(targetId, method, args) {
+      return { targetId, method, args };
+    },
+  };
+
+  test('_targetId is accessible', () => {
+    const obj = createJavaObject('o123', mockClient);
+    expect(obj._targetId).toBe('o123');
+  });
+
+  test('method access returns async function', () => {
+    const obj = createJavaObject('o1', mockClient);
+    expect(typeof obj.someMethod).toBe('function');
+  });
+
+  test('method call invokes callMethod with correct args', async () => {
+    const obj = createJavaObject('o1', mockClient);
+    const result = await obj.greet('World');
+    expect(result).toEqual({ targetId: 'o1', method: 'greet', args: ['World'] });
+  });
+
+  test('then is undefined (not a Promise)', () => {
+    const obj = createJavaObject('o1', mockClient);
+    expect(obj.then).toBeUndefined();
+  });
+
+  test('Symbol access is handled gracefully', () => {
+    const obj = createJavaObject('o1', mockClient);
+    expect(obj[Symbol.iterator]).toBeUndefined();
+  });
+
+  test('direct field assignment throws helpful error', () => {
+    const obj = createJavaObject('o1', mockClient);
+    expect(() => { obj.someField = 42; }).toThrow(/setField/);
+  });
+});

package/tests/unit/jvmView.test.js

@@ -0,0 +1,126 @@
+'use strict';
+
+const { JVMView, createJavaClass, createJavaPackage } = require('../../src/jvmView');
+
+// Minimal stub client
+const stubClient = {
+  async callMethod(targetId, methodName, args) {
+    return { _call: { targetId, methodName, args } };
+  },
+  async callConstructor(fqn, args) {
+    return { _ctor: { fqn, args } };
+  },
+  async _sendCommand() { return 'yv'; },
+  _wrapObject: (id) => ({ _targetId: id }),
+  _lookupProxy: () => null,
+  _proxyPool: null,
+};
+
+describe('createJavaClass', () => {
+  test('has correct _fqn', () => {
+    const cls = createJavaClass('java.lang.String', stubClient);
+    expect(cls._fqn).toBe('java.lang.String');
+  });
+
+  test('has _targetId equal to z:<fqn> (for static calls)', () => {
+    const cls = createJavaClass('java.lang.Math', stubClient);
+    expect(cls._targetId).toBe('z:java.lang.Math');
+  });
+
+  test('static method access returns async function', () => {
+    const cls = createJavaClass('java.lang.Math', stubClient);
+    expect(typeof cls.abs).toBe('function');
+  });
+
+  test('static method call invokes callMethod with z:<fqn> as target', async () => {
+    const cls = createJavaClass('java.lang.Math', stubClient);
+    const result = await cls.abs(-5);
+    expect(result._call.targetId).toBe('z:java.lang.Math');
+    expect(result._call.methodName).toBe('abs');
+    expect(result._call.args).toEqual([-5]);
+  });
+
+  test('calling class as function invokes constructor', async () => {
+    const cls = createJavaClass('java.lang.StringBuilder', stubClient);
+    const result = await cls('hello');
+    expect(result._ctor.fqn).toBe('java.lang.StringBuilder');
+    expect(result._ctor.args).toEqual(['hello']);
+  });
+
+  test('Symbol properties are not proxied', () => {
+    const cls = createJavaClass('java.lang.String', stubClient);
+    expect(cls[Symbol.iterator]).toBeUndefined();
+  });
+
+  test('.then is undefined (not a Promise)', () => {
+    const cls = createJavaClass('java.lang.String', stubClient);
+    expect(cls.then).toBeUndefined();
+  });
+});
+
+describe('createJavaPackage', () => {
+  test('uppercase child becomes JavaClass', () => {
+    const pkg = createJavaPackage('java.lang', stubClient);
+    const cls = pkg.String;
+    expect(cls._fqn).toBe('java.lang.String');
+    expect(cls._isJavaClass).toBe(true);
+  });
+
+  test('lowercase child stays JavaPackage', () => {
+    const pkg = createJavaPackage('java', stubClient);
+    const subpkg = pkg.lang;
+    expect(subpkg._fqn).toBe('java.lang');
+    expect(subpkg._isJavaPackage).toBe(true);
+  });
+
+  test('chain: java.lang.Math._fqn', () => {
+    const pkg = createJavaPackage('java', stubClient);
+    expect(pkg.lang.Math._fqn).toBe('java.lang.Math');
+  });
+
+  test('calling package as function throws', () => {
+    const pkg = createJavaPackage('java', stubClient);
+    expect(() => pkg()).toThrow();
+  });
+});
+
+describe('JVMView', () => {
+  test('jvm.java is a JavaPackage', () => {
+    const jvm = new JVMView(stubClient);
+    const pkg = jvm.java;
+    expect(pkg._isJavaPackage).toBe(true);
+    expect(pkg._fqn).toBe('java');
+  });
+
+  test('jvm.java.lang.String is a JavaClass', () => {
+    const jvm = new JVMView(stubClient);
+    const cls = jvm.java.lang.String;
+    expect(cls._isJavaClass).toBe(true);
+    expect(cls._fqn).toBe('java.lang.String');
+  });
+
+  test('jvm.java.util.ArrayList is a JavaClass', () => {
+    const jvm = new JVMView(stubClient);
+    const cls = jvm.java.util.ArrayList;
+    expect(cls._fqn).toBe('java.util.ArrayList');
+  });
+
+  test('.then on jvm is undefined (not a Promise)', () => {
+    const jvm = new JVMView(stubClient);
+    expect(jvm.then).toBeUndefined();
+  });
+
+  test('javaImport registers shortcut', async () => {
+    const jvm = new JVMView(stubClient);
+    await jvm.javaImport('java.util.ArrayList');
+    const cls = jvm.ArrayList;
+    expect(cls._fqn).toBe('java.util.ArrayList');
+  });
+
+  test('getClass returns JavaClass', () => {
+    const jvm = new JVMView(stubClient);
+    const cls = jvm.getClass('java.lang.Runtime');
+    expect(cls._fqn).toBe('java.lang.Runtime');
+    expect(cls._isJavaClass).toBe(true);
+  });
+});

package/tests/unit/launcher.test.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const { launchGateway } = require('../../src/launcher');
+
+describe('launchGateway', () => {
+  test('throws when classpath is missing', async () => {
+    await expect(launchGateway({ mainClass: 'Foo' }))
+      .rejects.toThrow('classpath is required');
+  });
+
+  test('throws when mainClass is missing', async () => {
+    await expect(launchGateway({ classpath: '/some/path.jar' }))
+      .rejects.toThrow('mainClass is required');
+  });
+
+  test('times out when java process does not print the ready pattern', async () => {
+    // Spawn a process that never prints anything meaningful
+    await expect(
+      launchGateway({
+        classpath: '.',
+        mainClass: 'DoesNotExist',
+        readyPattern: /NEVER_MATCHES/,
+        timeout: 500,
+      })
+    ).rejects.toThrow(/timed out|exited with code/);
+  });
+});