1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/rt/vm/src/main/java/org/apidesign/vm4brwsr/Bck2Brwsr.java Tue Feb 26 16:54:16 2013 +0100
1.3 @@ -0,0 +1,116 @@
1.4 +/**
1.5 + * Back 2 Browser Bytecode Translator
1.6 + * Copyright (C) 2012 Jaroslav Tulach <jaroslav.tulach@apidesign.org>
1.7 + *
1.8 + * This program is free software: you can redistribute it and/or modify
1.9 + * it under the terms of the GNU General Public License as published by
1.10 + * the Free Software Foundation, version 2 of the License.
1.11 + *
1.12 + * This program is distributed in the hope that it will be useful,
1.13 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.14 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.15 + * GNU General Public License for more details.
1.16 + *
1.17 + * You should have received a copy of the GNU General Public License
1.18 + * along with this program. Look for COPYING file in the top folder.
1.19 + * If not, see http://opensource.org/licenses/GPL-2.0.
1.20 + */
1.21 +package org.apidesign.vm4brwsr;
1.22 +
1.23 +import java.io.IOException;
1.24 +import java.io.InputStream;
1.25 +import java.net.URL;
1.26 +import java.util.Enumeration;
1.27 +
1.28 +/** Build your own virtual machine! Use methods in this class to generate
1.29 + * a skeleton JVM in JavaScript that contains pre-compiled classes of your
1.30 + * choice. The generated script defines one JavaScript method that can
1.31 + * be used to bootstrap and load the virtual machine: <pre>
1.32 + * var vm = bck2brwsr();
1.33 + * var main = vm.loadClass('org.your.pkg.Main');
1.34 + * main.main__V_3Ljava_lang_String_2(null);
1.35 + * </pre>
1.36 + * In case one wants to initialize the virtual machine with ability to
1.37 + * load classes lazily when needed, one can provide a loader function to
1.38 + * when creating the virtual machine: <pre>
1.39 + * var vm = bck2brwsr(function(resource) {
1.40 + * return null; // byte[] for the resource
1.41 + * });
1.42 + * </pre>
1.43 + * In this scenario, when a request for an unknown class is made, the loader
1.44 + * function is asked for its byte code and the system dynamically transforms
1.45 + * it to JavaScript.
1.46 + * <p>
1.47 + * Instead of a loader function, one can also provide a URL to a JAR file.
1.48 + * The <code>bck2brwsr</code> system will do its best to download the file
1.49 + * and provide loader function for it automatically.
1.50 + * <p>
1.51 + * One can provide as many loader functions and JAR URL references as necessary.
1.52 + * Then the initialization code would look like:<pre>
1.53 + * var vm = bck2brwsr(url1, url2, fnctn1, url3, functn2);
1.54 + * </pre>
1.55 + * The provided URLs and loader functions will be consulted one by one.
1.56 + *
1.57 + * @author Jaroslav Tulach <jtulach@netbeans.org>
1.58 + */
1.59 +public final class Bck2Brwsr {
1.60 + private Bck2Brwsr() {
1.61 + }
1.62 +
1.63 + /** Generates virtual machine from bytes served by a <code>resources</code>
1.64 + * provider.
1.65 + *
1.66 + * @param out the output to write the generated JavaScript to
1.67 + * @param resources provider of class files to use
1.68 + * @param classes additional classes to include in the generated script
1.69 + * @throws IOException I/O exception can be thrown when something goes wrong
1.70 + */
1.71 + public static void generate(Appendable out, Resources resources, String... classes) throws IOException {
1.72 + StringArray arr = StringArray.asList(classes);
1.73 + arr.add(VM.class.getName().replace('.', '/'));
1.74 + VM.compile(resources, out, arr);
1.75 + }
1.76 +
1.77 + /** Generates virtual machine from bytes served by a class loader.
1.78 + *
1.79 + * @param out the output to write the generated JavaScript to
1.80 + * @param loader class loader to load needed classes from
1.81 + * @param classes additional classes to include in the generated script
1.82 + * @throws IOException I/O exception can be thrown when something goes wrong
1.83 + */
1.84 + public static void generate(Appendable out, final ClassLoader loader, String... classes) throws IOException {
1.85 + class R implements Resources {
1.86 + @Override
1.87 + public InputStream get(String name) throws IOException {
1.88 + Enumeration<URL> en = loader.getResources(name);
1.89 + URL u = null;
1.90 + while (en.hasMoreElements()) {
1.91 + u = en.nextElement();
1.92 + }
1.93 + if (u == null) {
1.94 + throw new IOException("Can't find " + name);
1.95 + }
1.96 + return u.openStream();
1.97 + }
1.98 + }
1.99 + generate(out, new R(), classes);
1.100 + }
1.101 +
1.102 + /** Provider of resources (classes and other files). The
1.103 + * {@link #generate(java.lang.Appendable, org.apidesign.vm4brwsr.Bck2Brwsr.Resources, java.lang.String[])
1.104 + * generator method} will call back here for all classes needed during
1.105 + * translation to JavaScript.
1.106 + */
1.107 + public interface Resources {
1.108 + /** Loads given resource (class or other file like image). The
1.109 + * resource name to load bytes for the {@link String} class
1.110 + * would be <code>"java/lang/String.class"</code>.
1.111 + *
1.112 + * @param resource path to resource to load
1.113 + * @return the input stream for the resource
1.114 + * @throws IOException can be thrown if the loading fails on some error
1.115 + * or the file cannot be found
1.116 + */
1.117 + public InputStream get(String resource) throws IOException;
1.118 + }
1.119 +}