jdk-sandbox: comparison langtools/test/com/sun/javadoc/lib/JavadocTester.java

equal deleted inserted replaced

-:601a611d0aee
+:af1a0220d0fa
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */
-import java.io.*;
+import java.io.BufferedWriter;
+import java.io.ByteArrayOutputStream;
+import java.io.File;
+import java.io.FileNotFoundException;
+import java.io.FileWriter;
+import java.io.FilenameFilter;
+import java.io.IOException;
+import java.io.PrintStream;
+import java.io.PrintWriter;
+import java.io.StringWriter;
+import java.lang.annotation.Annotation;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.ref.SoftReference;
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.nio.file.Files;
+import java.util.ArrayList;
+import java.util.EnumMap;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 /**
-* Runs javadoc and then runs regression tests on the resulting output.
+* Test framework for running javadoc and performing tests on the resulting output.
-* This class currently contains three tests:
+*
-* <ul>
+* <p>
-* <li> String search: Reads each file, complete with newlines,
+* Tests are typically written as subtypes of JavadocTester, with a main
-*      into a string.  Lets you search for strings that contain
+* method that creates an instance of the test class and calls the runTests()
-*      newlines.  String matching is case-sensitive.
+* method. The runTests() methods calls all the test methods declared in the class,
-*      You can run javadoc multiple times with different arguments,
+* and then calls a method to print a summary, and throw an exception if
-*      generating output into different destination directories, and
+* any of the test methods reported a failure.
-*      then perform a different array of tests on each one.
+*
-*      To do this, the run method accepts a test array for testing
+* <p>
-*      that a string is found, and a negated test array for testing
+* Test methods are identified with a @Test annotation. They have no parameters.
-*      that a string is not found.
+* The name of the method is not important, but if you have more than one, it is
-* <li> Run diffs: Iterate through the list of given file pairs
+* recommended that the names be meaningful and suggestive of the test case
-*      and diff the pairs.
+* contained therein.
-* <li> Check exit code: Check the exit code of Javadoc and
+*
-*      record whether the test passed or failed.
+* <p>
-* </ul>
+* Typically, a test method will invoke javadoc, and then perform various
+* checks on the results. The standard checks are:
+*
+* <dl>
+* <dt>checkExitCode
+* <dd>Check the exit code returned from javadoc.
+* <dt>checkOutput
+* <dd>Perform a series of checks on the contents on a file or output stream
+*     generated by javadoc.
+*     The checks can be either that a series of strings are found or are not found.
+* <dt>checkFiles
+* <dd>Perform a series of checks on the files generated by javadoc.
+*     The checks can be that a series of files are found or are not found.
+* </dl>
+*
+* <pre><code>
+*  public class MyTester extends JavadocTester {
+*      public static void main(String... args) throws Exception {
+*          MyTester tester = new MyTester();
+*          tester.runTests();
+*      }
+*
+*      // test methods...
+*      @Test
+*      void test() {
+*          javadoc(<i>args</i>);
+*          checkExit(Exit.OK);
+*          checkOutput(<i>file</i>, true,
+*              <i>strings-to-find</i>);
+*          checkOutput(<i>file</i>, false,
+*              <i>strings-to-not-find</i>);
+*      }
+*  }
+* </code></pre>
+*
+* <p>
+* If javadoc is run more than once in a test method, you can compare the
+* results that are generated with the diff method. Since files written by
+* javadoc typically contain a timestamp, you may want to use the -notimestamp
+* option if you are going to compare the results from two runs of javadoc.
+*
+* <p>
+* If you have many calls of checkOutput that are very similar, you can write
+* your own check... method to reduce the amount of duplication. For example,
+* if you want to check that many files contain the same string, you could
+* write a method that takes a varargs list of files and calls checkOutput
+* on each file in turn with the string to be checked.
+*
+* <p>
+* You can also write you own custom check methods, which can use
+* readFile to get the contents of a file generated by javadoc,
+* and then use pass(...) or fail(...) to report whether the check
+* succeeded or not.
+*
+* <p>
+* You can have many separate test methods, each identified with a @Test
+* annotation. However, you should <b>not</b> assume they will be called
+* in the order declared in your source file.  If the order of a series
+* of javadoc invocations is important, do that within a single method.
+* If the invocations are independent, for better clarity, use separate
+* test methods, each with their own set of checks on the results.
 *
 * @author Doug Kramer
 * @author Jamie Ho
-* @since 1.4.2
+* @author Jonathan Gibbons (rewrite)
 */
 public abstract class JavadocTester {
-protected static final String NL = System.getProperty("line.separator");
+public static final String FS = System.getProperty("file.separator");
-protected static final String FS = System.getProperty("file.separator");
+public static final String PS = System.getProperty("path.separator");
+public static final String NL = System.getProperty("line.separator");
-protected static final String SRC_DIR = System.getProperty("test.src", ".");
-protected static final String JAVA_VERSION = System.getProperty("java.version");
+public enum Output {
-protected static final String OUTPUT_DIR = "out";
+/** The name for error output from javadoc. */
-protected static final String[][] NO_TEST = new String[][] {};
+ERROR,
-protected static final String[] NO_FILE_TEST = new String[] {};
+/** The name for the notice output from javadoc. */
+NOTICE,
-/**
+/** The name for the warning output  from javadoc. */
-* Use this as the file name in the test array when you want to search
+WARNING,
-* for a string in the error output.
+/** The name for any output written to System.out. */
-*/
+STDOUT,
-public static final String ERROR_OUTPUT = "ERROR_OUTPUT";
+/** The name for any output written to System.err. */
+STDERR
-/**
+}
-* Use this as the file name in the test array when you want to search
-* for a string in the notice output.
+/** The output directory used in the most recent call of javadoc. */
-*/
+protected File outputDir;
-public static final String NOTICE_OUTPUT = "NOTICE_OUTPUT";
+/** The exit code of the most recent call of javadoc. */
-/**
+private int exitCode;
-* Use this as the file name in the test array when you want to search
-* for a string in the warning output.
+/** The output generated by javadoc to the various writers and streams. */
-*/
+private final Map<Output, String> outputMap = new EnumMap<>(Output.class);
-public static final String WARNING_OUTPUT = "WARNING_OUTPUT";
+/** A cache of file content, to avoid reading files unnecessarily. */
-/**
+private final Map<File,SoftReference<String>> fileContentCache = new HashMap<>();
-* Use this as the file name in the test array when you want to search
-* for a string in standard output.
+/** Stream used for logging messages. */
-*/
+private final PrintStream out = System.out;
-public static final String STANDARD_OUTPUT = "STANDARD_OUTPUT";
+/** The directory containing the source code for the test. */
-/**
+public static final String testSrc = System.getProperty("test.src");
-* The default doclet.
-*/
+/**
-public static final String DEFAULT_DOCLET_CLASS = "com.sun.tools.doclets.formats.html.HtmlDoclet";
+* Get the path for a source file in the test source directory.
-public static final String DEFAULT_DOCLET_CLASS_OLD = "com.sun.tools.doclets.standard.Standard";
+* @param path the path of a file or directory in the source directory
+* @return the full path of the specified file
-/**
+*/
-* The writer to write error messages.
+public static String testSrc(String path) {
-*/
+return new File(testSrc, path).getPath();
-public StringWriter errors;
+}
-/**
-* The writer to write notices.
-*/
-public StringWriter notices;
-/**
-* The writer to write warnings.
-*/
-public StringWriter warnings;
-/**
-* The buffer of warning output.
-*/
-public StringBuffer standardOut;
-/**
-* The output directory.
-*/
-private File outputDir;
 /**
 * Alternatives for checking the contents of a directory.
 */
-enum DirectoryCheck {
+public enum DirectoryCheck {
 /**
 * Check that the directory is empty.
 */
 EMPTY((file, name) -> true),
 /**
 }
 }
 private DirectoryCheck outputDirectoryCheck = DirectoryCheck.EMPTY;
-/**
+/** The current subtest number. Incremented when checking(...) is called. */
-* The current subtest number.
+private int numTestsRun = 0;
-*/
-private static int numTestsRun = 0;
+/** The number of subtests passed. Incremented when passed(...) is called. */
+private int numTestsPassed = 0;
-/**
-* The number of subtests passed.
+/** The current run of javadoc. Incremented when javadoc is called. */
-*/
+private int javadocRunNum = 0;
-private static int numTestsPassed = 0;
+/** The name of the standard doclet. */
-/**
+// This ought not to be necessary; there ought to be a javadoc entry point
-* The current run of javadoc
+// that does not require this to be know externally.
-*/
+private static final String standardDocletClassName =
-private static int javadocRunNum = 0;
+"com.sun.tools.doclets.standard.Standard";
-/**
+/** Marker annotation for test methods to be invoked by runTests. */
-* Construct a JavadocTester.
+@Retention(RetentionPolicy.RUNTIME)
-*/
+@interface Test { }
-public JavadocTester() {
-}
+/**
+* Run all methods annotated with @Test, followed by printSummary.
-/**
+* Typically called on a tester object in main()
-* Execute the tests.
+* @throws Exception if any errors occurred
-*
+*/
-* @param args             the arguments to pass to Javadoc
+public void runTests() throws Exception {
-* @param testArray        the array of tests
+for (Method m: getClass().getDeclaredMethods()) {
-* @param negatedTestArray the array of negated tests
+Annotation a = m.getAnnotation(Test.class);
-* @return                 the return code for the execution of Javadoc
+if (a != null) {
-*/
+try {
-public int run(String[] args,
+out.println("Running test " + m.getName());
-String[][] testArray, String[][] negatedTestArray) {
+m.invoke(this, new Object[] { });
-int returnCode = runJavadoc(args);
+} catch (InvocationTargetException e) {
-runTestsOnHTML(testArray, negatedTestArray);
+Throwable cause = e.getCause();
-return returnCode;
+throw (cause instanceof Exception) ? ((Exception) cause) : e;
 }
+out.println();
-/**
+}
-* Execute the tests.
+}
-*
+printSummary();
-* @param args                 the arguments to pass to Javadoc
+}
-* @param testArray            the array of tests
-* @param negatedTestArray     the array of negated tests
+/**
-* @param fileTestArray        the array of file tests
+* Run javadoc.
-* @param negatedFileTestArray the array of negated file tests
+* The output directory used by this call and the final exit code
-* @return                     the return code for the execution of Javadoc
+* will be saved for later use.
-*/
+* To aid the reader, it is recommended that calls to this method
-public int run(String[] args,
+* put each option and the arguments it takes on a separate line.
-String[][] testArray, String[][] negatedTestArray,
+*
-String[] fileTestArray, String[] negatedFileTestArray) {
+* Example:
-int returnCode = runJavadoc(args);
+* <pre><code>
-runTestsOnHTML(testArray, negatedTestArray);
+*  javadoc("-d", "out",
-runTestsOnFile(fileTestArray, negatedFileTestArray);
+*          "-sourcepath", testSrc,
-return returnCode;
+*          "-notimestamp",
-}
+*          "pkg1", "pkg2", "pkg3/C.java");
+* </code></pre>
-/**
+*
-* Execute Javadoc using the default doclet.
+* @param args the arguments to pass to javadoc
-*
+*/
-* @param args  the arguments to pass to Javadoc
+public void javadoc(String... args) {
-* @return      the return code from the execution of Javadoc
+outputMap.clear();
-*/
+fileContentCache.clear();
-public int runJavadoc(String[] args) {
-float javaVersion = Float.parseFloat(JAVA_VERSION.substring(0,3));
-String docletClass = javaVersion < 1.5 ?
-DEFAULT_DOCLET_CLASS_OLD : DEFAULT_DOCLET_CLASS;
-return runJavadoc(docletClass, args);
-}
-/**
-* Execute Javadoc.
-*
-* @param docletClass the doclet being tested.
-* @param args  the arguments to pass to Javadoc
-* @return      the return code from the execution of Javadoc
-*/
-public int runJavadoc(String docletClass, String[] args) {
 javadocRunNum++;
 if (javadocRunNum == 1) {
-System.out.println("\n" + "Running javadoc...");
+out.println("Running javadoc...");
 } else {
-System.out.println("\n" + "Running javadoc (run "
+out.println("Running javadoc (run "
 + javadocRunNum + ")...");
 }
-initOutputBuffers();
 outputDir = new File(".");
 for (int i = 0; i < args.length - 2; i++) {
 if (args[i].equals("-d")) {
 outputDir = new File(args[++i]);
 break;
 }
 }
+//        log.setOutDir(outputDir);
 outputDirectoryCheck.check(outputDir);
-ByteArrayOutputStream stdout = new ByteArrayOutputStream();
+// These are the primary streams used by javadoc
-PrintStream prevOut = System.out;
+WriterOutput errOut = new WriterOutput();
-System.setOut(new PrintStream(stdout));
+WriterOutput warnOut = new WriterOutput();
+WriterOutput noticeOut = new WriterOutput();
-ByteArrayOutputStream stderr = new ByteArrayOutputStream();
+// These are to catch output to System.out and System.err,
-PrintStream prevErr = System.err;
+// in case these are used instead of the primary streams
-System.setErr(new PrintStream(stderr));
+StreamOutput sysOut = new StreamOutput(System.out, System::setOut);
+StreamOutput sysErr = new StreamOutput(System.err, System::setErr);
-int returnCode = com.sun.tools.javadoc.Main.execute(
-"javadoc",
+try {
-new PrintWriter(errors, true),
+exitCode = com.sun.tools.javadoc.Main.execute(
-new PrintWriter(warnings, true),
+"javadoc",
-new PrintWriter(notices, true),
+errOut.pw, warnOut.pw, noticeOut.pw,
-docletClass,
+standardDocletClassName,
-getClass().getClassLoader(),
+args);
-args);
+} finally {
-System.setOut(prevOut);
+outputMap.put(Output.STDOUT, sysOut.close());
-standardOut = new StringBuffer(stdout.toString());
+outputMap.put(Output.STDERR, sysErr.close());
-System.setErr(prevErr);
+outputMap.put(Output.ERROR, errOut.close());
-errors.write(NL + stderr.toString());
+outputMap.put(Output.WARNING, warnOut.close());
+outputMap.put(Output.NOTICE, noticeOut.close());
-printJavadocOutput();
+}
-return returnCode;
-}
+outputMap.forEach((name, text) -> {
+if (!text.isEmpty()) {
-/**
+out.println("javadoc " + name + ":");
-* Set a filter to check the initial contents of the output directory
+out.println(text);
+}
+});
+}
+/**
+* Set the kind of check for the initial contents of the output directory
 * before javadoc is run.
 * The filter should return true for files that should <b>not</b> appear.
-*/
+* @param c the kind of check to perform
-public void setCheckOutputDirectoryCheck(DirectoryCheck c) {
+*/
+public void setOutputDirectoryCheck(DirectoryCheck c) {
 outputDirectoryCheck = c;
 }
-/**
+public enum Exit {
-* Create new string writer buffers
+OK(0),
-*/
+FAILED(1);
-private void initOutputBuffers() {
-errors   = new StringWriter();
+Exit(int code) {
-notices  = new StringWriter();
+this.code = code;
-warnings = new StringWriter();
+}
-}
+final int code;
-/**
+}
-* Run array of tests on the resulting HTML.
-* This method accepts a testArray for testing that a string is found
+/**
-* and a negatedTestArray for testing that a string is not found.
+* Check the exit code of the most recent call of javadoc.
 *
-* @param testArray         the array of tests
+* @param expected the exit code that is required for the test
-* @param negatedTestArray  the array of negated tests
+* to pass.
 */
-public void runTestsOnHTML(String[][] testArray, String[][] negatedTestArray) {
+public void checkExit(Exit expected) {
-runTestsOnHTML(testArray, false);
+checking("check exit code");
-runTestsOnHTML(negatedTestArray, true);
+if (exitCode == expected.code) {
-}
+passed("return code " + exitCode);
+} else {
-/**
+failed("return code " + exitCode +"; expected " + expected.code + " (" + expected + ")");
-* Run array of tests on the generated files.
+}
-* This method accepts a fileTestArray for testing if a file is generated
+}
-* and a negatedFileTestArray for testing if a file is not found.
-* The files are relative to the most recent output directory specified
+/**
-* with -d.
+* Check for content in (or not in) the generated output.
-*
+* Within the search strings, the newline character \n
-* @param fileTestArray         the array of file tests
+* will be translated to the platform newline character sequence.
-* @param negatedFileTestArray  the array of negated file tests
+* @param path a path within the most recent output directory
-*/
+*  or the name of one of the output buffers, identifying
-public void runTestsOnFile(String[] fileTestArray, String[] negatedFileTestArray) {
+*  where to look for the search strings.
-runTestsOnFile(outputDir, fileTestArray, false);
+* @param expectedFound true if all of the search strings are expected
-runTestsOnFile(outputDir, negatedFileTestArray, true);
+*  to be found, or false if all of the strings are expected to be
-}
+*  not found
+* @param strings the strings to be searched for
-/**
+*/
-* Run the array of tests on the resulting HTML.
+public void checkOutput(String path, boolean expectedFound, String... strings) {
-* The files are relative to the most recent output directory specified
+// Read contents of file
-* with -d.
+String fileString;
-*
+try {
-* @param testArray the array of tests
+fileString = readFile(outputDir, path);
-* @param isNegated true if test is negated; false otherwise
+} catch (Error e) {
-*/
+if (!expectedFound) {
-private void runTestsOnHTML(String[][] testArray , boolean isNegated) {
+failed("Error reading file: " + e);
-for (String[] test : testArray) {
+return;
-numTestsRun++;
+}
-System.out.print("Running subtest #" + numTestsRun + "... ");
+throw e;
-// Get string to find
+}
-String stringToFind = test[1];
+checkOutput(path, fileString, expectedFound, strings);
-// Read contents of file into a string
+}
-String fileString;
-try {
+/**
-fileString = readFileToString(outputDir, test[0]);
+* Check for content in (or not in) the one of the output streams written by
-} catch (Error e) {
+* javadoc. Within the search strings, the newline character \n
-if (isNegated) {
+* will be translated to the platform newline character sequence.
-System.out.println( "FAILED, due to " + e + "\n");
+* @param output the output stream to check
-continue;
+* @param expectedFound true if all of the search strings are expected
-}
+*  to be found, or false if all of the strings are expected to be
-throw e;
+*  not found
-}
+* @param strings the strings to be searched for
+*/
+public void checkOutput(Output output, boolean expectedFound, String... strings) {
+checkOutput(output.toString(), outputMap.get(output), expectedFound, strings);
+}
+private void checkOutput(String path, String fileString, boolean expectedFound, String... strings) {
+for (String stringToFind : strings) {
+//            log.logCheckOutput(path, expectedFound, stringToFind);
+checking("checkOutput");
 // Find string in file's contents
 boolean isFound = findString(fileString, stringToFind);
-if ((isNegated && !isFound) || (!isNegated && isFound)) {
+if (isFound == expectedFound) {
-numTestsPassed += 1;
+passed(path + ": " + (isFound ? "found:" : "not found:") + "\n"
-System.out.println("Passed" + "\n"
++ stringToFind + "\n");
-+ (isNegated ? "not found:" : "found:") + "\n"
-+ stringToFind + " in " + test[0] + "\n");
 } else {
-System.out.println("FAILED, when searching for:" + "\n"
+failed(path + ": " + (isFound ? "found:" : "not found:") + "\n"
-+ stringToFind
++ stringToFind + "\n");
-+ " in " + test[0] + "\n");
+}
 }
 }
-}
+/**
-/**
+* Check for files in (or not in) the generated output.
-* Run the array of file tests on the generated files.
+* @param expectedFound true if all of the files are expected
-*
+*  to be found, or false if all of the files are expected to be
-* @param testArray the array of file tests
+*  not found
-* @param isNegated true if test is negated; false otherwise
+* @param paths the files to check, within the most recent output directory.
-*/
+* */
-private void runTestsOnFile(File baseDir, String[] testArray, boolean isNegated) {
+public void checkFiles(boolean expectedFound, String... paths) {
-for (String fileName : testArray) {
+for (String path: paths) {
-numTestsRun++;
+//            log.logCheckFile(path, expectedFound);
-String failedString = "FAILED: file (" + fileName + ") found" + "\n";
+checking("checkFile");
-String passedString = "Passed" + "\n" +
+File file = new File(outputDir, path);
-"file (" + fileName + ") not found" + "\n";
+boolean isFound = file.exists();
-System.out.print("Running subtest #" + numTestsRun + "... ");
+if (isFound == expectedFound) {
-try {
+passed(path + ": " + (isFound ? "found:" : "not found:") + "\n");
-File file = new File(baseDir, fileName);
+} else {
-if ((file.exists() && !isNegated) || (!file.exists() && isNegated)) {
+failed(path + ": " + (isFound ? "found:" : "not found:") + "\n");
-numTestsPassed += 1;
+}
-System.out.println(passedString);
+}
-} else {
+}
-System.out.println(failedString);
-}
+/**
-} catch (Error e) {
+* Check that a series of strings are found in order in a file in
-System.err.println(e);
+* the generated output.
-}
+* @param path the file to check
-}
+* @param strings  the strings whose order to check
-}
+*/
+public void checkOrder(String path, String... strings) {
-/**
+String fileString = readOutputFile(path);
-* Iterate through the list of given file pairs and diff each file.
+int prevIndex = -1;
+for (String s : strings) {
+int currentIndex = fileString.indexOf(s);
+checking(s + " at index " + currentIndex);
+if (currentIndex >= prevIndex) {
+passed(s + "is in the correct order");
+} else {
+failed(s + " is in the wrong order.");
+}
+prevIndex = currentIndex;
+}
+}
+/**
+* Compare a set of files in each of two directories.
 *
 * @param baseDir1 the directory containing the first set of files
 * @param baseDir2 the directory containing the second set of files
 * @param files the set of files to be compared
-* @throws Error if any differences are found between
+*/
-* file pairs.
+public void diff(String baseDir1, String baseDir2, String... files) {
-*/
-public void runDiffs(String baseDir1, String baseDir2, String[] files) throws Error {
-runDiffs(baseDir1, baseDir2, files, true);
-}
-/**
-* Iterate through the list of given file pairs and diff each file.
-*
-* @param baseDir1 the directory containing the first set of files
-* @param baseDir2 the directory containing the second set of files
-* @param files the set of files to be compared
-* @param throwErrorIfNoMatch flag to indicate whether or not to throw
-* an error if the files do not match.
-*
-* @throws Error if any differences are found between
-* file pairs and throwErrorIfNoMatch is true.
-*/
-public void runDiffs(String baseDir1, String baseDir2, String[] files, boolean throwErrorIfNoMatch) throws Error {
 File bd1 = new File(baseDir1);
 File bd2 = new File(baseDir2);
 for (String file : files) {
-diff(bd1, bd2, file, throwErrorIfNoMatch);
+diff(bd1, bd2, file);
 }
 }
 /**
-* Check the exit code of Javadoc and record whether the test passed
+* A utility to copy a directory from one place to another.
-* or failed.
+*
-*
+* @param targetDir the directory to copy.
-* @param expectedExitCode The exit code that is required for the test
+* @param destDir the destination to copy the directory to.
-* to pass.
+*/
-* @param actualExitCode The actual exit code from the previous run of
+// TODO: convert to using java.nio.Files.walkFileTree
-* Javadoc.
+public void copyDir(String targetDir, String destDir) {
-*/
+try {
-public void checkExitCode(int expectedExitCode, int actualExitCode) {
+File targetDirObj = new File(targetDir);
-numTestsRun++;
+File destDirParentObj = new File(destDir);
-if (expectedExitCode == actualExitCode) {
+File destDirObj = new File(destDirParentObj, targetDirObj.getName());
-System.out.println( "Passed" + "\n" + " got return code " +
+if (! destDirParentObj.exists()) {
-actualExitCode);
+destDirParentObj.mkdir();
-numTestsPassed++;
+}
-} else {
+if (! destDirObj.exists()) {
-System.out.println( "FAILED: expected return code " +
+destDirObj.mkdir();
-expectedExitCode + " but got " + actualExitCode);
+}
-}
+String[] files = targetDirObj.list();
-}
+for (String file : files) {
+File srcFile = new File(targetDirObj, file);
-/**
+File destFile = new File(destDirObj, file);
-* Print a summary of the test results.
+if (srcFile.isFile()) {
-*/
+out.println("Copying " + srcFile + " to " + destFile);
-protected void printSummary() {
+copyFile(destFile, srcFile);
-if ( numTestsRun != 0 && numTestsPassed == numTestsRun ) {
+} else if(srcFile.isDirectory()) {
-// Test passed
+copyDir(srcFile.getAbsolutePath(), destDirObj.getAbsolutePath());
-System.out.println("\n" + "All " + numTestsPassed
+}
-+ " subtests passed");
+}
-} else {
+} catch (IOException exc) {
-// Test failed
+throw new Error("Could not copy " + targetDir + " to " + destDir);
-throw new Error("\n" + (numTestsRun - numTestsPassed)
+}
-+ " of " + (numTestsRun)
+}
-+ " subtests failed\n");
-}
+/**
-}
+* Copy source file to destination file.
+*
-/**
+* @param destfile the destination file
-* Print the output stored in the buffers.
+* @param srcfile the source file
-*/
+* @throws IOException
-protected void printJavadocOutput() {
+*/
-System.out.println(STANDARD_OUTPUT + " : \n" + getStandardOutput());
+public void copyFile(File destfile, File srcfile) throws IOException {
-System.err.println(ERROR_OUTPUT + " : \n" + getErrorOutput());
+Files.copy(srcfile.toPath(), destfile.toPath());
-System.err.println(WARNING_OUTPUT + " : \n" + getWarningOutput());
+}
-System.out.println(NOTICE_OUTPUT + " : \n" + getNoticeOutput());
-}
+/**
+* Read a file from the output directory.
-/**
-* Read the file and return it as a string.
 *
 * @param fileName  the name of the file to read
 * @return          the file in string format
 */
-public String readFileToString(String fileName) throws Error {
+public String readOutputFile(String fileName) throws Error {
-return readFileToString(outputDir, fileName);
+return readFile(outputDir, fileName);
+}
+protected String readFile(String fileName) throws Error {
+return readFile(outputDir, fileName);
+}
+protected String readFile(String baseDir, String fileName) throws Error {
+return readFile(new File(baseDir), fileName);
 }
 /**
 * Read the file and return it as a string.
 *
 * @param baseDir   the directory in which to locate the file
 * @param fileName  the name of the file to read
 * @return          the file in string format
 */
-private String readFileToString(File baseDir, String fileName) throws Error {
+private String readFile(File baseDir, String fileName) throws Error {
-switch (fileName) {
-case ERROR_OUTPUT:
-return getErrorOutput();
-case NOTICE_OUTPUT:
-return getNoticeOutput();
-case WARNING_OUTPUT:
-return getWarningOutput();
-case STANDARD_OUTPUT:
-return getStandardOutput();
-}
 try {
 File file = new File(baseDir, fileName);
-if ( !file.exists() ) {
+SoftReference<String> ref = fileContentCache.get(file);
-System.out.println("\n" + "FILE DOES NOT EXIST: " + fileName);
+String content = (ref == null) ? null : ref.get();
-}
+if (content != null)
-char[] allChars;
+return content;
-try (BufferedReader in = new BufferedReader(new FileReader(file))) {
-// Create an array of characters the size of the file
+content = new String(Files.readAllBytes(file.toPath()));
-allChars = new char[(int)file.length()];
+fileContentCache.put(file, new SoftReference(content));
-// Read the characters into the allChars array
+return content;
-in.read(allChars, 0, (int)file.length());
-}
-// Convert to a string
-String allCharsString = new String(allChars);
-return allCharsString;
 } catch (FileNotFoundException e) {
 System.err.println(e);
 throw new Error("File not found: " + fileName);
 } catch (IOException e) {
 System.err.println(e);
 throw new Error("Error reading file: " + fileName);
 }
 }
+protected void checking(String message) {
+numTestsRun++;
+print("Starting subtest " + numTestsRun, message);
+}
+protected void passed(String message) {
+numTestsPassed++;
+print("Passed", message);
+}
+protected void failed(String message) {
+print("FAILED", message);
+}
+private void print(String prefix, String message) {
+if (message.isEmpty())
+out.println(prefix);
+else {
+out.print(prefix);
+out.print(": ");
+out.println(message.replace("\n", NL));
+}
+}
+/**
+* Print a summary of the test results.
+*/
+protected void printSummary() {
+//        log.write();
+if (numTestsRun != 0 && numTestsPassed == numTestsRun) {
+// Test passed
+out.println();
+out.println("All " + numTestsPassed + " subtests passed");
+} else {
+// Test failed
+throw new Error((numTestsRun - numTestsPassed)
++ " of " + (numTestsRun)
++ " subtests failed");
+}
+}
+/**
+* Search for the string in the given file and return true
+* if the string was found.
+*
+* @param fileString    the contents of the file to search through
+* @param stringToFind  the string to search for
+* @return              true if the string was found
+*/
+private boolean findString(String fileString, String stringToFind) {
+// javadoc (should) always use the platform newline sequence,
+// but in the strings to find it is more convenient to use the Java
+// newline character. So we translate \n to NL before we search.
+stringToFind = stringToFind.replace("\n", NL);
+return fileString.contains(stringToFind);
+}
 /**
 * Compare the two given files.
 *
 * @param baseDir1 the directory in which to locate the first file
 * @param baseDir2 the directory in which to locate the second file
 * @param file the file to compare in the two base directories
 * @param throwErrorIFNoMatch flag to indicate whether or not to throw
 * an error if the files do not match.
 * @return true if the files are the same and false otherwise.
 */
-private boolean diff(File baseDir1, File baseDir2, String file,
+private void diff(File baseDir1, File baseDir2, String file) {
-boolean throwErrorIFNoMatch) throws Error {
+String file1Contents = readFile(baseDir1, file);
-String file1Contents = readFileToString(baseDir1, file);
+String file2Contents = readFile(baseDir2, file);
-String file2Contents = readFileToString(baseDir2, file);
+checking("diff " + new File(baseDir1, file) + ", " + new File(baseDir2, file));
-numTestsRun++;
 if (file1Contents.trim().compareTo(file2Contents.trim()) == 0) {
-System.out.println("Diff successful: " + new File(baseDir1, file) + ", " + new File(baseDir2, file));
+passed("files are equal");
-numTestsPassed++;
-return true;
-} else if (throwErrorIFNoMatch) {
-throw new Error("Diff failed: " + new File(baseDir1, file) + ", " + new File(baseDir2, file));
 } else {
-return false;
+failed("files differ");
 }
 }
 /**
-* Search for the string in the given file and return true
+* Utility class to simplify the handling of temporarily setting a
-* if the string was found.
+* new stream for System.out or System.err.
-*
+*/
-* @param fileString    the contents of the file to search through
+private static class StreamOutput {
-* @param stringToFind  the string to search for
+// functional interface to set a stream.
-* @return              true if the string was found
+private interface Initializer {
-*/
+void set(PrintStream s);
-private boolean findString(String fileString, String stringToFind) {
+}
-return fileString.contains(stringToFind.replace("\n", NL));
-}
+private final ByteArrayOutputStream baos = new ByteArrayOutputStream();
+private final PrintStream ps = new PrintStream(baos);
+private final PrintStream prev;
-/**
+private final Initializer init;
-* Return the standard output.
-* @return the standard output
+StreamOutput(PrintStream s, Initializer init) {
-*/
+prev = s;
-public String getStandardOutput() {
+init.set(ps);
-return standardOut.toString();
+this.init = init;
 }
-/**
+String close() {
-* Return the error output.
+init.set(prev);
-* @return the error output
+ps.close();
-*/
+return baos.toString();
-public String getErrorOutput() {
+}
-return errors.getBuffer().toString();
+}
-}
+/**
-/**
+* Utility class to simplify the handling of creating an in-memory PrintWriter.
-* Return the notice output.
+*/
-* @return the notice output
+private static class WriterOutput {
-*/
+private final StringWriter sw = new StringWriter();
-public String getNoticeOutput() {
+final PrintWriter pw = new PrintWriter(sw);
-return notices.getBuffer().toString();
+String close() {
-}
+pw.close();
+return sw.toString();
-/**
+}
-* Return the warning output.
+}
-* @return the warning output
-*/
-public String getWarningOutput() {
+//    private final Logger log = new Logger();
-return warnings.getBuffer().toString();
-}
+//--------- Logging --------------------------------------------------------
+//
-/**
+// This class writes out the details of calls to checkOutput and checkFile
-* A utility to copy a directory from one place to another.
+// in a canonical way, so that the resulting file can be checked against
-* We may possibly want to move this to our doclet toolkit in
+// similar files from other versions of JavadocTester using the same logging
-* the near future and maintain it from there.
+// facilities.
-*
-* @param targetDir the directory to copy.
+static class Logger {
-* @param destDir the destination to copy the directory to.
+private static final int PREFIX = 40;
-*/
+private static final int SUFFIX = 20;
-public static void copyDir(String targetDir, String destDir) {
+private static final int MAX = PREFIX + SUFFIX;
-if (targetDir.endsWith("SCCS")) {
+List<String> tests = new ArrayList<>();
-return;
+String outDir;
-}
+String rootDir = rootDir();
-try {
-File targetDirObj = new File(targetDir);
+static String rootDir() {
-File destDirParentObj = new File(destDir);
+File f = new File(".").getAbsoluteFile();
-File destDirObj = new File(destDirParentObj, targetDirObj.getName());
+while (!new File(f, ".hg").exists())
-if (! destDirParentObj.exists()) {
+f = f.getParentFile();
-destDirParentObj.mkdir();
+return f.getPath();
 }
-if (! destDirObj.exists()) {
-destDirObj.mkdir();
+void setOutDir(File outDir) {
-}
+this.outDir = outDir.getPath();
-String[] files = targetDirObj.list();
+}
-for (String file : files) {
-File srcFile = new File(targetDirObj, file);
+void logCheckFile(String file, boolean positive) {
-File destFile = new File(destDirObj, file);
+// Strip the outdir because that will typically not be the same
-if (srcFile.isFile()) {
+if (file.startsWith(outDir + "/"))
-System.out.println("Copying " + srcFile + " to " + destFile);
+file = file.substring(outDir.length() + 1);
-copyFile(destFile, srcFile);
+tests.add(file + " " + positive);
-} else if(srcFile.isDirectory()) {
+}
-copyDir(srcFile.getAbsolutePath(), destDirObj.getAbsolutePath());
+void logCheckOutput(String file, boolean positive, String text) {
+// Compress the string to be displayed in the log file
+String simpleText = text.replaceAll("\\s+", " ").replace(rootDir, "[ROOT]");
+if (simpleText.length() > MAX)
+simpleText = simpleText.substring(0, PREFIX)
++ "..." + simpleText.substring(simpleText.length() - SUFFIX);
+// Strip the outdir because that will typically not be the same
+if (file.startsWith(outDir + "/"))
+file = file.substring(outDir.length() + 1);
+// The use of text.hashCode ensure that all of "text" is taken into account
+tests.add(file + " " + positive + " " + text.hashCode() + " " + simpleText);
+}
+void write() {
+// sort the log entries because the subtests may not be executed in the same order
+tests.sort((a, b) -> a.compareTo(b));
+try (BufferedWriter bw = new BufferedWriter(new FileWriter("tester.log"))) {
+for (String t: tests) {
+bw.write(t);
+bw.newLine();
 }
-}
+} catch (IOException e) {
-} catch (IOException exc) {
+throw new Error("problem writing log: " + e);
-throw new Error("Could not copy " + targetDir + " to " + destDir);
+}
-}
-}
-/**
-* Copy source file to destination file.
-*
-* @param destfile the destination file
-* @param srcfile the source file
-* @throws SecurityException
-* @throws IOException
-*/
-public static void copyFile(File destfile, File srcfile)
-throws IOException {
-byte[] bytearr = new byte[512];
-int len;
-FileInputStream input = new FileInputStream(srcfile);
-File destDir = destfile.getParentFile();
-destDir.mkdirs();
-FileOutputStream output = new FileOutputStream(destfile);
-try {
-while ((len = input.read(bytearr)) != -1) {
-output.write(bytearr, 0, len);
-}
-} catch (FileNotFoundException | SecurityException exc) {
-} finally {
-input.close();
-output.close();
 }
 }
 }

changeset 24399	af1a0220d0fa
parent 24217	25b12d4d4192
child 25004	b33effe4f252