org.apidesign.vm4brwsr

## Class Bck2Brwsr

- java.lang.Object
- - org.apidesign.vm4brwsr.Bck2Brwsr

-     public final class Bck2Brwsr
      extends Object

  Build your own virtual machine! Use methods in this class to generate a skeleton JVM in JavaScript that contains pre-compiled classes of your choice:

       Writer w = new StringWriter();
       Bck2Brwsr.newCompiler()
         .resources(org.apidesign.vm4brwsr.Bck2Brwsr.Resources)
         .addRootClasses(java.lang.String...)
         .addClasses(java.lang.String...)
         .addExported(java.lang.String...)
         .generate(w);
       System.out.print(w.toString());

  The generated script defines one JavaScript method that can be used to bootstrap and load the virtual machine:

       var vm = bck2brwsr();
       var main = vm.loadClass('org.your.pkg.Main');
       main.invoke('main');

  In case one wants to initialize the virtual machine with ability to load classes lazily when needed, one can provide a loader function to when creating the virtual machine:

       var vm = bck2brwsr(function(resource) {
         return null; // byte[] for the resource
       });

  In this scenario, when a request for an unknown class is made, the loader function is asked for its byte code and the system dynamically transforms it to JavaScript.

  Instead of a loader function, one can also provide a URL to a JAR file or a library JavaScript file generated with `library(java.lang.String...)` option on. The `bck2brwsr` system will do its best to download the file and provide loader function for it automatically. In order to use the JAR file `emul.zip` module needs to be available in the system.

  One can provide as many loader functions and URL references as necessary. Then the initialization code would look like:

       var vm = bck2brwsr(url1, url2, fnctn1, url3, functn2);

  The provided URLs and loader functions will be consulted one by one.

  The initialization of the Bck2Brwsr is done asynchronously since version 0.9. E.g. call to

       var vm = bck2brwsr('myapp.js');
       var main = vm.loadClass('org.your.pkg.Main');
       main.invoke('main');

  returns immediately and the call to the static main method will happen once the virtual machine is initialized and the class available.
  Author:
    Jaroslav Tulach

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `Bck2Brwsr.Resources` Provider of resources (classes and other files).

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Bck2Brwsr` | `addClasses(String... classes)` Adds additional classes to the list of those that should be included in the generated JavaScript file.
    `Bck2Brwsr` | `addExported(String... exported)` Adds exported classes or packages.
    `Bck2Brwsr` | `addResources(String... resources)` These resources should be made available in the compiled file in binary form.
    `Bck2Brwsr` | `addRootClasses(String... classes)` Adds additional classes to the list of those that should be included in the generated JavaScript file.
    `void` | `generate(Appendable out)` Generates virtual machine based on previous configuration of the compiler.
    `static void` | `generate(Appendable out, Bck2Brwsr.Resources resources, String... classes)` Helper method to generate virtual machine from bytes served by a `resources` provider.
    `static void` | `generate(Appendable out, ClassLoader loader, String... classes)` Helper method to generate virtual machine from bytes served by a class loader.
    `Bck2Brwsr` | `library(String... classpath)` Should one generate a library? By default the system generates all transitive classes needed by the the transitive closure of `addRootClasses(java.lang.String...)` and `addClasses(java.lang.String...)`.
    `static Bck2Brwsr` | `newCompiler()` Creates new instance of Bck2Brwsr compiler which is ready to generate empty Bck2Brwsr virtual machine.
    `Bck2Brwsr` | `obfuscation(ObfuscationLevel level)` Changes the obfuscation level for the compiler by creating new instance which inherits all values from `this` and adjust the level of obfuscation.
    `Bck2Brwsr` | `resources(Bck2Brwsr.Resources res)` A way to change the provider of additional resources (classes) for the compiler.
    `Bck2Brwsr` | `resources(ClassLoader loader)` A way to change the provider of additional resources (classes) for the compiler by specifying classloader to use for loading them.
    `Bck2Brwsr` | `resources(ClassLoader loader, boolean ignoreBootClassPath)` A way to change the provider of additional resources (classes) for the compiler by specifying classloader to use for loading them.
    `Bck2Brwsr` | `standalone(boolean includeVM)` Turns on the standalone mode.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### generate

          public static void generate(Appendable out,
                                      Bck2Brwsr.Resources resources,
                                      String... classes)
                               throws IOException

      Helper method to generate virtual machine from bytes served by a `resources` provider.
      Parameters:
        `out` - the output to write the generated JavaScript to
        `resources` - provider of class files to use
        `classes` - additional classes to include in the generated script
      Throws:
        `IOException` - I/O exception can be thrown when something goes wrong

    - #### generate

          public static void generate(Appendable out,
                                      ClassLoader loader,
                                      String... classes)
                               throws IOException

      Helper method to generate virtual machine from bytes served by a class loader.
      Parameters:
        `out` - the output to write the generated JavaScript to
        `loader` - class loader to load needed classes from
        `classes` - additional classes to include in the generated script
      Throws:
        `IOException` - I/O exception can be thrown when something goes wrong

    - #### newCompiler

          public static Bck2Brwsr newCompiler()

      Creates new instance of Bck2Brwsr compiler which is ready to generate empty Bck2Brwsr virtual machine. The instance can be further configured by calling chain of methods. For example:

           newCompiler().resources(loader).addRootClasses("your/Clazz").generate(out);

      Returns:
        new instance of the Bck2Brwsr compiler
      Since:
        0.5

    - #### addExported

          public Bck2Brwsr addExported(String... exported)

      Adds exported classes or packages. If the string ends with slash, it is considered a name of package. If it does not, it is a name of a class (without `.class` suffix). The exported classes are prevented from being obfuscated. All public classes in exported packages are prevented from being obfuscated. By listing the packages or classes in this method, these classes are not guaranteed to be included in the generated script. Use `addClasses(java.lang.String...)` to include the classes.
      Parameters:
        `exported` - names of classes and packages to treat as exported
      Returns:
        new instances of the Bck2Brwsr compiler which inherits all values from `this` except list of exported classes

    - #### addRootClasses

          public Bck2Brwsr addRootClasses(String... classes)

      Adds additional classes to the list of those that should be included in the generated JavaScript file. These classes are guaranteed to be available in the generated virtual machine code accessible using their fully qualified name. This brings the same behavior as if the classes were added by `addClasses(java.lang.String...)` and exported via `addExported(java.lang.String...)`.
      Parameters:
        `classes` - the classes to add to the compilation
      Returns:
        new instance of the Bck2Brwsr compiler which inherits all values from `this`

    - #### addClasses

          public Bck2Brwsr addClasses(String... classes)

      Adds additional classes to the list of those that should be included in the generated JavaScript file. These classes are guaranteed to be present, but they may not be accessible through their fully qualified name.
      Parameters:
        `classes` - the classes to add to the compilation
      Returns:
        new instance of the Bck2Brwsr compiler which inherits all values from `this`
      Since:
        0.9

    - #### addResources

          public Bck2Brwsr addResources(String... resources)

      These resources should be made available in the compiled file in binary form. These resources can then be loaded by `ClassLoader.getResource(java.lang.String)` and similar methods.
      Parameters:
        `resources` - names of the resources to be loaded by `Bck2Brwsr.Resources.get(java.lang.String)`
      Returns:
        new instance of the Bck2Brwsr compiler which inherits all values from `this` just adds few more resource names for processing
      Since:
        0.9

    - #### obfuscation

          public Bck2Brwsr obfuscation(ObfuscationLevel level)

      Changes the obfuscation level for the compiler by creating new instance which inherits all values from `this` and adjust the level of obfuscation.
      Parameters:
        `level` - the new level of obfuscation
      Returns:
        new instance of the compiler with changed level of obfuscation
      Since:
        0.5

    - #### resources

          public Bck2Brwsr resources(Bck2Brwsr.Resources res)

      A way to change the provider of additional resources (classes) for the compiler.
      Parameters:
        `res` - the implementation of resources provider
      Returns:
        new instance of the compiler with all values remaining the same, just with different resources provider
      Since:
        0.5

    - #### library

          public Bck2Brwsr library(String... classpath)

      Should one generate a library? By default the system generates all transitive classes needed by the the transitive closure of `addRootClasses(java.lang.String...)` and `addClasses(java.lang.String...)`. By turning on the library mode, only classes explicitly listed will be included in the archive. The others will be referenced as external ones.

      A library archive may specify its classpath - e.g. link to other libraries that should also be included in the application. One can specify the list of libraries as vararg to this method. These are relative URL with respect to location of this library. The runtime system then prefers seek for ".js" suffix of the library and only then seeks for the classical ".jar" path.

      Parameters:
        `classpath` - the array of JARs that are referenced by this library, one can specify `library((String[])null)` to turn the library mode on, but keep the list of libraries unchanged
      Returns:
        new instance of the compiler with library flag changed
      Since:
        0.9

    - #### standalone

          public Bck2Brwsr standalone(boolean includeVM)

      Turns on the standalone mode. E.g. does the opposite of calling `library(java.lang.String...)`, but also allows to specify whether the Bck2Brwsr VM should be included at all. If not, only the skeleton of the launcher is generated without any additional VM classes referenced.
      Parameters:
        `includeVM` - should the VM be compiled in, or left out
      Returns:
        new instance of the compiler with standalone mode on
      Since:
        0.9

    - #### resources

          public Bck2Brwsr resources(ClassLoader loader)

      A way to change the provider of additional resources (classes) for the compiler by specifying classloader to use for loading them.
      Parameters:
        `loader` - class loader to load the resources from
      Returns:
        new instance of the compiler with all values being the same, just different resources provider
      Since:
        0.5

    - #### resources

          public Bck2Brwsr resources(ClassLoader loader,
                                     boolean ignoreBootClassPath)

      A way to change the provider of additional resources (classes) for the compiler by specifying classloader to use for loading them.
      Parameters:
        `loader` - class loader to load the resources from
        `ignoreBootClassPath` - `true` if classes loaded from `rt.jar`
      Returns:
        new instance of the compiler with all values being the same, just different resources provider
      Since:
        0.9

    - #### generate

          public void generate(Appendable out)
                        throws IOException

      Generates virtual machine based on previous configuration of the compiler.
      Parameters:
        `out` - the output to write the generated JavaScript to
      Throws:
        `IOException` - I/O exception can be thrown when something goes wrong
      Since:
        0.5

Copyright © 2025 API Design. All Rights Reserved.