8173303: Add module-subgraph images to main platform documentation

Co-authored-by: Jonathan Gibbons <jonathan.gibbons@oracle.com>
Reviewed-by: alanb, chegar, erikj, ihse, lancea
This commit is contained in:
Mandy Chung 2017-03-29 09:40:41 -07:00
parent 4fa7bde21b
commit 6d568376c9
50 changed files with 388 additions and 45 deletions

View File

@ -1,5 +1,5 @@
#
# Copyright (c) 2014, 2016, Oracle and/or its affiliates. All rights reserved.
# Copyright (c) 2014, 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
@ -31,7 +31,7 @@ include MakeBase.gmk
include ModuleTools.gmk
GENGRAPHS_DIR := $(IMAGES_OUTPUTDIR)/gengraphs
SPEC_DOTFILES_DIR := $(IMAGES_OUTPUTDIR)/spec-dotfiles
SPEC_DOTFILES_DIR := $(GENGRAPHS_DIR)/spec-dotfiles
TOOLS_MODULE_SRCDIR := $(JDK_TOPDIR)/make/src/classes/build/tools/jigsaw
$(GENGRAPHS_DIR)/jdk.dot: $(BUILD_JIGSAW_TOOLS)

View File

@ -1,5 +1,5 @@
#
# Copyright (c) 2013, 2016, Oracle and/or its affiliates. All rights reserved.
# Copyright (c) 2013, 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
@ -23,8 +23,9 @@
# questions.
#
include $(SPEC)
include MakeBase.gmk
ifndef _MODULE_TOOLS_GMK
_MODULE_TOOLS_GMK := 1
include JavaCompilation.gmk
TOOLS_CLASSES_DIR := $(BUILDTOOLS_OUTPUTDIR)/tools_jigsaw_classes
@ -32,7 +33,7 @@ TOOLS_CLASSES_DIR := $(BUILDTOOLS_OUTPUTDIR)/tools_jigsaw_classes
# To avoid reevaluating the compilation setup for the tools each time this file
# is included, the actual compilation is handled by CompileModuleTools.gmk. The
# following trick is used to be able to declare a dependency on the built tools.
BUILD_TOOLS_JDK := $(call SetupJavaCompilationCompileTarget, \
BUILD_JIGSAW_TOOLS := $(call SetupJavaCompilationCompileTarget, \
BUILD_JIGSAW_TOOLS, $(TOOLS_CLASSES_DIR))
TOOL_GENGRAPHS := $(BUILD_JAVA) -esa -ea -cp $(TOOLS_CLASSES_DIR) \
@ -47,3 +48,5 @@ TOOL_ADD_PACKAGES_ATTRIBUTE := $(BUILD_JAVA) $(JAVA_FLAGS_SMALL) \
-cp $(TOOLS_CLASSES_DIR) \
--add-exports java.base/jdk.internal.module=ALL-UNNAMED \
build.tools.jigsaw.AddPackagesAttribute
endif # _MODULE_TOOLS_GMK

View File

@ -26,7 +26,6 @@
package build.tools.jigsaw;
import com.sun.tools.jdeps.ModuleDotGraph;
import com.sun.tools.jdeps.ModuleDotGraph.DotGraphBuilder;
import java.io.IOException;
import java.lang.module.Configuration;
@ -36,10 +35,15 @@ import java.lang.module.ModuleReference;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Properties;
import java.util.Set;
import java.util.function.Function;
import java.util.stream.Collectors;
/**
* Generate the DOT file for a module graph for each module in the JDK
@ -50,13 +54,19 @@ public class GenGraphs {
public static void main(String[] args) throws Exception {
Path dir = null;
boolean spec = false;
Properties props = null;
for (int i=0; i < args.length; i++) {
String arg = args[i];
if (arg.equals("--spec")) {
spec = true;
} else if (arg.equals("--dot-attributes")) {
if (i++ == args.length) {
throw new IllegalArgumentException("Missing argument: --dot-attributes option");
}
props = new Properties();
props.load(Files.newInputStream(Paths.get(args[i])));
} else if (arg.equals("--output")) {
i++;
dir = i < args.length ? Paths.get(args[i]) : null;
dir = ++i < args.length ? Paths.get(args[i]) : null;
} else if (arg.startsWith("-")) {
throw new IllegalArgumentException("Invalid option: " + arg);
}
@ -67,11 +77,14 @@ public class GenGraphs {
System.exit(1);
}
// setup and configure the dot graph attributes
initDotGraphAttributes();
Files.createDirectories(dir);
GenGraphs genGraphs = new GenGraphs(dir, spec);
ModuleGraphAttributes attributes;
if (props != null) {
attributes = new ModuleGraphAttributes(props);
} else {
attributes = new ModuleGraphAttributes();
}
GenGraphs genGraphs = new GenGraphs(dir, spec, attributes);
// print dot file for each module
Map<String, Configuration> configurations = new HashMap<>();
@ -99,49 +112,149 @@ public class GenGraphs {
genGraphs.genDotFiles(configurations);
}
static void initDotGraphAttributes() {
int h = 1000;
DotGraphBuilder.weight("java.se", "java.sql.rowset", h * 10);
DotGraphBuilder.weight("java.sql.rowset", "java.sql", h * 10);
DotGraphBuilder.weight("java.sql", "java.xml", h * 10);
DotGraphBuilder.weight("java.xml", "java.base", h * 10);
/**
* Custom dot file attributes.
*/
static class ModuleGraphAttributes implements ModuleDotGraph.Attributes {
static Map<String, String> DEFAULT_ATTRIBUTES = Map.of(
"ranksep", "0.6",
"fontsize", "12",
"fontcolor", BLACK,
"fontname", "DejaVuSans",
"arrowsize", "1",
"arrowwidth", "2",
"arrowcolor", DARK_GRAY,
// custom
"requiresMandatedColor", LIGHT_GRAY,
"javaSubgraphColor", ORANGE,
"jdkSubgraphColor", BLUE
);
DotGraphBuilder.sameRankNodes(Set.of("java.logging", "java.scripting", "java.xml"));
DotGraphBuilder.sameRankNodes(Set.of("java.sql"));
DotGraphBuilder.sameRankNodes(Set.of("java.compiler", "java.instrument"));
DotGraphBuilder.sameRankNodes(Set.of("java.desktop", "java.management"));
DotGraphBuilder.sameRankNodes(Set.of("java.corba", "java.xml.ws"));
DotGraphBuilder.sameRankNodes(Set.of("java.xml.bind", "java.xml.ws.annotation"));
DotGraphBuilder.setRankSep(0.7);
DotGraphBuilder.setFontSize(12);
DotGraphBuilder.setArrowSize(1);
DotGraphBuilder.setArrowWidth(2);
final Map<String, Integer> weights = new HashMap<>();
final List<Set<String>> ranks = new ArrayList<>();
final Map<String, String> attrs;
ModuleGraphAttributes(Map<String, String> attrs) {
int h = 1000;
weight("java.se", "java.sql.rowset", h * 10);
weight("java.sql.rowset", "java.sql", h * 10);
weight("java.sql", "java.xml", h * 10);
weight("java.xml", "java.base", h * 10);
ranks.add(Set.of("java.logging", "java.scripting", "java.xml"));
ranks.add(Set.of("java.sql"));
ranks.add(Set.of("java.compiler", "java.instrument"));
ranks.add(Set.of("java.desktop", "java.management"));
ranks.add(Set.of("java.corba", "java.xml.ws"));
ranks.add(Set.of("java.xml.bind", "java.xml.ws.annotation"));
this.attrs = attrs;
}
ModuleGraphAttributes() {
this(DEFAULT_ATTRIBUTES);
}
ModuleGraphAttributes(Properties props) {
this(toAttributes(props));
}
@Override
public double rankSep() {
return Double.valueOf(attrs.get("ranksep"));
}
@Override
public int fontSize() {
return Integer.valueOf(attrs.get("fontsize"));
}
@Override
public String fontName() {
return attrs.get("fontname");
}
@Override
public String fontColor() {
return attrs.get("fontcolor");
}
@Override
public int arrowSize() {
return Integer.valueOf(attrs.get("arrowsize"));
}
@Override
public int arrowWidth() {
return Integer.valueOf(attrs.get("arrowwidth"));
}
@Override
public String arrowColor() {
return attrs.get("arrowcolor");
}
@Override
public List<Set<String>> ranks() {
return ranks;
}
@Override
public String requiresMandatedColor() {
return attrs.get("requiresMandatedColor");
}
@Override
public String javaSubgraphColor() {
return attrs.get("javaSubgraphColor");
}
@Override
public String jdkSubgraphColor() {
return attrs.get("jdkSubgraphColor");
}
@Override
public int weightOf(String s, String t) {
int w = weights.getOrDefault(s + ":" + t, 1);
if (w != 1)
return w;
if (s.startsWith("java.") && t.startsWith("java."))
return 10;
return 1;
}
public void weight(String s, String t, int w) {
weights.put(s + ":" + t, w);
}
static Map<String, String> toAttributes(Properties props) {
return DEFAULT_ATTRIBUTES.keySet().stream()
.collect(Collectors.toMap(Function.identity(),
k -> props.getProperty(k, DEFAULT_ATTRIBUTES.get(k))));
}
}
private final Path dir;
private final boolean spec;
GenGraphs(Path dir, boolean spec) {
private final ModuleGraphAttributes attributes;
GenGraphs(Path dir, boolean spec, ModuleGraphAttributes attributes) {
this.dir = dir;
this.spec = spec;
this.attributes = attributes;
}
void genDotFiles(Map<String, Configuration> configurations) throws IOException {
ModuleDotGraph dotGraph = new ModuleDotGraph(configurations, spec);
dotGraph.genDotFiles(dir);
dotGraph.genDotFiles(dir, attributes);
}
/**
* Returns true for any name if generating graph for non-spec;
* otherwise, returns true except "jdk" and name with "jdk.internal." prefix
*/
boolean accept(String name, ModuleDescriptor descriptor) {
if (!spec) return true;
if (name.equals("jdk"))
return false;
if (name.equals("java.se") || name.equals("java.se.ee"))
if (!spec)
return true;
// only the module that has exported API
return descriptor.exports().stream()
.filter(e -> !e.isQualified())
.findAny().isPresent();
return !name.equals("jdk") && !name.startsWith("jdk.internal.");
}
}
}

