java-bridge 2.2.3-beta.2 → 2.2.3

package/dist/native.d.ts

@@ -3,6 +3,16 @@
 
 /* auto-generated by NAPI-RS */
 
+/** Options for the interface proxies */
+export interface InterfaceProxyOptions {
+  /**
+   * If true, the proxy will be kept as a daemon
+   * proxy after the interface has been destroyed
+   */
+  keepAsDaemon?: boolean
+}
+/** Clears the list of daemon proxies. */
+export function clearDaemonProxies(): void
 /**
  * Options for the Java VM.
  * Not the same as vm arguments.
@@ -22,6 +32,10 @@ export interface JavaOptions {
  * Throws an error if the library could not be found.
  */
 export function getJavaLibPath(): string
+export class JavaInterfaceProxy {
+  get proxy(): object | null
+  reset(force?: boolean | undefined | null): void
+}
 /**
  * The main java class.
  * This should only be created once per process.
@@ -63,15 +77,15 @@ export class Java {
   appendClasspath(classpath: string | string[]): void
   /** Set the stdout/stderr callbacks */
   setStdoutCallbacks(stdoutCallback?: ((err: Error | null, data?: string) => void) | undefined | null, stderrCallback?: ((err: Error | null, data?: string) => void) | undefined | null): StdoutRedirect
-  createInterfaceProxy(classname: string, methods: Record<string, (err: null | Error, callback: (err: Error | null, data?: any | null) => void, ...args: any[]) => void>): JavaInterfaceProxy
+  createInterfaceProxy(classname: string, methods: Record<string, (err: null | Error, callback: (err: Error | null, data?: any | null) => void, ...args: any[]) => void>, options?: InterfaceProxyOptions | undefined | null): JavaInterfaceProxy
   /** Check if `this` is instance of `other` */
   isInstanceOf(thisObj: object, other: string | object): boolean
   get classLoader(): object
   set classLoader(classLoader: object)
 }
