changeset 462:52319f9ba066

Benchmark generators Javadocs.
author shade
date Mon, 03 Mar 2014 23:01:50 +0400
parents adb938a4aaca
children 9260eb8cc032
files jmh-core/src/main/java/org/openjdk/jmh/generators/annotations/APGeneratorSource.java jmh-core/src/main/java/org/openjdk/jmh/generators/bytecode/ASMGeneratorSource.java jmh-core/src/main/java/org/openjdk/jmh/generators/core/BenchmarkGenerator.java jmh-core/src/main/java/org/openjdk/jmh/generators/source/ClassInfo.java jmh-core/src/main/java/org/openjdk/jmh/generators/source/FieldInfo.java jmh-core/src/main/java/org/openjdk/jmh/generators/source/GeneratorSource.java jmh-core/src/main/java/org/openjdk/jmh/generators/source/MetadataInfo.java jmh-core/src/main/java/org/openjdk/jmh/generators/source/MethodInfo.java jmh-core/src/main/java/org/openjdk/jmh/generators/source/ParameterInfo.java
diffstat 9 files changed, 200 insertions(+), 14 deletions(-) [+]
line wrap: on
line diff
--- a/jmh-core/src/main/java/org/openjdk/jmh/generators/annotations/APGeneratorSource.java	Mon Mar 03 21:21:26 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/generators/annotations/APGeneratorSource.java	Mon Mar 03 23:01:50 2014 +0400
@@ -114,13 +114,13 @@
     }
 
     @Override
