Bck2Brwsr (Virtual Machine for Browser 1.0-SNAPSHOT API)

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).

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

Class Bck2Brwsr

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

generate

generate

newCompiler

addExported

addRootClasses

addClasses

addResources

obfuscation

resources

library

standalone

resources

resources

generate