java-bridge 2.3.0 → 2.5.0

package/dist/java.d.ts

@@ -1,6 +1,6 @@
-import { InterfaceProxyOptions, Java, JavaOptions } from '../native';
+import { InterfaceProxyOptions, Java, JavaOptions, JavaConfig, ClassConfiguration } from '../native';
 import { JavaClass, JavaClassConstructorType, JavaVersion, UnknownJavaClass, UnknownJavaClassType } from './definitions';
-export { clearDaemonProxies } from '../native';
+export { clearDaemonProxies, clearClassProxies, logging } from '../native';
 /**
  * Options for creating the Java VM.
  */
@@ -116,6 +116,14 @@ export declare function setClassLoader(classLoader: UnknownJavaClass): void;
  * constructor type of the class as the template parameter to get
  * the proper type returned. You could also just cast the result.
  *
+ * When passing a {@link ClassConfiguration} object, the config will be applied
+ * to this class. This config does not apply to any other class.
+ * If you want to change the config for all classes, use the
+ * {@link config} class in order to do that. Any undefined field
+ * in the config will be ignored and the default value will be used.
+ * If you want to change the sync and async suffixes to an empty string,
+ * you can pass an empty string as the suffix.
+ *
  * ## Examples
  * ### Import ``java.util.ArrayList`` and create a new instance of it
  * ```ts
@@ -130,10 +138,10 @@ export declare function setClassLoader(classLoader: UnknownJavaClass): void;
  *
  * ### Import ``java.util.ArrayList`` with types
  * ```ts
- * import { importClass, JavaClassInstance, JavaType } from 'java-bridge';
+ * import { importClass, JavaClass, JavaType } from 'java-bridge';
  *
  * // Definitions for class java.util.List
