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

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 - by default gets turned into

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