js4j 0.1.0

package/examples/01-basic.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Example 01 — Basic usage
+ *
+ * Shows how to connect to a Java gateway, call methods on the entry point
+ * object, and work with primitive types (numbers, strings, booleans, null).
+ *
+ * Run:
+ *   node examples/01-basic.js
+ */
+
+const { startTestGateway } = require('./_gateway');
+
+async function main() {
+  console.log('Connecting to Java gateway...\n');
+  const { gateway, kill } = await startTestGateway();
+
+  try {
+    const ep = gateway.entry_point;
+
+    // -----------------------------------------------------------------------
+    // Arithmetic
+    // -----------------------------------------------------------------------
+    console.log('--- Arithmetic ---');
+    console.log('add(3, 4)        =', await ep.add(3, 4));           // 7
+    console.log('multiply(6, 7)   =', await ep.multiply(6, 7));      // 42
+    console.log('divide(5.5, 2.2) =', await ep.divide(5.5, 2.2));    // 2.5
+    console.log('addDoubles(1.1, 2.2) =', await ep.addDoubles(1.1, 2.2)); // 3.3
+    console.log('addLongs(2^32, 1) =', await ep.addLongs(4294967296, 1)); // 4294967297
+
+    // -----------------------------------------------------------------------
+    // Strings
+    // -----------------------------------------------------------------------
+    console.log('\n--- Strings ---');
+    console.log(await ep.greet('World'));                          // Hello, World!
+    console.log(await ep.concatenate('foo', 'bar'));               // foobar
+    console.log('length("hello") =', await ep.stringLength('hello'));  // 5
+    console.log(await ep.toUpperCase('js4j'));                    // JS4J
+    console.log('containsSubstring =', await ep.containsSubstring('hello world', 'world')); // true
+    console.log(await ep.repeatString('ab', 3));                  // ababab
+
+    // -----------------------------------------------------------------------
+    // Booleans
+    // -----------------------------------------------------------------------
+    console.log('\n--- Booleans ---');
+    console.log('true && false =', await ep.andBool(true, false));  // false
+    console.log('true || false =', await ep.orBool(true, false));   // true
+    console.log('!true         =', await ep.notBool(true));         // false
+
+    // -----------------------------------------------------------------------
+    // Null handling
+    // -----------------------------------------------------------------------
+    console.log('\n--- Null ---');
+    console.log('maybeNull(false) =', await ep.maybeNull(false));  // "not null"
+    console.log('maybeNull(true)  =', await ep.maybeNull(true));   // null
+    console.log('isNull(null)     =', await ep.isNull(null));      // true
+
+    // -----------------------------------------------------------------------
+    // Type round-trips
+    // -----------------------------------------------------------------------
+    console.log('\n--- Type round-trips ---');
+    console.log('echoInt(42)      =', await ep.echoInt(42));
+    console.log('echoDouble(3.14) =', await ep.echoDouble(3.14));
+    console.log('echoBool(true)   =', await ep.echoBool(true));
+    console.log('echoString("hi") =', await ep.echoString('hi'));
+
+  } finally {
+    await kill();
+    console.log('\nGateway shut down.');
+  }
+}
+
+main().catch((err) => { console.error(err.message); process.exit(1); });