-export class JavaInterfaceProxy {
-  get proxy(): object
-  reset(): void
+export class JavaConfig {
+  static setRunEventLoopWhenInterfaceProxyIsActive(value: boolean): void
+  static getRunEventLoopWhenInterfaceProxyIsActive(): boolean
 }
 export class StdoutRedirect {
   on(event: string, callback?: ((...args: any[]) => any) | null): void

package/dist/ts-src/TypescriptDefinitionGenerator.d.ts

@@ -2,6 +2,7 @@ export interface MethodDeclaration {
     returnType: string;
     parameters: string[];
     isStatic: boolean;
+    isDefault: boolean;
 }
 /**
  * A java class declaration converted to typescript
@@ -41,8 +42,11 @@ export default class TypescriptDefinitionGenerator {
     private readonly progressCallback;
     private readonly resolvedImports;
     private usesBasicOrJavaType;
+    private usesNewProxy;
+    private usesInterfaceProxy;
     private readonly additionalImports;
     private readonly importsToResolve;
+    private readonly interfaceImports;
     /**
      * Create a new `TypescriptDefinitionGenerator` instance
      *
@@ -64,6 +68,9 @@ export default class TypescriptDefinitionGenerator {
     private convertParameter;
     private convertParameters;
     private static createMethodComment;
+    private createMethodSignature;
+    private createInterfaceMethodSignatures;
+    private createNewProxyMethod;
     private createMethod;
     private convertMethod;
     private getAdditionalImports;

package/dist/ts-src/index.d.ts

@@ -9,7 +9,7 @@ export type { internal };
 export * from './java';
 import * as java from './java';
 export default java;
-export { getJavaLibPath } from '../native';
+export { getJavaLibPath, InterfaceProxyOptions } from '../native';
 export { getJavaVersion, getJavaVersionSync } from './util';
 import TypescriptDefinitionGenerator from './TypescriptDefinitionGenerator';
 export { TypescriptDefinitionGenerator };

package/dist/ts-src/java.d.ts

@@ -1,5 +1,6 @@
-import { Java, JavaOptions } from '../native';
+import { InterfaceProxyOptions, Java, JavaOptions } from '../native';
 import { JavaClass, JavaClassConstructorType, JavaVersion, UnknownJavaClass, UnknownJavaClassType } from './definitions';
+export { clearDaemonProxies } from '../native';
 /**
  * Options for creating the Java VM.
  */
@@ -433,7 +434,12 @@ export declare namespace stdout {
  * ## See also
  * * {@link newProxy}
  */
-export interface JavaInterfaceProxy {
+export interface JavaInterfaceProxy<T extends ProxyRecord<T> = AnyProxyRecord> {
+    /**
+     * A dummy property to make sure the type is correct.
+     * This property will never be set.
+     */
+    _dummy?: T;
     /**
      * Destroy the proxy class.
      * After this call any call to any method defined by the
@@ -442,8 +448,11 @@ export interface JavaInterfaceProxy {
      * specifically implementing methods that will be called
      * from another (java) thread.
      * Throws an error if the proxy has already been destroyed.
+     *
+     * @param force whether to force the destruction of the proxy
+     * if it should be kept alive as a daemon
      */
-    reset(): void;
+    reset(force?: boolean): void;
 }
 /**
  * An interface proxy method.
@@ -454,6 +463,8 @@ export interface JavaInterfaceProxy {
  * @return the value to pass back to the java process
  */
 export type ProxyMethod = (...args: any[]) => any;
+export type ProxyRecord<T> = Partial<Record<keyof T, ProxyMethod>>;
+export type AnyProxyRecord = Record<string, ProxyMethod>;
 /**
  * Create a new java interface proxy.
  * This allows you to implement java interfaces in javascript.
@@ -551,16 +562,92 @@ export type ProxyMethod = (...args: any[]) => any;
  *   an exception will be thrown in the java process.
  * * Any errors thrown in the javascript process will be rethrown in the java process.
  *
+ * ### Possible deadlock warning
+ * When calling a java method that uses an interface defined by this, you must call
+ * that method using the interface asynchronously as Node.js is single threaded
+ * and can't wait for the java method to return while calling the proxy method at the
+ * same time.
+ *
+ * If you still want to call everything in a synchronous manner, make sure to enable
+ * running the event loop while waiting for a java method to return by setting
+ * {@link config.runEventLoopWhenInterfaceProxyIsActive} to true.
+ * **This may cause application crashes, so it is strongly recommended to just use async methods.**
+ *
+ * ### Keeping the proxy alive
+ * If you want to keep the proxy alive, you must keep this instance in scope.
+ * If that is not an option for you, you can manually keep the proxy alive
+ * by setting the {@link InterfaceProxyOptions}.keepAsDaemon option to true.
+ *
+ * ```ts
+ * const proxy = newProxy('java.lang.Runnable', {
+ *    run: (): void => {
+ *      console.log('Hello World!');
+ *    }
+ * }, {
+ *    keepAsDaemon: true
+ * });
+ *
+ * const TimeUnit = java.importClass('java.util.concurrent.TimeUnit');
+ * const ScheduledThreadPoolExecutor = java.importClass(
+ *     'java.util.concurrent.ScheduledThreadPoolExecutor'
+ * );
+ * const executor = new ScheduledThreadPoolExecutor(1);
+ *
+ * // 'proxy' will eventually be garbage collected,
+ * // but it will be kept alive due to this option.
+ * executor.scheduleAtFixedRateSync(proxy, 0, 1, TimeUnit.SECONDS);
+ * ```
+ *
+ * This will keep the proxy alive internally, thus the instance can be moved
+ * out of scope. However, this will also keep the JVM alive, so you should
+ * only use this if you are sure that you want to keep the JVM alive.
+ *
+ * If you want to destroy the proxy, you must call {@link clearDaemonProxies}.
+ * This will destroy all proxies which are kept alive by this option.
+ * Calling {@link JavaInterfaceProxy.reset} will not destroy a proxy
+ * kept alive by this option unless the force option is set to true.
+ *
  * ## See also
  * * {@link JavaInterfaceProxy}
+ * * {@link InterfaceProxyOptions}
  *
  * @param interfaceName the name of the java interface to implement
  * @param methods the methods to implement.
+ * @param opts the options to use
  * @returns a proxy class to pass back to the java process
  */
-export declare function newProxy(interfaceName: string, methods: Record<string, ProxyMethod>): JavaInterfaceProxy;
+export declare function newProxy<T extends ProxyRecord<T> = AnyProxyRecord>(interfaceName: string, methods: T, opts?: InterfaceProxyOptions): JavaInterfaceProxy<T>;
 /**
  * Get the static java instance.
  * This has no real use, all important methods are exported explicitly.
  */
 export declare function getJavaInstance(): Java | null;
+/**
+ * Configuration options for the java bridge.
+ */
+export declare class config {
+    /**
+     * **Experimental Feature**
+     *
+     * Set whether to run the event loop when an interface proxy is active.
+     * This is disabled by default. Enabling this will cause the bridge
+     * to run the event loop when an interface proxy either as direct
+     * proxy or as daemon proxy is active. This is only required if the
+     * proxied method calls back into the javascript process in the same thread.
+     * If the proxy is used either in an async method or in a different thread,
+     * this is not required.
+     *
+     * **Note:** Enabling this may cause the application to crash. Use with caution.
+     *
+     * @experimental
+     * @param value whether to run the event loop when an interface proxy is active
+     */
+    static set runEventLoopWhenInterfaceProxyIsActive(value: boolean);
+    /**
+     * **Experimental Feature**
+     *
+     * Get whether to run the event loop when an interface proxy is active.
+     * @experimental
+     */
+    static get runEventLoopWhenInterfaceProxyIsActive(): boolean;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "java-bridge",
-  "version": "2.2.3-beta.2",
+  "version": "2.2.3",
   "main": "dist/index.prod.min.js",
   "types": "dist/ts-src/index.d.ts",
   "description": "A bridge between Node.js and Java APIs",
@@ -56,8 +56,9 @@
     "build:java:win32": "cd java-src && .\\gradlew.bat shadowJar",
     "prepublishOnly": "napi prepublish -t npm",
     "test": "npm run testOnly",
-    "testOnly": "mocha -r ts-node/register test/*.test.ts --reporter mocha-multi-reporters --reporter-options configFile=mocha-reporter-config.json",
+    "testOnly": "npm run mocha",
     "pretestOnly": "npm run generateTestTypes",
+    "mocha": "mocha -r ts-node/register test/*.test.ts --reporter mocha-multi-reporters --reporter-options configFile=mocha-reporter-config.json",
     "pretest": "npm run build",
     "version": "napi version",
     "prettier": "prettier --write .",
@@ -73,29 +74,31 @@
     "glob": "^8.1.0",
     "ora": "^6.1.2",
     "typescript": "^4.9.5",
-    "yargs": "^17.6.2"
+    "yargs": "^17.7.1"
   },
   "devDependencies": {
-    "@napi-rs/cli": "^2.14.6",
+    "@napi-rs/cli": "^2.14.8",
     "@types/chai": "^4.3.4",
-    "@types/glob": "^8.0.1",
+    "@types/folder-hash": "^4.0.2",
+    "@types/glob": "^8.1.0",
     "@types/is-ci": "^3.0.0",
     "@types/mocha": "^10.0.1",
-    "@types/node": "^18.11.18",
+    "@types/node": "^18.14.1",
     "@types/semver": "^7.3.13",
-    "@types/webpack-node-externals": "^2.5.3",
-    "@types/which": "^2.0.1",
+    "@types/webpack-node-externals": "^3.0.0",
+    "@types/which": "^2.0.2",
     "@types/yargs": "^17.0.22",
     "chai": "^4.3.7",
     "cpy-cli": "^4.2.0",
     "expose-gc": "^1.0.0",
+    "folder-hash": "^4.0.4",
     "is-ci": "^3.0.1",
     "mocha": "^10.2.0",
     "mocha-junit-reporter": "^2.2.0",
     "mocha-multi-reporters": "^1.5.1",
     "nanobench": "^3.0.0",
     "node-loader": "^2.0.0",
-    "prettier": "^2.8.3",
+    "prettier": "^2.8.4",
     "rimraf": "^4.1.2",
     "run-script-os": "^1.1.6",
     "semver": "^7.3.8",
@@ -103,18 +106,18 @@
     "ts-loader": "^9.4.2",
     "ts-node": "^10.9.1",
     "tslib": "^2.5.0",
-    "typedoc": "^0.23.24",
+    "typedoc": "^0.23.25",
     "webpack": "^5.75.0",
     "webpack-cli": "^5.0.1",
     "webpack-node-externals": "^3.0.0",
     "which": "^3.0.0"
   },
   "optionalDependencies": {
-    "java-bridge-win32-x64-msvc": "2.2.3-beta.2",
-    "java-bridge-darwin-x64": "2.2.3-beta.2",
-    "java-bridge-linux-x64-gnu": "2.2.3-beta.2",
-    "java-bridge-darwin-arm64": "2.2.3-beta.2",
-    "java-bridge-win32-ia32-msvc": "2.2.3-beta.2",
-    "java-bridge-linux-arm64-gnu": "2.2.3-beta.2"
+    "java-bridge-win32-x64-msvc": "2.2.3",
+    "java-bridge-darwin-x64": "2.2.3",
+    "java-bridge-linux-x64-gnu": "2.2.3",
+    "java-bridge-darwin-arm64": "2.2.3",
+    "java-bridge-win32-ia32-msvc": "2.2.3",
+    "java-bridge-linux-arm64-gnu": "2.2.3"
   }
 }