changeset 17146:9fc68c99204d

8180208: Provide a new docs bundle page Reviewed-by: ihse, jjg
author mchung
date Fri, 12 May 2017 13:29:38 -0700
parents a046521803b2
children c5b0465f06d0
files make/CompileModuleTools.gmk make/CompileTools.gmk make/ModuleTools.gmk make/src/classes/build/tools/docs/GenDocsBundlePage.java make/src/classes/build/tools/docs/docs-bundle-page.html make/src/classes/build/tools/docs/docs-module-groups.properties
diffstat 6 files changed, 449 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/make/CompileModuleTools.gmk	Fri May 12 15:15:43 2017 -0400
+++ b/make/CompileModuleTools.gmk	Fri May 12 13:29:38 2017 -0700
@@ -23,21 +23,33 @@
 # questions.
 #
 
+default: all
+
 include $(SPEC)
 include MakeBase.gmk
 include JavaCompilation.gmk
 include SetupJavaCompilers.gmk
 
+################################################################################
+
 TOOLS_CLASSES_DIR := $(BUILDTOOLS_OUTPUTDIR)/tools_jigsaw_classes
 
 $(eval $(call SetupJavaCompilation,BUILD_JIGSAW_TOOLS, \
     SETUP := GENERATE_USINGJDKBYTECODE, \
     SRC := $(JDK_TOPDIR)/make/src/classes, \
     INCLUDES := build/tools/deps \
+                build/tools/docs \
                 build/tools/jigsaw, \
+    COPY := .properties .html, \
     BIN := $(TOOLS_CLASSES_DIR), \
     ADD_JAVAC_FLAGS := \
         --add-modules jdk.jdeps \
         --add-exports java.base/jdk.internal.module=ALL-UNNAMED \
         --add-exports jdk.jdeps/com.sun.tools.jdeps=ALL-UNNAMED \
 ))
+
+TARGETS += $(BUILD_JIGSAW_TOOLS)
+
+################################################################################
+
+all: $(TARGETS)
--- a/make/CompileTools.gmk	Fri May 12 15:15:43 2017 -0400
+++ b/make/CompileTools.gmk	Fri May 12 13:29:38 2017 -0700
@@ -46,6 +46,7 @@
     SETUP := GENERATE_OLDBYTECODE, \
     SRC := $(BUILD_TOOLS_SRC_DIRS), \
     EXCLUDES := build/tools/deps \
+                build/tools/docs \
                 build/tools/jigsaw, \
     BIN := $(BUILDTOOLS_OUTPUTDIR)/jdk_tools_classes))
 
--- a/make/ModuleTools.gmk	Fri May 12 15:15:43 2017 -0400
+++ b/make/ModuleTools.gmk	Fri May 12 13:29:38 2017 -0700
@@ -49,4 +49,7 @@
     --add-exports java.base/jdk.internal.module=ALL-UNNAMED \
     build.tools.jigsaw.AddPackagesAttribute
 