package/examples/02-collections.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Example 02 — Java collections
+ *
+ * Demonstrates JavaList, JavaSet, JavaMap, and JavaArray — the wrappers
+ * js4j creates automatically when Java methods return collection types.
+ *
+ * Run:
+ *   node examples/02-collections.js
+ */
+
+const { startTestGateway } = require('./_gateway');
+
+async function main() {
+  console.log('Connecting to Java gateway...\n');
+  const { gateway, kill } = await startTestGateway();
+
+  try {
+    const ep = gateway.entry_point;
+
+    // -----------------------------------------------------------------------
+    // JavaList
+    // -----------------------------------------------------------------------
+    console.log('--- JavaList ---');
+    const list = await ep.getStringList();   // returns ArrayList<String>
+
+    console.log('size()          =', await list.size());           // 3
+    console.log('get(0)          =', await list.get(0));           // alpha
+    console.log('get(2)          =', await list.get(2));           // gamma
+    console.log('contains("beta")=', await list.contains('beta')); // true
+    console.log('indexOf("gamma")=', await list.indexOf('gamma')); // 2
+
+    // Mutation
+    await list.add('delta');
+    console.log('after add("delta"), size =', await list.size());  // 4
+
+    // Convert to a plain JS array
+    const arr = await list.toArray();
+    console.log('toArray()       =', arr);                         // ['alpha','beta','gamma','delta']
+
+    // Iteration with for-await
+    process.stdout.write('for-await: ');
+    for await (const item of list) process.stdout.write(item + ' ');
+    console.log();
+
+    // -----------------------------------------------------------------------
+    // JavaSet
+    // -----------------------------------------------------------------------
+    console.log('\n--- JavaSet ---');
+    const set = await ep.getStringSet();     // returns LinkedHashSet<String>
+
+    console.log('size()          =', await set.size());             // 3
+    console.log('contains("one") =', await set.contains('one'));    // true
+    console.log('contains("four")=', await set.contains('four'));   // false
+
+    await set.add('four');
+    console.log('after add("four"), size =', await set.size());     // 4
+
+    const nativeSet = await set.toSet();     // JS Set
+    console.log('toSet()         =', nativeSet);
+
+    // -----------------------------------------------------------------------
+    // JavaMap
+    // -----------------------------------------------------------------------
+    console.log('\n--- JavaMap ---');
+    const map = await ep.getStringIntMap();  // returns LinkedHashMap<String,Integer>
+
+    console.log('size()          =', await map.size());             // 3
+    console.log('get("a")        =', await map.get('a'));           // 1
+    console.log('get("z")        =', await map.get('z'));           // null
+    console.log('containsKey("b")=', await map.containsKey('b'));   // true
+
+    await map.put('d', 4);
+    console.log('after put("d",4), size =', await map.size());      // 4
+
+    // Convert to a plain JS object
+    const obj = await map.toObject();
+    console.log('toObject()      =', obj);                          // { a:1, b:2, c:3, d:4 }
+
+    // -----------------------------------------------------------------------
+    // JavaArray
+    // -----------------------------------------------------------------------
+    console.log('\n--- JavaArray ---');
+    const intArr = await ep.getIntArray();  // int[]{10,20,30,40,50}
+
+    console.log('length()        =', await intArr.length());         // 5
+    console.log('get(0)          =', await intArr.get(0));           // 10
+    console.log('get(4)          =', await intArr.get(4));           // 50
+
+    // Convert all elements to a JS array
+    console.log('toArray()       =', await intArr.toArray());        // [10,20,30,40,50]
+
+    // Create a new Java array from the JS side
+    const newArr = await gateway.newArray(gateway.jvm.java.lang.Integer, 3);
+    await newArr.set(0, 100);
+    await newArr.set(1, 200);
+    await newArr.set(2, 300);
+    console.log('newArray result =', await newArr.toArray());        // [100,200,300]
+
+  } finally {
+    await kill();
+    console.log('\nGateway shut down.');
+  }
+}
+
+main().catch((err) => { console.error(err.message); process.exit(1); });