-    public Writer newResource(String path) throws IOException {
-        return processingEnv.getFiler().createResource(StandardLocation.CLASS_OUTPUT, "", path).openWriter();
+    public Writer newResource(String resourcePath) throws IOException {
+        return processingEnv.getFiler().createResource(StandardLocation.CLASS_OUTPUT, "", resourcePath).openWriter();
     }
 
     @Override
-    public Writer newFile(String objectName) throws IOException {
-        return processingEnv.getFiler().createSourceFile(objectName).openWriter();
+    public Writer newClass(String className) throws IOException {
+        return processingEnv.getFiler().createSourceFile(className).openWriter();
     }
 
     @Override
--- a/jmh-core/src/main/java/org/openjdk/jmh/generators/bytecode/ASMGeneratorSource.java	Mon Mar 03 21:21:26 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/generators/bytecode/ASMGeneratorSource.java	Mon Mar 03 23:01:50 2014 +0400
@@ -88,15 +88,15 @@
     }
 
     @Override
-    public Writer newResource(String path) throws IOException {
-        String pathName = targetDir.getAbsolutePath() + "/" + path;
+    public Writer newResource(String resourcePath) throws IOException {
+        String pathName = targetDir.getAbsolutePath() + "/" + resourcePath;
         new File(pathName.substring(0, pathName.lastIndexOf("/"))).mkdirs();
         return new FileWriter(new File(pathName));
     }
 
     @Override
-    public Writer newFile(String objectName) throws IOException {
-        String pathName = targetSourceDir.getAbsolutePath() + "/" + objectName.replaceAll("\\.", "/");
+    public Writer newClass(String className) throws IOException {
+        String pathName = targetSourceDir.getAbsolutePath() + "/" + className.replaceAll("\\.", "/");
         new File(pathName.substring(0, pathName.lastIndexOf("/"))).mkdirs();
         return new FileWriter(new File(pathName + ".java"));
     }
--- a/jmh-core/src/main/java/org/openjdk/jmh/generators/core/BenchmarkGenerator.java	Mon Mar 03 21:21:26 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/generators/core/BenchmarkGenerator.java	Mon Mar 03 23:01:50 2014 +0400
@@ -82,6 +82,12 @@
 import java.util.concurrent.atomic.AtomicIntegerFieldUpdater;
 
 /**
+ * Benchmark generator.
+ * <p/>
+ * Benchmark generator is the agnostic piece of code which generates
+ * synthetic Java code for JMH benchmarks. {@link GeneratorSource} is
+ * used to feed the generator with the required metadata.
+ *
  * @author Aleksey Shipilev (aleksey.shipilev@oracle.com)
  */
 public class BenchmarkGenerator {
@@ -103,6 +109,11 @@
         plugins.add(compilerControl);
     }
 
+    /**
+     * Execute the next phase of benchmark generation.
+     * Multiple calls to this method are acceptable, even with the difference sources
+     * @param source generator source to get the metadata from
+     */
     public void generate(GeneratorSource source) {
         try {
             for (Plugin sub : plugins) {
@@ -130,6 +141,12 @@
         }
     }
 
+    /**
+     * Finish generating the benchmarks.
+     * Must be called at the end of generation.
+     *
+     * @param source source generator to use
+     */
     public void complete(GeneratorSource source) {
         for (Plugin sub : plugins) {
             sub.finish(source);
@@ -438,7 +455,7 @@
     private void generateClass(GeneratorSource source, ClassInfo classInfo, BenchmarkInfo info) {
         try {
             // Create file and open an outputstream
-            PrintWriter writer = new PrintWriter(source.newFile(info.generatedName), false);
+            PrintWriter writer = new PrintWriter(source.newClass(info.generatedName), false);
 
             // Write package and imports
             writer.println("package " + info.generatedPackageName + ';');
--- a/jmh-core/src/main/java/org/openjdk/jmh/generators/source/ClassInfo.java	Mon Mar 03 21:21:26 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/generators/source/ClassInfo.java	Mon Mar 03 23:01:50 2014 +0400
@@ -32,30 +32,72 @@
  */
 public interface ClassInfo extends MetadataInfo {
 
+    /**
+     * @return fully qualified package name
+     */
     String getPackageName();
 
+    /**
+     *
+     * @return fully qualified class name
+     */
     String getQualifiedName();
 
+    /**
+     * @return short class name
+     */
     String getName();
 
+    /**
+     * @return reference to super-class metadata
+     */
     ClassInfo getSuperClass();
 
+    /**
+     * @return reference to syntactically-enclosing class
+     */
     ClassInfo getDeclaringClass();
 
+    /**
+     * @return collection of all fields in class
+     */
     Collection<FieldInfo> getFields();
 
+    /**
+     * @return collection of all methods in class
+     */
     Collection<MethodInfo> getMethods();
 
+    /**
+     * @return collection of all constructors in class
+     */
     Collection<MethodInfo> getConstructors();
 
+    /**
+     * @param annClass annotation class
+     * @param <T> annotation type
+     * @return class-level annotation, if any; null otherwise
+     */
     <T extends Annotation> T getAnnotation(Class<T> annClass);
 
+    /**
+     * @return true, if class is abstract
+     */
     boolean isAbstract();
 
+    /**
+     * @return true, if class is abstract
+     */
     boolean isPublic();
 
+    /**
+     * @return true, if class is strictfp
+     */
     boolean isStrictFP();
 
+    /**
+     * @return true, if class is final
+     */
     boolean isFinal();
 }
 
--- a/jmh-core/src/main/java/org/openjdk/jmh/generators/source/FieldInfo.java	Mon Mar 03 21:21:26 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/generators/source/FieldInfo.java	Mon Mar 03 23:01:50 2014 +0400
@@ -26,18 +26,41 @@
 
 import java.lang.annotation.Annotation;
 
+/**
+ * Field metadata info.
+ */
 public interface FieldInfo extends MetadataInfo {
 
+    /**
+     * @return field name
+     */
     String getName();
 
+    /**
+     * @return fully qualified field type
+     */
     String getType();
 
+    /**
+     * @return reference to syntactically-enclosing class
+     */
     ClassInfo getDeclaringClass();
 
+    /**
+     * @param annClass annotation class
+     * @param <T> annotation type
+     * @return field-level annotation, if any; null otherwise
+     */
     <T extends Annotation> T getAnnotation(Class<T> annClass);
 
+    /**
+     * @return true, if field is public
+     */
     boolean isPublic();
 
+    /**
+     * @return true, if field is static
+     */
     boolean isStatic();
 
 }
--- a/jmh-core/src/main/java/org/openjdk/jmh/generators/source/GeneratorSource.java	Mon Mar 03 21:21:26 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/generators/source/GeneratorSource.java	Mon Mar 03 23:01:50 2014 +0400
@@ -28,19 +28,74 @@
 import java.io.Writer;
 import java.util.Collection;
 
+/**
+ * Generator source.
+ *
+ * This is an entry point towards {@link org.openjdk.jmh.generators.core.BenchmarkGenerator}
+ * interface.
+ */
 public interface GeneratorSource {
 
+    /**
+     * @return collection of all resolved classes
+     */
     Collection<ClassInfo> getClasses();
 
+    /**
+     * Resolve class info for a name.
+     * <p/>
+     * Users may call this method for the classes not
+     * listed in {@link #getClasses()} call, the implementation
+     * has to have the fall-back strategy for these cases.
+     *
+     * @param className class name
+     * @return class metainfo
+     */
     ClassInfo resolveClass(String className);
 
-    Writer newResource(String path) throws IOException;
+    /**
+     * Returns the Writer for the given resource.
+     * Callers are responsible for closing Writers.
+     *
+     * @param resourcePath resource path
+     * @return writer usable to write the resource
+     * @throws IOException if something wacked happens
+     */
+    Writer newResource(String resourcePath) throws IOException;
 
-    Writer newFile(String objectName) throws IOException;
+    /**
+     * Returns the Writer for the given class.
+     * Callers are responsible for closing Writers.
+     *
+     * @param className class name
+     * @return writer usable to write the resource
+     * @throws IOException if something wacked happens
+     */
+    Writer newClass(String className) throws IOException;
 
+    /**
+     * Print the error.
+     * Calling this method should not terminate anything.
+     *
+     * @param message error.
+     */
     void printError(String message);
 
+    /**
+     * Print the error.
+     * Calling this method should not terminate anything.
+     *
+     * @param message error.
+     * @param element metadata element, to which this error is tailored
+     */
     void printError(String message, MetadataInfo element);
 
+    /**
+     * Print the error.
+     * Calling this method should not terminate anything.
+     *
+     * @param message error.
+     * @param throwable exception causing the error
+     */
     void printError(String message, Throwable throwable);
 }
--- a/jmh-core/src/main/java/org/openjdk/jmh/generators/source/MetadataInfo.java	Mon Mar 03 21:21:26 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/generators/source/MetadataInfo.java	Mon Mar 03 23:01:50 2014 +0400
@@ -24,5 +24,8 @@
  */
 package org.openjdk.jmh.generators.source;
 
+/**
+ * Super-interface for all metadata elements.
+ */
 public interface MetadataInfo {
 }
--- a/jmh-core/src/main/java/org/openjdk/jmh/generators/source/MethodInfo.java	Mon Mar 03 21:21:26 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/generators/source/MethodInfo.java	Mon Mar 03 23:01:50 2014 +0400
@@ -27,22 +27,61 @@
 import java.lang.annotation.Annotation;
 import java.util.Collection;
 
+/**
+ * Method info.
+ */
 public interface MethodInfo extends Comparable<MethodInfo>, MetadataInfo {
 
+    /**
+     * @return short method name.
+     */
     String getName();
+
+    /**
+     * @return fully qualified method name, includes class qualified name
+     */
     String getQualifiedName();
+
+    /**
+     * @return fully qualified return type
+     */
     String getReturnType();
 
+    /**
+     * @return collection of method parameters.
+     */
+    Collection<ParameterInfo> getParameters();
+
+    /**
+     * @return reference to syntactically-enclosing class
+     */
     ClassInfo getDeclaringClass();
 
-    Collection<ParameterInfo> getParameters();
-
+    /**
+     * @param annClass annotation class
+     * @param <T> annotation type
+     * @return method-level annotation, if any; null otherwise
+     */
     <T extends Annotation> T getAnnotation(Class<T> annClass);
 
+    /**
+     * @return true, if method is public
+     */
     boolean isPublic();
+
+    /**
+     * @return true, if method is abstract
+     */
     boolean isAbstract();
+
+    /**
+     * @return true, if method is synchronized
+     */
     boolean isSynchronized();
+
+    /**
+     * @return true, if method is strictfp
+     */
     boolean isStrictFP();
 
-
 }
--- a/jmh-core/src/main/java/org/openjdk/jmh/generators/source/ParameterInfo.java	Mon Mar 03 21:21:26 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/generators/source/ParameterInfo.java	Mon Mar 03 23:01:50 2014 +0400
@@ -24,6 +24,13 @@
  */
 package org.openjdk.jmh.generators.source;
 
+/**
+ * Method parameter metadata.
+ */
 public interface ParameterInfo extends MetadataInfo {
+
+    /**
+     * @return parameter type
+     */
     ClassInfo getType();
 }