- * declare class List <T extends JavaType> extends JavaClassInstance {
+ * declare class List<T extends JavaType> extends JavaClass {
  *     size(): Promise<number>;
  *     sizeSync(): number;
  *     add(e: T): Promise<void>;
@@ -168,15 +176,36 @@ export declare function setClassLoader(classLoader: UnknownJavaClass): void;
  * assert.equals(list.getSync(1), 'World');
  * ```
  *
+ * ### Import ``java.util.ArrayList`` with custom config
+ * ```ts
+ * import { importClass, config } from 'java-bridge';
+ *
+ * // Import java.util.ArrayList with custom config
+ * const ArrayList = importClass('java.util.ArrayList', {
+ *    syncSuffix: '',
+ *    asyncSuffix: 'Async',
+ * });
+ *
+ * // Create a new instance of ArrayList
+ * const list = new ArrayList();
+ *
+ * // Call the async method
+ * await list.addAsync('Hello World!');
+ *
+ * // Call the sync method
+ * list.add('Hello World!');
+ * ```
+ *
  * @template T the type of the java class to import as a js type
  * @param classname the name of the class to resolve
+ * @param config the config to use when importing the class
  * @return the java class constructor
  */
-export declare function importClass<T extends JavaClassConstructorType = UnknownJavaClassType>(classname: string): T;
+export declare function importClass<T extends JavaClassConstructorType = UnknownJavaClassType>(classname: string, config?: ClassConfiguration): T;
 /**
  * @inheritDoc importClass
  */
-export declare function importClassAsync<T extends JavaClassConstructorType = UnknownJavaClassType>(classname: string): Promise<T>;
+export declare function importClassAsync<T extends JavaClassConstructorType = UnknownJavaClassType>(classname: string, config?: ClassConfiguration): Promise<T>;
 /**
  * Append a single or multiple jars to the class path.
  *
@@ -463,7 +492,14 @@ export interface JavaInterfaceProxy<T extends ProxyRecord<T> = AnyProxyRecord> {
  * @return the value to pass back to the java process
  */
 export type ProxyMethod = (...args: any[]) => any;
+/**
+ * A record of methods to implement.
+ * Useful for creating a proxy for a specific interface.
+ */
 export type ProxyRecord<T> = Partial<Record<keyof T, ProxyMethod>>;
+/**
+ * A generic proxy record.
+ */
 export type AnyProxyRecord = Record<string, ProxyMethod>;
 /**
  * Create a new java interface proxy.
@@ -558,6 +594,9 @@ export type AnyProxyRecord = Record<string, ProxyMethod>;
  * ## Notes
  * * Keep this instance in scope to not destroy the interface proxy.
  * * Call {@link JavaInterfaceProxy.reset} to instantly destroy this instance.
+ *   Please note that calling {@link JavaInterfaceProxy.reset} is not necessary,
+ *   the proxy instance will be automatically destroyed when it is garbage collected.
+ *   Calling {@link JavaInterfaceProxy.reset} will just speed up the process.
  * * If any method is queried by the java process and not implemented in here,
  *   an exception will be thrown in the java process.
  * * Any errors thrown in the javascript process will be rethrown in the java process.
@@ -570,7 +609,7 @@ export type AnyProxyRecord = Record<string, ProxyMethod>;
  *
  * 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.
+ * {@link JavaConfig.runEventLoopWhenInterfaceProxyIsActive} to true.
  * **This may cause application crashes, so it is strongly recommended to just use async methods.**
  *
  * ### Keeping the proxy alive
@@ -623,31 +662,6 @@ export declare function newProxy<T extends ProxyRecord<T> = AnyProxyRecord>(inte
  */
 export declare function getJavaInstance(): Java | null;
 /**
- * Configuration options for the java bridge.
+ * @inheritDoc JavaConfig
  */
-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;
-}
+export declare const config: JavaConfig;

package/dist/native.d.ts

@@ -3,6 +3,76 @@
 
 /* auto-generated by NAPI-RS */
 
+/**
+ * Configuration for the Java class proxy.
+ *
+ * @since 2.4.0
+ */
+export interface ClassConfiguration {
+  /**
+   * If true, the event loop will be run when an interface proxy is active.
+   * If not specified, the value from the global configuration will be used.
+   */
+  runEventLoopWhenInterfaceProxyIsActive?: boolean
+  /**
+   * If true, the custom inspect method will be used to display the object in the console.
+   * If not specified, the value from the global configuration will be used.
+   */
+  customInspect?: boolean
+  /**
+   * The suffix to use for synchronous methods.
+   * Set this value to an empty string to disable the suffix.
+   * The default value is "Sync".
+   * Setting this value to the same value as asyncSuffix will result in an error.
+   * If not specified, the value from the global configuration will be used.
+   */
+  syncSuffix?: string
+  /**
+   * The suffix to use for asynchronous methods.
+   * Set this value to an empty string to disable the suffix.
+   * The default value is an empty string.
+   * Setting this value to the same value as syncSuffix will result in an error.
+   * If not specified, the value from the global configuration will be used.
+   */
+  asyncSuffix?: string
+}
+/**
+ * Configuration for the Java class proxy.
+ *
+ * @since 2.4.0
+ */
+export interface Config {
+  /**
+   * If true, the event loop will be run when an interface proxy is active.
+   *
+   * @since 2.2.3
+   */
+  runEventLoopWhenInterfaceProxyIsActive: boolean
+  /**
+   * If true, the custom inspect method will be used to display the object in the console.
+   *
+   * @since 2.4.0
+   */
+  customInspect: boolean
+  /**
+   * The suffix to use for synchronous methods.
+   * Set this value to an empty string to disable the suffix.
+   * The default value is "Sync".
+   * Setting this value to the same value as asyncSuffix will result in an error.
+   *
+   * @since 2.4.0
+   */
+  syncSuffix?: string
+  /**
+   * The suffix to use for asynchronous methods.
+   * Set this value to an empty string to disable the suffix.
+   * The default value is an empty string.
+   * Setting this value to the same value as syncSuffix will result in an error.
+   *
+   * @since 2.4.0
+   */
+  asyncSuffix?: string
+}
 /** Options for the interface proxies */
 export interface InterfaceProxyOptions {
   /**
@@ -13,6 +83,14 @@ export interface InterfaceProxyOptions {
 }
 /** Clears the list of daemon proxies. */
 export function clearDaemonProxies(): void
+/**
+ * Clear the class proxy cache.
+ * Use this method in order to reset the config for all class proxies.
+ * The new config will be applied once the class is imported again.
+ *
+ * @since 2.4.0
+ */
+export function clearClassProxies(): void
 /**
  * Options for the Java VM.
  * Not the same as vm arguments.
@@ -54,13 +132,13 @@ export class Java {
    * Will import the class and parse all of its methods and fields.
    * The imported class will be cached for future use.
    */
-  importClass(className: string): object
+  importClass(className: string, config?: ClassConfiguration | undefined | null): object
   /**
    * Import a java class (async)
    * Will return a promise that resolves to the class instance.
    * @see importClass
    */
-  importClassAsync(className: string): Promise<object>
+  importClassAsync(className: string, config?: ClassConfiguration | undefined | null): Promise<object>
   /**
    * Get the wanted JVM version.
    * This may not match the actual JVM version.
@@ -83,11 +161,189 @@ export class Java {
   get classLoader(): object
   set classLoader(classLoader: object)
 }
+/**
+ * Configuration options for the java bridge.
+ *
+ * As of version 2.4.0, the options are cached inside the class proxy cache.
+ * This means that changing the options will not affect any class proxies
+ * that have already been created by importing a class using {@link importClass}
+ * or {@link importClassAsync}. You must clear the class proxy cache using the
+ * {@link clearClassProxies} method in order to apply the new options to all
+ * classes imported at a later date. This does not affect already instantiated
+ * or imported classes.
+ *
+ * Do not instantiate this class. Use the {@link default.config} instance instead.
+ *
+ * @since 2.2.3
+ */
 export class JavaConfig {
-  static setRunEventLoopWhenInterfaceProxyIsActive(value: boolean): void
-  static getRunEventLoopWhenInterfaceProxyIsActive(): boolean
+  /**
+   * Do not instantiate this class.
+   * Use the {@link default.config} instance instead.
+   */
+  constructor()
+  /**
+   * **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.
+   *
+   * @since 2.2.3
+   * @experimental
+   * @param value whether to run the event loop when an interface proxy is active
+   */
+  set runEventLoopWhenInterfaceProxyIsActive(value: boolean)
+  /**
+   * **Experimental Feature**
+   *
+   * Get whether to run the event loop when an interface proxy is active.
+   * @since 2.2.3
+   * @experimental
+   */
+  get runEventLoopWhenInterfaceProxyIsActive(): boolean
+  /**
+   * Whether to add custom inspect methods to java objects.
+   * This is disabled by default.
+   * This allows console.log to print java objects in a more readable way
+   * using the `toString` method of the java object.
+   *
+   * @since 2.4.0
+   * @param value whether to add custom inspect methods to java objects
+   */
+  set customInspect(value: boolean)
+  /**
+   * Get whether to add custom inspect methods to java objects.
+   *
+   * @since 2.4.0
+   * @returns whether to add custom inspect methods to java objects
+   */
+  get customInspect(): boolean
+  /**
+   * Set the suffix for synchronous methods.
+   * This is `Sync` by default.
+   * Pass `null` or an empty string to disable the suffix.
+   * This must not be the same as the {@link asyncSuffix}.
+   *
+   * This option does not affect standard methods of java classes
+   * like `toString`, `toStringSync`, `toStringAsync` and `newInstanceAsync`.
+   *
+   * ## Example
+   * ```ts
+   * import { config, clearClassProxies } from 'java-bridge';
+   *
+   * // Set the async suffix in order to prevent errors
+   * config.asyncSuffix = 'Async';
+   * // Set the sync suffix to an empty string
+   * config.syncSuffix = '';
+   * // This would do the same
+   * config.syncSuffix = null;
+   *
+   * // Clear the class proxy cache
+   * clearClassProxies();
+   *
+   * // Import the class
+   * const ArrayList = importClass('java.util.ArrayList');
+   *
+   * // Create a new instance
+   * const list = new ArrayList();
+   *
+   * // Call the method
+   * list.add('Hello World!');
+   *
+   * // Async methods now have the 'Async' suffix
+   * await list.addAsync('Hello World!');
+   * ```
+   *
+   * @see asyncSuffix
+   * @since 2.4.0
+   * @param value the suffix to use for synchronous methods
+   */
+  set syncSuffix(value: string | undefined | null)
+  /**
+   * Get the suffix for synchronous methods.
+   *
+   * @since 2.4.0
+   */
+  get syncSuffix(): string | null
+  /**
+   * Set the suffix for asynchronous methods.
+   * This is `Async` by default.
+   * Pass `null` or an empty string to disable the suffix.
+   * This must not be the same as the {@link syncSuffix}.
+   *
+   * This option does not affect standard methods of java classes
+   * like `toString`, `toStringSync`, `toStringAsync` and `newInstanceAsync`.
+   *
+   * @see syncSuffix
+   * @since 2.4.0
+   * @param value the suffix to use for asynchronous methods
+   */
+  set asyncSuffix(value: string | undefined | null)
+  /**
+   * Get the suffix for asynchronous methods.
+   *
+   * @since 2.4.0
+   */
+  get asyncSuffix(): string | null
+  /**
+   * Override the whole config.
+   * If you want to change only a single field, use the static setters instead.
+   *
+   * @since 2.4.0
+   * @param value the config to use
+   */
+  set config(value: Config)
+  /**
+   * Get the current config.
+   *
+   * @since 2.4.0
+   */
+  get config(): Config
+  /**
+   * Reset the config to the default values.
+   *
+   * @since 2.4.0
+   */
+  reset(): void
 }
 export class StdoutRedirect {
   on(event: string, callback?: ((...args: any[]) => any) | null): void
   reset(): void
 }
+export namespace logging {
+  /**
+   * This method is not supported in this build.
+   * It will print a warning to stderr when called.
+   *
+   * Re-compile the native module with the `log` feature to enable logging.
+   */
+  export function setLogCallbacks(out: ((data: string | null) => void) | null | undefined, err: ((data: string | null) => void) | null | undefined): void
+  /**
+   * This method is not supported in this build.
+   * It will print a warning to stderr when called.
+   *
+   * Re-compile the native module with the `log` feature to enable logging.
+   */
+  export function initLogger(path: string): void
+  /**
+   * This method is not supported in this build.
+   * It will print a warning to stderr when called.
+   *
+   * Re-compile the native module with the `log` feature to enable logging.
+   */
+  export function resetLogCallbacks(): void
+  /**
+   * Whether logging is supported.
+   * Logging is disabled by default.
+   * This constant currently is set to `false`
+   * as logging is not supported in this build.
+   */
+  export const LOGGING_SUPPORTED: boolean
+}

package/dist/nativeLib.d.ts

@@ -1,2 +1,2 @@
 export declare function getNativeLibPath(isPackagedElectron: boolean): string;
-export declare function getJavaLibPath(isPackagedElectron: boolean): string;
+export declare function getJavaLibPath(): string;