JDK-8272984: javadoc support for SOURCE_DATE_EPOCH

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java

@@ -214,6 +214,12 @@ public HtmlConfiguration(Doclet doclet, Locale locale, Reporter reporter) {
         docletVersion = v;
 
         conditionalPages = EnumSet.noneOf(ConditionalPage.class);
+
+        // See https://reproducible-builds.org/docs/source-date-epoch/
+        String sourceDateEpoch = System.getenv(("SOURCE_DATE_EPOCH"));
+        buildDate = (sourceDateEpoch != null && sourceDateEpoch.matches("[0-9]+"))
+                ? new Date(Long.parseLong(sourceDateEpoch) * 1000)
+                : new Date();
     }
     protected void initConfiguration(DocletEnvironment docEnv,
                                      Function<String, String> resourceKeyMapper) {
@@ -223,7 +229,7 @@ protected void initConfiguration(DocletEnvironment docEnv,
     }
 
     private final Runtime.Version docletVersion;
-    public final Date startTime = new Date();
+    public final Date buildDate;
 
     @Override
     public Runtime.Version getDocletVersion() {

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java

@@ -452,7 +452,7 @@ public void printHtmlDocument(List<String> metakeywords,
             throws DocFileIOException {
         List<DocPath> additionalStylesheets = configuration.getAdditionalStylesheets();
         additionalStylesheets.addAll(localStylesheets);
-        Head head = new Head(path, configuration.getDocletVersion(), configuration.startTime)
+        Head head = new Head(path, configuration.getDocletVersion(), configuration.buildDate)
                 .setTimestamp(!options.noTimestamp())
                 .setDescription(description)
                 .setGenerator(getGenerator(getClass()))

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/IndexRedirectWriter.java

@@ -74,7 +74,7 @@ private IndexRedirectWriter(HtmlConfiguration configuration, DocPath filename, D
      * @throws DocFileIOException if there is a problem generating the file
      */
     private void generateIndexFile() throws DocFileIOException {
-        Head head = new Head(path, configuration.getDocletVersion(), configuration.startTime)
+        Head head = new Head(path, configuration.getDocletVersion(), configuration.buildDate)
                 .setTimestamp(!options.noTimestamp())
                 .setDescription("index redirect")
                 .setGenerator(getGenerator(getClass()))

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SourceToHTMLConverter.java

@@ -232,7 +232,7 @@ public void convertClass(TypeElement te, DocPath outputdir)
      * @param path the path for the file.
      */
     private void writeToFile(Content body, DocPath path, TypeElement te) throws DocFileIOException {
-        Head head = new Head(path, configuration.getDocletVersion(), configuration.startTime)
+        Head head = new Head(path, configuration.getDocletVersion(), configuration.buildDate)
 //                .setTimestamp(!options.notimestamp) // temporary: compatibility!
                 .setTitle(resources.getText("doclet.Window_Source_title"))
 //                .setCharset(options.charset) // temporary: compatibility!

test/langtools/jdk/javadoc/doclet/testSourceDateEpoch/TestSourceDateEpoch.java

@@ -0,0 +1,122 @@
+/*
+ * Copyright (c) 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * 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.
+ */
+
+/*
+ * @test
+ * @bug      8272984
+ * @summary  javadoc support for SOURCE_DATE_EPOCH
+ * @library  /tools/lib ../../lib
+ * @modules  jdk.javadoc/jdk.javadoc.internal.tool
+ * @build    toolbox.ToolBox javadoc.tester.*
+ * @run main TestSourceDateEpoch
+ */
+
+import java.io.BufferedReader;
+import java.nio.file.Path;
+import java.text.SimpleDateFormat;
+import java.util.Calendar;
+import java.util.Date;
+import java.util.List;
+
+import javadoc.tester.JavadocTester;
+import toolbox.ToolBox;
+
+public class TestSourceDateEpoch extends JavadocTester {
+
+    /**
+     * The entry point of the test.
+     *
+     * @param args the array of command line arguments
+     * @throws Exception if the test fails
+     */
+    public static void main(String... args) throws Exception {
+        TestSourceDateEpoch tester = new TestSourceDateEpoch();
+        tester.runTests(m -> new Object[] { Path.of(m.getName()) });
+    }
+
+    ToolBox tb = new ToolBox();
+
+    @Test
+    public void testSourceDateEpoch(Path base) throws Exception {
+        Calendar c = Calendar.getInstance(); // uses current date, time, timezone etc
+        // adjust the calendar to some date before the default used by javadoc (i.e. today)
+        c.add(Calendar.DAY_OF_MONTH, -100);
+        // set a specific time, such as 10 to 3. (Rupert Brooke, Grantchester)
+        c.set(Calendar.HOUR, 2);
+        c.set(Calendar.MINUTE, 50);
+        c.set(Calendar.SECOND, 0);
+        c.set(Calendar.AM_PM, Calendar.PM);
+        Date testDate = c.getTime();
+        out.println("Test Date: '" + testDate + "'");
+
+        Path srcDir = base.resolve("src");
+        tb.writeJavaFiles(srcDir, """
+                package p;
+                /** Comment. */
+                public interface I { }
+                """);
+        Path outDir = base.resolve("out");
+
+        // execute javadoc in a separate VM so that we can set the SOURCE_DATE_EPOCH environment variable.
+        Path javaHome = Path.of(System.getProperty("java.home"));
+        Path javadocBin = javaHome.resolve("bin").resolve("javadoc" + (ToolBox.isWindows() ? ".exe" : ""));
+
+        List<String> cmdArgs = List.of(javadocBin.toString(),
+                "-d", outDir.toString(),
+                "-sourcepath", srcDir.toString(),
+                "p");
+
+        ProcessBuilder pb = new ProcessBuilder(cmdArgs)
+                .redirectErrorStream(true);
+        pb.environment().put("SOURCE_DATE_EPOCH", Long.toString(c.getTimeInMillis() / 1000));
+        Process p = pb.start();
+        try (BufferedReader in = p.inputReader()) {
+            in.lines().forEach(out::println);
+        }
+        int rc = p.waitFor();
+        if (rc != 0) {
+            throw new Exception("javadoc failed: rc=" + rc);
+        }
+
+        // set the outputDir used by JavadocTester
+        outputDir = outDir;
+
+        int featureVersion = Runtime.version().feature();
+        String generatedByStamp = testDate.toString(); // matches what javadoc will use internally
+        String generatedBy = String.format("<!-- Generated by javadoc (%d) on %s -->",
+                featureVersion, generatedByStamp);
+
+        SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
+        String dcCreatedStamp = dateFormat.format(testDate);
+        String dcCreated = String.format("""
+                        <meta name="dc.created" content="%s">""",
+                dcCreatedStamp);
+
+        // check the timestamps in all generated HTML files
+        for (Path file : tb.findFiles(".html", outputDir)) {
+            checkOutput(outputDir.relativize(file).toString(), true,
+                    generatedBy,
+                    dcCreated);
+        }
+    }
+}