# HG changeset patch # User anazarov # Date 1406239968 25200 # Node ID 14935053bb07c079de200c38bc06b9a00003b5a8 # Parent 48eab270456cf8c7719d3cd6f59c40f01f2d5093 8050979: Provide javadoc for "framework" classes in langtools tests Reviewed-by: jjg diff -r 48eab270456c -r 14935053bb07 langtools/test/tools/javac/classfiles/attributes/LocalVariableTable/LocalVariableTestBase.java --- a/langtools/test/tools/javac/classfiles/attributes/LocalVariableTable/LocalVariableTestBase.java Thu Jul 24 13:11:03 2014 +0100 +++ b/langtools/test/tools/javac/classfiles/attributes/LocalVariableTable/LocalVariableTestBase.java Thu Jul 24 15:12:48 2014 -0700 @@ -36,14 +36,26 @@ import static java.lang.String.format; import static java.util.stream.Collectors.*; - +/** + * Base class for LocalVariableTable and LocalVariableTypeTable attributes tests. + * To add tests cases you should extend this class. + * Then implement {@link #getVariableTables} to get LocalVariableTable or LocalVariableTypeTable attribute. + * Then add method with local variables. + * Finally, annotate method with information about expected variables and their types + * by several {@link LocalVariableTestBase.ExpectedLocals} annotations. + * To run test invoke {@link #test()} method. + * If there are variables with the same name, set different scopes for them. + * + * @see #test() + */ public abstract class LocalVariableTestBase extends TestBase { public static final int DEFAULT_SCOPE = 0; private final ClassFile classFile; private final Class clazz; - protected abstract List getVariableTables(Code_attribute codeAttribute); - + /** + * @param clazz class to test. Must contains annotated methods with expected results. + */ public LocalVariableTestBase(Class clazz) { this.clazz = clazz; try { @@ -53,8 +65,12 @@ } } + protected abstract List getVariableTables(Code_attribute codeAttribute); - //info in the LocalVariableTable attribute is compared against expected info stored in annotations + /** + * Finds expected variables with their type in VariableTable. + * Also does consistency checks, like variables from the same scope must point to different indexes. + */ public void test() throws IOException { List testMethods = Stream.of(clazz.getDeclaredMethods()) .filter(m -> m.getAnnotationsByType(ExpectedLocals.class).length > 0) @@ -198,7 +214,10 @@ } } - + /** + * LocalVariableTable and LocalVariableTypeTable are similar. + * VariableTable interface is introduced to test this attributes in the same way without code duplication. + */ interface VariableTable { int localVariableTableLength(); @@ -231,14 +250,23 @@ } } + /** + * Used to store expected results in sources + */ @Retention(RetentionPolicy.RUNTIME) @Repeatable(Container.class) @interface ExpectedLocals { + /** + * @return name of a local variable + */ String name(); + /** + * @return type of local variable in the internal format. + */ String type(); - //variables from different scopes can share local variable table index and/or name. + //variables from different scopes can share the local variable table index and/or name. int scope() default DEFAULT_SCOPE; } diff -r 48eab270456c -r 14935053bb07 langtools/test/tools/javac/classfiles/attributes/SourceFile/SourceFileTestBase.java --- a/langtools/test/tools/javac/classfiles/attributes/SourceFile/SourceFileTestBase.java Thu Jul 24 13:11:03 2014 +0100 +++ b/langtools/test/tools/javac/classfiles/attributes/SourceFile/SourceFileTestBase.java Thu Jul 24 15:12:48 2014 -0700 @@ -30,18 +30,41 @@ import java.util.Map; import javax.tools.JavaFileObject; +/** + * Base class for Source file attribute tests. Checks expected file name for specified classes in the SourceFile attribute. + * To add new tests you should extend the SourceFileTestBase class and invoke {@link #test} for static sources + * or {@link #compileAndTest} for generated sources. For more information see corresponding methods. + * + * @see #test + * @see #compileAndTest + */ public class SourceFileTestBase extends TestBase { - + /** + * Checks expected fileName for the specified class in the SourceFile attribute. + * + * @param classToTest class to check its SourceFile attribute + * @param fileName expected name of the file from which the test file is compiled. + */ protected void test(Class classToTest, String fileName) throws Exception { assertAttributePresent(ClassFile.read(getClassFile(classToTest)), fileName); } + /** + * Checks expected fileName for the specified class in the SourceFile attribute. + * + * @param classToTest class name to check its SourceFile attribute + * @param fileName expected name of the file from which the test file is compiled. + */ protected void test(String classToTest, String fileName) throws Exception { assertAttributePresent(ClassFile.read(getClassFile(classToTest + ".class")), fileName); } /** - * Compile sourceCode and for all "classesToTest" checks SourceFile attribute. + * Compiles sourceCode and for each specified class name checks the SourceFile attribute. + * The file name is extracted from source code. + * + * @param sourceCode source code to compile + * @param classesToTest class names to check their SourceFile attribute. */ protected void compileAndTest(String sourceCode, String... classesToTest) throws Exception { diff -r 48eab270456c -r 14935053bb07 langtools/test/tools/javac/classfiles/attributes/lib/TestBase.java --- a/langtools/test/tools/javac/classfiles/attributes/lib/TestBase.java Thu Jul 24 13:11:03 2014 +0100 +++ b/langtools/test/tools/javac/classfiles/attributes/lib/TestBase.java Thu Jul 24 15:12:48 2014 -0700 @@ -23,11 +23,14 @@ import java.io.File; import java.io.IOException; -import java.io.PrintStream; -import java.util.*; +import java.util.List; +import java.util.Objects; import java.util.function.Function; import java.util.stream.Stream; -import javax.tools.*; +import javax.tools.DiagnosticCollector; +import javax.tools.JavaCompiler; +import javax.tools.JavaFileObject; +import javax.tools.ToolProvider; import static java.lang.String.format; import static java.lang.System.lineSeparator; @@ -36,6 +39,11 @@ import static java.util.stream.Collectors.joining; import static java.util.stream.Collectors.toList; +/** + * Base class for class file attribute tests. + * Contains methods for compiling generated sources in memory, + * for reading files from disk and a lot of assert* methods. + */ public class TestBase { public static final String LINE_SEPARATOR = lineSeparator(); @@ -66,35 +74,48 @@ } } + /** + * Compiles sources in memory. + * + * @param sources to compile. + * @return memory file manager which contains class files and class loader. + */ public InMemoryFileManager compile(String... sources) throws IOException, CompilationException { return compile(emptyList(), sources); } /** - * @param options - compiler options - * @param sources + * Compiles sources in memory. + * + * @param options compiler options. + * @param sources sources to compile. * @return map where key is className, value is corresponding ClassFile. - * @throws IOException */ - public InMemoryFileManager compile(List options, String...sources) + public InMemoryFileManager compile(List options, String... sources) throws IOException, CompilationException { return compile(options, ToolBox.JavaSource::new, asList(sources)); } + /** + * Compiles sources in memory. + * + * @param sources sources[i][0] - name of file, sources[i][1] - sources. + * @return map where key is className, value is corresponding ClassFile. + */ public InMemoryFileManager compile(String[]... sources) throws IOException, CompilationException { return compile(emptyList(), sources); } /** - * @param options - compiler options - * @param sources - sources[i][0] - name of file, sources[i][1] - sources + * Compiles sources in memory. + * + * @param options compiler options + * @param sources sources[i][0] - name of file, sources[i][1] - sources. * @return map where key is className, value is corresponding ClassFile. - * @throws IOException - * @throws CompilationException */ - public InMemoryFileManager compile(List options, String[]...sources) + public InMemoryFileManager compile(List options, String[]... sources) throws IOException, CompilationException { return compile(options, src -> new ToolBox.JavaSource(src[0], src[1]), asList(sources)); } @@ -142,11 +163,22 @@ return getClassFile(clazz.getName().replace(".", "/") + ".class"); } + /** + * Prints message to standard error. New lines are converted to system dependent NL. + * + * @param message string to print. + */ public void echo(String message) { System.err.println(message.replace("\n", LINE_SEPARATOR)); } - public void printf(String template, Object...args) { + /** + * Substitutes args in template and prints result to standard error. New lines are converted to system dependent NL. + * + * @param template template in standard String.format(...) format. + * @param args arguments to substitute in template. + */ + public void printf(String template, Object... args) { System.err.printf(template, Stream.of(args) .map(Objects::toString) .map(m -> m.replace("\n", LINE_SEPARATOR))