jaroslav@298: /**
jaroslav@298:  * Back 2 Browser Bytecode Translator
jaroslav@298:  * Copyright (C) 2012 Jaroslav Tulach <jaroslav.tulach@apidesign.org>
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: <pre>
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:  * </pre>
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: <pre>
jaroslav@298:  * var vm = bck2brwsr(function(resource) { 
jaroslav@298:  *   return null; // byte[] for the resource
jaroslav@298:  * });
jaroslav@298:  * </pre>
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:  * <p>
jaroslav@729:  * Instead of a loader function, one can also provide a URL to a JAR file.
jaroslav@729:  * The <code>bck2brwsr</code> system will do its best to download the file
jaroslav@729:  * and provide loader function for it automatically.
jaroslav@729:  * <p>
jaroslav@729:  * One can provide as many loader functions and JAR URL references as necessary.
jaroslav@729:  * Then the initialization code would look like:<pre>
jaroslav@729:  * var vm = bck2brwsr(url1, url2, fnctn1, url3, functn2);
jaroslav@729:  * </pre>
jaroslav@729:  * The provided URLs and loader functions will be consulted one by one.
jaroslav@298:  *
jaroslav@298:  * @author Jaroslav Tulach <jtulach@netbeans.org>
jaroslav@298:  */
jaroslav@298: public final class Bck2Brwsr {
jaroslav@874:     private final ObfuscationLevel level;
jaroslav@874:     private final StringArray classes;
jaroslav@874:     private final Resources res;
jaroslav@874: 
jaroslav@874:     private Bck2Brwsr(ObfuscationLevel level, StringArray classes, Resources resources) {
jaroslav@874:         this.level = level;
jaroslav@874:         this.classes = classes;
jaroslav@874:         this.res = resources;
jaroslav@298:     }
jaroslav@874:     
jaroslav@874:     /** Helper method to generate virtual machine from bytes served by a <code>resources</code>
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:      * <pre>
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:      * </pre>
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@874:         StringArray arr = StringArray.asList(VM.class.getName().replace('.', '/'));
jaroslav@874:         return new Bck2Brwsr(ObfuscationLevel.NONE, arr, null);
lubomir@849:     }
lubomir@849: 
jaroslav@874:     /** Creates new instance of the Bck2Brwsr compiler which inherits
jaroslav@874:      * all values from <code>this</code> instance and adds additional classes 
jaroslav@874:      * to the list of those that should be compiled by the {@link #generate(java.lang.Appendable)} 
jaroslav@874:      * method.
jaroslav@874:      * 
jaroslav@874:      * @param classes the classes to add to the compilation
jaroslav@874:      * @return new instance of the compiler
jaroslav@874:      */
jaroslav@874:     public Bck2Brwsr addRootClasses(String... classes) {
jaroslav@874:         if (classes.length == 0) {
jaroslav@874:             return this;
jaroslav@874:         } else {
jaroslav@874:             return new Bck2Brwsr(level, this.classes.addAndNew(classes), res);
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 <code>this</code> 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@874:         return new Bck2Brwsr(level, classes, res);
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@874:         return new Bck2Brwsr(level, classes, res);
jaroslav@874:     }
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 <code>true</code> if classes loaded
jaroslav@1365:      *    from <code>rt.jar</code> 
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@1359:         Resources r = res != null ? res : new LdrRsrcs(Bck2Brwsr.class.getClassLoader(), false);
jaroslav@874:         if (level != ObfuscationLevel.NONE) {
lubomir@849:             try {
jaroslav@874:                 ClosureWrapper.produceTo(out, level, r, classes);
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@874:         VM.compile(r, out, classes);
jaroslav@298:     }
jaroslav@298:     
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 <code>"java/lang/String.class"</code>.
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: }