package/examples/03-objects.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Example 03 — Java objects
+ *
+ * Shows how to work with Java objects returned from the gateway:
+ *   - Calling methods on entry-point-created objects (Counter)
+ *   - Creating Java standard-library objects from the JS side (StringBuilder)
+ *   - Reading and writing fields via gateway.getField / gateway.setField
+ *   - Introspection: getMethods, getFields, getStaticMembers, help
+ *
+ * Run:
+ *   node examples/03-objects.js
+ */
+
+const { startTestGateway } = require('./_gateway');
+
+async function main() {
+  console.log('Connecting to Java gateway...\n');
+  const { gateway, kill } = await startTestGateway();
+
+  try {
+    const ep  = gateway.entry_point;
+    const jvm = gateway.jvm;
+
+    // -----------------------------------------------------------------------
+    // Objects returned by the entry point
+    // -----------------------------------------------------------------------
+    console.log('--- Counter object ---');
+    const counter = await ep.createCounter(10);
+
+    console.log('getValue()      =', await counter.getValue());  // 10
+    await counter.increment();
+    await counter.increment();
+    console.log('after 2x increment:', await counter.getValue()); // 12
+    await counter.add(8);
+    console.log('after add(8)    =', await counter.getValue());  // 20
+    await counter.decrement();
+    console.log('after decrement =', await counter.getValue());  // 19
+    await counter.reset();
+    console.log('after reset     =', await counter.getValue());  // 0
+
+    console.log('toString()      =', await counter.toString());  // Counter(0)
+
+    // -----------------------------------------------------------------------
+    // Creating Java objects from the JS side via gateway.jvm
+    // -----------------------------------------------------------------------
+    console.log('\n--- StringBuilder (created from JS) ---');
+    const sb = await jvm.java.lang.StringBuilder('Hello');
+    await sb.append(', ');
+    await sb.append('World');
+    await sb.append('!');
+    console.log('toString()      =', await sb.toString());       // Hello, World!
+    console.log('length()        =', await sb.length());         // 13
+
+    // -----------------------------------------------------------------------
+    // Static methods via the jvm namespace
+    // -----------------------------------------------------------------------
+    console.log('\n--- Static methods ---');
+    const absVal = await jvm.java.lang.Math.abs(-42);
+    console.log('Math.abs(-42)   =', absVal);                    // 42
+
+    const maxVal = await jvm.java.lang.Math.max(17, 99);
+    console.log('Math.max(17,99) =', maxVal);                    // 99
+
+    const sqrtVal = await jvm.java.lang.Math.sqrt(12.25);
+    console.log('Math.sqrt(12.25) =', sqrtVal);                  // 3.5
+
+    const parsed  = await jvm.java.lang.Integer.parseInt('255');
+    console.log('Integer.parseInt("255") =', parsed);            // 255
+
+    // -----------------------------------------------------------------------
+    // Static fields via gateway.getField
+    // -----------------------------------------------------------------------
+    console.log('\n--- Static fields ---');
+    const pi      = await gateway.getField(jvm.java.lang.Math, 'PI');
+    const maxInt  = await gateway.getField(jvm.java.lang.Integer, 'MAX_VALUE');
+    console.log('Math.PI         =', pi);                        // 3.141592...
+    console.log('Integer.MAX_VALUE =', maxInt);                  // 2147483647
+
+    // -----------------------------------------------------------------------
+    // Introspection
+    // -----------------------------------------------------------------------
+    console.log('\n--- Introspection ---');
+    const methods = await gateway.getMethods(counter);
+    console.log('Counter methods:', methods.sort().join(', '));
+
+    const staticMembers = await gateway.getStaticMembers(jvm.java.lang.Math);
+    const mathStatics = staticMembers.filter(m => ['abs', 'max', 'min', 'sqrt', 'PI', 'E'].includes(m));
+    console.log('Math static members (subset):', mathStatics.sort().join(', '));
+
+  } finally {
+    await kill();
+    console.log('\nGateway shut down.');
+  }
+}
+
+main().catch((err) => { console.error(err.message); process.exit(1); });

package/examples/04-callbacks.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Example 04 — Callbacks (Java → JS)
+ *
+ * Demonstrates passing JavaScript objects to Java as interface implementations.
+ * Java calls back into Node.js over a separate TCP connection handled by the
+ * CallbackServer.
+ *
+ * Run:
+ *   node examples/04-callbacks.js
+ */
+
+const { startTestGateway } = require('./_gateway');
+const { createJavaProxy } = require('../src/callbackServer');
+const { ClientServer } = require('../src/clientServer');
+const { GatewayParameters, CallbackServerParameters } = require('../src/gateway');
+
+async function main() {
+  console.log('Connecting to Java gateway (with callback server)...\n');
+  const { process: jvmProcess, kill: killProcess } = await startTestGateway();
+
+  const cs = new ClientServer(
+    new GatewayParameters({ port: 25333 }),
+    new CallbackServerParameters({ port: 25334 })
+  );
+  await cs.connect();
+
+  try {
+    const jvm = cs.jvm;
+
+    // -----------------------------------------------------------------------
+    // Runnable — Java calls run() on the JS object
+    // -----------------------------------------------------------------------
+    console.log('--- Runnable callback ---');
+
+    let runCount = 0;
+    const runnable = createJavaProxy(['java.lang.Runnable'], {
+      run() {
+        runCount++;
+        console.log(`  run() called! (invocation #${runCount})`);
+        return null;
+      },
+    });
+
+    const thread = await jvm.java.lang.Thread(runnable);
+    await thread.start();
+    await thread.join();
+
+    console.log(`Runnable was invoked ${runCount} time(s)`);
+
+    // -----------------------------------------------------------------------
+    // Comparator — Java calls compare(a, b) to sort a list
+    // -----------------------------------------------------------------------
+    console.log('\n--- Comparator callback (sort by string length) ---');
+
+    const byLength = createJavaProxy(['java.util.Comparator'], {
+      compare(a, b) {
+        return String(a).length - String(b).length;
+      },
+    });
+
+    const words = await jvm.java.util.ArrayList();
+    await words.add('banana'); await words.add('fig'); await words.add('apple');
+    await words.add('kiwi');   await words.add('date');
+    await jvm.java.util.Collections.sort(words, byLength);
+
+    const sorted = await words.toArray();
+    console.log('Sorted by length:', sorted);
+
+    // -----------------------------------------------------------------------
+    // Callable — returns a value back to Java
+    // -----------------------------------------------------------------------
+    console.log('\n--- Callable callback (returns a value) ---');
+
+    const callable = createJavaProxy(['java.util.concurrent.Callable'], {
+      call() {
+        const value = 'computed by JavaScript at ' + new Date().toISOString();
+        console.log('  call() invoked, returning:', value);
+        return value;
+      },
+    });
+
+    const future = await jvm.java.util.concurrent.FutureTask(callable);
+    await future.run();
+    const result = await future.get();
+    console.log('FutureTask result:', result);
+
+  } finally {
+    await cs.shutdown();
+    killProcess();
+    console.log('\nGateway shut down.');
+  }
+}
+
+main().catch((err) => { console.error(err.message); process.exit(1); });