View File

@ -0,0 +1,2 @@
arrowcolor=#999999
requiresMandatedColor=#999999

View File

@ -0,0 +1,96 @@
/*
* 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.taglet;
import java.util.EnumSet;
import java.util.List;
import java.util.Set;
import javax.lang.model.element.Element;
import com.sun.source.doctree.DocTree;
import jdk.javadoc.doclet.Taglet;
import static jdk.javadoc.doclet.Taglet.Location.*;
/**
* A block tag to optionally insert a reference to a module graph.
*/
public class ModuleGraph implements Taglet {
private static final boolean enableModuleGraph =
Boolean.getBoolean("enableModuleGraph");
/** Returns the set of locations in which a taglet may be used. */
@Override
public Set<Location> getAllowedLocations() {
return EnumSet.of(MODULE);
}
@Override
public boolean isInlineTag() {
return false;
}
@Override
public String getName() {
return "moduleGraph";
}
@Override
public String toString(List<? extends DocTree> tags, Element element) {
if (!enableModuleGraph) {
return "";
}
String moduleName = element.getSimpleName().toString();
String imageFile = moduleName + "-graph.png";
int thumbnailHeight = -1;
String hoverImage = "";
if (!moduleName.equals("java.base")) {
thumbnailHeight = 100; // also appears in the stylesheet
hoverImage = "<span>"
+ getImage(moduleName, imageFile, -1, true)
+ "</span>";
}
return "<dt>"
+ "<span class=\"simpleTagLabel\">Module Graph:</span>\n"
+ "</dt>"
+ "<dd>"
+ "<a class=moduleGraph href=\"" + imageFile + "\">"
+ getImage(moduleName, imageFile, thumbnailHeight, false)
+ hoverImage
+ "</a>"
+ "</dd>";
}
private static final String VERTICAL_ALIGN = "vertical-align:top";
private static final String BORDER = "border: solid lightgray 1px;";
private String getImage(String moduleName, String file, int height, boolean useBorder) {
return String.format("<img style=\"%s\" alt=\"Module graph for %s\" src=\"%s\"%s>",
useBorder ? BORDER + " " + VERTICAL_ALIGN : VERTICAL_ALIGN,
moduleName,
file,
(height <= 0 ? "" : " height=\"" + height + "\""));
}
}