+TOOL_GEN_DOCS_BUNDLE_PAGE := $(BUILD_JAVA) -esa -ea -cp $(TOOLS_CLASSES_DIR) \
+    build.tools.docs.GenDocsBundlePage
+
 endif # _MODULE_TOOLS_GMK
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/make/src/classes/build/tools/docs/GenDocsBundlePage.java	Fri May 12 13:29:38 2017 -0700
@@ -0,0 +1,186 @@
+/*
+ * Copyright (c) 2017, 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.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * 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.
+ */
+
+package build.tools.docs;
+
+import java.io.BufferedReader;
+import java.io.BufferedWriter;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.io.PrintWriter;
+import java.lang.module.ModuleFinder;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.HashMap;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Properties;
+import java.util.Set;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+/**
+ * Build tool to generate the docs bundle index page.
+ */
+public class GenDocsBundlePage {
+    private static String DOCS_BUNDLE_PAGE = "docs-bundle-page.html";
+    private static String MODULE_GROUPS_PROPS = "docs-module-groups.properties";
+
+    private static String USAGE =
+        "GenDocsBundlePage --output <file path> --title <title>" +
+        "                  [--template <template>]";
+
+    public static void main(String... args) throws IOException {
+        String title = null;
+        Path outputfile = null;
+        Path template = null;
+        for (int i=0; i < args.length; i++) {
+            String option = args[i];
+            if (option.equals("--output")) {
+                outputfile = Paths.get(getArgument(args, option, ++i));
+            } else if (option.equals("--title")) {
+                title = getArgument(args, option, ++i);
+            } else if (option.equals("--template")) {
+                template = Paths.get(getArgument(args, option, ++i));
+            } else if (option.startsWith("-")) {
+                throw new IllegalArgumentException("Invalid option: " + option);
+            }
+        }
+
+        if (outputfile == null) {
+            System.err.println("ERROR: must specify --output option");
+            System.exit(1);
+        }
+        if (title == null) {
+            System.err.println("ERROR: must specify --title option");
+            System.exit(1);
+        }
+
+        try (InputStream is = readTemplate(template);
+             BufferedReader reader = new BufferedReader(new InputStreamReader(is)))
+        {
+            new GenDocsBundlePage(title, outputfile).run(reader);
+        }
+    }
+
+    private static String getArgument(String[] args, String option, int index) {
+        if (index < args.length) {
+            return args[index];
+        }
+        throw new IllegalArgumentException("Argument must be specified for " + option);
+    }
+
+    private static InputStream readTemplate(Path template) throws IOException {
+        if (template != null) {
+            return Files.newInputStream(template);
+        } else {
+            return GenDocsBundlePage.class.getResourceAsStream(DOCS_BUNDLE_PAGE);
+        }
+    }
+
+    private static final String HEADER_TITLE = "@HEADER_TITLE@";
+    final Path outputfile;
+    final String title;
+    final Map<String, String> moduleGroups;
+
+    GenDocsBundlePage(String title, Path outputfile) throws IOException
+    {
+        this.outputfile = outputfile;
+        this.title = title;
+        this.moduleGroups = moduleGroups();
+    }
+
+    static Map<String, String> moduleGroups() throws IOException {
+        ModuleFinder finder = ModuleFinder.ofSystem();
+        Map<String, String> groups = new HashMap<>();
+        try (InputStream in = GenDocsBundlePage.class.getResourceAsStream(MODULE_GROUPS_PROPS)) {
+            Properties props = new Properties();
+            props.load(in);
+            for (String key: props.stringPropertyNames()) {
+                Set<String> mods = Stream.of(props.getProperty(key).split("\\s+"))
+                                         .filter(mn -> finder.find(mn).isPresent())
+                                         .map(String::trim)
+                                         .collect(Collectors.toSet());
+
+                // divide into 3 columns: Java SE, JDK, JavaFX
+                StringBuilder sb = new StringBuilder();
+                sb.append(mods.stream()
+                              .filter(mn -> mn.startsWith("java."))
+                              .sorted()
+                              .map(GenDocsBundlePage::toHRef)
+                              .collect(Collectors.joining("\n")));
+                sb.append("</td>\n<td>")
+                  .append(mods.stream()
+                              .filter(mn -> mn.startsWith("jdk."))
+                              .sorted()
+                              .map(GenDocsBundlePage::toHRef)
+                              .collect(Collectors.joining("\n")));
+                sb.append("</td>\n<td>");
+                if (mods.stream().anyMatch(mn -> mn.startsWith("javafx."))) {
+                    sb.append(mods.stream()
+                                  .filter(mn -> mn.startsWith("javafx."))
+                                  .sorted()
+                                  .map(GenDocsBundlePage::toHRef)
+                                  .collect(Collectors.joining("\n")));
+                }
+                String name = "@" + key.toUpperCase(Locale.ENGLISH) + "@";
+                groups.put(name, sb.toString());
+            }
+        }
+        return groups;
+    }
+
+    static String toHRef(String mn) {
+        return String.format("<a href=\"api/%s-summary.html\">%s</a><br>", mn, mn);
+    }
+
+    void run(BufferedReader reader) throws IOException {
+        if (Files.notExists(outputfile.getParent())) {
+            Files.createDirectories(outputfile.getParent());
+        }
+        try (BufferedWriter bw = Files.newBufferedWriter(outputfile, StandardCharsets.UTF_8);
+             PrintWriter writer = new PrintWriter(bw)) {
+            reader.lines().map(this::genOutputLine)
+                  .forEach(writer::println);
+        }
+    }
+
+    String genOutputLine(String line) {
+        if (line.contains(HEADER_TITLE)) {
+            line = line.replace(HEADER_TITLE, title);
+        }
+        if (line.contains("@")) {
+            for (Map.Entry<String,String> e: moduleGroups.entrySet()) {
+                if (line.contains(e.getKey())) {
+                    line = line.replace(e.getKey(), e.getValue());
+                }
+            }
+        }
+        return line;
+    }
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/make/src/classes/build/tools/docs/docs-bundle-page.html	Fri May 12 13:29:38 2017 -0700
@@ -0,0 +1,146 @@
+<!--
+Copyright (c) 2017, 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.  Oracle designates this
+particular file as subject to the "Classpath" exception as provided
+by Oracle in the LICENSE file that accompanied this code.
+
+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.
+-->
+
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta http-equiv="content-type" content="text/html;" charset="utf-8">
+  <style type="text/css">
+table {
+  border-collapse: collapse;
+}
+table {
+  border: 1px solid black;
+}
+th ,td {
+  border: 0px solid black;
+}
+thead th {
+  background-color: #DDD;
+}
+tbody > tr:nth-child(even) {
+    background-color: #EEE
+}
+tbody > tr:nth-child(odd) {
+    background-color: #FFF
+}
+th, td {
+  font-family: sans-serif; /* could eventually be DejaVu */
+  font-size: small;
+  padding: 5px 10px;
+  vertical-align:top;
+}
+td a {
+  text-decoration: none;
+}
+tr th {
+  text-align:left;
+}
+caption {
+  font-size: smaller;
+  font-weight: bold;
+}
+</style>
+<title>@HEADER_TITLE@</title>
+</head>
+<body>
+
+<h1>@HEADER_TITLE@</h1>
+
+<ul>
+<li><a href="api/index.html">JDK API Specification</a></li>
+<li>Java Language Specification</li>
+<li>Java Virtual Machine Specification</li>
+</ul>
+
+<table>
+<caption>Modules</caption>
+<thead>
+<tr>
+  <th scope="col">Group</th>
+  <th scope="col">Java SE</th>
+  <th scope="col">JDK</th>
+  <th scope="col">JavaFX</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+  <th scope="row">Foundation</th>
+  <td>@CORE_MODULES@</td>
+</tr>
+<tr>
+<th scope="row">Security</th>
+  <td>@SECURITY_MODULES@</td>
+</tr>
+<tr>
+<th scope="row">Instrumentation and<br>Management</th>
+  <td>@INSTRUMENT_MGMT_MODULES@</td>
+</tr>
+<tr>
+<th scope="row">Integration</th>
+  <td>@INTEGRATION_MODULES@</td>
+</tr>
+<tr>
+  <th scope="row">User Interface</th>
+  <td>@UI_TOOLKITS_MODULES@</td>
+</tr>
+<tr>
+  <th scope="row">Compiler and Scripting</th>
+  <td>@COMPILER_SCRIPTING_MODULES@</td>
+</tr>
+<tr>
+  <th scope="row">Debugging</th>
+  <td>@DEBUG_MODULES@</td>
+</tr>
+<tr>
+  <th scope="row">Tools and Tool APIs</th>
+  <td>@TOOL_MODULES@</td>
+</tr>
+<tr>
+  <th scope="row">Incubating Features</th>
+  <td>@INCUBATOR_MODULES@</td>
+</tr>
+<tr>
+  <th scope="row">Java EE</th>
+  <td>@JAVA_EE_MODULES@</td>
+</tr>
+<tr>
+  <th scope="row"></th>
+  <th scope="row">Outside Java SE</th>
+  <th scope="row">JDK</th>
+  <th scope="row">JavaFX</th>
+</tr>
+<tr>
+  <th scope="row">Others</th>
+  <td>@OTHER_MODULES@</td>
+</tr>
+</tbody>
+</table>
+
+<p>
+<hr/>
+<a href="legal/cpyr.html">Copyright</a>&copy; 1993, 2017, Oracle and/or its affiliates. All rights reserved.</p>
+</body>
+</html>
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/make/src/classes/build/tools/docs/docs-module-groups.properties	Fri May 12 13:29:38 2017 -0700
@@ -0,0 +1,101 @@
+# Module Grouping for the docs bundle page
+#
+
+core_modules=\
+java.base \
+jdk.charsets \
+jdk.localedata \
+jdk.net \
+jdk.sctp \
+jdk.zipfs
+
+java_ee_modules=\
+java.activation \
+java.corba \
+java.transaction \
+java.xml.bind \
+java.xml.ws \
+java.xml.ws.annotation
+
+security_modules=\
+java.security.jgss \
+java.security.sasl \
+java.xml.crypto \
+jdk.security.auth \
+jdk.security.jgss \
+jdk.crypto.cryptoki \
+jdk.crypto.ec \
+jdk.crypto.mscapi \
+jdk.crypto.ucrypto
+
+instrument_mgmt_modules=\
+java.instrument \
+java.management \
+java.management.rmi \
+jdk.jfr \
+jdk.management \
+jdk.management.agent \
+jdk.management.cmm \
+jdk.management.jfr \
+jdk.management.resource \
+
+integration_modules=\
+java.logging \
+java.naming \
+java.prefs \
+java.rmi \
+java.sql \
+java.sql.rowset \
+java.xml \
+jdk.httpserver \
+jdk.naming.dns \
+jdk.naming.rmi
+
+ui_toolkits_modules=\
+java.datatransfer \
+java.desktop \
+javafx.base \
+javafx.controls \
+javafx.fxml \
+javafx.graphics \
+javafx.media \
+javafx.swing \
+javafx.web \
+jdk.accessibility
+
+other_modules=\
+java.jnlp \
+java.smartcardio \
+jdk.jsobject \
+jdk.xml.dom
+
+debug_modules=\
+jdk.jdi \
+jdk.jdwp.agent
+
+tool_modules=\
+jdk.attach \
+jdk.editpad \
+jdk.jartool \
+jdk.javadoc \
+jdk.jcmd \
+jdk.jconsole \
+jdk.jdeps \
+jdk.jlink \
+jdk.jshell \
+jdk.jstatd \
+jdk.pack \
+jdk.policytool \
+jdk.packager.services \
+jdk.rmic
+
+compiler_scripting_modules=\
+java.compiler \
+java.scripting \
+jdk.compiler \
+jdk.dynalink \
+jdk.scripting.nashorn \
+jdk.scripting.nashorn.shell
+
+incubator_modules=\
+jdk.incubator.httpclient