8276892: Provide a way to emulate exceptional situations in FileManager when using JavadocTester

Reviewed-by: prappo

Author: jonathan-gibbons

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties

@@ -45,7 +45,7 @@ doclet.exception.write.file=Error writing file: {0}\n\
 \t({1})
 doclet.exception.read.resource=Error reading system resource: {0}\n\
 \t({1})
-doclet.internal.exception=An internal exception has occurred. \n\
+doclet.internal.exception=An internal exception has occurred.\n\
 \t({0})
 doclet.internal.report.bug=\
 Please file a bug against the javadoc tool via the Java bug reporting page\n\

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Main.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2021, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -24,7 +24,12 @@
  */
 package jdk.javadoc.internal.tool;
 
+import javax.tools.JavaFileManager;
+import javax.tools.StandardJavaFileManager;
 import java.io.PrintWriter;
+import java.util.Objects;
+
+import com.sun.tools.javac.util.Context;
 
 /**
  * Provides external entry points (tool and programmatic) for the javadoc program.
@@ -37,11 +42,6 @@
 
 public class Main {
 
-    /**
-     * This constructor should never be called.
-     */
-    private Main() { throw new AssertionError(); }
-
     /**
      * The main entry point called by the launcher. This will call
      * System.exit with an appropriate return value.
@@ -88,6 +88,65 @@ public static int execute(String[] args, PrintWriter outWriter, PrintWriter errW
         return jdoc.begin(args).exitCode;
     }
 
+
+    // builder-style API to run javadoc
+
+    private PrintWriter outWriter;
+    private PrintWriter errWriter;
+    private StandardJavaFileManager fileManager;
+
+    /**
+     * Creates a default builder to run javadoc.
+     */
+    public Main() { }
+
+    /**
+     * Sets the output and error streams to be used when running javadoc.
+     * The streams may be the same; they must not be {@code null}.
+     *
+     * @param outWriter the output stream
+     * @param errWriter the error stream
+     *
+     * @return this object
+     */
+    public Main setStreams(PrintWriter outWriter, PrintWriter errWriter) {
+        this.outWriter = Objects.requireNonNull(outWriter);
+        this.errWriter = Objects.requireNonNull(errWriter);
+        return this;
+    }
+
+    /**
+     * Sets the file manager to be used when running javadoc.
+     * A value of {@code null} means to use the default file manager.
+     *
+     * @param fileManager the file manager to use
+     *
+     * @return this object
+     */
+    public Main setFileManager(StandardJavaFileManager fileManager) {
+        this.fileManager = fileManager;
+        return this;
+    }
+
+    /**
+     * Runs javadoc with preconfigured values and a given set of arguments.
+     * Any errors will be reported to the error stream, or to {@link System#err}
+     * if no error stream has been specified with {@code setStreams}.
+     *
+     * @param args the arguments
+     *
+     * @return a value indicating the success or otherwise of the run
+     */
+    public Result run(String... args) {
+        Context context = null;
+        if (fileManager != null) {
+            context = new Context();
+            context.put(JavaFileManager.class, fileManager);
+        }
+        Start jdoc = new Start(context, null, outWriter, errWriter, null, null);
+        return jdoc.begin(args);
+    }
+
     public enum Result {
         /** completed with no errors */
         OK(0),

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java

@@ -36,6 +36,7 @@
 import java.util.IllformedLocaleException;
 import java.util.List;
 import java.util.Locale;
+import java.util.Map;
 import java.util.Objects;
 import java.util.Set;
 import java.util.function.Supplier;
@@ -520,7 +521,21 @@ private Result parseAndExecute(List<String> argList, Iterable<? extends JavaFile
         }
 
         if (fileManager instanceof BaseFileManager bfm) {
+            // standard file manager: use direct support for handling options
             bfm.handleOptions(options.fileManagerOptions());
+        } else {
+            // unrecognized file manager:
+            for (Map.Entry<com.sun.tools.javac.main.Option, String> e: options.fileManagerOptions().entrySet()) {
+                String optName = e.getKey().getPrimaryName();
+                String optValue = e.getValue();
+                try {
+                    if (!fileManager.handleOption(optName, List.of(optValue).iterator())) {
+                        log.error("main.unknown.option.for.filemanager", optName);
+                    }
+                } catch (IllegalArgumentException ex) {
+                    log.error("main.bad.arg.for.filemanager.option", optName, ex.getMessage());
+                }
+            }
         }
 
         String mr = com.sun.tools.javac.main.Option.MULTIRELEASE.primaryName;

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/resources/javadoc.properties

@@ -302,6 +302,8 @@ main.warnings.Werror=warnings found and -Werror specified
 main.unknown.error=an unknown error has occurred
 main.internal.error=an internal error has occurred
 main.unexpected.exception=an unexpected exception was caught: {0}
+main.unknown.option.for.filemanager=option not supported by file manager: {0}
+main.bad.arg.for.filemanager.option=bad value for file manager option {0}: "{1}"
 doclet.internal.report.bug=\
 Please file a bug against the javadoc tool via the Java bug reporting page\n\
 (http://bugreport.java.com) after checking the Bug Database (http://bugs.java.com)\n\

test/langtools/jdk/javadoc/lib/javadoc/tester/JavadocTester.java

@@ -58,6 +58,7 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
+import javax.tools.StandardJavaFileManager;
 
 
 /**
@@ -245,6 +246,7 @@ void check(Path dir) {
     private boolean automaticCheckLinks = true;
     private boolean automaticCheckUniqueOUT = true;
     private boolean useStandardStreams = false;
+    private StandardJavaFileManager fileManager = null;
 
     /** The current subtest number. Incremented when checking(...) is called. */
     private int numTestsRun = 0;
@@ -371,9 +373,17 @@ public void javadoc(String... args) {
         StreamOutput sysErr = new StreamOutput(System.err, System::setErr);
 
         try {
-            exitCode = useStandardStreams
-                    ? jdk.javadoc.internal.tool.Main.execute(args)              // use sysOut, sysErr
-                    : jdk.javadoc.internal.tool.Main.execute(args, outOut.pw);  // default
+            jdk.javadoc.internal.tool.Main main = new jdk.javadoc.internal.tool.Main();
+            if (useStandardStreams) {
+                // use sysOut, sysErr
+            } else {
+                // default: use single explicit stream
+                main.setStreams(outOut.pw, outOut.pw);
+            }
+            if (fileManager != null) {
+                main.setFileManager(fileManager);
+            }
+            exitCode = main.run(args).exitCode;
         } finally {
             outputMap.put(Output.STDOUT, sysOut.close());
             outputMap.put(Output.STDERR, sysErr.close());
@@ -442,6 +452,15 @@ public void setUseStandardStreams(boolean b) {
         useStandardStreams = b;
     }
 
+    /**
+     * Sets the file manager to use for subsequent invocations of javadoc.
+     * If {@code null}, a default file manager will be created and used
+     * for each invocation.
+     */
+    public void setFileManager(StandardJavaFileManager fm) {
+        fileManager = fm;
+    }
+
     /**
      * The exit codes returned by the javadoc tool.
      * @see jdk.javadoc.internal.tool.Main.Result