From 3d3b5abce8d9e7bd68010c44bfaf93013ac5214e Mon Sep 17 00:00:00 2001 From: konsoletyper Date: Wed, 19 Mar 2014 01:37:07 +0400 Subject: [PATCH] Adds JavaDocs --- teavm-core/pom.xml | 81 ++++++++++++----- .../org/teavm/model/ClassHolderSource.java | 2 +- .../java/org/teavm/model/FieldReference.java | 2 +- .../java/org/teavm/model/MethodReference.java | 25 +++++- .../resource/ResourceClassHolderMapper.java | 2 +- .../org/teavm/resource/ResourceReader.java | 2 +- .../src/main/java/org/teavm/vm/TeaVM.java | 89 +++++++++++++++++++ .../java/org/teavm/vm/TeaVMEntryPoint.java | 46 ++++++++++ .../main/java/org/teavm/vm/spi/TeaVMHost.java | 13 ++- 9 files changed, 235 insertions(+), 27 deletions(-) diff --git a/teavm-core/pom.xml b/teavm-core/pom.xml index 35e0778a1..ac7a7dfe3 100644 --- a/teavm-core/pom.xml +++ b/teavm-core/pom.xml @@ -43,27 +43,58 @@ - org.apache.maven.plugins - maven-checkstyle-plugin - 2.11 - - - validate - validate - - config_loc=${basedir} - checkstyle.xml - UTF-8 - true - true - false - - - check - - - - + org.apache.maven.plugins + maven-checkstyle-plugin + 2.11 + + + validate + validate + + config_loc=${basedir} + checkstyle.xml + UTF-8 + true + true + false + + + check + + + + + + org.apache.maven.plugins + maven-javadoc-plugin + 2.9.1 + + + build-javadoc + + jar + + verify + + + + protected + + + + org.apache.maven.plugins + maven-source-plugin + 2.2.1 + + + attach-sources + verify + + jar-no-fork + + + + @@ -74,6 +105,14 @@ findbugs-maven-plugin 2.5.2 + + org.apache.maven.plugins + maven-javadoc-plugin + 2.9.1 + + protected + + \ No newline at end of file diff --git a/teavm-core/src/main/java/org/teavm/model/ClassHolderSource.java b/teavm-core/src/main/java/org/teavm/model/ClassHolderSource.java index 792d15b0f..1995ee5a1 100644 --- a/teavm-core/src/main/java/org/teavm/model/ClassHolderSource.java +++ b/teavm-core/src/main/java/org/teavm/model/ClassHolderSource.java @@ -17,7 +17,7 @@ package org.teavm.model; /** * - * @author konsoletyper + * @author Alexey Andreev */ public interface ClassHolderSource extends ClassReaderSource { @Override diff --git a/teavm-core/src/main/java/org/teavm/model/FieldReference.java b/teavm-core/src/main/java/org/teavm/model/FieldReference.java index 42e476131..b20876f54 100644 --- a/teavm-core/src/main/java/org/teavm/model/FieldReference.java +++ b/teavm-core/src/main/java/org/teavm/model/FieldReference.java @@ -17,7 +17,7 @@ package org.teavm.model; /** * - * @author konsoletyper + * @author Alexey Andreev */ public class FieldReference { private String className; diff --git a/teavm-core/src/main/java/org/teavm/model/MethodReference.java b/teavm-core/src/main/java/org/teavm/model/MethodReference.java index 154703e40..3f5ad5da4 100644 --- a/teavm-core/src/main/java/org/teavm/model/MethodReference.java +++ b/teavm-core/src/main/java/org/teavm/model/MethodReference.java @@ -16,8 +16,15 @@ package org.teavm.model; /** + *

Specifies a fully qualified name of a method, including its name, class name, parameter types + * and return value type. This class overloads equals and hashCode + * so that any two references to one method are considered equal.

* - * @author konsoletyper + *

Though in Java language it is enough to have only parameter types to uniquely identify + * a method, JVM uses return value as well. Java generates bridge methods to make + * adjust the JVM's behavior.

+ * + * @author Alexey Andreev */ public class MethodReference { private String className; @@ -28,6 +35,22 @@ public class MethodReference { this.descriptor = descriptor; } + /** + *

Creates a new reference to a method.

+ * + *

For example, here is how you should call this constructor to create a reference to + * the Integer.valueOf(int) method: + * + * 

+     * new MethodReference("java.lang.Integer", "valueOf",
+     *         ValueType.INT, ValueType.object("java.lang.Integer"))
+     *
+ * + * @param className the name of the class that owns the method. + * @param name the name of the method. + * @param signature descriptor of a method, as described in VM spec. The last element is + * a type of a returning value, and all the remaining elements are types of arguments. + */ public MethodReference(String className, String name, ValueType... signature) { this(className, new MethodDescriptor(name, signature)); } diff --git a/teavm-core/src/main/java/org/teavm/resource/ResourceClassHolderMapper.java b/teavm-core/src/main/java/org/teavm/resource/ResourceClassHolderMapper.java index d9dbcd9d0..b1c89dfe8 100644 --- a/teavm-core/src/main/java/org/teavm/resource/ResourceClassHolderMapper.java +++ b/teavm-core/src/main/java/org/teavm/resource/ResourceClassHolderMapper.java @@ -25,7 +25,7 @@ import org.teavm.parsing.Parser; /** * - * @author konsoletyper + * @author Alexey Andreev */ public class ResourceClassHolderMapper implements Mapper { private ResourceReader resourceReader; diff --git a/teavm-core/src/main/java/org/teavm/resource/ResourceReader.java b/teavm-core/src/main/java/org/teavm/resource/ResourceReader.java index 571dccd35..1aa113eb0 100644 --- a/teavm-core/src/main/java/org/teavm/resource/ResourceReader.java +++ b/teavm-core/src/main/java/org/teavm/resource/ResourceReader.java @@ -20,7 +20,7 @@ import java.io.InputStream; /** * - * @author konsoletyper + * @author Alexey Andreev */ public interface ResourceReader { boolean hasResource(String name); diff --git a/teavm-core/src/main/java/org/teavm/vm/TeaVM.java b/teavm-core/src/main/java/org/teavm/vm/TeaVM.java index d5001f6d7..5db617e44 100644 --- a/teavm-core/src/main/java/org/teavm/vm/TeaVM.java +++ b/teavm-core/src/main/java/org/teavm/vm/TeaVM.java @@ -34,6 +34,31 @@ import org.teavm.vm.spi.TeaVMHost; import org.teavm.vm.spi.TeaVMPlugin; /** + *

TeaVM itself. This class builds a JavaScript VM that runs a certain code. + * Here you can specify entry points into your code (such like {@code main} method). + * TeaVM guarantees that all required classes and methods will be provided by + * built VM.

+ * + *

Here is a typical code snippet:

+ * + * 
{@code
+ *ClassLoader classLoader = ...; // obtain ClassLoader somewhere
+ *ClassHolderSource classSource = new ClasspathClassHolderSource(classLoader);
+ *TeaVM vm = new TeaVMBuilder()
+ *        .setClassLoader(classLoader)
+ *        .setClassSource(classSource)
+ *        .build();
+ *vm.setMinifying(false); // optionally disable obfuscation
+ *vm.installPlugins();    // install all default plugins
+ *                        // that are found in a classpath
+ *vm.addEntryPoint("main", new MethodReference(
+ *        "fully.qualified.ClassName",  "main",
+ *         ValueType.array(ValueType.object("java.lang.String")),
+ *         ValueType.VOID));
+ *StringBuilder sb = new StringBuilder();
+ *vm.build(sb, null);
+ *vm.checkForMissingItems();
+ *}
* * @author Alexey Andreev */ @@ -84,10 +109,20 @@ public class TeaVM implements TeaVMHost { return classLoader; } + /** + * Reports whether this TeaVM instance uses obfuscation when generating the JavaScript code. + * + * @see #setMinifying(boolean) + */ public boolean isMinifying() { return minifying; } + /** + * Specifies whether this TeaVM instance uses obfuscation when generating the JavaScript code. + * + * @see #isMinifying() + */ public void setMinifying(boolean minifying) { this.minifying = minifying; } @@ -100,6 +135,10 @@ public class TeaVM implements TeaVMHost { this.bytecodeLogging = bytecodeLogging; } + /** + * Specifies configuration properties for TeaVM and its plugins. You should call this method before + * installing any plugins or interceptors. + */ public void setProperties(Properties properties) { this.properties.clear(); if (properties != null) { @@ -112,6 +151,19 @@ public class TeaVM implements TeaVMHost { return new Properties(properties); } + /** + *

Adds an entry point. TeaVM guarantees, that all methods that are required by the entry point + * will be available at run-time in browser. Also you need to specify for each parameter of entry point + * which actual types will be passed here by calling {@link TeaVMEntryPoint#withValue(int, String)}. + * It is highly recommended to read explanation on {@link TeaVMEntryPoint} class documentation.

+ * + *

You should call this method after installing all plugins and interceptors, but before + * doing the actual build.

+ * + * @param name the name under which this entry point will be available for JavaScript code. + * @param ref a full reference to the method which is an entry point. + * @return an entry point that you can additionally adjust. + */ public TeaVMEntryPoint entryPoint(String name, MethodReference ref) { if (entryPoints.containsKey(name)) { throw new IllegalArgumentException("Entry point with public name `" + name + "' already defined " + @@ -144,22 +196,53 @@ public class TeaVM implements TeaVMHost { dependencyChecker.initClass(className, DependencyStack.ROOT); } + /** + * Gets a {@link ClassHolderSource} which is used by this TeaVM instance. It is exactly what was + * passed to {@link TeaVMBuilder#setClassSource(ClassHolderSource)}. + */ public ClassHolderSource getClassSource() { return classSource; } + /** + *

After building indicates whether build has failed due to some missing items (classes, methods and fields) + * in the classpath. This can happen when you forgot some items in class path or when your code uses unimplemented + * Java class library methods. The behavior of this method before building is not specified.

+ */ public boolean hasMissingItems() { return dependencyChecker.hasMissingItems(); } + /** + *

After building allows to build report on all items (classes, methods, fields) that are missing. + * This can happen when you forgot some items in class path or when your code uses unimplemented + * Java class library methods. The behavior of this method before building is not specified.

+ */ public void showMissingItems(Appendable target) throws IOException { dependencyChecker.showMissingItems(target); } + /** + *

After building checks whether the build has failed due to some missing items (classes, methods and fields). + * If it has failed, throws exception, containing report on all missing items. + * This can happen when you forgot some items in class path or when your code uses unimplemented + * Java class library methods. The behavior of this method before building is not specified.

+ */ public void checkForMissingItems() { dependencyChecker.checkForMissingItems(); } + /** + *

Does actual build. Call this method after TeaVM is fully configured and all entry points + * are specified. This method may fail if there are items (classes, methods and fields) + * that are required by entry points, but weren't found in classpath. In this case no + * actual generation happens and no exceptions thrown, but you can further call + * {@link #checkForMissingItems()} or {@link #hasMissingItems()} to learn the build state.

+ * + * @param writer where to generate JavaScript. Should not be null. + * @param target where to generate additional resources. Can be null, but if there are + * plugins or inteceptors that generate additional resources, the build process will fail. + */ public void build(Appendable writer, BuildTarget target) throws RenderingException { AliasProvider aliasProvider = minifying ? new MinifyingAliasProvider() : new DefaultAliasProvider(); DefaultNamingStrategy naming = new DefaultNamingStrategy(aliasProvider, classSource); @@ -388,6 +471,12 @@ public class TeaVM implements TeaVMHost { } } + /** + *

Finds and install all plugins in the current class path. The standard {@link ServiceLoader} + * approach is used to find plugins. So this method scans all + * META-INF/services/org.teavm.vm.spi.TeaVMPlugin resources and + * obtains all implementation classes that are enumerated there.

+ */ public void installPlugins() { for (TeaVMPlugin plugin : ServiceLoader.load(TeaVMPlugin.class, classLoader)) { plugin.install(this); diff --git a/teavm-core/src/main/java/org/teavm/vm/TeaVMEntryPoint.java b/teavm-core/src/main/java/org/teavm/vm/TeaVMEntryPoint.java index 4f27c7e56..b75ec9728 100644 --- a/teavm-core/src/main/java/org/teavm/vm/TeaVMEntryPoint.java +++ b/teavm-core/src/main/java/org/teavm/vm/TeaVMEntryPoint.java @@ -15,10 +15,56 @@ */ package org.teavm.vm; +import java.util.HashMap; import org.teavm.dependency.MethodDependency; import org.teavm.model.MethodReference; /** + *

An entry point to a generated VM that is used to enter the VM from a JavaScript code. + * The entry point is added by {@link TeaVM#entryPoint(String, MethodReference)}. + * Use {@link #withValue(int, String)} to specify actual types that are passed to the entry point.

+ * + *

In the simple case of static method without arguments you won't deal with this class. But + * sometimes you have to. Consider the following example:

+ * + * 
{@code
+ *static void entryPoint(Map map) {
+ *    for (Map.Entry entry : map.entrySet()) {
+ *        System.out.println(entry.getKey() + " => " + entry.getValue());
+ *    }
+ *}}
+ * + *

Now you want to call this method from JavaScript, and you pass a {@link HashMap} to this method. + * Let's see how you achieve it:

+ * + * 
{@code
+ *vm.exportType("JavaHashMap", "java.util.HashMap");
+ *vm.entryPoint("initJavaHashMap", new MethodReference("java.util.HashMap",
+ *        "", ValueType.VOID));
+ *vm.entryPoint("putValueIntoJavaMap", new MethodReference(
+ *        "java.util.Map", "put",
+ *        ValueType.object("java.lang.Object"), ValueType.object("java.lang.Object"),
+ *        ValueType.object("java.lang.Object")))
+ *        .withValue(0, "java.util.HashMap")
+ *        .withValue(1, "java.lang.String")
+ *        .withValue(2, "java.lang.String");
+ *vm.entryPoint("entryPoint", new MethodReference(
+ *        "fully.qualified.ClassName", "entryPoint",
+ *        ValueType.object("java.util.Map"), ValueType.VOID))
+ *        .withValue(1, "java.util.HashMap")
+ *}
+ * + *

And in JavaScript you would do the following:

+ * + * 
{@code
+ *var map = new JavaHashMap();
+ *initJavaHashMap(map);
+ *putValueIntoJavaMap(map, $rt_str("foo"), $rt_str("bar"));
+ *entryPoint(map);
+ *}
+ * + *

If you didn't call .withValue(1, "java.util.HashMap"), TeaVM could not know, + * what implementation of #entrySet method to include.

* * @author Alexey Andreev */ diff --git a/teavm-core/src/main/java/org/teavm/vm/spi/TeaVMHost.java b/teavm-core/src/main/java/org/teavm/vm/spi/TeaVMHost.java index 68fc73314..59f8fdf47 100644 --- a/teavm-core/src/main/java/org/teavm/vm/spi/TeaVMHost.java +++ b/teavm-core/src/main/java/org/teavm/vm/spi/TeaVMHost.java @@ -20,9 +20,12 @@ import org.teavm.dependency.DependencyListener; import org.teavm.javascript.ni.Generator; import org.teavm.model.ClassHolderTransformer; import org.teavm.model.MethodReference; +import org.teavm.vm.TeaVM; +import org.teavm.vm.TeaVMBuilder; /** - * + *

A host of plugins for TeaVM. Plugins are provided with this interface + * in order to give them ability to extend TeaVM.

* @author Alexey Andreev */ public interface TeaVMHost { @@ -34,7 +37,15 @@ public interface TeaVMHost { void add(RendererListener listener); + /** + * Gets class loaded that is used by TeaVM. This class loader is usually specified by + * {@link TeaVMBuilder#setClassLoader(ClassLoader)} + */ ClassLoader getClassLoader(); + /** + * Gets configuration properties. These properties are usually specified by + * {@link TeaVM#setProperties(Properties)} + */ Properties getProperties(); }