8182029: Make the top-level docs index.html to a HTML-level redirect to the API overview page
Reviewed-by: alanb, erikj, ihse
--- a/jdk/make/ModuleTools.gmk Tue Jun 13 09:13:28 2017 -0700
+++ b/jdk/make/ModuleTools.gmk Tue Jun 13 10:44:18 2017 -0700
@@ -49,7 +49,4 @@
--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
--- a/jdk/make/src/classes/build/tools/docs/GenDocsBundlePage.java Tue Jun 13 09:13:28 2017 -0700
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,247 +0,0 @@
-/*
- * 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.ModuleDescriptor;
-import java.lang.module.ModuleFinder;
-import java.lang.module.ModuleReference;
-import java.nio.charset.StandardCharsets;
-import java.nio.file.Files;
-import java.nio.file.Path;
-import java.nio.file.Paths;
-import java.util.Arrays;
-import java.util.Comparator;
-import java.util.HashMap;
-import java.util.Locale;
-import java.util.Map;
-import java.util.Properties;
-import java.util.Set;
-import java.util.function.Predicate;
-import java.util.stream.Stream;
-import static java.util.stream.Collectors.*;
-
-/**
- * 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, Set<ModuleDescriptor>> moduleGroups = new HashMap<>();
- GenDocsBundlePage(String title, Path outputfile) throws IOException
- {
- this.outputfile = outputfile;
- this.title = title;
-
- // read module groups
- ModuleFinder finder = ModuleFinder.ofSystem();
- try (InputStream in = GenDocsBundlePage.class.getResourceAsStream(MODULE_GROUPS_PROPS)) {
- Properties props = new Properties();
- props.load(in);
- for (String key: props.stringPropertyNames()) {
- Set<ModuleDescriptor> mods =
- Stream.of(props.getProperty(key).split("\\s+"))
- .map(String::trim)
- .flatMap(mn -> finder.find(mn).stream())
- .map(ModuleReference::descriptor)
- .collect(toSet());
-
- String name = "@" + key.toUpperCase(Locale.ENGLISH) + "@";
- moduleGroups.put(name, mods);
- };
- }
- }
-
- 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);
- }
- int i = line.indexOf('@');
- int j = line.indexOf('@', i+1);
- if (i >= 0 && i < j) {
- String name = line.substring(i, j+1);
- if (moduleGroups.containsKey(name)) {
- line = line.replace(name, formatModuleGroup(name));
- }
- }
- return line;
- }
-
- String toHRef(ModuleDescriptor md) {
- String mn = md.name();
- String formattedName;
- if (hasExportedAPIs(md)) {
- // has exported APIs
- formattedName = mn;
- } else if (!md.provides().isEmpty()) {
- // a provider
- formattedName = "<i>" + mn + "</i>";
- } else {
- // a tool
- formattedName = "<i>" + mn + "</i>";
- }
- return String.format("<a href=\"api/%s-summary.html\">%s</a>",
- mn, formattedName);
- }
-
- String formatModuleGroup(String groupName) {
- StringBuilder sb = new StringBuilder();
- // organize in Java SE, JDK, JavaFX, JCP groups
- Set<ModuleDescriptor> modules = moduleGroups.get(groupName);
- Arrays.stream(ModuleGroup.values())
- .forEach(g -> {
- Set<ModuleDescriptor> mods = modules.stream()
- .filter(md -> g.predicate.test(md.name()))
- .collect(toSet());
- if (!mods.isEmpty()) {
- sb.append("<div class=" + g.cssClass + ">\n");
- // modules with exported API
- mods.stream()
- .filter(this::hasExportedAPIs)
- .sorted(Comparator.comparing(ModuleDescriptor::name))
- .map(this::toHRef)
- .forEach(m -> sb.append(m).append("\n"));
-
- // tools and providers
- mods.stream()
- .filter(md -> !hasExportedAPIs(md))
- .sorted(Comparator.comparing(ModuleDescriptor::name))
- .map(this::toHRef)
- .forEach(m -> sb.append(m).append("\n"));
- sb.append("</div>");
- }
- });
- return sb.toString();
- }
-
- private boolean hasExportedAPIs(ModuleDescriptor md) {
- if (md.exports().stream().anyMatch(e -> !e.isQualified())) {
- return true;
- }
- // this should check if any indirect exports
- // checking requires transitive would be sufficient for JDK modules
- if (md.requires().stream()
- .map(ModuleDescriptor.Requires::modifiers)
- .anyMatch(mods -> mods.contains(ModuleDescriptor.Requires.Modifier.TRANSITIVE))) {
- return true;
- }
- return false;
- }
-
- private static final Set<String> NON_JAVA_SE_MODULES =
- Set.of("java.jnlp", "java.smartcardio");
-
- /**
- * CSS class names are defined in docs-bundle-page.html
- */
- enum ModuleGroup {
- JAVA_SE("javase", mn -> mn.startsWith("java.") && !NON_JAVA_SE_MODULES.contains(mn)),
- JDK("jdk", mn -> mn.startsWith("jdk.")),
- JAVAFX("javafx", mn -> mn.startsWith("javafx.")),
- NON_JAVA_SE("jcp", NON_JAVA_SE_MODULES::contains);
-
- final String cssClass;
- final Predicate<String> predicate;
- ModuleGroup(String cssClass, Predicate<String> predicate) {
- this.cssClass = cssClass;
- this.predicate = predicate;
- }
- }
-}
--- a/jdk/make/src/classes/build/tools/docs/docs-bundle-page.html Tue Jun 13 09:13:28 2017 -0700
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,171 +0,0 @@
-<!--
-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>
-<title>@HEADER_TITLE@</title>
-
-<meta http-equiv="content-type" content="text/html;" charset="utf-8">
-<link rel="stylesheet" href="resources/jdk-default.css" type="text/css" />
-<style type="text/css">
-
-table a { text-decoration: none }
-table { border: none }
-th, td { border: 2px solid white; }
-thead th { background-color: #DDD }
-tbody th { background-color: #EEE }
-
-table div.javase, ul.key span.javase { background-color: #C6E7F3 }
-table div.jdk, ul.key span.jdk { background-color: #ECE1C5 }
-table div.javafx, ul.key span.javafx { background-color: #ECEDCC }
-table div.jcp, ul.key span.jcp { background-color: #E9E9E9 }
-td div { padding: 3px 5px; color: blue }
-table tbody td div a { padding: 0 .5em; margin: 0: 1em; }
-table tbody td div a:link { color: black }
-table tbody td div a:visited { color: black }
-table tbody td div a[href]:hover { color: black; text-decoration: underline }
-td { padding: 0 }
-table tbody td div a { padding: 0 .5em; margin: 0: 1em }
-
-.key { font-size: smaller; }
-ul.key li { display:inline-block; padding: 0 1em }
-ul.key span {
- border: 1px solid black;
- font-family: DejaVu Sans Mono, monospace;
-}
-ul.key span:before { content: " " }
-ul.key span:after { content: " " }
-
-caption {
- text-align: center;
-}
-
-tr:nth-child(even), tr:nth-child(even) th[scope=row] {
- background-color: #EEE;
-}
-tr:nth-child(odd), tr:nth-child(odd) th[scope=row] {
- background-color: #EEE;
-}
-
-</style>
-</head>
-
-<h1>@HEADER_TITLE@</h1>
-
-<ul>
-<li><a href="api/index.html">JDK API Specification</a></li>
-<li><a href="https://docs.oracle.com/javase/specs/">
- Java Language and Virtual Machine Specifications</a></li>
-<li><a href="https://www.oracle.com/pls/topic/lookup?ctx=javase9&id=tools_reference_overview">
- Tools Reference</a></li>
-</ul>
-
-
-<table>
-<caption style="display:none">JDK Modules</caption>
-<thead>
-<tr>
- <th scope="col">Group</th>
- <th scope="col">Modules</th>
-</tr>
-</thead>
-<tbody>
-<tr>
- <th scope="row">Foundation</th>
- <td>@JAVA_BASE@</td>
-</tr>
-<tr>
- <th scope="row">Integration</th>
- <td>@INTEGRATION_MODULES@</td>
-</tr>
-<tr>
- <th scope="row">User Interface</th>
- <td>@UI_MODULES@</td>
-</tr>
-<tr>
- <th scope="row">Compilation</th>
- <td>@COMPILER_MODULES@</td>
-</tr>
-<tr>
- <th scope="row">Scripting</th>
- <td>@SCRIPTING_MODULES@</td>
-</tr>
-<tr>
- <th scope="row">Security</th>
- <td>@SECURITY_MODULES@</td>
-</tr>
-<tr>
- <th scope="row">Management</th>
- <td>@MANAGEMENT_MODULES@</td>
-</tr>
-<tr>
- <th scope="row">Instrumentation</th>
- <td>@INSTRUMENT_MODULES@</td>
-</tr>
-<tr>
- <th scope="row">Serviceability</th>
- <td>@SVC_MODULES@</td>
-</tr>
-<tr>
- <th scope="row">Packaging</th>
- <td>@PACKAGING_MODULES@</td>
-</tr>
-<tr>
- <th scope="row">Incubator</th>
- <td>@INCUBATOR_MODULES@</td>
-</tr>
-<tr>
- <th scope="row">Non-Java SE</th>
- <td>@OTHER_MODULES@</td>
-</tr>
-<tr>
- <th scope="row">Java EE</th>
- <td>@JAVA_EE_MODULES@</td>
-</tr>
-<tr>
- <th scope="row">Aggregator</th>
- <td>@AGGREGATOR_MODULES@</td>
-</tr>
-</tbody>
-</table>
-
-<p class="key">Key:
-<ul class="key">
-<li><span class="javase"> </span> Java SE
-<li><span class="jdk"> </span> JDK
-<li><span class="javafx"> </span> JavaFX
-<li><span class="jcp"> </span> Non-Java SE
-<li><i>italic</i> No Exported API (e.g. a tool or provider)</li>
-</ul>
-
-<p>
-<hr>
-<a href="legal/cpyr.html">Copyright</a> © 1993, 2017, Oracle and/or its affiliates. All rights reserved.</p>
-
-</body>
-</html>
-
-
--- a/jdk/make/src/classes/build/tools/docs/docs-module-groups.properties Tue Jun 13 09:13:28 2017 -0700
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,114 +0,0 @@
-# Module Grouping for the docs bundle page
-#
-
-java_base=\
-java.base
-
-java_ee_modules=\
-java.activation \
-java.corba \
-java.transaction \
-java.xml.bind \
-java.xml.ws \
-java.xml.ws.annotation \
-jdk.xml.bind \
-jdk.xml.ws
-
-aggregator_modules=\
-java.se \
-java.se.ee
-
-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 \
-jdk.policytool
-
-instrument_modules=\
-java.instrument
-
-management_modules=\
-java.management \
-java.management.rmi \
-jdk.management \
-jdk.management.agent \
-jdk.management.cmm \
-jdk.management.jfr \
-jdk.management.resource \
-jdk.snmp \
-jdk.jconsole
-
-integration_modules=\
-java.logging \
-java.naming \
-java.prefs \
-java.rmi \
-java.sql \
-java.sql.rowset \
-java.xml \
-jdk.charsets \
-jdk.localedata \
-jdk.net \
-jdk.sctp \
-jdk.jsobject \
-jdk.httpserver \
-jdk.naming.dns \
-jdk.naming.rmi \
-jdk.xml.dom \
-jdk.zipfs
-
-ui_modules=\
-java.datatransfer \
-java.desktop \
-javafx.base \
-javafx.controls \
-javafx.fxml \
-javafx.graphics \
-javafx.media \
-javafx.swing \
-javafx.web \
-jdk.accessibility
-
-svc_modules=\
-jdk.jfr \
-jdk.attach \
-jdk.jcmd \
-jdk.jdi \
-jdk.jdwp.agent \
-jdk.jstatd \
-jdk.hotspot.agent
-
-packaging_modules=\
-jdk.jartool \
-jdk.jlink \
-jdk.pack \
-jdk.packager.services
-
-compiler_modules=\
-java.compiler \
-jdk.compiler \
-jdk.javadoc \
-jdk.jdeps \
-jdk.editpad \
-jdk.jshell \
-jdk.rmic
-
-scripting_modules=\
-java.scripting \
-jdk.dynalink \
-jdk.scripting.nashorn \
-jdk.scripting.nashorn.shell
-
-other_modules=\
-java.jnlp \
-java.smartcardio
-
-incubator_modules=\
-jdk.incubator.httpclient
-