2 * Back 2 Browser Bytecode Translator
3 * Copyright (C) 2012 Jaroslav Tulach <jaroslav.tulach@apidesign.org>
5 * This program is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation, version 2 of the License.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License
15 * along with this program. Look for COPYING file in the top folder.
16 * If not, see http://opensource.org/licenses/GPL-2.0.
18 package org.apidesign.vm4brwsr;
20 import java.io.IOException;
21 import java.io.InputStream;
22 import org.apidesign.bck2brwsr.core.Exported;
24 /** Build your own virtual machine! Use methods in this class to generate
25 * a skeleton JVM in JavaScript that contains pre-compiled classes of your
26 * choice. The generated script defines one JavaScript method that can
27 * be used to bootstrap and load the virtual machine: <pre>
28 * var vm = bck2brwsr();
29 * var main = vm.loadClass('org.your.pkg.Main');
30 * main.main__V_3Ljava_lang_String_2(null);
32 * In case one wants to initialize the virtual machine with ability to
33 * load classes lazily when needed, one can provide a loader function to
34 * when creating the virtual machine: <pre>
35 * var vm = bck2brwsr(function(resource) {
36 * return null; // byte[] for the resource
39 * In this scenario, when a request for an unknown class is made, the loader
40 * function is asked for its byte code and the system dynamically transforms
43 * Instead of a loader function, one can also provide a URL to a JAR file.
44 * The <code>bck2brwsr</code> system will do its best to download the file
45 * and provide loader function for it automatically.
47 * One can provide as many loader functions and JAR URL references as necessary.
48 * Then the initialization code would look like:<pre>
49 * var vm = bck2brwsr(url1, url2, fnctn1, url3, functn2);
51 * The provided URLs and loader functions will be consulted one by one.
53 * @author Jaroslav Tulach <jtulach@netbeans.org>
55 public final class Bck2Brwsr {
56 private final ObfuscationLevel level;
57 private final StringArray rootcls;
58 private final StringArray classes;
59 private final StringArray resources;
60 private final Resources res;
61 private final boolean extension;
63 private Bck2Brwsr(ObfuscationLevel level, StringArray rootcls, StringArray classes, StringArray resources, Resources res, boolean extension) {
65 this.rootcls = rootcls;
66 this.classes = classes;
67 this.resources = resources;
69 this.extension = extension;
72 /** Helper method to generate virtual machine from bytes served by a <code>resources</code>
75 * @param out the output to write the generated JavaScript to
76 * @param resources provider of class files to use
77 * @param classes additional classes to include in the generated script
78 * @throws IOException I/O exception can be thrown when something goes wrong
80 public static void generate(Appendable out, Resources resources, String... classes) throws IOException {
81 newCompiler().resources(resources).addRootClasses(classes).generate(out);
84 /** Helper method to generate virtual machine from bytes served by a class loader.
86 * @param out the output to write the generated JavaScript to
87 * @param loader class loader to load needed classes from
88 * @param classes additional classes to include in the generated script
89 * @throws IOException I/O exception can be thrown when something goes wrong
91 public static void generate(Appendable out, ClassLoader loader, String... classes) throws IOException {
92 newCompiler().resources(loader).addRootClasses(classes).generate(out);
95 /** Creates new instance of Bck2Brwsr compiler which is ready to generate
96 * empty Bck2Brwsr virtual machine. The instance can be further
97 * configured by calling chain of methods. For example:
99 * {@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)};
102 * @return new instance of the Bck2Brwsr compiler
105 public static Bck2Brwsr newCompiler() {
106 return new Bck2Brwsr(ObfuscationLevel.NONE, new StringArray(), new StringArray(), new StringArray(), null, false);
109 /** Adds additional classes
110 * to the list of those that should be included in the generated
112 * These classes are guaranteed to be available in the
113 * generated virtual machine code accessible using their fully
114 * qualified name. This brings the same behavior as if the
115 * classes were added by {@link #addClasses(java.lang.String...) } and
116 * were annotated with {@link Exported} annotation.
118 * @param classes the classes to add to the compilation
119 * @return new instance of the Bck2Brwsr compiler which inherits
120 * all values from <code>this</code>
122 public Bck2Brwsr addRootClasses(String... classes) {
123 if (classes.length == 0) {
126 return new Bck2Brwsr(level, rootcls.addAndNew(classes), this.classes, resources, res,
131 /** Adds additional classes
132 * to the list of those that should be included in the generated
133 * JavaScript file. These classes are guaranteed to be present,
134 * but they may not be accessible through their fully qualified
137 * @param classes the classes to add to the compilation
138 * @return new instance of the Bck2Brwsr compiler which inherits
139 * all values from <code>this</code>
142 public Bck2Brwsr addClasses(String... classes) {
143 if (classes.length == 0) {
146 return new Bck2Brwsr(level, rootcls, this.classes.addAndNew(classes), resources, res,
151 /** These resources should be made available in the compiled file in
152 * binary form. These resources can then be loaded
153 * by {@link ClassLoader#getResource(java.lang.String)} and similar
156 * @param resources names of the resources to be loaded by {@link Resources#get(java.lang.String)}
157 * @return new instance of the Bck2Brwsr compiler which inherits
158 * all values from <code>this</code> just adds few more resource names
162 public Bck2Brwsr addResources(String... resources) {
163 if (resources.length == 0) {
166 return new Bck2Brwsr(level, rootcls, this.classes,
167 this.resources.addAndNew(resources), res, extension
172 /** Changes the obfuscation level for the compiler by creating new instance
173 * which inherits all values from <code>this</code> and adjust the level
176 * @param level the new level of obfuscation
177 * @return new instance of the compiler with changed level of obfuscation
180 public Bck2Brwsr obfuscation(ObfuscationLevel level) {
181 return new Bck2Brwsr(level, rootcls, classes, resources, res, extension);
184 /** A way to change the provider of additional resources (classes) for the
187 * @param res the implementation of resources provider
188 * @return new instance of the compiler with all values remaining the same, just
189 * with different resources provider
192 public Bck2Brwsr resources(Resources res) {
193 return new Bck2Brwsr(level, rootcls, classes, resources, res, extension);
196 /** Should one generate a library? By default the system generates
197 * all transitive classes needed by the the transitive closure of
198 * {@link #addRootClasses(java.lang.String...)} and {@link #addClasses(java.lang.String...)}.
199 * By turning on the library mode, only classes explicitly listed
200 * will be included in the archive. The others will be referenced
203 * @param library turn on the library mode?
204 * @return new instance of the compiler with library flag changed
207 public Bck2Brwsr library(boolean library) {
208 return new Bck2Brwsr(level, rootcls, classes, resources, res, library);
211 /** A way to change the provider of additional resources (classes) for the
212 * compiler by specifying classloader to use for loading them.
214 * @param loader class loader to load the resources from
215 * @return new instance of the compiler with all values being the same, just
216 * different resources provider
219 public Bck2Brwsr resources(final ClassLoader loader) {
220 return resources(new LdrRsrcs(loader));
223 /** Generates virtual machine based on previous configuration of the
226 * @param out the output to write the generated JavaScript to
229 public void generate(Appendable out) throws IOException {
230 if (level != ObfuscationLevel.NONE) {
232 ClosureWrapper.produceTo(out, level, this);
234 } catch (IOException ex) {
236 } catch (Throwable ex) {
237 out.append("/* Failed to obfuscate: " + ex.getMessage()
242 VM.compile(out, this);
249 Resources getResources() {
250 return res != null ? res : new LdrRsrcs(Bck2Brwsr.class.getClassLoader());
253 String[] allClasses() {
254 return classes.addAndNew(rootcls.toArray()).toArray();
257 StringArray rootClasses() {
261 boolean isExtension() {
265 /** Provider of resources (classes and other files). The
266 * {@link #generate(java.lang.Appendable, org.apidesign.vm4brwsr.Bck2Brwsr.Resources, java.lang.String[])
267 * generator method} will call back here for all classes needed during
268 * translation to JavaScript.
270 public interface Resources {
271 /** Loads given resource (class or other file like image). The
272 * resource name to load bytes for the {@link String} class
273 * would be <code>"java/lang/String.class"</code>.
275 * @param resource path to resource to load
276 * @return the input stream for the resource
277 * @throws IOException can be thrown if the loading fails on some error
278 * or the file cannot be found
280 public InputStream get(String resource) throws IOException;