package/examples/05-stdlib.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Example 05 — Java standard library
+ *
+ * Demonstrates direct access to Java standard-library classes via the
+ * gateway.jvm namespace — no custom Java code required.
+ *
+ * Topics covered:
+ *   - java.lang  (String, Math, System, Integer, StringBuilder)
+ *   - java.util  (ArrayList, HashMap, TreeMap, Collections, UUID, Date)
+ *   - java.time  (LocalDate, LocalDateTime, Duration) [Java 8+]
+ *   - javaImport shortcut
+ *
+ * Run:
+ *   node examples/05-stdlib.js
+ */
+
+const { startTestGateway } = require('./_gateway');
+
+async function main() {
+  console.log('Connecting to Java gateway...\n');
+  const { gateway, kill } = await startTestGateway();
+
+  try {
+    const jvm = gateway.jvm;
+
+    // -----------------------------------------------------------------------
+    // java.lang
+    // -----------------------------------------------------------------------
+    console.log('--- java.lang ---');
+
+    const sb = await jvm.java.lang.StringBuilder();
+    await sb.append('js4j');
+    await sb.append(' + ');
+    await sb.append('Java');
+    console.log('StringBuilder:', await sb.toString());
+
+    const strVal = await jvm.java.lang.String.valueOf(42);
+    console.log('String.valueOf(42): ', strVal);
+
+    console.log('Math.PI:  ', await gateway.getField(jvm.java.lang.Math, 'PI'));
+    console.log('Math.exp(1.5):', await jvm.java.lang.Math.exp(1.5));
+    console.log('Math.floor(3.9):', await jvm.java.lang.Math.floor(3.9));
+    console.log('Math.log(Math.E):', await jvm.java.lang.Math.log(
+      await gateway.getField(jvm.java.lang.Math, 'E')
+    ));
+
+    const ms = await jvm.java.lang.System.currentTimeMillis();
+    console.log('System.currentTimeMillis:', ms);
+
+    console.log('Integer.MAX_VALUE:', await gateway.getField(jvm.java.lang.Integer, 'MAX_VALUE'));
+    console.log('Integer.toBinaryString(255):', await jvm.java.lang.Integer.toBinaryString(255));
+    console.log('Integer.toHexString(255):', await jvm.java.lang.Integer.toHexString(255));
+
+    // -----------------------------------------------------------------------
+    // java.util
+    // -----------------------------------------------------------------------
+    console.log('\n--- java.util ---');
+
+    const list = await jvm.java.util.ArrayList();
+    await list.add('cherry');
+    await list.add('apple');
+    await list.add('banana');
+    await jvm.java.util.Collections.sort(list);
+    console.log('Sorted ArrayList:', await list.toArray());
+
+    const map = await jvm.java.util.HashMap();
+    await map.put('x', 10);
+    await map.put('y', 20);
+    await map.put('z', 30);
+    console.log('HashMap size:  ', await map.size());
+    console.log('HashMap get x: ', await map.get('x'));
+
+    const tree = await jvm.java.util.TreeMap(map);
+    const keys = await tree.keySet();
+    console.log('TreeMap keys:  ', await keys.toArray());
+
+    const uuid = await jvm.java.util.UUID.randomUUID();
+    const uuidStr = await uuid.toString();
+    console.log('UUID:          ', uuidStr);
+    console.log('UUID version:  ', await uuid.version());
+
+    const nums = await jvm.java.util.ArrayList();
+    await nums.add(5); await nums.add(3); await nums.add(9); await nums.add(1); await nums.add(7);
+    console.log('max of [5,3,9,1,7]:', await jvm.java.util.Collections.max(nums));
+    console.log('min of [5,3,9,1,7]:', await jvm.java.util.Collections.min(nums));
+
+    // -----------------------------------------------------------------------
+    // java.time  (Java 8+)
+    // -----------------------------------------------------------------------
+    console.log('\n--- java.time ---');
+
+    const today = await jvm.java.time.LocalDate.now();
+    console.log('LocalDate.now():', await today.toString());
+
+    const fixed = await jvm.java.time.LocalDate.of(2000, 1, 1);
+    console.log('Year 2000:      ', await fixed.toString());
+
+    const duration = await jvm.java.time.Duration.ofHours(3);
+    console.log('Duration (3h):  ', await duration.toString());
+    console.log('In minutes:     ', await duration.toMinutes());
+
+    // -----------------------------------------------------------------------
+    // javaImport — shortcut access
+    // -----------------------------------------------------------------------
+    console.log('\n--- javaImport shortcut ---');
+
+    await gateway.javaImport('java.util.LinkedList');
+    const linked = await jvm.LinkedList();
+    await linked.add('first');
+    await linked.add('second');
+    await linked.addFirst('zeroth');
+    console.log('LinkedList:', await linked.toArray());
+
+  } finally {
+    await kill();
+    console.log('\nGateway shut down.');
+  }
+}
+
+main().catch((err) => { console.error(err.message); process.exit(1); });

