mirror/teavm
2
0
Fork 0
mirror of https://github.com/konsoletyper/teavm.git synced 2025-03-13 11:46:46 +08:00
Code Issues Packages Projects Releases Wiki Activity

Adds JavaDocs

Browse Source
This commit is contained in:
konsoletyper 2014-03-19 01:37:07 +04:00
parent eaa4da45fa
commit 3d3b5abce8
9 changed files with 235 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
teavm-core/pom.xml
View File

@ -43,27 +43,58 @@
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<version>2.11</version>
<executions>
<execution>
<id>validate</id>
<phase>validate</phase>
<configuration>
<propertyExpansion>config_loc=${basedir}</propertyExpansion>
<configLocation>checkstyle.xml</configLocation>
<encoding>UTF-8</encoding>
<consoleOutput>true</consoleOutput>
<failsOnError>true</failsOnError>
<linkXRef>false</linkXRef>
</configuration>
<goals>
<goal>check</goal>
</goals>
</execution>
</executions>
</plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<version>2.11</version>
<executions>
<execution>
<id>validate</id>
<phase>validate</phase>
<configuration>
<propertyExpansion>config_loc=${basedir}</propertyExpansion>
<configLocation>checkstyle.xml</configLocation>
<encoding>UTF-8</encoding>
<consoleOutput>true</consoleOutput>
<failsOnError>true</failsOnError>
<linkXRef>false</linkXRef>
</configuration>
<goals>
<goal>check</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9.1</version>
<executions>
<execution>
<id>build-javadoc</id>
<goals>
<goal>jar</goal>
</goals>
<phase>verify</phase>
</execution>
</executions>
<configuration>
<show>protected</show>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>2.2.1</version>
<executions>
<execution>
<id>attach-sources</id>
<phase>verify</phase>
<goals>
<goal>jar-no-fork</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
@ -74,6 +105,14 @@
<artifactId>findbugs-maven-plugin</artifactId>
<version>2.5.2</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9.1</version>
<configuration>
<show>protected</show>
</configuration>
</plugin>
</plugins>
</reporting>
</project>

2
teavm-core/src/main/java/org/teavm/model/ClassHolderSource.java
View File

@ -17,7 +17,7 @@ package org.teavm.model;
/**
*
* @author konsoletyper
* @author Alexey Andreev
*/
public interface ClassHolderSource extends ClassReaderSource {
@Override

2
teavm-core/src/main/java/org/teavm/model/FieldReference.java
View File

@ -17,7 +17,7 @@ package org.teavm.model;
/**
*
* @author konsoletyper
* @author Alexey Andreev
*/
public class FieldReference {
private String className;

25
teavm-core/src/main/java/org/teavm/model/MethodReference.java
View File

@ -16,8 +16,15 @@
package org.teavm.model;
/**
* <p>Specifies a fully qualified name of a method, including its name, class name, parameter types
* and return value type. This class overloads <code>equals</code> and <code>hashCode</code>
* so that any two references to one method are considered equal.</p>
*
* @author konsoletyper
* <p>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 <b>bridge</b> methods to make
* adjust the JVM's behavior.</p>
*
* @author Alexey Andreev
*/
public class MethodReference {
private String className;
@ -28,6 +35,22 @@ public class MethodReference {
this.descriptor = descriptor;
}
/**
* <p>Creates a new reference to a method.</p>
*
* <p>For example, here is how you should call this constructor to create a reference to
* the <code>Integer.valueOf(int)</code> method:
*
* <pre>
* new MethodReference("java.lang.Integer", "valueOf",
* ValueType.INT, ValueType.object("java.lang.Integer"))
* </pre>
*
* @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));
}

2
teavm-core/src/main/java/org/teavm/resource/ResourceClassHolderMapper.java
View File

@ -25,7 +25,7 @@ import org.teavm.parsing.Parser;
/**
*
* @author konsoletyper
* @author Alexey Andreev
*/
public class ResourceClassHolderMapper implements Mapper<String, ClassHolder> {
private ResourceReader resourceReader;

2
teavm-core/src/main/java/org/teavm/resource/ResourceReader.java
View File

@ -20,7 +20,7 @@ import java.io.InputStream;
/**
*
* @author konsoletyper
* @author Alexey Andreev
*/
public interface ResourceReader {
boolean hasResource(String name);

89
teavm-core/src/main/java/org/teavm/vm/TeaVM.java
View File

@ -34,6 +34,31 @@ import org.teavm.vm.spi.TeaVMHost;
import org.teavm.vm.spi.TeaVMPlugin;
/**
* <p>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.</p>
*
* <p>Here is a typical code snippet:</p>
*
* <pre>{@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();
*}</pre>
*
* @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);
}
/**
* <p>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.</p>
*
* <p>You should call this method after installing all plugins and interceptors, but before
* doing the actual build.</p>
*
* @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;
}
/**
* <p>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.</p>
*/
public boolean hasMissingItems() {
return dependencyChecker.hasMissingItems();
}
/**
* <p>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.</p>
*/
public void showMissingItems(Appendable target) throws IOException {
dependencyChecker.showMissingItems(target);
}
/**
* <p>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.</p>
*/
public void checkForMissingItems() {
dependencyChecker.checkForMissingItems();
}
/**
* <p>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.</p>
*
* @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 {
}
}
/**
* <p>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
* <code>META-INF/services/org.teavm.vm.spi.TeaVMPlugin</code> resources and
* obtains all implementation classes that are enumerated there.</p>
*/
public void installPlugins() {
for (TeaVMPlugin plugin : ServiceLoader.load(TeaVMPlugin.class, classLoader)) {
plugin.install(this);

46
teavm-core/src/main/java/org/teavm/vm/TeaVMEntryPoint.java
View File

@ -15,10 +15,56 @@
*/
package org.teavm.vm;
import java.util.HashMap;
import org.teavm.dependency.MethodDependency;
import org.teavm.model.MethodReference;
/**
* <p>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.</p>
*
* <p>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:</p>
*
* <pre>{@code
*static void entryPoint(Map<Object, Object> map) {
* for (Map.Entry<Object, Object> entry : map.entrySet()) {
* System.out.println(entry.getKey() + " => " + entry.getValue());
* }
*}}</pre>
*
* <p>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:</p>
*
* <pre>{@code
*vm.exportType("JavaHashMap", "java.util.HashMap");
*vm.entryPoint("initJavaHashMap", new MethodReference("java.util.HashMap",
* "<init>", 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")
*}</pre>
*
* <p>And in JavaScript you would do the following:</p>
*
* <pre>{@code
*var map = new JavaHashMap();
*initJavaHashMap(map);
*putValueIntoJavaMap(map, $rt_str("foo"), $rt_str("bar"));
*entryPoint(map);
*}</pre>
*
* <p>If you didn't call <code>.withValue(1, "java.util.HashMap")</code>, TeaVM could not know,
* what implementation of <code>#entrySet</code> method to include.</p>
*
* @author Alexey Andreev
*/

13
teavm-core/src/main/java/org/teavm/vm/spi/TeaVMHost.java
View File

@ -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;
/**
*
* <p>A host of plugins for TeaVM. Plugins are provided with this interface
* in order to give them ability to extend TeaVM.</p>
* @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();
}