jaroslav@298: /** jaroslav@298: * Back 2 Browser Bytecode Translator jaroslav@298: * Copyright (C) 2012 Jaroslav Tulach jaroslav@298: * jaroslav@298: * This program is free software: you can redistribute it and/or modify jaroslav@298: * it under the terms of the GNU General Public License as published by jaroslav@298: * the Free Software Foundation, version 2 of the License. jaroslav@298: * jaroslav@298: * This program is distributed in the hope that it will be useful, jaroslav@298: * but WITHOUT ANY WARRANTY; without even the implied warranty of jaroslav@298: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the jaroslav@298: * GNU General Public License for more details. jaroslav@298: * jaroslav@298: * You should have received a copy of the GNU General Public License jaroslav@298: * along with this program. Look for COPYING file in the top folder. jaroslav@298: * If not, see http://opensource.org/licenses/GPL-2.0. jaroslav@298: */ jaroslav@298: package org.apidesign.vm4brwsr; jaroslav@298: jaroslav@298: import java.io.IOException; jaroslav@298: import java.io.InputStream; jaroslav@298: jaroslav@298: /** Build your own virtual machine! Use methods in this class to generate jaroslav@298: * a skeleton JVM in JavaScript that contains pre-compiled classes of your jaroslav@298: * choice. The generated script defines one JavaScript method that can jaroslav@298: * be used to bootstrap and load the virtual machine: 
jaroslav@298:  * var vm = bck2brwsr();
jaroslav@298:  * var main = vm.loadClass('org.your.pkg.Main');
jaroslav@298:  * main.main__V_3Ljava_lang_String_2(null);
jaroslav@298:  *
jaroslav@298: * In case one wants to initialize the virtual machine with ability to jaroslav@298: * load classes lazily when needed, one can provide a loader function to jaroslav@298: * when creating the virtual machine: 
jaroslav@298:  * var vm = bck2brwsr(function(resource) { 
jaroslav@298:  *   return null; // byte[] for the resource
jaroslav@298:  * });
jaroslav@298:  *
jaroslav@424: * In this scenario, when a request for an unknown class is made, the loader jaroslav@298: * function is asked for its byte code and the system dynamically transforms jaroslav@298: * it to JavaScript. jaroslav@729: *

jaroslav@729: * Instead of a loader function, one can also provide a URL to a JAR file. jaroslav@729: * The bck2brwsr system will do its best to download the file jaroslav@729: * and provide loader function for it automatically. jaroslav@729: *

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

jaroslav@729:  * var vm = bck2brwsr(url1, url2, fnctn1, url3, functn2);
jaroslav@729:  *
jaroslav@729: * The provided URLs and loader functions will be consulted one by one. jaroslav@298: * jaroslav@298: * @author Jaroslav Tulach jaroslav@298: */ jaroslav@298: public final class Bck2Brwsr { jaroslav@874: private final ObfuscationLevel level; jaroslav@1583: private final StringArray exported; jaroslav@874: private final StringArray classes; jaroslav@1493: private final StringArray resources; jaroslav@874: private final Resources res; jaroslav@1584: private final Boolean extension; jaroslav@1604: private final StringArray classpath; jaroslav@874: jaroslav@1584: private Bck2Brwsr( jaroslav@1604: ObfuscationLevel level, jaroslav@1604: StringArray exported, StringArray classes, StringArray resources, jaroslav@1604: Resources res, jaroslav@1604: Boolean extension, StringArray classpath jaroslav@1584: ) { jaroslav@874: this.level = level; jaroslav@1583: this.exported = exported; jaroslav@874: this.classes = classes; jaroslav@1493: this.resources = resources; jaroslav@1493: this.res = res; lubomir@1029: this.extension = extension; jaroslav@1604: this.classpath = classpath; jaroslav@298: } jaroslav@874: jaroslav@874: /** Helper method to generate virtual machine from bytes served by a resources jaroslav@298: * provider. lubomir@849: * jaroslav@298: * @param out the output to write the generated JavaScript to jaroslav@298: * @param resources provider of class files to use jaroslav@298: * @param classes additional classes to include in the generated script jaroslav@298: * @throws IOException I/O exception can be thrown when something goes wrong jaroslav@298: */ jaroslav@298: public static void generate(Appendable out, Resources resources, String... classes) throws IOException { jaroslav@874: newCompiler().resources(resources).addRootClasses(classes).generate(out); lubomir@849: } lubomir@849: jaroslav@874: /** Helper method to generate virtual machine from bytes served by a class loader. lubomir@849: * lubomir@849: * @param out the output to write the generated JavaScript to lubomir@849: * @param loader class loader to load needed classes from lubomir@849: * @param classes additional classes to include in the generated script lubomir@849: * @throws IOException I/O exception can be thrown when something goes wrong lubomir@849: */ lubomir@849: public static void generate(Appendable out, ClassLoader loader, String... classes) throws IOException { jaroslav@874: newCompiler().resources(loader).addRootClasses(classes).generate(out); jaroslav@874: } jaroslav@874: jaroslav@874: /** Creates new instance of Bck2Brwsr compiler which is ready to generate jaroslav@874: * empty Bck2Brwsr virtual machine. The instance can be further jaroslav@874: * configured by calling chain of methods. For example: jaroslav@874: * 
jaroslav@874:      * {@link #createCompiler()}.{@link #resources(org.apidesign.vm4brwsr.Bck2Brwsr.Resources) resources(loader)}.{@link #addRootClasses(java.lang.String[]) addRootClasses("your/Clazz")}.{@link #generate(java.lang.Appendable) generate(out)};
jaroslav@874:      *
jaroslav@874: * jaroslav@874: * @return new instance of the Bck2Brwsr compiler jaroslav@874: * @since 0.5 jaroslav@874: */ jaroslav@874: public static Bck2Brwsr newCompiler() { jaroslav@1604: return new Bck2Brwsr( jaroslav@1604: ObfuscationLevel.NONE, jaroslav@1604: new StringArray(), new StringArray(), new StringArray(), jaroslav@1604: null, false, null jaroslav@1604: ); lubomir@849: } jaroslav@1583: jaroslav@1583: /** Adds exported classes or packages. If the string ends jaroslav@1583: * with slash, it is considered a name of package. If it does not, jaroslav@1583: * it is a name of a class (without .class suffix). jaroslav@1583: * The exported classes are prevented from being obfuscated. jaroslav@1583: * All public classes in exported packages are prevented from jaroslav@1583: * being obfuscated. By listing the packages or classes in this jaroslav@1583: * method, these classes are not guaranteed to be included in jaroslav@1583: * the generated script. Use {@link #addClasses} to include jaroslav@1583: * the classes. jaroslav@1583: * jaroslav@1583: * @param exported names of classes and packages to treat as exported jaroslav@1583: * @return new instances of the Bck2Brwsr compiler which inherits jaroslav@1583: * all values from this except list of exported classes jaroslav@1583: */ jaroslav@1583: public Bck2Brwsr addExported(String... exported) { jaroslav@1583: return new Bck2Brwsr( jaroslav@1583: level, this.exported.addAndNew(exported), jaroslav@1604: classes, resources, res, extension, classpath jaroslav@1583: ); jaroslav@1583: } lubomir@849: jaroslav@1491: /** Adds additional classes jaroslav@1491: * to the list of those that should be included in the generated jaroslav@1491: * JavaScript file. jaroslav@1491: * These classes are guaranteed to be available in the jaroslav@1491: * generated virtual machine code accessible using their fully jaroslav@1491: * qualified name. This brings the same behavior as if the jaroslav@1491: * classes were added by {@link #addClasses(java.lang.String...) } and jaroslav@1583: * exported via {@link #addExported(java.lang.String...)}. jaroslav@874: * jaroslav@874: * @param classes the classes to add to the compilation jaroslav@1491: * @return new instance of the Bck2Brwsr compiler which inherits jaroslav@1491: * all values from this jaroslav@874: */ jaroslav@874: public Bck2Brwsr addRootClasses(String... classes) { jaroslav@874: if (classes.length == 0) { jaroslav@874: return this; jaroslav@1583: } jaroslav@1583: return addExported(classes).addClasses(classes); jaroslav@874: } jaroslav@874: jaroslav@1491: /** Adds additional classes jaroslav@1491: * to the list of those that should be included in the generated jaroslav@1491: * JavaScript file. These classes are guaranteed to be present, jaroslav@1491: * but they may not be accessible through their fully qualified jaroslav@1491: * name. jaroslav@1491: * jaroslav@1491: * @param classes the classes to add to the compilation jaroslav@1491: * @return new instance of the Bck2Brwsr compiler which inherits jaroslav@1491: * all values from this jaroslav@1491: * @since 0.9 jaroslav@1491: */ jaroslav@1491: public Bck2Brwsr addClasses(String... classes) { jaroslav@1491: if (classes.length == 0) { jaroslav@1491: return this; jaroslav@1491: } else { jaroslav@1583: return new Bck2Brwsr(level, exported, jaroslav@1583: this.classes.addAndNew(classes), resources, res, jaroslav@1604: extension, classpath); jaroslav@1491: } jaroslav@1491: } jaroslav@1491: jaroslav@1493: /** These resources should be made available in the compiled file in jaroslav@1493: * binary form. These resources can then be loaded jaroslav@1493: * by {@link ClassLoader#getResource(java.lang.String)} and similar jaroslav@1493: * methods. jaroslav@1493: * jaroslav@1493: * @param resources names of the resources to be loaded by {@link Resources#get(java.lang.String)} jaroslav@1493: * @return new instance of the Bck2Brwsr compiler which inherits jaroslav@1493: * all values from this just adds few more resource names jaroslav@1493: * for processing jaroslav@1493: * @since 0.9 jaroslav@1493: */ jaroslav@1493: public Bck2Brwsr addResources(String... resources) { jaroslav@1493: if (resources.length == 0) { jaroslav@1493: return this; jaroslav@1493: } else { jaroslav@1583: return new Bck2Brwsr(level, exported, this.classes, jaroslav@1604: this.resources.addAndNew(resources), res, extension, classpath jaroslav@1493: ); jaroslav@874: } jaroslav@874: } jaroslav@874: jaroslav@874: /** Changes the obfuscation level for the compiler by creating new instance jaroslav@874: * which inherits all values from this and adjust the level jaroslav@874: * of obfuscation. jaroslav@874: * jaroslav@874: * @param level the new level of obfuscation jaroslav@874: * @return new instance of the compiler with changed level of obfuscation jaroslav@874: * @since 0.5 jaroslav@874: */ jaroslav@874: public Bck2Brwsr obfuscation(ObfuscationLevel level) { jaroslav@1604: return new Bck2Brwsr(level, exported, classes, resources, res, extension, classpath); jaroslav@874: } jaroslav@874: jaroslav@874: /** A way to change the provider of additional resources (classes) for the jaroslav@874: * compiler. jaroslav@874: * jaroslav@874: * @param res the implementation of resources provider jaroslav@874: * @return new instance of the compiler with all values remaining the same, just jaroslav@874: * with different resources provider jaroslav@874: * @since 0.5 jaroslav@874: */ jaroslav@874: public Bck2Brwsr resources(Resources res) { jaroslav@1604: return new Bck2Brwsr( jaroslav@1604: level, exported, classes, resources, jaroslav@1604: res, extension, classpath jaroslav@1604: ); lubomir@1029: } lubomir@1029: jaroslav@1491: /** Should one generate a library? By default the system generates jaroslav@1491: * all transitive classes needed by the the transitive closure of jaroslav@1491: * {@link #addRootClasses(java.lang.String...)} and {@link #addClasses(java.lang.String...)}. jaroslav@1491: * By turning on the library mode, only classes explicitly listed jaroslav@1491: * will be included in the archive. The others will be referenced jaroslav@1491: * as external ones. jaroslav@1604: *

jaroslav@1604: * A library archive may specify its classpath - e.g. link to jaroslav@1604: * other libraries that should also be included in the application. jaroslav@1604: * One can specify the list of libraries as vararg to this method. jaroslav@1604: * These are relative URL with respect to location of this library. jaroslav@1604: * The runtime system then prefers seek for ".js" suffix of the library jaroslav@1604: * and only then seeks for the classical ".jar" path. jaroslav@1491: * jaroslav@1604: * @param classpath the array of JARs that are referenced by this library - jaroslav@1604: * by default gets turned into jaroslav@1491: * @return new instance of the compiler with library flag changed jaroslav@1491: * @since 0.9 jaroslav@1491: */ jaroslav@1604: public Bck2Brwsr library(String... classpath) { jaroslav@1604: return new Bck2Brwsr( jaroslav@1604: level, exported, classes, jaroslav@1604: resources, res, true, jaroslav@1604: StringArray.asList(classpath) jaroslav@1604: ); jaroslav@874: } jaroslav@1584: jaroslav@1584: /** Turns on the standalone mode. E.g. acts like {@link #library(boolean) library(false)}, jaroslav@1584: * but also allows to specify whether the Bck2Brwsr VM should jaroslav@1584: * be included at all. If not, only the skeleton of the launcher is jaroslav@1584: * generated without any additional VM classes referenced. jaroslav@1584: * jaroslav@1584: * @param includeVM should the VM be compiled in, or left out jaroslav@1584: * @return new instance of the compiler with standalone mode on jaroslav@1584: * @since 0.9 jaroslav@1584: */ jaroslav@1584: public Bck2Brwsr standalone(boolean includeVM) { jaroslav@1604: return new Bck2Brwsr( jaroslav@1604: level, exported, classes, resources, jaroslav@1604: res, includeVM ? false : null, null jaroslav@1604: ); jaroslav@1584: } jaroslav@874: jaroslav@874: /** A way to change the provider of additional resources (classes) for the jaroslav@874: * compiler by specifying classloader to use for loading them. jaroslav@874: * jaroslav@874: * @param loader class loader to load the resources from jaroslav@874: * @return new instance of the compiler with all values being the same, just jaroslav@874: * different resources provider jaroslav@874: * @since 0.5 jaroslav@874: */ jaroslav@874: public Bck2Brwsr resources(final ClassLoader loader) { jaroslav@1365: return resources(loader, false); jaroslav@1365: } jaroslav@1365: jaroslav@1365: /** A way to change the provider of additional resources (classes) for the jaroslav@1365: * compiler by specifying classloader to use for loading them. jaroslav@1365: * jaroslav@1365: * @param loader class loader to load the resources from jaroslav@1365: * @param ignoreBootClassPath true if classes loaded jaroslav@1365: * from rt.jar jaroslav@1365: * @return new instance of the compiler with all values being the same, just jaroslav@1365: * different resources provider jaroslav@1365: * @since 0.9 jaroslav@1365: */ jaroslav@1365: public Bck2Brwsr resources(final ClassLoader loader, boolean ignoreBootClassPath) { jaroslav@1365: return resources(new LdrRsrcs(loader, ignoreBootClassPath)); jaroslav@874: } jaroslav@874: jaroslav@874: /** Generates virtual machine based on previous configuration of the jaroslav@874: * compiler. lubomir@849: * lubomir@849: * @param out the output to write the generated JavaScript to lubomir@860: * @since 0.5 lubomir@849: */ jaroslav@874: public void generate(Appendable out) throws IOException { jaroslav@874: if (level != ObfuscationLevel.NONE) { lubomir@849: try { jaroslav@1493: ClosureWrapper.produceTo(out, level, this); lubomir@849: return; lubomir@849: } catch (IOException ex) { lubomir@849: throw ex; lubomir@849: } catch (Throwable ex) { lubomir@849: out.append("/* Failed to obfuscate: " + ex.getMessage() lubomir@849: + " */\n"); lubomir@849: } jaroslav@750: } lubomir@849: jaroslav@1493: VM.compile(out, this); jaroslav@298: } jaroslav@298: jaroslav@1493: // jaroslav@1493: // Internal getters jaroslav@1493: // jaroslav@1493: jaroslav@1493: Resources getResources() { jaroslav@1513: return res != null ? res : new LdrRsrcs(Bck2Brwsr.class.getClassLoader(), false); jaroslav@1493: } jaroslav@1493: jaroslav@1495: StringArray allResources() { jaroslav@1495: return resources; jaroslav@1495: } jaroslav@1495: jaroslav@1583: StringArray classes() { jaroslav@1583: return classes; jaroslav@1583: } jaroslav@1583: jaroslav@1583: StringArray exported() { jaroslav@1583: return exported; jaroslav@1493: } jaroslav@1493: jaroslav@1493: boolean isExtension() { jaroslav@1584: return Boolean.TRUE.equals(extension); jaroslav@1584: } jaroslav@1584: jaroslav@1584: boolean includeVM() { jaroslav@1584: return extension != null; jaroslav@874: } jaroslav@1604: jaroslav@1604: StringArray classpath() { jaroslav@1604: return classpath; jaroslav@1604: } lubomir@1086: jaroslav@298: /** Provider of resources (classes and other files). The jaroslav@298: * {@link #generate(java.lang.Appendable, org.apidesign.vm4brwsr.Bck2Brwsr.Resources, java.lang.String[]) jaroslav@298: * generator method} will call back here for all classes needed during jaroslav@298: * translation to JavaScript. jaroslav@298: */ jaroslav@298: public interface Resources { jaroslav@298: /** Loads given resource (class or other file like image). The jaroslav@298: * resource name to load bytes for the {@link String} class jaroslav@298: * would be "java/lang/String.class". jaroslav@298: * jaroslav@298: * @param resource path to resource to load jaroslav@298: * @return the input stream for the resource jaroslav@298: * @throws IOException can be thrown if the loading fails on some error jaroslav@298: * or the file cannot be found jaroslav@298: */ jaroslav@298: public InputStream get(String resource) throws IOException; jaroslav@298: } jaroslav@298: }