package/examples/_gateway.js

@@ -0,0 +1,78 @@
+'use strict';
+
+/**
+ * Shared helper used by all examples.
+ *
+ * Locates the py4j JAR, compiles TestEntryPoint.java if needed,
+ * then launches the gateway and returns { gateway, kill }.
+ *
+ * Set PY4J_JAR=/path/to/py4j.jar if auto-detection fails.
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { launchGateway } = require('../src/launcher');
+
+const ROOT      = path.resolve(__dirname, '..');
+const JAVA_DIR  = path.join(ROOT, 'java');
+const BUILD_DIR = path.join(JAVA_DIR, 'build');
+
+function findPy4jJar() {
+  if (process.env.PY4J_JAR) return process.env.PY4J_JAR;
+
+  // Common system install locations
+  const fixed = [
+    '/usr/share/py4j/py4j.jar',
+    '/usr/local/share/py4j/py4j.jar',
+  ];
+  for (const p of fixed) {
+    if (fs.existsSync(p)) return p;
+  }
+
+  // pip install py4j puts the JAR next to the Python package
+  try {
+    const site = execSync(
+      'python3 -c "import py4j, os; print(os.path.dirname(py4j.__file__))"',
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    ).trim();
+    const libDir = path.join(site, 'java', 'lib');
+    if (fs.existsSync(libDir)) {
+      const jar = fs.readdirSync(libDir).find(f => f.endsWith('.jar'));
+      if (jar) return path.join(libDir, jar);
+    }
+  } catch (_) {}
+
+  return null;
+}
+
+function buildIfNeeded(jar) {
+  const cls = path.join(BUILD_DIR, 'TestEntryPoint.class');
+  if (fs.existsSync(cls)) return; // already built
+
+  console.log('Compiling TestEntryPoint.java...');
+  fs.mkdirSync(BUILD_DIR, { recursive: true });
+  execSync(
+    `javac -cp "${jar}" -d "${BUILD_DIR}" "${path.join(JAVA_DIR, 'TestEntryPoint.java')}"`,
+    { stdio: 'inherit' }
+  );
+  console.log('Compiled.\n');
+}
+
+async function startTestGateway() {
+  const jar = findPy4jJar();
+  if (!jar) {
+    throw new Error(
+      'py4j JAR not found. Install py4j (pip install py4j) or set PY4J_JAR=/path/to/py4j.jar'
+    );
+  }
+
+  buildIfNeeded(jar);
+
+  return launchGateway({
+    classpath: `${BUILD_DIR}${path.delimiter}${jar}`,
+    mainClass: 'TestEntryPoint',
+  });
+}
+
+module.exports = { startTestGateway };