View File

@ -26,6 +26,7 @@
/**
* Defines the foundational APIs of the Java SE Platform.
*
* @moduleGraph
* @since 9
*/
module java.base {

View File

@ -24,8 +24,9 @@
*/
/**
* Defines an API for transferring data between and within applications.
* Defines the API for transferring data between and within applications.
*
* @moduleGraph
* @since 9
*/
module java.datatransfer {

View File

@ -27,6 +27,7 @@
* Defines the AWT and Swing user interface toolkits, plus APIs for
* accessibility, audio, imaging, printing, and JavaBeans.
*
* @moduleGraph
* @since 9
*/
module java.desktop {

View File

@ -27,6 +27,7 @@
* Defines services that allow agents to
* instrument programs running on the JVM.
*
* @moduleGraph
* @since 9
*/
module java.instrument {

View File

@ -26,6 +26,7 @@
/**
* Defines the Java Logging API.
*
* @moduleGraph
* @since 9
*/
module java.logging {

View File

@ -46,6 +46,7 @@
* and load the appropriate {@code JMXConnectorServerProvider} service
* implementation for the given protocol.
*
* @moduleGraph
* @since 9
*/
module java.management.rmi {

View File

@ -29,6 +29,7 @@
* The JMX API consists of interfaces for monitoring and management of the
* JVM and other components in the Java runtime.
*
* @moduleGraph
* @since 9
*/
module java.management {

View File

@ -26,6 +26,7 @@
/**
* Defines the Java Naming and Directory Interface (JNDI) API.
*
* @moduleGraph
* @since 9
*/
module java.naming {

View File

@ -26,6 +26,7 @@
/**
* Defines the Preferences API.
*
* @moduleGraph
* @since 9
*/
module java.prefs {

View File

@ -26,6 +26,7 @@
/**
* Defines the Remote Method Invocation (RMI) API.
*
* @moduleGraph
* @since 9
*/
module java.rmi {

View File

@ -26,6 +26,7 @@
/**
* Defines the Scripting API.
*
* @moduleGraph
* @since 9
*/
module java.scripting {

View File

@ -29,6 +29,7 @@
* This module requires {@code java.se} and supplements it with modules
* that define CORBA and Java EE APIs. These modules are upgradeable.
*
* @moduleGraph
* @since 9
*/
@SuppressWarnings("deprecation")

View File

@ -29,6 +29,7 @@
* The modules defining CORBA and Java EE APIs are not required by
* this module, but they are required by {@code java.se.ee}.
*
* @moduleGraph
* @since 9
*/
module java.se {

View File

@ -28,6 +28,7 @@
* <P>
* This module also contains GSS-API mechanisms including Kerberos v5 and SPNEGO.
*
* @moduleGraph
* @since 9
*/
module java.security.jgss {

View File

@ -30,6 +30,7 @@
* This module also contains SASL mechanisms including DIGEST-MD5,
* CRAM-MD5, and NTLM.
*
* @moduleGraph
* @since 9
*/
module java.security.sasl {

View File

@ -26,6 +26,7 @@
/**
* Defines the Java Smart Card I/O API.
*
* @moduleGraph
* @since 9
*/
module java.smartcardio {

View File

@ -26,6 +26,7 @@
/**
* Defines the JDBC RowSet API.
*
* @moduleGraph
* @since 9
*/
module java.sql.rowset {

View File

@ -26,6 +26,7 @@
/**
* Defines the JDBC API.
*
* @moduleGraph
* @since 9
*/
module java.sql {

View File

@ -29,6 +29,7 @@
* The subset consists of RMI exception types which are mapped to CORBA system
* exceptions by the 'Java Language to IDL Mapping Specification'.
*
* @moduleGraph
* @since 9
*/
@Deprecated(since="9", forRemoval=true)

View File

@ -24,8 +24,9 @@
*/
/**
* Defines an API for XML cryptography.
* Defines the API for XML cryptography.
*
* @moduleGraph
* @since 9
*/
module java.xml.crypto {

View File

@ -26,6 +26,7 @@
/**
* Defines the attach API.
*
* @moduleGraph
* @since 9
*/
module jdk.attach {

View File

@ -23,6 +23,13 @@
* questions.
*/
/**
* {@link java.nio.charset.Charset Charset} provider for the charsets that
* are not in {@code java.base} (mostly double byte and IBM charsets).
*
* @moduleGraph
* @since 9
*/
module jdk.charsets {
provides java.nio.charset.spi.CharsetProvider
with sun.nio.cs.ext.ExtendedCharsets;

View File

@ -26,6 +26,7 @@
/**
* The SunPKCS11 security provider.
*
* @moduleGraph
* @since 9
*/
module jdk.crypto.cryptoki {

View File

@ -26,6 +26,7 @@
/**
* The SunEC security provider.
*
* @moduleGraph
* @since 9
*/
module jdk.crypto.ec {

View File

@ -26,6 +26,7 @@
/**
* The SunMSCAPI security provider.
*
* @moduleGraph
* @since 9
*/
module jdk.crypto.mscapi {

View File

@ -26,6 +26,7 @@
/**
* The OracleUCrypto security provider.
*
* @moduleGraph
* @since 9
*/
module jdk.crypto.ucrypto {

View File

@ -23,6 +23,12 @@
* questions.
*/
/**
* Defines the JDK-specific API for HTTP server.
*
* @moduleGraph
* @since 9
*/
module jdk.httpserver {
exports com.sun.net.httpserver;

View File

@ -23,6 +23,13 @@
* questions.
*/
/**
* Defines tools for manipulating Java Archive (JAR) files,
* including the jar and jarsigner tools.
*
* @moduleGraph
* @since 9
*/
module jdk.jartool {
exports com.sun.jarsigner;
exports jdk.security.jarsigner;

View File

@ -23,6 +23,13 @@
* questions.
*/
/**
* Defines tools for diagnostics and troubleshooting a JVM,
* including the jcmd, jps, jstat and other diagnostics tools.
*
* @moduleGraph
* @since 9
*/
module jdk.jcmd {
requires jdk.attach;
requires jdk.internal.jvmstat;

View File

@ -23,6 +23,13 @@
* questions.
*/
/**
* Defines the JMX graphical tool, jconsole, for monitoring and managing
* a running application.
*
* @moduleGraph
* @since 9
*/
module jdk.jconsole {
requires transitive java.desktop;
requires transitive java.management;

View File

@ -26,6 +26,7 @@
/**
* Defines the Java Debugger Interface.
*
* @moduleGraph
* @since 9
*/
module jdk.jdi {

View File

@ -26,6 +26,7 @@
/**
* Java Debug Wire Protocol.
*
* @moduleGraph
* @since 9
*/
module jdk.jdwp.agent {

View File

@ -23,6 +23,12 @@
* questions.
*/
/**
* Defines the Java linker tool, jlink.
*
* @moduleGraph
* @since 9
*/
module jdk.jlink {
requires jdk.internal.opt;
requires jdk.jdeps;

View File

@ -23,6 +23,12 @@
* questions.
*/
/**
* Defines the API for the JavaScript Object.
*
* @moduleGraph
* @since 9
*/
module jdk.jsobject {
requires java.desktop;
exports netscape.javascript;

View File

@ -23,6 +23,13 @@
* questions.
*/
/**
* Defines the tool for starting a daemon for the jstat tool to monitor
* JVM statistics remotely.
*
* @moduleGraph
* @since 9
*/
module jdk.jstatd {
requires java.rmi;
requires jdk.internal.jvmstat;
@ -32,4 +39,3 @@ module jdk.jstatd {
provides sun.jvmstat.monitor.MonitoredHostService with sun.jvmstat.perfdata.monitor.protocol.rmi.MonitoredHostRmiService;
}

View File

@ -23,6 +23,12 @@
* questions.
*/
/**
* Locale data provider for locales other than {@linkplain java.util.Locale#US US locale}.
*
* @moduleGraph
* @since 9
*/
module jdk.localedata {
provides sun.util.locale.provider.LocaleDataMetaInfo with
sun.util.resources.cldr.provider.CLDRLocaleDataMetaInfo,

View File

@ -23,6 +23,12 @@
* questions.
*/
/**
* Define the JMX management agent.
*
* @moduleGraph
* @since 9
*/
module jdk.management.agent {
requires java.management;
requires java.management.rmi;

View File

@ -23,6 +23,12 @@
* questions.
*/
/**
* Defines the JDK-specific Management Interfaces for JVM.
*
* @moduleGraph
* @since 9
*/
module jdk.management {
requires transitive java.management;

View File

@ -23,6 +23,12 @@
* questions.
*/
/**
* DNS Java Naming provider.
*
* @moduleGraph
* @since 9
*/
module jdk.naming.dns {
requires java.naming;

View File

@ -23,6 +23,12 @@
* questions.
*/
/**
* RMI Java Naming provider.
*
* @moduleGraph
* @since 9
*/
module jdk.naming.rmi {
requires java.naming;
requires java.rmi;

View File

@ -23,6 +23,12 @@
* questions.
*/
/**
* Defines the JDK-specific Networking API.
*
* @moduleGraph
* @since 9
*/
module jdk.net {
exports jdk.net;
}

View File

@ -23,6 +23,12 @@
* questions.
*/
/**
* Defines the JDK-specific API for SCTP.
*
* @moduleGraph
* @since 9
*/
module jdk.sctp {
exports com.sun.nio.sctp;
}

View File

@ -27,6 +27,7 @@
* Contains the implementation of the javax.security.auth.* interfaces and
* various authentication modules.
*
* @moduleGraph
* @since 9
*/
module jdk.security.auth {

View File

@ -27,6 +27,7 @@
* Defines Java extensions to the GSS-API and an implementation of the SASL
* GSSAPI mechanism.
*
* @moduleGraph
* @since 9
*/
module jdk.security.jgss {

View File

@ -23,6 +23,12 @@
* questions.
*/
/**
* Zip file system provider.
*
* @moduleGraph
* @since 9
*/
module jdk.zipfs {
provides java.nio.file.spi.FileSystemProvider with jdk.nio.zipfs.ZipFileSystemProvider;
}