changeset 17770:f834f39cb870

Merge
author prr
date Thu, 29 Jun 2017 13:07:19 -0700
parents a00c069b6a3b fabd68add4d0
children 08ec9924fcbf
files 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 src/java.desktop/share/classes/javax/swing/JOptionPane.java src/java.desktop/share/classes/module-info.java src/java.instrument/share/classes/java/lang/instrument/package.html test/java/util/ServiceLoader/modules/BadProvidersTest.java test/java/util/ServiceLoader/modules/Basic.java test/java/util/ServiceLoader/modules/badfactories/badreturntype/ProviderFactory.java test/java/util/ServiceLoader/modules/badfactories/classnotpublic/ProviderFactory.java test/java/util/ServiceLoader/modules/badfactories/classnotpublic/Service.java test/java/util/ServiceLoader/modules/badfactories/methodnotpublic/ProviderFactory.java test/java/util/ServiceLoader/modules/badfactories/methodnotpublic/Service.java test/java/util/ServiceLoader/modules/badfactories/returnsnull/ProviderFactory.java test/java/util/ServiceLoader/modules/badfactories/returnsnull/Service.java test/java/util/ServiceLoader/modules/badfactories/throwsexception/ProviderFactory.java test/java/util/ServiceLoader/modules/badfactories/throwsexception/Service.java test/java/util/ServiceLoader/modules/badproviders/ctornotpublic/Provider.java test/java/util/ServiceLoader/modules/badproviders/ctornotpublic/Service.java test/java/util/ServiceLoader/modules/badproviders/notasubtype/Provider.java test/java/util/ServiceLoader/modules/badproviders/notpublic/Provider.java test/java/util/ServiceLoader/modules/badproviders/notpublic/Service.java test/java/util/ServiceLoader/modules/badproviders/throwsexception/Provider.java test/java/util/ServiceLoader/modules/badproviders/throwsexception/Service.java test/java/util/ServiceLoader/modules/modules/bananascript/module-info.java test/java/util/ServiceLoader/modules/modules/bananascript/org/banana/BananaScript.java test/java/util/ServiceLoader/modules/modules/bananascript/org/banana/BananaScriptEngineFactory.java test/java/util/ServiceLoader/modules/modules/test1/module-info.java test/java/util/ServiceLoader/modules/modules/test1/p/ProviderFactory.java test/java/util/ServiceLoader/modules/modules/test1/p/Service.java test/java/util/ServiceLoader/modules/modules/test2/module-info.java test/java/util/ServiceLoader/modules/modules/test2/p/Provider.java test/java/util/ServiceLoader/modules/modules/test2/p/Service.java test/java/util/ServiceLoader/modules/src/pearscript/META-INF/services/javax.script.ScriptEngineFactory test/java/util/ServiceLoader/modules/src/pearscript/org/pear/PearScript.java test/java/util/ServiceLoader/modules/src/pearscript/org/pear/PearScriptEngineFactory.java test/lib/testlibrary/jdk/testlibrary/Platform.java test/tools/launcher/modules/permit/AttemptAccess.java test/tools/launcher/modules/permit/PermitIllegalAccess.java
diffstat 461 files changed, 15299 insertions(+), 9870 deletions(-) [+]
line wrap: on
line diff
--- a/.hgtags	Fri Jun 23 09:48:10 2017 -0700
+++ b/.hgtags	Thu Jun 29 13:07:19 2017 -0700
@@ -430,3 +430,5 @@
 a5506b425f1bf91530d8417b57360e5d89328c0c jdk-9+173
 42f18c931bd4fae5c206ccf6d8e591e4c4e69d31 jdk-9+174
 5f504872a75b71f2fb19299f0d1e3395cf32eaa0 jdk-10+12
+e6c4f6ef717d104dba880e2dae538690c993b46f jdk-9+175
+4540d6376f3ef22305cca546f85f9b2ce9a210c4 jdk-10+13
--- a/.jcheck/conf	Fri Jun 23 09:48:10 2017 -0700
+++ b/.jcheck/conf	Thu Jun 29 13:07:19 2017 -0700
@@ -1,1 +1,2 @@
 project=jdk10
+bugids=dup
--- a/make/ModuleTools.gmk	Fri Jun 23 09:48:10 2017 -0700
+++ b/make/ModuleTools.gmk	Thu Jun 29 13:07:19 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/make/mapfiles/libjava/mapfile-vers	Fri Jun 23 09:48:10 2017 -0700
+++ b/make/mapfiles/libjava/mapfile-vers	Thu Jun 29 13:07:19 2017 -0700
@@ -278,7 +278,6 @@
                 Java_java_lang_Module_addExports0;
                 Java_java_lang_Module_addExportsToAll0;
                 Java_java_lang_Module_addExportsToAllUnnamed0;
-                Java_java_lang_Module_addPackage0;
 
 		Java_jdk_internal_loader_BootLoader_getSystemPackageLocation;
 		Java_jdk_internal_loader_BootLoader_getSystemPackageNames;
--- a/make/src/classes/build/tools/docs/GenDocsBundlePage.java	Fri Jun 23 09:48:10 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/make/src/classes/build/tools/docs/docs-bundle-page.html	Fri Jun 23 09:48:10 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">&nbsp;</span>&nbsp; Java SE
-<li><span class="jdk">&nbsp;</span>&nbsp; JDK
-<li><span class="javafx">&nbsp;</span>&nbsp; JavaFX
-<li><span class="jcp">&nbsp;</span>&nbsp; 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> &copy 1993, 2017, Oracle and/or its affiliates. All rights reserved.</p>
-
-</body>
-</html>
-	
-	
--- a/make/src/classes/build/tools/docs/docs-module-groups.properties	Fri Jun 23 09:48:10 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
-
--- a/make/src/classes/build/tools/jigsaw/technology-summary.html	Fri Jun 23 09:48:10 2017 -0700
+++ b/make/src/classes/build/tools/jigsaw/technology-summary.html	Thu Jun 29 13:07:19 2017 -0700
@@ -1,625 +1,534 @@
 <html>
 <head>
-<title>JDK Technology Summary</title>
+<title>JCP Technologies in JDK 9</title>
 <style type="text/css">
 table { border: 1px solid black; border-collapse: collapse; }
-tr.se-base { background-color: bisque; }
-tr.se-misc { background-color: lavender; }
-tr.se-ee   { background-color: lightgreen; }
+tr.se-base { background-color: yellow; }
+tr.se-misc { background-color: bisque; }
+tr.se-ee   { background-color: sandybrown; }
 tr.se-ext  { background-color: pink; }
-td { font-family: monospace; padding: 4px; border: 1px solid; }
+tr.non-se  { background-color: lightsteelblue; }
+td { font-family: monospace; padding: 5px; border: 1px solid; }
+td.agg     { background-color: lightgray; }
 </style>
 </head>
 
-<h1>JCP Technologies in the Modular JDK</h1>
+<h1>JCP Technologies in JDK 9</h1>
 
-<p><em>Last updated 2015-03-06 (Added java.datatransfer. Assumes JNLP is modularized, and StAX joins the Java SE Platform.)</em></p>
+<p><em>Last updated 2017-06-08</em></p>
 
-<p><a href="module-summary.html">JDK Module Summary</a> | Technologies in the <a href="https://docs.oracle.com/javase/8/docs/">Java SE Documentation</a></p>
+<p><a href="module-summary.html">JDK 9 Module Summary</a> | Technologies in the <a href="https://docs.oracle.com/javase/8/docs/">Java SE 8 Documentation</a></p>
 
 <table>
 <tr><th>Legend</th></tr>
 <tr class="se-base"><td><a href="https://jcp.org/en/jsr/platform?listBy=2&listByType=platform">JCP technology in the Java SE Platform only -- in java.base</a></td></tr>
 <tr class="se-misc"><td><a href="https://jcp.org/en/jsr/platform?listBy=2&listByType=platform">JCP technology in the Java SE Platform only -- not in java.base</a></td></tr>
-<tr class="se-ee"><td><a href="https://jcp.org/en/jsr/platform?listBy=3&listByType=platform">JCP technology in the Java SE Platform and the Java EE Platform</a></a></td></tr>
-<tr class="se-ext"><td><a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#endorsed-standards-apis">JCP technology in the Java SE Platform based on non-JCP standards</a></a></td></tr>
-<tr><td>JCP technology in neither the Java SE or EE Platforms</td></tr>
+<tr class="se-ee"><td><a href="https://jcp.org/en/jsr/platform?listBy=3&listByType=platform">JCP technology in the Java SE Platform derived from the Java EE Platform</a></a></td></tr>
+<tr class="se-ext"><td><a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#endorsed-standards-apis">JCP technology in the Java SE Platform derived from non-JCP standards</a></a></td></tr>
+<tr class="non-se"><td>JCP technology in neither the Java SE or EE Platforms</td></tr>
 </table>
 
-<p><em>An <strong>upgradeable</strong> module contains JCP technology that is in the Java SE Platform but is not exclusive to the Java SE Platform, i.e., the green and pink technologies. Most upgradeable modules are defined by loaders other than the bootstrap.</em></p>
-
 <br/>
 
 <table>
 <tr>
+<th>JSR</th>
 <th>Technology</th>
-<th>Original JSR</th>
-<th><a href="https://jcp.org/en/procedures/jcp2#DEF">Original Target</a></th>
+<th><a href="https://jcp.org/en/procedures/jcp2_10#3.3.1.2">Evolved By</a></th>
 <th>Module</th>
-<th><a href="https://jcp.org/en/procedures/jcp2#2.1.2">Evolved By</a></th>
-<th>History</th>
-<th>Profile/SE</th>
 <th>Loader</th>
 <th>Upg?</th>
+<th>Notes</th>
+<th>Aggregator</th>
+</tr>
+
+<tr class="se-base">
+<td>---</td>
+<td>Collections, Concurrency, <br/> Core Reflection, I18N, I/O, <br/> JAAS, JCA, JSSE, Math, Net, Text</td>
+<td>UJSR for Java SE</td>
+<td><a href="module-summary.html#java.base"/>java.base</a></td>
+<td>boot</td>
+<td>No</td>
+<td></td>
+<td class="agg" rowspan=37><a href="module-summary.html#java.se"/>java.se</a></td>
 </tr>
 
 <tr class="se-misc">
-<td>JMX</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=3">3</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.management">java.management</a></td>
+<td>---</td>
+<td>A11Y, Applet, AWT, Beans, <br/> Image I/O, Java 2D, <br/> Print, Sound, Swing</td>
 <td>UJSR for Java SE</td>
-<td></td>
-<td>3</td>
+<td><a href="module-summary.html#java.desktop"/>java.desktop</a></td>
 <td>boot</td>
 <td>No</td>
+<td></td>
 </tr>
 
 <tr class="se-misc">
-<td>Print Service</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=6">6</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.desktop">java.desktop</a></td>
+<td>---</td>
+<td>Data Transfer</td>
 <td>UJSR for Java SE</td>
-<td></td>
-<td>SE</td>
+<td><a href="module-summary.html#java.datatransfer"/>java.datatransfer</a></td>
 <td>boot</td>
 <td>No</td>
+<td></td>
 </tr>
 
 <tr class="se-misc">
-<td>Preferences</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=10">10</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.prefs">java.prefs</a></td>
+<td>---</td>
+<td>JNDI</td>
 <td>UJSR for Java SE</td>
-<td></td>
-<td>3</td>
+<td><a href="module-summary.html#java.naming"/>java.naming</a></td>
 <td>boot</td>
 <td>No</td>
+<td></td>
 </tr>
 
 <tr class="se-misc">
-<td>Image I/O</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=15">15</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.desktop">java.desktop</a></td>
+<td>---</td>
+<td>RMI</td>
 <td>UJSR for Java SE</td>
-<td></td>
-<td>SE</td>
+<td><a href="module-summary.html#java.rmi"/>java.rmi</a></td>
 <td>boot</td>
 <td>No</td>
+<td></td>
 </tr>
 
 <tr class="se-misc">
-<td>SASL</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=28">28</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.security.sasl"/>java.security.sasl</a></td>
+<td><a href="https://jcp.org/en/jsr/detail?id=3">3</a></td>
+<td>JMX</td>
 <td>UJSR for Java SE</td>
-<td></td>
-<td>3</td>
+<td><a href="module-summary.html#java.management">java.management</a></td>
 <td>boot</td>
 <td>No</td>
+<td></td>
 </tr>
 
 <tr class="se-misc">
-<td>Logging</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=47">47</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.logging">java.logging</a></td>
+<td><a href="https://jcp.org/en/jsr/detail?id=6">6</a></td>
+<td>Print Service</td>
 <td>UJSR for Java SE</td>
-<td></td>
-<td>1</td>
+<td><a href="module-summary.html#java.desktop">java.desktop</a></td>
 <td>boot</td>
 <td>No</td>
+<td></td>
+</tr>
+
+<tr class="se-misc">
+<td><a href="https://jcp.org/en/jsr/detail?id=10">10</a></td>
+<td>Preferences</td>
+<td>UJSR for Java SE</td>
+<td><a href="module-summary.html#java.prefs">java.prefs</a></td>
+<td>boot</td>
+<td>No</td>
+<td></td>
+</tr>
+
+<tr class="se-misc">
+<td><a href="https://jcp.org/en/jsr/detail?id=15">15</a></td>
+<td>Image I/O</td>
+<td>UJSR for Java SE</td>
+<td><a href="module-summary.html#java.desktop">java.desktop</a></td>
+<td>boot</td>
+<td>No</td>
+<td></td>
+</tr>
+
+<tr class="se-misc">
+<td><a href="https://jcp.org/en/jsr/detail?id=28">28</a></td>
+<td>SASL</td>
+<td>UJSR for Java SE</td>
+<td><a href="module-summary.html#java.security.sasl"/>java.security.sasl</a></td>
+<td>boot</td>
+<td>No</td>
+<td></td>
+</tr>
+
+<tr class="se-misc">
+<td><a href="https://jcp.org/en/jsr/detail?id=47">47</a></td>
+<td>Logging</td>
+<td>UJSR for Java SE</td>
+<td><a href="module-summary.html#java.logging">java.logging</a></td>
+<td>boot</td>
+<td>No</td>
+<td></td>
 </tr>
 
 <tr class="se-base">
+<td><a href="https://jcp.org/en/jsr/detail?id=51">51</a></td>
 <td>NIO</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=51">51</a></td>
-<td>Java SE</td>
+<td>UJSR for Java SE</td>
 <td><a href="module-summary.html#java.base"/>java.base</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>1</td>
 <td>boot</td>
 <td>No</td>
-</tr>
-
-<tr>
-<td>JNLP</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=56">56</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.desktop">java.jnlp</a></td>
-<td>Original JSR</td>
 <td></td>
-<td>N/A</td>
-<td>boot</td>
-<td>No</td>
 </tr>
 
 <tr class="se-misc">
+<td><a href="https://jcp.org/en/jsr/detail?id=57">57</a></td>
 <td>Beans Persistence</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=57">57</a></td>
-<td>Java SE</td>
+<td>UJSR for Java SE</td>
 <td><a href="module-summary.html#java.desktop">java.desktop</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>SE</td>
 <td>boot</td>
 <td>No</td>
+<td></td>
 </tr>
 
 <tr class="se-misc">
+<td><a href="https://jcp.org/en/jsr/detail?id=72">72</a></td>
 <td>GSS</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=72">72</a></td>
-<td>Java SE</td>
+<td>UJSR for Java SE</td>
 <td><a href="module-summary.html#java.security.jgss">java.security.jgss</a></td>
-<td>UJSR for Java SE</td>
+<td>plat</td>
+<td>No</td>
 <td></td>
-<td>3</td>
-<td>boot</td>
-<td>No</td>
 </tr>
 
 <tr class="se-misc">
+<td><a href="https://jcp.org/en/jsr/detail?id=105">105</a></td>
 <td>XML Digital Signature</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=105">105</a></td>
-<td>Java SE</td>
+<td>UJSR for Java SE</td>
 <td><a href="module-summary.html#java.xml.crypto">java.xml.crypto</a></td>
-<td>UJSR for Java SE</td>
+<td>plat</td>
+<td>No</td>
 <td></td>
-<td>3</td>
-<td>boot</td>
-<td>No</td>
 </tr>
 
 <tr class="se-misc">
+<td><a href="https://jcp.org/en/jsr/detail?id=114">114</a></td>
 <td>JDBC Rowset</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=114">114</a></td>
-<td>Java SE</td>
+<td>Original JSR</td>
 <td><a href="module-summary.html#java.sql.rowset">java.sql.rowset</a></td>
-<td>Original JSR</td>
-<td>Co-evolved with JDBC</td>
-<td>3</td>
-<td>boot</td>
+<td>plat</td>
 <td>No</td>
+<td>Co-developed with JDBC</td>
 </tr>
 
 <tr class="se-misc">
+<td><a href="https://jcp.org/en/jsr/detail?id=160">160</a></td>
 <td>JMX Remote</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=160">160</a></td>
-<td>Java SE</td>
+<td>UJSR for Java SE</td>
 <td><a href="module-summary.html#java.management">java.management</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>3</td>
 <td>boot</td>
 <td>No</td>
+<td></td>
 </tr>
 
 <tr class="se-misc">
-<td>Profiling (Agent)</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=163">163</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.instrument">java.instrument</a></td>
+<td><a href="https://jcp.org/en/jsr/detail?id=160">160</a></td>
+<td>JMX Remote (RMI)</td>
 <td>UJSR for Java SE</td>
-<td></td>
-<td>3</td>
+<td><a href="module-summary.html#java.management.rmi">java.management.rmi</a></td>
 <td>boot</td>
 <td>No</td>
+<td></td>
+</tr>
+
+
+<tr class="se-misc">
+<td><a href="https://jcp.org/en/jsr/detail?id=163">163</a></td>
+<td>Instrumentation</td>  <!-- Profiling (Agent) -->
+<td>UJSR for Java SE</td>
+<td><a href="module-summary.html#java.instrument">java.instrument</a></td>
+<td>boot</td>
+<td>No</td>
+<td>Co-developed with JVMTI</td>
 </tr>
 
 <tr class="se-misc">
-<td>Profiling (JMX)</td>
 <td><a href="https://jcp.org/en/jsr/detail?id=163">163</a></td>
-<td>Java SE</td>
+<td>Monitoring & Management</td>  <!-- Profiling (JMX) -->
+<td>UJSR for Java SE</td>
 <td><a href="module-summary.html#java.management">java.management</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>3</td>
 <td>boot</td>
 <td>No</td>
+<td></td>
 </tr>
 
 <tr class="se-base">
+<td><a href="https://jcp.org/en/jsr/detail?id=166">166</a></td>
 <td>Concurrency Utilities</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=166">166</a></td>
-<td>Java SE</td>
+<td>UJSR for Java SE</td>
 <td><a href="module-summary.html#java.base"/>java.base</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>1</td>
 <td>boot</td>
 <td>No</td>
+<td></td>
+</tr>
+
+<tr class="se-misc">
+<td><a href="https://jcp.org/en/jsr/detail?id=173">173</a></td>
+<td>StAX</td>
+<td>UJSR for Java SE</td>
+<td><a href="module-summary.html#java.xml">java.xml</a></td>
+<td>boot</td>
+<td>No</td>
+<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a></td>
 </tr>
 
 <tr class="se-base">
-<td>Annotations</td>
 <td><a href="https://jcp.org/en/jsr/detail?id=175">175</a></td>
-<td>Java SE</td>
+<td>Annotations (Core Reflection)</td>
+<td>UJSR for Java SE</td>
 <td><a href="module-summary.html#java.base"/>java.base</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>1</td>
 <td>boot</td>
 <td>No</td>
+<td></td>
 </tr>
 
 <tr class="se-misc">
-<td>StAX</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=173">173</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.xml">java.xml</a></td>
-<td>Original JSR</td>
-<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a></td>
-<td>2</td>
-<td>boot</td>
-<td>No</td>
+<td><a href="https://jcp.org/en/jsr/detail?id=175">175</a></td>
+<td>Annotations (Language Model)</td>
+<td>UJSR for Java SE</td>
+<td><a href="module-summary.html#java.compiler"/>java.compiler</a></td>
+<td>plat</td>
+<td>Yes</td>
+<td>Co-located with a former Standalone Technology</td>
 </tr>
 
 <tr class="se-misc">
-<td>Annotations (Language Model)</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=175">175</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.compiler"/>java.compiler</a></td>
+<td><a href="https://jcp.org/en/jsr/detail?id=199">199</a></td>
+<td>Compiler</td>
+<td>Original JSR</td>
+<td><a href="module-summary.html#java.compiler">java.compiler</a></td>
+<td>plat</td>
+<td>Yes</td>
+<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a></td>
+</tr>
+
+<tr class="se-base">
+<td><a href="https://jcp.org/en/jsr/detail?id=200">200</a></td>
+<td>Pack200</td>
 <td>UJSR for Java SE</td>
-<td></td>
-<td>3</td>
+<td><a href="module-summary.html#java.base"/>java.base</a></td>
 <td>boot</td>
 <td>No</td>
+<td></td>
+</tr>
+
+<tr class="se-base">
+<td><a href="https://jcp.org/en/jsr/detail?id=203">203</a></td>
+<td>NIO.2</td>
+<td>UJSR for Java SE</td>
+<td><a href="module-summary.html#java.base"/>java.base</a></td>
+<td>boot</td>
+<td>No</td>
+<td></td>
 </tr>
 
 <tr class="se-misc">
-<td>Compiler</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=199">199</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.compiler">java.compiler</a></td>
-<td>Original JSR</td>
-<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a></td>
-<td>3</td>
+<td><a href="https://jcp.org/en/jsr/detail?id=206">206</a></td>
+<td>JAXP</td>
+<td>UJSR for Java SE</td>
+<td><a href="module-summary.html#java.xml">java.xml</a></td>
 <td>boot</td>
 <td>No</td>
+<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a></td>
+</tr>
+
+<tr class="se-misc">
+<td><a href="https://jcp.org/en/jsr/detail?id=221">221</a></td>
+<td>JDBC</td>
+<td>Original JSR</td>
+<td><a href="module-summary.html#java.sql">java.sql</a></td>
+<td>plat</td>
+<td>No</td>
+<td>Co-developed with JDBC Rowset</td>
+</tr>
+
+<tr class="se-misc">
+<td><a href="https://jcp.org/en/jsr/detail?id=223">223</a></td>
+<td>Scripting</td>
+<td>UJSR for Java SE</td>
+<td><a href="module-summary.html#java.scripting">java.scripting</a></td>
+<td>plat</td>
+<td>No</td>
+<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a></td>
+</tr>
+
+<tr class="se-misc">
+<td><a href="https://jcp.org/en/jsr/detail?id=269">269</a></td>
+<td>Annotation Processing</td>
+<td>Original JSR</td>
+<td><a href="module-summary.html#java.compiler">java.compiler</a></td>
+<td>plat</td>
+<td>Yes</td>
+<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a></td>
 </tr>
 
 <tr class="se-base">
-<td>Pack200</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=200">200</a></td>
-<td>Java SE</td>
+<td><a href="https://jcp.org/en/jsr/detail?id=292">292</a></td>
+<td>InvokeDynamic</td>
+<td>UJSR for Java SE</td>
 <td><a href="module-summary.html#java.base"/>java.base</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>1</td>
 <td>boot</td>
 <td>No</td>
+<td></td>
 </tr>
 
 <tr class="se-base">
-<td>NIO.2</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=203">203</a></td>
-<td>Java SE</td>
+<td><a href="https://jcp.org/en/jsr/detail?id=308">308</a></td>
+<td>Type Annotations (Core Reflection)</td>
+<td>UJSR for Java SE</td>
 <td><a href="module-summary.html#java.base"/>java.base</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>1</td>
 <td>boot</td>
 <td>No</td>
+<td></td>
 </tr>
 
 <tr class="se-misc">
-<td>JAXP</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=206">206</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.xml">java.xml</a></td>
+<td><a href="https://jcp.org/en/jsr/detail?id=308">308</a></td>
+<td>Type Annotations (Language Model)</td>
 <td>UJSR for Java SE</td>
-<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a></td>
-<td>2</td>
+<td><a href="module-summary.html#java.compiler"/>java.compiler</a></td>
+<td>plat</td>
+<td>Yes</td>
+<td>Co-located with a former Standalone Technology</td>
+</tr>
+
+<tr class="se-base">
+<td><a href="https://jcp.org/en/jsr/detail?id=310">310</a></td>
+<td>Date and Time</td>
+<td>UJSR for Java SE</td>
+<td><a href="module-summary.html#java.base"/>java.base</a></td>
 <td>boot</td>
 <td>No</td>
+<td></td>
+</tr>
+
+<tr class="se-base">
+<td><a href="https://jcp.org/en/jsr/detail?id=335">335</a></td>
+<td>Streams</td>
+<td>UJSR for Java SE</td>
+<td><a href="module-summary.html#java.base"/>java.base</a></td>
+<td>boot</td>
+<td>No</td>
+<td></td>
+</tr>
+
+<tr class="se-ext">
+<td>(W3C)</td>
+<td>DOM, SAX</td>
+<td>UJSR for Java SE</td>
+<td><a href="module-summary.html#java.xml">java.xml</a></td>
+<td>boot</td>
+<td>No</td>
+<td>Formerly an <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#endorsed-standards-apis">Endorsed Standard</a></td>
+</tr>
+
+<tr class="se-ext">
+<td>(OMG)</td>
+<td>RMI-IIOP, IDL</td>
+<td>UJSR for Java SE</td>
+<td><a href="module-summary.html#java.corba"/>java.corba</a></td>
+<td>plat</td>
+<td>Yes</td>
+<td>Formerly an <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#endorsed-standards-apis">Endorsed Standard</a></td>
+<td class="agg" rowspan=7><a href="module-summary.html#java.se.ee"/>java.se.ee</a></td>
+</tr>
+
+<tr class="se-ee">
+<td><a href="https://jcp.org/en/jsr/detail?id=67">67</a></td>
+<td>SAAJ</td>
+<td>Original JSR</td>
+<td><a href="module-summary.html#java.xml.ws">java.xml.ws</a></td>
+<td>plat</td>
+<td>Yes</td>
+<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a> (f.k.a. JAXM)</td>
+</tr>
+
+<tr class="se-ee">
+<td><a href="https://jcp.org/en/jsr/detail?id=181">181</a></td>
+<td>Web Services Metadata</td>
+<td>Original JSR</td>
+<td><a href="module-summary.html#java.xml.ws">java.xml.ws</a></td>
+<td>plat</td>
+<td>Yes</td>
+<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a> (unlisted)</td>
+</tr>
+
+<tr class="se-ee">
+<td><a href="https://jcp.org/en/jsr/detail?id=222">222</a></td>
+<td>JAXB</td>
+<td>Original JSR</td>
+<td><a href="module-summary.html#java.xml.bind">java.xml.bind</a></td>
+<td>plat</td>
+<td>Yes</td>
+<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a></td>
+</tr>
+
+<tr class="se-ee">
+<td><a href="https://jcp.org/en/jsr/detail?id=224">224</a></td>
+<td>JAXWS</td>
+<td>Original JSR</td>
+<td><a href="module-summary.html#java.xml.ws">java.xml.ws</a></td>
+<td>plat</td>
+<td>Yes</td>
+<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a></td>
+</tr>
+
+<!-- The Java SE Platform incorporates a smaller version of the javax.annotation package than the Java EE Platform. -->
+<tr class="se-ee">
+<td><a href="https://jcp.org/en/jsr/detail?id=250">250</a></td>
+<td>Common Annotations</td>
+<td>Original JSR</td>
+<td><a href="module-summary.html#java.xml.ws.annotation">java.xml.ws.annotation</a></td>
+<td>plat</td>
+<td>Yes</td>
+<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a> (unlisted)</td>
+</tr>
+
+<!-- The Java SE Platform incorporates a smaller version of the javax.transaction package than the Java EE Platform. -->
+<tr class="se-ee">
+<td><a href="https://jcp.org/en/jsr/detail?id=907">907</a></td>
+<td>JTA (non-XA)</td>
+<td>Original JSR</td>
+<td><a href="module-summary.html#java.transaction">java.transaction</a></td>
+<td>plat</td>
+<td>Yes</td>
+<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a> (unlisted)</td>
+</tr>
+
+<!-- The Java SE Platform incorporates the same version of the javax.transaction.xa package as the Java EE Platform. -->
+<tr class="se-ee">
+<td><a href="https://jcp.org/en/jsr/detail?id=907">907</a></td>
+<td>JTA (XA)</td>
+<td>Original JSR</td>
+<td><a href="module-summary.html#java.sql"/>java.sql</a></td>
+<td>plat</td>
+<td>No</td>
+<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a> (unlisted)</td>
+<td class="agg"><a href="module-summary.html#java.se"/>java.se</a></td>
 </tr>
 
 <tr class="se-misc">
-<td>JDBC</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=221">221</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.sql">java.sql</a></td>
+<td><a href="https://jcp.org/en/jsr/detail?id=925">925</a></td>
+<td>JAF</td>
 <td>Original JSR</td>
-<td>Co-evolved with JDBC Rowset</td>
-<td>2</td>
-<td>boot</td>
-<td>No</td>
+<td><a href="module-summary.html#java.activation">java.activation</a></a></td>
+<td>plat</td>
+<td>Yes</td>
+<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a> (unlisted)</td>
+<td class="agg"><a href="module-summary.html#java.se.ee"/>java.se.ee</a></td>
 </tr>
 
-<tr class="se-misc">
-<td>Scripting</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=223">223</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.scripting">java.scripting</a></td>
+<tr class="non-se">
+<td><a href="https://jcp.org/en/jsr/detail?id=56">56</a></td>
+<td>JNLP</td>
 <td>Original JSR</td>
-<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a></td>
-<td>1</td>
-<td>boot</td>
-<td>No</td>
+<td><a href="module-summary.html#java.desktop">java.jnlp</a></td>
+<td>plat</td>
+<td>Yes</td>
+<td></td>
+<td class="agg" rowspan=2>None</td>
 </tr>
 
-<tr>
+<tr class="non-se">
+<td><a href="https://jcp.org/en/jsr/detail?id=268">268</a></td>
 <td>Smart Card I/O</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=268">268</a></td>
-<td>Java SE</td>
+<td>Original JSR</td>
 <td><a href="module-summary.html#java.smartcardio">java.smartcardio</a></td>
-<td>Original JSR</td>
+<td>plat</td>
+<td>No</td>
 <td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a> (unlisted)</td>
-<td>N/A</td>
-<td>boot</td>
-<td>No</td>
-</tr>
-
-<tr class="se-misc">
-<td>Annotation Processing</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=269">269</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.compiler">java.compiler</a></td>
-<td>Original JSR</td>
-<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a></td>
-<td>3</td>
-<td>boot</td>
-<td>No</td>
-</tr>
-
-<tr class="se-base">
-<td>InvokeDynamic</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=292">292</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.base"/>java.base</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>1</td>
-<td>boot</td>
-<td>No</td>
-</tr>
-
-<tr class="se-base">
-<td>Type Annotations</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=308">308</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.base"/>java.base</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>1</td>
-<td>boot</td>
-<td>No</td>
-</tr>
-
-<tr class="se-misc">
-<td>Type Annotations (Language Model)</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=308">308</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.compiler"/>java.compiler</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>3</td>
-<td>boot</td>
-<td>No</td>
-</tr>
-
-<tr class="se-base">
-<td>Date and Time</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=310">310</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.base"/>java.base</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>1</td>
-<td>boot</td>
-<td>No</td>
-</tr>
-
-<tr class="se-base">
-<td>Streams</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=335">335</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.base"/>java.base</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>1</td>
-<td>boot</td>
-<td>No</td>
-</tr>
-
-<tr class="se-base">
-<td>Collections, Math, I18N, I/O, Net, Reflection</td>
-<td>---</td>
-<td>---</td>
-<td><a href="module-summary.html#java.base"/>java.base</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>1</td>
-<td>boot</td>
-<td>No</td>
-</tr>
-
-<tr class="se-base">
-<td>JCA, JAAS, JSSE</td>
-<td>---</td>
-<td>---</td>
-<td><a href="module-summary.html#java.base"/>java.base</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>1</td>
-<td>boot</td>
-<td>No</td>
-</tr>
-
-<tr class="se-misc">
-<td>Applet, AWT, Swing, Java 2D, Beans, A11Y, Sound</td>
-<td>---</td>
-<td>---</td>
-<td><a href="module-summary.html#java.desktop"/>java.desktop</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>SE</td>
-<td>boot</td>
-<td>No</td>
-</tr>
-
-<tr class="se-misc">
-<td>Data Transfer</td>
-<td>---</td>
-<td>---</td>
-<td><a href="module-summary.html#java.datatransfer"/>java.datatransfer</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>SE</td>
-<td>boot</td>
-<td>No</td>
-</tr>
-
-<tr class="se-misc">
-<td>JNDI</td>
-<td>---</td>
-<td>---</td>
-<td><a href="module-summary.html#java.naming"/>java.naming</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>3</td>
-<td>boot</td>
-<td>No</td>
-</tr>
-
-<tr class="se-misc">
-<td>RMI</td>
-<td>---</td>
-<td>---</td>
-<td><a href="module-summary.html#java.rmi"/>java.rmi</a></td>
-<td>UJSR for Java SE</td>
-<td></td>
-<td>2</td>
-<td>boot</td>
-<td>No</td>
-</tr>
-
-<tr class="se-misc">
-<td>JAF</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=925">925</a></td>
-<td>---</td>
-<td><a href="module-summary.html#java.activation">java.activation</a></a></td>
-<td>Original JSR</td>
-<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a> (unlisted)</td>
-<td>SE</td>
-<td>ext</td>
-<td>Yes</td>
-</tr>
-
-<tr class="se-ext">
-<td>RMI-IIOP, IDL</td>
-<td>(OMG)</td>
-<td>---</td>
-<td><a href="module-summary.html#java.corba"/>java.corba</a></td>
-<td>UJSR for Java SE</td>
-<td>Formerly an <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#endorsed-standards-apis">Endorsed Standard</a></td>
-<td>SE</td>
-<td>ext</td>
-<td>Yes</td>
-</tr>
-
-<tr class="se-ext">
-<td>DOM, SAX</td>
-<td>(W3C)</td>
-<td>---</td>
-<td><a href="module-summary.html#java.xml">java.xml</a></td>
-<td>UJSR for Java SE</td>
-<td>Formerly an <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#endorsed-standards-apis">Endorsed Standard</a></td>
-<td>2</td>
-<td>boot</td>
-<td>No</td>
-</tr>
-
-<tr class="se-ee">
-<td>SAAJ</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=67">67</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.xml.ws">java.xml.ws</a></td>
-<td>Original JSR</td>
-<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a> (f.k.a. JAXM)</td>
-<td>SE</td>
-<td>ext</td>
-<td>Yes</td>
-</tr>
-
-<tr class="se-ee">
-<td>Web Services Metadata</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=181">181</a></td>
-<td>Java EE</td>
-<td><a href="module-summary.html#java.xml.ws">java.xml.ws</a></td>
-<td>Original JSR</td>
-<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a> (unlisted)</td>
-<td>SE</td>
-<td>ext</td>
-<td>Yes</td>
-</tr>
-
-<tr class="se-ee">
-<td>JAXB</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=222">222</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.xml.bind">java.xml.bind</a></td>
-<td>Original JSR</td>
-<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a></td>
-<td>SE</td>
-<td>ext</td>
-<td>Yes</td>
-</tr>
-
-<tr class="se-ee">
-<td>JAXWS</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=224">224</a></td>
-<td>Java SE</td>
-<td><a href="module-summary.html#java.xml.ws">java.xml.ws</a></td>
-<td>Original JSR</td>
-<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a></td>
-<td>SE</td>
-<td>ext</td>
-<td>Yes</td>
-</tr>
-
-<!-- Alex: The Java SE Platform incorporates a cutdown version of the javax.annotation package from the Java EE Platform. -->
-<tr class="se-ee">
-<td>Common Annotations</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=250">250</a></td>
-<td>Java SE,EE</td>
-<td><a href="module-summary.html#java.xml.ws.annotation">java.xml.ws.annotation</a></td>
-<td>Original JSR</td>
-<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a> (unlisted)</td>
-<td>SE</td>
-<td>ext</td>
-<td>Yes</td>
-</tr>
-
-<!-- Alex: The Java SE Platform incorporates a cutdown version of the javax.transaction package from the Java EE Platform. -->
-<tr class="se-ee">
-<td>JTA (non-XA)</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=907">907</a></td>
-<td>---</td>
-<td><a href="module-summary.html#java.transaction">java.transaction</a></td>
-<td>Original JSR</td>
-<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a> (unlisted)</td>
-<td>SE</td>
-<td>ext</td>
-<td>Yes</td>
-</tr>
-
-<!-- Alex: The Java SE Platform incorporates the same version of the javax.transaction.xa package as the Java EE Platform. -->
-<tr class="se-ee">
-<td>JTA (XA)</td>
-<td><a href="https://jcp.org/en/jsr/detail?id=907">907</a></td>
-<td>---</td>
-<td><a href="module-summary.html#java.sql"/>java.sql</a></td>
-<td>Original JSR</td>
-<td>Formerly a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/standards/#standalone-technologies">Standalone Technology</a> (unlisted)</td>
-<td>2</td>
-<td>boot</td>
-<td>No</td>
 </tr>
 
 </table>
--- a/src/java.base/share/classes/java/io/File.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/io/File.java	Thu Jun 29 13:07:19 2017 -0700
@@ -916,23 +916,28 @@
      * Returns the time that the file denoted by this abstract pathname was
      * last modified.
      *
+     * @apiNote
+     * While the unit of time of the return value is milliseconds, the
+     * granularity of the value depends on the underlying file system and may
+     * be larger.  For example, some file systems use time stamps in units of
+     * seconds.
+     *
      * <p> Where it is required to distinguish an I/O exception from the case
      * where {@code 0L} is returned, or where several attributes of the
      * same file are required at the same time, or where the time of last
      * access or the creation time are required, then the {@link
      * java.nio.file.Files#readAttributes(Path,Class,LinkOption[])
-     * Files.readAttributes} method may be used.
-     *
-     * @apiNote
-     * While the unit of time of the return value is milliseconds,
-     * the granularity of the value depends on the underlying
-     * file system and may be larger.  For example, some
-     * file systems use time stamps in units of seconds.
+     * Files.readAttributes} method may be used.  If however only the
+     * time of last modification is required, then the
+     * {@link java.nio.file.Files#getLastModifiedTime(Path,LinkOption[])
+     * Files.getLastModifiedTime} method may be used instead.
      *
      * @return  A <code>long</code> value representing the time the file was
      *          last modified, measured in milliseconds since the epoch
      *          (00:00:00 GMT, January 1, 1970), or <code>0L</code> if the
-     *          file does not exist or if an I/O error occurs
+     *          file does not exist or if an I/O error occurs.  The value may
+     *          be negative indicating the number of milliseconds before the
+     *          epoch
      *
      * @throws  SecurityException
      *          If a security manager exists and its {@link
--- a/src/java.base/share/classes/java/lang/Class.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/lang/Class.java	Thu Jun 29 13:07:19 2017 -0700
@@ -50,6 +50,7 @@
 import java.security.AccessController;
 import java.security.PrivilegedAction;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Collection;
 import java.util.HashMap;
 import java.util.HashSet;
@@ -2067,25 +2068,6 @@
     }
 
     /**
-     * Returns a {@code Method} object that reflects the specified public
-     * member method of the class or interface represented by this
-     * {@code Class} object.
-     *
-     * @param name the name of the method
-     * @param parameterTypes the list of parameters
-     * @return the {@code Method} object that matches the specified
-     *         {@code name} and {@code parameterTypes}; {@code null}
-     *         if the method is not found or the name is
-     *         "&lt;init&gt;"or "&lt;clinit&gt;".
-     */
-    Method getMethodOrNull(String name, Class<?>... parameterTypes) {
-        Objects.requireNonNull(name);
-        Method method = getMethod0(name, parameterTypes);
-        return method == null ? null : getReflectionFactory().copyMethod(method);
-    }
-
-
-    /**
      * Returns a {@code Constructor} object that reflects the specified
      * public constructor of the class represented by this {@code Class}
      * object. The {@code parameterTypes} parameter is an array of
@@ -2225,7 +2207,6 @@
 
 
     /**
-     *
      * Returns an array containing {@code Method} objects reflecting all the
      * declared methods of the class or interface represented by this {@code
      * Class} object, including public, protected, default (package)
@@ -2453,6 +2434,30 @@
         return getReflectionFactory().copyMethod(method);
     }
 
+    /**
+     * Returns the list of {@code Method} objects for the declared public
+     * methods of this class or interface that have the specified method name
+     * and parameter types.
+     *
+     * @param name the name of the method
+     * @param parameterTypes the parameter array
+     * @return the list of {@code Method} objects for the public methods of
+     *         this class matching the specified name and parameters
+     */
+    List<Method> getDeclaredPublicMethods(String name, Class<?>... parameterTypes) {
+        Method[] methods = privateGetDeclaredMethods(/* publicOnly */ true);
+        ReflectionFactory factory = getReflectionFactory();
+        List<Method> result = new ArrayList<>();
+        for (Method method : methods) {
+            if (method.getName().equals(name)
+                && Arrays.equals(
+                    factory.getExecutableSharedParameterTypes(method),
+                    parameterTypes)) {
+                result.add(factory.copyMethod(method));
+            }
+        }
+        return result;
+    }
 
     /**
      * Returns a {@code Constructor} object that reflects the specified
--- a/src/java.base/share/classes/java/lang/ClassLoader.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/lang/ClassLoader.java	Thu Jun 29 13:07:19 2017 -0700
@@ -93,12 +93,20 @@
  * <p> Class loaders may typically be used by security managers to indicate
  * security domains.
  *
+ * <p> In addition to loading classes, a class loader is also responsible for
+ * locating resources. A resource is some data (a "{@code .class}" file,
+ * configuration data, or an image for example) that is identified with an
+ * abstract '/'-separated path name. Resources are typically packaged with an
+ * application or library so that they can be located by code in the
+ * application or library. In some cases, the resources are included so that
+ * they can be located by other libraries.
+ *
  * <p> The {@code ClassLoader} class uses a delegation model to search for
  * classes and resources.  Each instance of {@code ClassLoader} has an
- * associated parent class loader.  When requested to find a class or
- * resource, a {@code ClassLoader} instance will delegate the search for the
- * class or resource to its parent class loader before attempting to find the
- * class or resource itself.
+ * associated parent class loader. When requested to find a class or
+ * resource, a {@code ClassLoader} instance will usually delegate the search
+ * for the class or resource to its parent class loader before attempting to
+ * find the class or resource itself.
  *
  * <p> Class loaders that support concurrent loading of classes are known as
  * <em>{@linkplain #isRegisteredAsParallelCapable() parallel capable}</em> class
@@ -129,11 +137,13 @@
  *     classes and JDK-specific run-time classes that are defined by the
  *     platform class loader or its ancestors.
  *     <p> To allow for upgrading/overriding of modules defined to the platform
- *     class loader, and where classes in the upgraded version link to
- *     classes in modules defined to the application class loader, the
- *     platform class loader may delegate to the application class loader.
- *     In other words, classes in named modules defined to the application
- *     class loader may be visible to the platform class loader. </li>
+ *     class loader, and where upgraded modules read modules defined to class
+ *     loaders other than the platform class loader and its ancestors, then
+ *     the platform class loader may have to delegate to other class loaders,
+ *     the application class loader for example.
+ *     In other words, classes in named modules defined to class loaders
+ *     other than the platform class loader and its ancestors may be visible
+ *     to the platform class loader. </li>
  * <li><p>{@linkplain #getSystemClassLoader() System class loader}.
  *     It is also known as <em>application class loader</em> and is distinct
  *     from the platform class loader.
@@ -498,7 +508,7 @@
      *
      *   <li><p> Invoke the {@link #loadClass(String) loadClass} method
      *   on the parent class loader.  If the parent is {@code null} the class
-     *   loader built-in to the virtual machine is used, instead.  </p></li>
+     *   loader built into the virtual machine is used, instead.  </p></li>
      *
      *   <li><p> Invoke the {@link #findClass(String)} method to find the
      *   class.  </p></li>
@@ -681,8 +691,9 @@
      * This method should be overridden by class loader implementations that
      * follow the delegation model for loading classes, and will be invoked by
      * the {@link #loadClass loadClass} method after checking the
-     * parent class loader for the requested class.  The default implementation
-     * throws a {@code ClassNotFoundException}.
+     * parent class loader for the requested class.
+     *
+     * @implSpec The default implementation throws {@code ClassNotFoundException}.
      *
      * @param  name
      *         The <a href="#name">binary name</a> of the class
@@ -1127,8 +1138,9 @@
                 putIfAbsent(pname, (certs == null? nocerts:certs));
         }
         if (pcerts != null && !compareCerts(pcerts, certs)) {
-            throw new SecurityException("class \""+ name +
-                 "\"'s signer information does not match signer information of other classes in the same package");
+            throw new SecurityException("class \"" + name
+                + "\"'s signer information does not match signer information"
+                + " of other classes in the same package");
         }
     }
 
@@ -1329,12 +1341,7 @@
      * that is independent of the location of the code.
      *
      * <p> The name of a resource is a '{@code /}'-separated path name that
-     * identifies the resource.
-     *
-     * <p> This method will first search the parent class loader for the
-     * resource; if the parent is {@code null} the path of the class loader
-     * built-in to the virtual machine is searched.  That failing, this method
-     * will invoke {@link #findResource(String)} to find the resource.  </p>
+     * identifies the resource. </p>
      *
      * <p> Resources in named modules are subject to the encapsulation rules
      * specified by {@link Module#getResourceAsStream Module.getResourceAsStream}.
@@ -1344,6 +1351,11 @@
      * opened} unconditionally (even if the caller of this method is in the
      * same module as the resource). </p>
      *
+     * @implSpec The default implementation will first search the parent class
+     * loader for the resource; if the parent is {@code null} the path of the
+     * class loader built into the virtual machine is searched. If not found,
+     * this method will invoke {@link #findResource(String)} to find the resource.
+     *
      * @apiNote Where several modules are defined to the same class loader,
      * and where more than one module contains a resource with the given name,
      * then the ordering that modules are searched is not specified and may be
@@ -1387,10 +1399,7 @@
      * that is independent of the location of the code.
      *
      * <p> The name of a resource is a {@code /}-separated path name that
-     * identifies the resource.
-     *
-     * <p> The delegation order for searching is described in the documentation
-     * for {@link #getResource(String)}.  </p>
+     * identifies the resource. </p>
      *
      * <p> Resources in named modules are subject to the encapsulation rules
      * specified by {@link Module#getResourceAsStream Module.getResourceAsStream}.
@@ -1398,7 +1407,15 @@
      * name ending with "{@code .class}", this method will only find resources in
      * packages of named modules when the package is {@link Module#isOpen(String)
      * opened} unconditionally (even if the caller of this method is in the
-     * same module as the resource).</p>
+     * same module as the resource). </p>
+     *
+     * @implSpec The default implementation will first search the parent class
+     * loader for the resource; if the parent is {@code null} the path of the
+     * class loader built into the virtual machine is searched. It then
+     * invokes {@link #findResources(String)} to find the resources with the
+     * name in this class loader. It returns an enumeration whose elements
+     * are the URLs found by searching the parent class loader followed by
+     * the elements found with {@code findResources}.
      *
      * @apiNote Where several modules are defined to the same class loader,
      * and where more than one module contains a resource with the given name,
@@ -1424,8 +1441,6 @@
      *          If I/O errors occur
      * @throws  NullPointerException If {@code name} is {@code null}
      *
-     * @see  #findResources(String)
-     *
      * @since  1.2
      * @revised 9
      * @spec JPMS
@@ -1453,9 +1468,6 @@
      * <p> The name of a resource is a {@code /}-separated path name that
      * identifies the resource.
      *
-     * <p> The search order is described in the documentation for {@link
-     * #getResource(String)}.
-     *
      * <p> The resources will be located when the returned stream is evaluated.
      * If the evaluation results in an {@code IOException} then the I/O
      * exception is wrapped in an {@link UncheckedIOException} that is then
@@ -1469,6 +1481,10 @@
      * opened} unconditionally (even if the caller of this method is in the
      * same module as the resource). </p>
      *
+     * @implSpec The default implementation invokes {@link #getResources(String)
+     * getResources} to find all the resources with the given name and returns
+     * a stream with the elements in the enumeration as the source.
+     *
      * @apiNote When overriding this method it is recommended that an
      * implementation ensures that any delegation is consistent with the {@link
      * #getResource(java.lang.String) getResource(String)} method. This should
@@ -1486,8 +1502,6 @@
      *
      * @throws  NullPointerException If {@code name} is {@code null}
      *
-     * @see  #findResources(String)
-     *
      * @since  9
      */
     public Stream<URL> resources(String name) {
@@ -1506,7 +1520,7 @@
 
     /**
      * Finds the resource with the given name. Class loader implementations
-     * should override this method to specify where to find resources.
+     * should override this method.
      *
      * <p> For resources in named modules then the method must implement the
      * rules for encapsulation specified in the {@code Module} {@link
@@ -1515,6 +1529,8 @@
      * modules unless the package is {@link Module#isOpen(String) opened}
      * unconditionally. </p>
      *
+     * @implSpec The default implementation returns {@code null}.
+     *
      * @param  name
      *         The resource name
      *
@@ -1535,8 +1551,7 @@
     /**
      * Returns an enumeration of {@link java.net.URL URL} objects
      * representing all the resources with the given name. Class loader
-     * implementations should override this method to specify where to load
-     * resources from.
+     * implementations should override this method.
      *
      * <p> For resources in named modules then the method must implement the
      * rules for encapsulation specified in the {@code Module} {@link
@@ -1545,6 +1560,9 @@
      * modules unless the package is {@link Module#isOpen(String) opened}
      * unconditionally. </p>
      *
+     * @implSpec The default implementation returns an enumeration that
+     * contains no elements.
+     *
      * @param  name
      *         The resource name
      *
@@ -1899,7 +1917,8 @@
                 // the system class loader is the built-in app class loader during startup
                 return getBuiltinAppClassLoader();
             case 3:
-                throw new InternalError("getSystemClassLoader should only be called after VM booted");
+                String msg = "getSystemClassLoader should only be called after VM booted";
+                throw new InternalError(msg);
             case 4:
                 // system fully initialized
                 assert VM.isBooted() && scl != null;
@@ -2146,7 +2165,7 @@
      * @revised 9
      * @spec JPMS
      *
-     * @see <a href="../../../technotes/guides/jar/jar.html#sealing">
+     * @see <a href="{@docRoot}/../specs/jar/jar.html#sealing">
      *      The JAR File Specification: Package Sealing</a>
      */
     protected Package definePackage(String name, String specTitle,
--- a/src/java.base/share/classes/java/lang/FdLibm.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/lang/FdLibm.java	Thu Jun 29 13:07:19 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 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
@@ -116,6 +116,10 @@
         private static final double F =  0x1.9b6db6db6db6ep0;  //   45/28   ~= 1.60714285714285720630e+00
         private static final double G =  0x1.6db6db6db6db7p-2; //    5/14   ~= 3.57142857142857150787e-01
 
+        private Cbrt() {
+            throw new UnsupportedOperationException();
+        }
+
         public static strictfp double compute(double x) {
             double  t = 0.0;
             double sign;
@@ -195,6 +199,10 @@
         public static final double TWO_MINUS_600 = 0x1.0p-600;
         public static final double TWO_PLUS_600  = 0x1.0p+600;
 
+        private Hypot() {
+            throw new UnsupportedOperationException();
+        }
+
         public static strictfp double compute(double x, double y) {
             double a = Math.abs(x);
             double b = Math.abs(y);
@@ -331,6 +339,10 @@
      *      representable.
      */
     public static class Pow {
+        private Pow() {
+            throw new UnsupportedOperationException();
+        }
+
         public static strictfp double compute(final double x, final double y) {
             double z;
             double r, s, t, u, v, w;
@@ -664,6 +676,10 @@
         private static final double P4   = -0x1.bbd41c5d26bf1p-20; // -1.65339022054652515390e-06
         private static final double P5   =  0x1.6376972bea4d0p-25; //  4.13813679705723846039e-08
 
+        private Exp() {
+            throw new UnsupportedOperationException();
+        }
+
         // should be able to forgo strictfp due to controlled over/underflow
         public static strictfp double compute(double x) {
             double y;
--- a/src/java.base/share/classes/java/lang/LayerInstantiationException.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/lang/LayerInstantiationException.java	Thu Jun 29 13:07:19 2017 -0700
@@ -63,8 +63,8 @@
     }
 
     /**
-     * Constructs a {@code FindException} with the given detail message
-     * and cause.
+     * Constructs a {@code LayerInstantiationException} with the given detail
+     * message and cause.
      *
      * @param msg
      *        The detail message; can be {@code null}
@@ -74,6 +74,5 @@
     public LayerInstantiationException(String msg, Throwable cause) {
         super(msg, cause);
     }
-
 }
 
--- a/src/java.base/share/classes/java/lang/Module.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/lang/Module.java	Thu Jun 29 13:07:19 2017 -0700
@@ -43,6 +43,7 @@
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.HashSet;
+import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
@@ -55,8 +56,10 @@
 
 import jdk.internal.loader.BuiltinClassLoader;
 import jdk.internal.loader.BootLoader;
+import jdk.internal.loader.ClassLoaders;
 import jdk.internal.misc.JavaLangAccess;
 import jdk.internal.misc.SharedSecrets;
+import jdk.internal.module.IllegalAccessLogger;
 import jdk.internal.module.ModuleLoaderMap;
 import jdk.internal.module.ServicesCatalog;
 import jdk.internal.module.Resources;
@@ -162,7 +165,6 @@
     }
 
 
-
     /**
      * Returns {@code true} if this module is a named module.
      *
@@ -249,12 +251,10 @@
 
     // special Module to mean "all unnamed modules"
     private static final Module ALL_UNNAMED_MODULE = new Module(null);
+    private static final Set<Module> ALL_UNNAMED_MODULE_SET = Set.of(ALL_UNNAMED_MODULE);
 
     // special Module to mean "everyone"
     private static final Module EVERYONE_MODULE = new Module(null);
-
-    // set contains EVERYONE_MODULE, used when a package is opened or
-    // exported unconditionally
     private static final Set<Module> EVERYONE_SET = Set.of(EVERYONE_MODULE);
 
 
@@ -534,12 +534,12 @@
             return true;
 
         // all packages are exported/open to self
-        if (other == this && containsPackage(pn))
+        if (other == this && descriptor.packages().contains(pn))
             return true;
 
         // all packages in open and automatic modules are open
         if (descriptor.isOpen() || descriptor.isAutomatic())
-            return containsPackage(pn);
+            return descriptor.packages().contains(pn);
 
         // exported/opened via module declaration/descriptor
         if (isStaticallyExportedOrOpen(pn, other, open))
@@ -555,42 +555,48 @@
 
     /**
      * Returns {@code true} if this module exports or opens a package to
-     * the given module via its module declaration.
+     * the given module via its module declaration or CLI options.
      */
     private boolean isStaticallyExportedOrOpen(String pn, Module other, boolean open) {
-        // package is open to everyone or <other>
+        // test if package is open to everyone or <other>
         Map<String, Set<Module>> openPackages = this.openPackages;
-        if (openPackages != null) {
-            Set<Module> targets = openPackages.get(pn);
-            if (targets != null) {
-                if (targets.contains(EVERYONE_MODULE))
-                    return true;
-                if (other != EVERYONE_MODULE && targets.contains(other))
-                    return true;
-            }
+        if (openPackages != null && allows(openPackages.get(pn), other)) {
+            return true;
         }
 
         if (!open) {
-            // package is exported to everyone or <other>
+            // test package is exported to everyone or <other>
             Map<String, Set<Module>> exportedPackages = this.exportedPackages;
-            if (exportedPackages != null) {
-                Set<Module> targets = exportedPackages.get(pn);
-                if (targets != null) {
-                    if (targets.contains(EVERYONE_MODULE))
-                        return true;
-                    if (other != EVERYONE_MODULE && targets.contains(other))
-                        return true;
-                }
+            if (exportedPackages != null && allows(exportedPackages.get(pn), other)) {
+                return true;
             }
         }
 
         return false;
     }
 
+    /**
+     * Returns {@code true} if targets is non-null and contains EVERYONE_MODULE
+     * or the given module. Also returns true if the given module is an unnamed
+     * module and targets contains ALL_UNNAMED_MODULE.
+     */
+    private boolean allows(Set<Module> targets, Module module) {
+       if (targets != null) {
+           if (targets.contains(EVERYONE_MODULE))
+               return true;
+           if (module != EVERYONE_MODULE) {
+               if (targets.contains(module))
+                   return true;
+               if (!module.isNamed() && targets.contains(ALL_UNNAMED_MODULE))
+                   return true;
+           }
+        }
+        return false;
+    }
 
     /**
-     * Returns {@code true} if this module reflectively exports or opens given
-     * package package to the given module.
+     * Returns {@code true} if this module reflectively exports or opens the
+     * given package to the given module.
      */
     private boolean isReflectivelyExportedOrOpen(String pn, Module other, boolean open) {
         // exported or open to all modules
@@ -632,6 +638,22 @@
         return false;
     }
 
+    /**
+     * Returns {@code true} if this module reflectively exports the
+     * given package to the given module.
+     */
+    boolean isReflectivelyExported(String pn, Module other) {
+        return isReflectivelyExportedOrOpen(pn, other, false);
+    }
+
+    /**
+     * Returns {@code true} if this module reflectively opens the
+     * given package to the given module.
+     */
+    boolean isReflectivelyOpened(String pn, Module other) {
+        return isReflectivelyExportedOrOpen(pn, other, true);
+    }
+
 
     /**
      * If the caller's module is this module then update this module to export
@@ -800,7 +822,7 @@
     }
 
     /**
-     * Updates this module to export a package to all unnamed modules.
+     * Updates this module to open a package to all unnamed modules.
      *
      * @apiNote Used by the --add-opens command line option.
      */
@@ -808,7 +830,6 @@
         implAddExportsOrOpens(pn, Module.ALL_UNNAMED_MODULE, true, true);
     }
 
-
     /**
      * Updates a module to export or open a module to another module.
      *
@@ -825,12 +846,31 @@
         if (!isNamed() || descriptor.isOpen() || descriptor.isAutomatic())
             return;
 
-        // nothing to do if already exported/open to other
-        if (implIsExportedOrOpen(pn, other, open))
-            return;
+        // check if the package is already exported/open to other
+        if (implIsExportedOrOpen(pn, other, open)) {
+
+            // if the package is exported/open for illegal access then we need
+            // to record that it has also been exported/opened reflectively so
+            // that the IllegalAccessLogger doesn't emit a warning.
+            boolean needToAdd = false;
+            if (!other.isNamed()) {
+                IllegalAccessLogger l = IllegalAccessLogger.illegalAccessLogger();
+                if (l != null) {
+                    if (open) {
+                        needToAdd = l.isOpenForIllegalAccess(this, pn);
+                    } else {
+                        needToAdd = l.isExportedForIllegalAccess(this, pn);
+                    }
+                }
+            }
+            if (!needToAdd) {
+                // nothing to do
+                return;
+            }
+        }
 
         // can only export a package in the module
-        if (!containsPackage(pn)) {
+        if (!descriptor.packages().contains(pn)) {
             throw new IllegalArgumentException("package " + pn
                                                + " not in contents");
         }
@@ -850,7 +890,6 @@
         Map<String, Boolean> map = reflectivelyExports
             .computeIfAbsent(this, other,
                              (m1, m2) -> new ConcurrentHashMap<>());
-
         if (open) {
             map.put(pn, Boolean.TRUE);  // may need to promote from FALSE to TRUE
         } else {
@@ -858,6 +897,38 @@
         }
     }
 
+    /**
+     * Updates a module to open all packages returned by the given iterator to
+     * all unnamed modules.
+     *
+     * @apiNote Used during startup to open packages for illegal access.
+     */
+    void implAddOpensToAllUnnamed(Iterator<String> iterator) {
+        if (jdk.internal.misc.VM.isModuleSystemInited()) {
+            throw new IllegalStateException("Module system already initialized");
+        }
+
+        // replace this module's openPackages map with a new map that opens
+        // the packages to all unnamed modules.
+        Map<String, Set<Module>> openPackages = this.openPackages;
+        if (openPackages == null) {
+            openPackages = new HashMap<>();
+        } else {
+            openPackages = new HashMap<>(openPackages);
+        }
+        while (iterator.hasNext()) {
+            String pn = iterator.next();
+            Set<Module> prev = openPackages.putIfAbsent(pn, ALL_UNNAMED_MODULE_SET);
+            if (prev != null) {
+                prev.add(ALL_UNNAMED_MODULE);
+            }
+
+            // update VM to export the package
+            addExportsToAllUnnamed0(this, pn);
+        }
+        this.openPackages = openPackages;
+    }
+
 
     // -- services --
 
@@ -947,19 +1018,6 @@
 
     // -- packages --
 
-    // Additional packages that are added to the module at run-time.
-    private volatile Map<String, Boolean> extraPackages;
-
-    private boolean containsPackage(String pn) {
-        if (descriptor.packages().contains(pn))
-            return true;
-        Map<String, Boolean> extraPackages = this.extraPackages;
-        if (extraPackages != null && extraPackages.containsKey(pn))
-            return true;
-        return false;
-    }
-
-
     /**
      * Returns the set of package names for the packages in this module.
      *
@@ -974,89 +1032,19 @@
      */
     public Set<String> getPackages() {
         if (isNamed()) {
-
-            Set<String> packages = descriptor.packages();
-            Map<String, Boolean> extraPackages = this.extraPackages;
-            if (extraPackages == null) {
-                return packages;
-            } else {
-                return Stream.concat(packages.stream(),
-                                     extraPackages.keySet().stream())
-                        .collect(Collectors.toSet());
-            }
-
+            return descriptor.packages();
         } else {
             // unnamed module
             Stream<Package> packages;
             if (loader == null) {
                 packages = BootLoader.packages();
             } else {
-                packages = SharedSecrets.getJavaLangAccess().packages(loader);
+                packages = loader.packages();
             }
             return packages.map(Package::getName).collect(Collectors.toSet());
         }
     }
 
-    /**
-     * Add a package to this module without notifying the VM.
-     *
-     * @apiNote This method is VM white-box testing.
-     */
-    void implAddPackageNoSync(String pn) {
-        implAddPackage(pn.replace('/', '.'), false);
-    }
-
-    /**
-     * Add a package to this module.
-     *
-     * If {@code syncVM} is {@code true} then the VM is notified. This method is
-     * a no-op if this is an unnamed module or the module already contains the
-     * package.
-     *
-     * @throws IllegalArgumentException if the package name is not legal
-     * @throws IllegalStateException if the package is defined to another module
-     */
-    private void implAddPackage(String pn, boolean syncVM) {
-        // no-op if unnamed module
-        if (!isNamed())
-            return;
-
-        // no-op if module contains the package
-        if (containsPackage(pn))
-            return;
-
-        // check package name is legal for named modules
-        if (pn.isEmpty())
-            throw new IllegalArgumentException("Cannot add <unnamed> package");
-        for (int i=0; i<pn.length(); i++) {
-            char c = pn.charAt(i);
-            if (c == '/' || c == ';' || c == '[') {
-                throw new IllegalArgumentException("Illegal character: " + c);
-            }
-        }
-
-        // create extraPackages if needed
-        Map<String, Boolean> extraPackages = this.extraPackages;
-        if (extraPackages == null) {
-            synchronized (this) {
-                extraPackages = this.extraPackages;
-                if (extraPackages == null)
-                    this.extraPackages = extraPackages = new ConcurrentHashMap<>();
-            }
-        }
-
-        // update VM first in case it fails. This is a no-op if another thread
-        // beats us to add the package first
-        if (syncVM) {
-            // throws IllegalStateException if defined to another module
-            addPackage0(this, pn);
-            if (descriptor.isOpen() || descriptor.isAutomatic()) {
-                addExportsToAll0(this, pn);
-            }
-        }
-        extraPackages.putIfAbsent(pn, Boolean.TRUE);
-    }
-
 
     // -- creating Module objects --
 
@@ -1075,18 +1063,22 @@
         Map<String, Module> nameToModule = new HashMap<>();
         Map<String, ClassLoader> moduleToLoader = new HashMap<>();
 
-        boolean isBootLayer = (ModuleLayer.boot() == null);
         Set<ClassLoader> loaders = new HashSet<>();
+        boolean hasPlatformModules = false;
 
         // map each module to a class loader
         for (ResolvedModule resolvedModule : cf.modules()) {
             String name = resolvedModule.name();
             ClassLoader loader = clf.apply(name);
-            if (loader != null) {
-                moduleToLoader.put(name, loader);
+            moduleToLoader.put(name, loader);
+            if (loader == null || loader == ClassLoaders.platformClassLoader()) {
+                if (!(clf instanceof ModuleLoaderMap.Mapper)) {
+                    throw new IllegalArgumentException("loader can't be 'null'"
+                            + " or the platform class loader");
+                }
+                hasPlatformModules = true;
+            } else {
                 loaders.add(loader);
-            } else if (!(clf instanceof ModuleLoaderMap.Mapper)) {
-                throw new IllegalArgumentException("loader can't be 'null'");
             }
         }
 
@@ -1098,7 +1090,7 @@
             URI uri = mref.location().orElse(null);
             ClassLoader loader = moduleToLoader.get(resolvedModule.name());
             Module m;
-            if (loader == null && isBootLayer && name.equals("java.base")) {
+            if (loader == null && name.equals("java.base")) {
                 // java.base is already defined to the VM
                 m = Object.class.getModule();
             } else {
@@ -1157,8 +1149,12 @@
             initExportsAndOpens(m, nameToSource, nameToModule, layer.parents());
         }
 
-        // register the modules in the boot layer
-        if (isBootLayer) {
+        // if there are modules defined to the boot or platform class loaders
+        // then register the modules in the class loader's services catalog
+        if (hasPlatformModules) {
+            ClassLoader pcl = ClassLoaders.platformClassLoader();
+            ServicesCatalog bootCatalog = BootLoader.getServicesCatalog();
+            ServicesCatalog pclCatalog = ServicesCatalog.getServicesCatalog(pcl);
             for (ResolvedModule resolvedModule : cf.modules()) {
                 ModuleReference mref = resolvedModule.reference();
                 ModuleDescriptor descriptor = mref.descriptor();
@@ -1166,13 +1162,11 @@
                     String name = descriptor.name();
                     Module m = nameToModule.get(name);
                     ClassLoader loader = moduleToLoader.get(name);
-                    ServicesCatalog catalog;
                     if (loader == null) {
-                        catalog = BootLoader.getServicesCatalog();
-                    } else {
-                        catalog = ServicesCatalog.getServicesCatalog(loader);
+                        bootCatalog.register(m);
+                    } else if (loader == pcl) {
+                        pclCatalog.register(m);
                     }
-                    catalog.register(m);
                 }
             }
         }
@@ -1587,7 +1581,4 @@
 
     // JVM_AddModuleExportsToAllUnnamed
     private static native void addExportsToAllUnnamed0(Module from, String pn);
-
-    // JVM_AddModulePackage
-    private static native void addPackage0(Module m, String pn);
 }
--- a/src/java.base/share/classes/java/lang/ModuleLayer.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/lang/ModuleLayer.java	Thu Jun 29 13:07:19 2017 -0700
@@ -245,6 +245,32 @@
         }
 
         /**
+         * Updates module {@code source} in the layer to export a package to
+         * module {@code target}. This method is a no-op if {@code source}
+         * already exports the package to at least {@code target}.
+         *
+         * @param  source
+         *         The source module
+         * @param  pn
+         *         The package name
+         * @param  target
+         *         The target module
+         *
+         * @return This controller
+         *
+         * @throws IllegalArgumentException
+         *         If {@code source} is not in the module layer or the package
+         *         is not in the source module
+         *
+         * @see Module#addExports
+         */
+        public Controller addExports(Module source, String pn, Module target) {
+            ensureInLayer(source);
+            source.implAddExports(pn, target);
+            return this;
+        }
+
+        /**
          * Updates module {@code source} in the layer to open a package to
          * module {@code target}. This method is a no-op if {@code source}
          * already opens the package to at least {@code target}.
@@ -254,7 +280,7 @@
          * @param  pn
          *         The package name
          * @param  target
-         *         The target module to read
+         *         The target module
          *
          * @return This controller
          *
@@ -397,7 +423,7 @@
      * class loader and defines all modules to that class loader.
      *
      * <p> The class loader created by this method implements <em>direct
-     * delegation</em> when loading types from modules. When its {@link
+     * delegation</em> when loading classes from modules. If the {@link
      * ClassLoader#loadClass(String, boolean) loadClass} method is invoked to
      * load a class then it uses the package name of the class to map it to a
      * module. This may be a module in this layer and hence defined to the same
@@ -408,6 +434,12 @@
      * When {@code loadClass} is invoked to load classes that do not map to a
      * module then it delegates to the parent class loader. </p>
      *
+     * <p> The class loader created by this method locates resources
+     * ({@link ClassLoader#getResource(String) getResource}, {@link
+     * ClassLoader#getResources(String) getResources}, and other resource
+     * methods) in all modules in the layer before searching the parent class
+     * loader. </p>
+     *
      * <p> Attempting to create a layer with all modules defined to the same
      * class loader can fail for the following reasons:
      *
@@ -417,8 +449,8 @@
      *     configuration have the same package. </p></li>
      *
      *     <li><p> <em>Split delegation</em>: The resulting class loader would
-     *     need to delegate to more than one class loader in order to load types
-     *     in a specific package. </p></li>
+     *     need to delegate to more than one class loader in order to load
+     *     classes in a specific package. </p></li>
      *
      * </ul>
      *
@@ -481,7 +513,7 @@
      * class loader.
      *
      * <p> The class loaders created by this method implement <em>direct
-     * delegation</em> when loading types from modules. When {@link
+     * delegation</em> when loading classes from modules. If the {@link
      * ClassLoader#loadClass(String, boolean) loadClass} method is invoked to
      * load a class then it uses the package name of the class to map it to a
      * module. The package may be in the module defined to the class loader.
@@ -489,9 +521,15 @@
      * module defined to the class loader. It may be in a package exported by a
      * module in a parent layer. The class loader delegates to the class loader
      * of the module, throwing {@code ClassNotFoundException} if not found by
-     * that class loader.
-     * When {@code loadClass} is invoked to load classes that do not map to a
-     * module then it delegates to the parent class loader. </p>
+     * that class loader. When {@code loadClass} is invoked to load a class
+     * that does not map to a module then it delegates to the parent class
+     * loader. </p>
+     *
+     * <p> The class loaders created by this method locate resources
+     * ({@link ClassLoader#getResource(String) getResource}, {@link
+     * ClassLoader#getResources(String) getResources}, and other resource
+     * methods) in the module defined to the class loader before searching
+     * the parent class loader. </p>
      *
      * <p> If there is a security manager then the class loaders created by
      * this method will load classes and resources with privileges that are
@@ -576,10 +614,9 @@
      * <p> In addition, a layer cannot be created if the configuration contains
      * a module named "{@code java.base}", a configuration contains a module
      * with a package named "{@code java}" or a package name starting with
-     * "{@code java.}" and the module is mapped to a class loader other than
-     * the {@link ClassLoader#getPlatformClassLoader() platform class loader},
-     * or the function to map a module name to a class loader returns
-     * {@code null}. </p>
+     * "{@code java.}", or the function to map a module name to a class loader
+     * returns {@code null} or the {@linkplain ClassLoader#getPlatformClassLoader()
+     * platform class loader}. </p>
      *
      * <p> If the function to map a module name to class loader throws an error
      * or runtime exception then it is propagated to the caller of this method.
--- a/src/java.base/share/classes/java/lang/Package.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/lang/Package.java	Thu Jun 29 13:07:19 2017 -0700
@@ -109,7 +109,7 @@
  * and have no specification and implementation versioning information.
  *
  * @jvms 5.3 Run-time package
- * @see <a href="../../../technotes/guides/jar/jar.html#sealing">
+ * @see <a href="{@docRoot}/../specs/jar/jar.html#sealing">
  * The JAR File Specification: Package Sealing</a>
  * @see ClassLoader#definePackage(String, String, String, String, String, String, String, URL)
  *
--- a/src/java.base/share/classes/java/lang/SecurityManager.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/lang/SecurityManager.java	Thu Jun 29 13:07:19 2017 -0700
@@ -194,18 +194,15 @@
  * of system administrators who might need to perform multiple
  * tasks that require all (or numerous) permissions.
  * <p>
- * See <a href ="../../../technotes/guides/security/permissions.html">
- * Permissions in the JDK</a> for permission-related information.
+ * See {@extLink security_guide_permissions
+ * Permissions in the Java Development Kit (JDK)}
+ * for permission-related information.
  * This document includes, for example, a table listing the various SecurityManager
  * <code>check</code> methods and the permission(s) the default
  * implementation of each such method requires.
  * It also contains a table of all the version 1.2 methods
  * that require permissions, and for each such method tells
  * which permission it requires.
- * <p>
- * For more information about <code>SecurityManager</code> changes made in
- * the JDK and advice regarding porting of 1.1-style security managers,
- * see the <a href="../../../technotes/guides/security/index.html">security documentation</a>.
  *
  * @author  Arthur van Hoff
  * @author  Roland Schemers
@@ -1496,7 +1493,10 @@
      * Throws a {@code SecurityException} if the calling thread is not allowed
      * to access the specified package.
      * <p>
-     * This method is called by the {@code loadClass} method of class loaders.
+     * During class loading, this method may be called by the {@code loadClass}
+     * method of class loaders and by the Java Virtual Machine to ensure that
+     * the caller is allowed to access the package of the class that is
+     * being loaded.
      * <p>
      * This method checks if the specified package starts with or equals
      * any of the packages in the {@code package.access} Security Property.
--- a/src/java.base/share/classes/java/lang/System.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/lang/System.java	Thu Jun 29 13:07:19 2017 -0700
@@ -47,6 +47,8 @@
 import java.security.PrivilegedAction;
 import java.nio.channels.Channel;
 import java.nio.channels.spi.SelectorProvider;
+import java.util.Iterator;
+import java.util.List;
 import java.util.Map;
 import java.util.Objects;
 import java.util.Properties;
@@ -2069,8 +2071,8 @@
     private static void setJavaLangAccess() {
         // Allow privileged classes outside of java.lang
         SharedSecrets.setJavaLangAccess(new JavaLangAccess() {
-            public Method getMethodOrNull(Class<?> klass, String name, Class<?>... parameterTypes) {
-                return klass.getMethodOrNull(name, parameterTypes);
+            public List<Method> getDeclaredPublicMethods(Class<?> klass, String name, Class<?>... parameterTypes) {
+                return klass.getDeclaredPublicMethods(name, parameterTypes);
             }
             public jdk.internal.reflect.ConstantPool getConstantPool(Class<?> klass) {
                 return klass.getConstantPool();
@@ -2094,7 +2096,7 @@
                 return Class.getExecutableTypeAnnotationBytes(executable);
             }
             public <E extends Enum<E>>
-                    E[] getEnumConstantsShared(Class<E> klass) {
+            E[] getEnumConstantsShared(Class<E> klass) {
                 return klass.getEnumConstantsShared();
             }
             public void blockedOn(Thread t, Interruptible b) {
@@ -2122,9 +2124,6 @@
             public Class<?> findBootstrapClassOrNull(ClassLoader cl, String name) {
                 return cl.findBootstrapClassOrNull(name);
             }
-            public Stream<Package> packages(ClassLoader cl) {
-                return cl.packages();
-            }
             public Package definePackage(ClassLoader cl, String name, Module module) {
                 return cl.definePackage(name, module);
             }
@@ -2163,9 +2162,18 @@
             public void addOpensToAllUnnamed(Module m, String pn) {
                 m.implAddOpensToAllUnnamed(pn);
             }
+            public void addOpensToAllUnnamed(Module m, Iterator<String> packages) {
+                m.implAddOpensToAllUnnamed(packages);
+            }
             public void addUses(Module m, Class<?> service) {
                 m.implAddUses(service);
             }
+            public boolean isReflectivelyExported(Module m, String pn, Module other) {
+                return m.isReflectivelyExported(pn, other);
+            }
+            public boolean isReflectivelyOpened(Module m, String pn, Module other) {
+                return m.isReflectivelyOpened(pn, other);
+            }
             public ServicesCatalog getServicesCatalog(ModuleLayer layer) {
                 return layer.getServicesCatalog();
             }
--- a/src/java.base/share/classes/java/lang/invoke/MethodHandles.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/lang/invoke/MethodHandles.java	Thu Jun 29 13:07:19 2017 -0700
@@ -212,7 +212,7 @@
         if (!callerModule.isNamed() && targetModule.isNamed()) {
             IllegalAccessLogger logger = IllegalAccessLogger.illegalAccessLogger();
             if (logger != null) {
-                logger.logIfOpenedByBackdoor(lookup, targetClass);
+                logger.logIfOpenedForIllegalAccess(lookup, targetClass);
             }
         }
         return new Lookup(targetClass);
--- a/src/java.base/share/classes/java/lang/invoke/VarHandle.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/lang/invoke/VarHandle.java	Thu Jun 29 13:07:19 2017 -0700
@@ -110,6 +110,20 @@
  * boolean r = avh.compareAndSet(sa, 10, "expected", "new");
  * }</pre>
  *
+ * <p>Access modes control atomicity and consistency properties.
+ * <em>Plain</em> read ({@code get}) and write ({@code set})
+ * accesses are guaranteed to be bitwise atomic only for references
+ * and for primitive values of at most 32 bits, and impose no observable
+ * ordering constraints with respect to threads other than the
+ * executing thread. <em>Opaque</em> operations are bitwise atomic and
+ * coherently ordered with respect to accesses to the same variable.
+ * In addition to obeying Opaque properties, <em>Acquire</em> mode
+ * reads and their subsequent accesses are ordered after matching
+ * <em>Release</em> mode writes and their previous accesses.  In
+ * addition to obeying Acquire and Release properties, all
+ * <em>Volatile</em> operations are totally ordered with respect to
+ * each other.
+ *
  * <p>Access modes are grouped into the following categories:
  * <ul>
  * <li>read access modes that get the value of a variable under specified
--- a/src/java.base/share/classes/java/lang/module/Configuration.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/lang/module/Configuration.java	Thu Jun 29 13:07:19 2017 -0700
@@ -43,11 +43,10 @@
 
 /**
  * A configuration that is the result of <a href="package-summary.html#resolution">
- * resolution</a> or resolution with <a href="package-summary.html#servicebinding">
- * service binding</a>.
+ * resolution</a> or resolution with <a href="#service-binding">service binding</a>.
  *
  * <p> A configuration encapsulates the <em>readability graph</em> that is the
- * output of resolution. A readability graph is a directed graph where the nodes
+ * output of resolution. A readability graph is a directed graph whose vertices
  * are of type {@link ResolvedModule} and the edges represent the readability
  * amongst the modules. {@code Configuration} defines the {@link #modules()
  * modules()} method to get the set of resolved modules in the graph. {@code
@@ -176,8 +175,8 @@
      *         If resolution fails for any of the observability-related reasons
      *         specified by the static {@code resolve} method
      * @throws ResolutionException
-     *         If any of the post-resolution consistency checks specified by
-     *         the  static {@code resolve} method fail
+     *         If resolution fails any of the consistency checks specified by
+     *         the static {@code resolve} method
      * @throws SecurityException
      *         If locating a module is denied by the security manager
      */
@@ -219,8 +218,8 @@
      *         If resolution fails for any of the observability-related reasons
      *         specified by the static {@code resolve} method
      * @throws ResolutionException
-     *         If any of the post-resolution consistency checks specified by
-     *         the  static {@code resolve} method fail
+     *         If resolution fails any of the consistency checks specified by
+     *         the static {@code resolve} method
      * @throws SecurityException
      *         If locating a module is denied by the security manager
      */
@@ -234,7 +233,7 @@
 
     /**
      * Resolves a collection of root modules, with service binding, and with
-     * the empty configuration as its parent. The post resolution checks
+     * the empty configuration as its parent. The consistency checks
      * are optionally run.
      *
      * This method is used to create the configuration for the boot layer.
@@ -264,10 +263,9 @@
      * or dependences that are located in a parent configuration are resolved
      * no further and are not included in the resulting configuration. </p>
      *
-     * <p> When all modules have been resolved then the resulting dependency
-     * graph is checked to ensure that it does not contain cycles. A
-     * readability graph is constructed, and in conjunction with the module
-     * exports and service use, checked for consistency. </p>
+     * <p> When all modules have been enumerated then a readability graph
+     * is computed, and in conjunction with the module exports and service use,
+     * checked for consistency. </p>
      *
      * <p> Resolution may fail with {@code FindException} for the following
      * <em>observability-related</em> reasons: </p>
@@ -284,8 +282,8 @@
      *
      * </ul>
      *
-     * <p> Post-resolution consistency checks may fail with {@code
-     * ResolutionException} for the following reasons: </p>
+     * <p> Resolution may fail with {@code ResolutionException} if any of the
+     * following consistency checks fail: </p>
      *
      * <ul>
      *
@@ -329,9 +327,11 @@
      *         root modules
      *
      * @throws FindException
-     *         If resolution fails for an observability-related reason
+     *         If resolution fails for any of observability-related reasons
+     *         specified above
      * @throws ResolutionException
-     *         If a post-resolution consistency checks fails
+     *         If resolution fails for any of the consistency checks specified
+     *         above
      * @throws IllegalArgumentException
      *         If the list of parents is empty, or the list has two or more
      *         parents with modules for different target operating systems,
@@ -368,11 +368,11 @@
      * resolve} except that the graph of resolved modules is augmented
      * with modules induced by the service-use dependence relation. </p>
      *
-     * <p> More specifically, the root modules are resolved as if by calling
-     * {@code resolve}. The resolved modules, and all modules in the
-     * parent configurations, with {@link ModuleDescriptor#uses() service
-     * dependences} are then examined. All modules found by the given module
-     * finders that {@link ModuleDescriptor#provides() provide} an
+     * <p id="service-binding"> More specifically, the root modules are
+     * resolved as if by calling {@code resolve}. The resolved modules, and
+     * all modules in the parent configurations, with {@link ModuleDescriptor#uses()
+     * service dependences} are then examined. All modules found by the given
+     * module finders that {@link ModuleDescriptor#provides() provide} an
      * implementation of one or more of the service types are added to the
      * module graph and then resolved as if by calling the {@code
      * resolve} method. Adding modules to the module graph may introduce new
@@ -402,8 +402,8 @@
      *         If resolution fails for any of the observability-related reasons
      *         specified by the static {@code resolve} method
      * @throws ResolutionException
-     *         If any of the post-resolution consistency checks specified by
-     *         the  static {@code resolve} method fail
+     *         If resolution fails any of the consistency checks specified by
+     *         the static {@code resolve} method
      * @throws IllegalArgumentException
      *         If the list of parents is empty, or the list has two or more
      *         parents with modules for different target operating systems,
--- a/src/java.base/share/classes/java/lang/module/ModuleFinder.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/lang/module/ModuleFinder.java	Thu Jun 29 13:07:19 2017 -0700
@@ -48,7 +48,7 @@
 /**
  * A finder of modules. A {@code ModuleFinder} is used to find modules during
  * <a href="package-summary.html#resolution">resolution</a> or
- * <a href="package-summary.html#servicebinding">service binding</a>.
+ * <a href="Configuration.html#service-binding">service binding</a>.
  *
  * <p> A {@code ModuleFinder} can only find one module with a given name. A
  * {@code ModuleFinder} that finds modules in a sequence of directories, for
@@ -239,30 +239,35 @@
      *
      * <ul>
      *
-     *     <li><p> The module {@link ModuleDescriptor#name() name}, and {@link
-     *     ModuleDescriptor#version() version} if applicable, is derived from
-     *     the file name of the JAR file as follows: </p>
+     *     <li><p> If the JAR file has the attribute "{@code Automatic-Module-Name}"
+     *     in its main manifest then its value is the {@linkplain
+     *     ModuleDescriptor#name() module name}. The module name is otherwise
+     *     derived from the name of the JAR file. </p></li>
+     *
+     *     <li><p> The {@link ModuleDescriptor#version() version}, and the
+     *     module name when the attribute "{@code Automatic-Module-Name}" is not
+     *     present, are derived from the file name of the JAR file as follows: </p>
      *
      *     <ul>
      *
-     *         <li><p> The {@code .jar} suffix is removed. </p></li>
+     *         <li><p> The "{@code .jar}" suffix is removed. </p></li>
      *
      *         <li><p> If the name matches the regular expression {@code
      *         "-(\\d+(\\.|$))"} then the module name will be derived from the
      *         subsequence preceding the hyphen of the first occurrence. The
      *         subsequence after the hyphen is parsed as a {@link
-     *         ModuleDescriptor.Version} and ignored if it cannot be parsed as
-     *         a {@code Version}. </p></li>
+     *         ModuleDescriptor.Version Version} and ignored if it cannot be
+     *         parsed as a {@code Version}. </p></li>
      *
      *         <li><p> All non-alphanumeric characters ({@code [^A-Za-z0-9]})
      *         in the module name are replaced with a dot ({@code "."}), all
      *         repeating dots are replaced with one dot, and all leading and
      *         trailing dots are removed. </p></li>
      *
-     *         <li><p> As an example, a JAR file named {@code foo-bar.jar} will
-     *         derive a module name {@code foo.bar} and no version. A JAR file
-     *         named {@code foo-bar-1.2.3-SNAPSHOT.jar} will derive a module
-     *         name {@code foo.bar} and {@code 1.2.3-SNAPSHOT} as the version.
+     *         <li><p> As an example, a JAR file named "{@code foo-bar.jar}" will
+     *         derive a module name "{@code foo.bar}" and no version. A JAR file
+     *         named "{@code foo-bar-1.2.3-SNAPSHOT.jar}" will derive a module
+     *         name "{@code foo.bar}" and "{@code 1.2.3-SNAPSHOT}" as the version.
      *         </p></li>
      *
      *     </ul></li>
@@ -295,11 +300,12 @@
      * <p> If a {@code ModuleDescriptor} cannot be created (by means of the
      * {@link ModuleDescriptor.Builder ModuleDescriptor.Builder} API) for an
      * automatic module then {@code FindException} is thrown. This can arise
-     * when a legal module name cannot be derived from the file name of the JAR
-     * file, where the JAR file contains a {@code .class} in the top-level
-     * directory of the JAR file, where an entry in a service configuration
-     * file is not a legal class name or its package name is not in the set of
-     * packages derived for the module. </p>
+     * when the value of the "{@code Automatic-Module-Name}" attribute is not a
+     * legal module name, a legal module name cannot be derived from the file
+     * name of the JAR file, where the JAR file contains a {@code .class} in
+     * the top-level directory of the JAR file, where an entry in a service
+     * configuration file is not a legal class name or its package name is not
+     * in the set of packages derived for the module. </p>
      *
      * <p> In addition to JAR files, an implementation may also support modules
      * that are packaged in other implementation specific module formats. If
--- a/src/java.base/share/classes/java/lang/module/package-info.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/lang/module/package-info.java	Thu Jun 29 13:07:19 2017 -0700
@@ -27,118 +27,185 @@
  * Classes to support module descriptors and creating configurations of modules
  * by means of resolution and service binding.
  *
- * <h2><a id="resolution">Resolution</a></h2>
- *
- * <p> Resolution is the process of computing the transitive closure of a set
- * of root modules over a set of observable modules by resolving the
- * dependences expressed by {@link
- * java.lang.module.ModuleDescriptor.Requires requires} clauses.
- * The <em>dependence graph</em> is augmented with edges that take account of
- * implicitly declared dependences ({@code requires transitive}) to create a
- * <em>readability graph</em>. The result of resolution is a {@link
- * java.lang.module.Configuration Configuration} that encapsulates the
- * readability graph. </p>
- *
- * <p> As an example, suppose we have the following observable modules: </p>
- * <pre> {@code
- *     module m1 { requires m2; }
- *     module m2 { requires transitive m3; }
- *     module m3 { }
- *     module m4 { }
- * } </pre>
- *
- * <p> If the module {@code m1} is resolved then the resulting configuration
- * contains three modules ({@code m1}, {@code m2}, {@code m3}). The edges in
- * its readability graph are: </p>
- * <pre> {@code
- *     m1 --> m2  (meaning m1 reads m2)
- *     m1 --> m3
- *     m2 --> m3
- * } </pre>
- *
- * <p> Resolution is an additive process. When computing the transitive closure
- * then the dependence relation may include dependences on modules in {@link
- * java.lang.module.Configuration#parents() parent} configurations. The result
- * is a <em>relative configuration</em> that is relative to one or more parent
- * configurations and where the readability graph may have edges from modules
- * in the configuration to modules in parent configurations. </p>
- *
- * <p> As an example, suppose we have the following observable modules: </p>
- * <pre> {@code
- *     module m1 { requires m2; requires java.xml; }
- *     module m2 { }
- * } </pre>
- *
- * <p> If module {@code m1} is resolved with the configuration for the {@link
- * java.lang.ModuleLayer#boot() boot} layer as the parent then the resulting
- * configuration contains two modules ({@code m1}, {@code m2}). The edges in
- * its readability graph are:
- * <pre> {@code
- *     m1 --> m2
- *     m1 --> java.xml
- * } </pre>
- * where module {@code java.xml} is in the parent configuration. For
- * simplicity, this example omits the implicitly declared dependence on the
- * {@code java.base} module.
- *
- * <p> Requires clauses that are "{@code requires static}" express an optional
- * dependence (except at compile-time). If a module declares that it
- * "{@code requires static M}" then resolution does not search the observable
- * modules for "{@code M}". However, if "{@code M}" is resolved (because resolution
- * resolves a module that requires "{@code M}" without the {@link
- * java.lang.module.ModuleDescriptor.Requires.Modifier#STATIC static} modifier)
- * then the readability graph will contain read edges for each module that
- * "{@code requires static M}". </p>
- *
- * <p> {@link java.lang.module.ModuleDescriptor#isAutomatic() Automatic} modules
- * receive special treatment during resolution. Each automatic module is resolved
- * as if it "{@code requires transitive}" all observable automatic modules and
- * all automatic modules in the parent configurations. Each automatic module is
- * resolved so that it reads all other modules in the resulting configuration and
- * all modules in parent configurations. </p>
- *
- * <h2><a id="servicebinding">Service binding</a></h2>
- *
- * <p> Service binding is the process of augmenting a graph of resolved modules
- * from the set of observable modules induced by the service-use dependence
- * ({@code uses} and {@code provides} clauses). Any module that was not
- * previously in the graph requires resolution to compute its transitive
- * closure. Service binding is an iterative process in that adding a module
- * that satisfies some service-use dependence may introduce new service-use
- * dependences. </p>
- *
- * <p> Suppose we have the following observable modules: </p>
- * <pre> {@code
- *     module m1 { exports p; uses p.S; }
- *     module m2 { requires m1; provides p.S with p2.S2; }
- *     module m3 { requires m1; requires m4; provides p.S with p3.S3; }
- *     module m4 { }
- * } </pre>
- *
- * <p> If the module {@code m1} is resolved then the resulting graph of modules
- * has one module ({@code m1}). If the graph is augmented with modules induced
- * by the service-use dependence relation then the configuration will contain
- * four modules ({@code m1}, {@code m2}, {@code m3}, {@code m4}). The edges in
- * its readability graph are: </p>
- * <pre> {@code
- *     m2 --> m1
- *     m3 --> m1
- *     m3 --> m4
- * } </pre>
- * <p> The edges in the conceptual service-use graph are: </p>
- * <pre> {@code
- *     m1 --> m2  (meaning m1 uses a service that is provided by m2)
- *     m1 --> m3
- * } </pre>
- *
- * <h2>General Exceptions</h2>
- *
  * <p> Unless otherwise noted, passing a {@code null} argument to a constructor
  * or method of any class or interface in this package will cause a {@link
  * java.lang.NullPointerException NullPointerException} to be thrown. Additionally,
  * invoking a method with an array or collection containing a {@code null} element
  * will cause a {@code NullPointerException}, unless otherwise specified. </p>
  *
+ *
+ * <h1><a id="resolution">Resolution</a></h1>
+ *
+ * <p> Resolution is the process of computing how modules depend on each other.
+ * The process occurs at compile time and run time. </p>
+ *
+ * <p> Resolution is a two-step process. The first step recursively enumerates
+ * the 'requires' directives of a set of root modules. If all the enumerated
+ * modules are observable, then the second step computes their readability graph.
+ * The readability graph embodies how modules depend on each other, which in
+ * turn controls access across module boundaries. </p>
+ *
+ * <h2> Step 1: Recursive enumeration </h2>
+ *
+ * <p> Recursive enumeration takes a set of module names, looks up each of their
+ * module declarations, and for each module declaration, recursively enumerates:
+ *
+ * <ul>
+ *   <li> <p> the module names given by the 'requires' directives with the
+ *   'transitive' modifier, and </p></li>
+ *   <li> <p> at the discretion of the host system, the module names given by
+ *   the 'requires' directives without the 'transitive' modifier. </p></li>
+ * </ul>
+ *
+ * <p> Module declarations are looked up in a set of observable modules. The set
+ * of observable modules is determined in an implementation specific manner. The
+ * set of observable modules may include modules with explicit declarations
+ * (that is, with a {@code module-info.java} source file or {@code module-info.class}
+ * file) and modules with implicit declarations (that is,
+ * <a href="ModuleFinder.html#automatic-modules">automatic modules</a>).
+ * Because an automatic module has no explicit module declaration, it has no
+ * 'requires' directives of its own, although its name may be given by a
+ * 'requires' directive of an explicit module declaration. </p>
+
+ * <p> The set of root modules, whose names are the initial input to this
+ * algorithm, is determined in an implementation specific manner. The set of
+ * root modules may include automatic modules. </p>
+ *
+ * <p> If at least one automatic module is enumerated by this algorithm, then
+ * every observable automatic module must be enumerated, regardless of whether
+ * any of their names are given by 'requires' directives of explicit module
+ * declarations. </p>
+ *
+ * <p> If any of the following conditions occur, then resolution fails:
+ * <ul>
+ *   <li><p> Any root module is not observable. </p></li>
+ *   <li><p> Any module whose name is given by a 'requires' directive with the
+ *   'transitive' modifier is not observable. </p></li>
+ *   <li><p> At the discretion of the host system, any module whose name is given
+ *   by a 'requires' directive without the 'transitive' modifier is not
+ *   observable. </p></li>
+ *   <li><p> The algorithm in this step enumerates the same module name twice. This
+ *   indicates a cycle in the 'requires' directives, disregarding any 'transitive'
+ *   modifiers. </p></li>
+ * </ul>
+ *
+ * <p> Otherwise, resolution proceeds to step 2. </p>
+ *
+ * <h2> Step 2: Computing the readability graph </h2>
+ *
+ * <p> A 'requires' directive (irrespective of 'transitive') expresses that
+ * one module depends on some other module. The effect of the 'transitive'
+ * modifier is to cause additional modules to also depend on the other module.
+ * If module M 'requires transitive N', then not only does M depend on N, but
+ * any module that depends on M also depends on N. This allows M to be
+ * refactored so that some or all of its content can be moved to a new module N
+ * without breaking modules that have a 'requires M' directive. </p>
+ *
+ * <p> Module dependencies are represented by the readability graph. The
+ * readability graph is a directed graph whose vertices are the modules
+ * enumerated in step 1 and whose edges represent readability between pairs of
+ * modules. The edges are specified as follows:
+ *
+ * <p> First, readability is determined by the 'requires' directives of the
+ * enumerated modules, disregarding any 'transitive' modifiers:
+ *
+ * <ul>
+ *   <li><p> For each enumerated module A that 'requires' B: A "reads" B. </p></li>
+ *   <li><p> For each enumerated module X that is automatic: X "reads" every
+ *   other enumerated module (it is "as if" an automatic module has 'requires'
+ *   directives for every other enumerated module). </p></li>
+ * </ul>
+ *
+ * <p> Second, readability is augmented to account for 'transitive' modifiers:
+ * <ul>
+ *   <li> <p> For each enumerated module A that "reads" B: </p>
+ *     <ul>
+ *     <li><p> If B 'requires transitive' C, then A "reads" C as well as B. This
+ *     augmentation is recursive: since A "reads" C, if C 'requires transitive'
+ *     D, then A "reads" D as well as C and B. </p></li>
+ *     <li><p> If B is an automatic module, then A "reads" every other enumerated
+ *     automatic module. (It is "as if" an automatic module has 'requires transitive'
+ *     directives for every other enumerated automatic module).</p> </li>
+ *     </ul>
+ *   </li>
+ * </ul>
+ *
+ * <p> Finally, every module "reads" itself. </p>
+ *
+ * <p> If any of the following conditions occur in the readability graph, then
+ * resolution fails:
+ * <ul>
+ *   <li><p> A module "reads" two or more modules with the same name. This includes
+ *   the case where a module "reads" another with the same name as itself. </p></li>
+ *   <li><p> Two or more modules export a package with the same name to a module
+ *   that "reads" both. This includes the case where a module M containing package
+ *   p "reads" another module that exports p to M. </p></li>
+ *   <li><p> A module M declares that it 'uses p.S' or 'provides p.S with ...' but
+ *   package p is neither in module M nor exported to M by any module that M
+ *   "reads". </p></li>
+ * </ul>
+ * <p> Otherwise, resolution succeeds, and the result of resolution is the
+ * readability graph.
+ *
+ * <h2> Root modules </h2>
+ *
+ * <p> The set of root modules at compile-time is usually the set of modules
+ * being compiled. At run-time, the set of root modules is usually the
+ * application module specified to the 'java' launcher. When compiling code in
+ * the unnamed module, or at run-time when the main application class is loaded
+ * from the class path, then the default set of root modules is implementation
+ * specific (In the JDK implementation it is the module "java.se", if observable,
+ * and every observable module that exports an API). </p>
+ *
+ * <h2> Observable modules </h2>
+ *
+ * <p> The set of observable modules at both compile-time and run-time is
+ * determined by searching several different paths, and also by searching
+ * the compiled modules built in to the environment. The search order is as
+ * follows: </p>
+ *
+ * <ol>
+ *   <li><p> At compile time only, the compilation module path. This path
+ *   contains module definitions in source form.  </p></li>
+ *
+ *   <li><p> The upgrade module path. This path contains compiled definitions of
+ *   modules that will be observed in preference to the compiled definitions of
+ *   any <i>upgradeable modules</i> that are present in (3) and (4). See the Java
+ *   SE Platform for the designation of which standard modules are upgradeable.
+ *   </p></li>
+ *
+ *   <li><p> The system modules, which are the compiled definitions built in to
+ *   the environment. </p></li>
+ *
+ *   <li><p> The application module path. This path contains compiled definitions
+ *   of library and application modules. </p></li>
+ *
+ * </ol>
+ *
+ * <h2> 'requires' directives with 'static' modifier </h2>
+ *
+ * <p> 'requires' directives that have the 'static' modifier express an optional
+ * dependence at run time. If a module declares that it 'requires static M' then
+ * resolution does not search the observable modules for M to satisfy the dependency.
+ * However, if M is recursively enumerated at step 1 then all modules that are
+ * enumerated and `requires static M` will read M. </p>
+ *
+ * <h2> Completeness </h2>
+ *
+ * <p> Resolution may be partial at compile-time in that the complete transitive
+ * closure may not be required to compile a set of modules. Minimally, the
+ * readability graph that is constructed and validated at compile-time includes
+ * the modules being compiled, their direct dependences, and all implicitly
+ * declared dependences (requires transitive). </p>
+ *
+ * <p> At run-time, resolution is an additive process. The recursive enumeration
+ * at step 1 may be relative to previous resolutions so that a root module,
+ * or a module named in a 'requires' directive, is not enumerated when it was
+ * enumerated by a previous (or parent) resolution. The readability graph that
+ * is the result of resolution may therefore have a vertex for a module enumerated
+ * in step 1 but with an edge to represent that the module reads a module that
+ * was enumerated by previous (or parent) resolution. </p>
+ *
  * @since 9
  * @spec JPMS
  */
--- a/src/java.base/share/classes/java/lang/reflect/AccessibleObject.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/lang/reflect/AccessibleObject.java	Thu Jun 29 13:07:19 2017 -0700
@@ -304,7 +304,7 @@
         if (isClassPublic && declaringModule.isExported(pn, callerModule)) {
             // member is public
             if (Modifier.isPublic(modifiers)) {
-                logIfExportedByBackdoor(caller, declaringClass);
+                logIfExportedForIllegalAccess(caller, declaringClass);
                 return true;
             }
 
@@ -312,14 +312,14 @@
             if (Modifier.isProtected(modifiers)
                 && Modifier.isStatic(modifiers)
                 && isSubclassOf(caller, declaringClass)) {
-                logIfExportedByBackdoor(caller, declaringClass);
+                logIfExportedForIllegalAccess(caller, declaringClass);
                 return true;
             }
         }
 
         // package is open to caller
         if (declaringModule.isOpen(pn, callerModule)) {
-            logIfOpenedByBackdoor(caller, declaringClass);
+            logIfOpenedForIllegalAccess(caller, declaringClass);
             return true;
         }
 
@@ -353,26 +353,26 @@
         return false;
     }
 
-    private void logIfOpenedByBackdoor(Class<?> caller, Class<?> declaringClass) {
+    private void logIfOpenedForIllegalAccess(Class<?> caller, Class<?> declaringClass) {
         Module callerModule = caller.getModule();
         Module targetModule = declaringClass.getModule();
         // callerModule is null during early startup
         if (callerModule != null && !callerModule.isNamed() && targetModule.isNamed()) {
             IllegalAccessLogger logger = IllegalAccessLogger.illegalAccessLogger();
             if (logger != null) {
-                logger.logIfOpenedByBackdoor(caller, declaringClass, this::toShortString);
+                logger.logIfOpenedForIllegalAccess(caller, declaringClass, this::toShortString);
             }
         }
     }
 
-    private void logIfExportedByBackdoor(Class<?> caller, Class<?> declaringClass) {
+    private void logIfExportedForIllegalAccess(Class<?> caller, Class<?> declaringClass) {
         Module callerModule = caller.getModule();
         Module targetModule = declaringClass.getModule();
         // callerModule is null during early startup
         if (callerModule != null && !callerModule.isNamed() && targetModule.isNamed()) {
             IllegalAccessLogger logger = IllegalAccessLogger.illegalAccessLogger();
             if (logger != null) {
-                logger.logIfExportedByBackdoor(caller, declaringClass, this::toShortString);
+                logger.logIfExportedForIllegalAccess(caller, declaringClass, this::toShortString);
             }
         }
     }
@@ -634,7 +634,7 @@
         }
 
         // access okay
-        logIfExportedByBackdoor(caller, memberClass);
+        logIfExportedForIllegalAccess(caller, memberClass);
 
         // Success: Update the cache.
         Object cache = (targetClass != null
--- a/src/java.base/share/classes/java/lang/reflect/MalformedParameterizedTypeException.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/lang/reflect/MalformedParameterizedTypeException.java	Thu Jun 29 13:07:19 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2008, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 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
@@ -36,4 +36,21 @@
  */
 public class MalformedParameterizedTypeException extends RuntimeException {
     private static final long serialVersionUID = -5696557788586220964L;
+
+    /**
+     * Constructs a {@code MalformedParameterizedTypeException} with
+     * no detail message.
+     */
+    public MalformedParameterizedTypeException() {
+        super();
+    }
+
+    /**
+     * Constructs a {@code MalformedParameterizedTypeException} with
+     * the given detail message.
+     * @param message the detail message; may be {@code null}
+     */
+    public MalformedParameterizedTypeException(String message) {
+        super(message);
+    }
 }
--- a/src/java.base/share/classes/java/security/AlgorithmParameterGenerator.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/security/AlgorithmParameterGenerator.java	Thu Jun 29 13:07:19 2017 -0700
@@ -64,8 +64,7 @@
  * AlgorithmParameterGenerator (via a call to an {@code init} method),
  * each provider must supply (and document) a default initialization.
  * See the Keysize Restriction sections of the
- * <a href="{@docRoot}/../technotes/guides/security/SunProviders.html">
- * JDK Providers</a>
+ * {@extLink security_guide_jdk_providers JDK Providers}
  * document for information on the AlgorithmParameterGenerator defaults
  * used by JDK providers.
  * However, note that defaults may vary across different providers.
--- a/src/java.base/share/classes/java/security/AlgorithmParameterGeneratorSpi.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/security/AlgorithmParameterGeneratorSpi.java	Thu Jun 29 13:07:19 2017 -0700
@@ -40,8 +40,7 @@
  * AlgorithmParameterGenerator (via a call to an {@code engineInit}
  * method), each provider must supply (and document) a default initialization.
  * See the Keysize Restriction sections of the
- * <a href="{@docRoot}/../technotes/guides/security/SunProviders.html">
- * JDK Providers</a>
+ * {@extLink security_guide_jdk_providers JDK Providers}
  * document for information on the AlgorithmParameterGenerator defaults
  * used by JDK providers.
  * However, note that defaults may vary across different providers.
--- a/src/java.base/share/classes/java/security/Key.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/security/Key.java	Thu Jun 29 13:07:19 2017 -0700
@@ -114,10 +114,10 @@
     /**
      * Returns the standard algorithm name for this key. For
      * example, "DSA" would indicate that this key is a DSA key.
-     * See Appendix A in the <a href=
-     * "../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">
-     * Java Cryptography Architecture API Specification &amp; Reference </a>
-     * for information about standard algorithm names.
+     * See the <a href=
+     * "{@docRoot}/../specs/security/standard-names.html">
+     * Java Security Standard Algorithm Names</a> document
+     * for more information.
      *
      * @return the name of the algorithm associated with this key.
      */
--- a/src/java.base/share/classes/java/security/KeyPairGenerator.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/security/KeyPairGenerator.java	Thu Jun 29 13:07:19 2017 -0700
@@ -96,8 +96,7 @@
  * (via a call to an {@code initialize} method), each provider must
  * supply (and document) a default initialization.
  * See the Keysize Restriction sections of the
- * <a href="{@docRoot}/../technotes/guides/security/SunProviders.html">
- * JDK Providers</a>
+ * {@extLink security_guide_jdk_providers JDK Providers}
  * document for information on the KeyPairGenerator defaults used by
  * JDK providers.
  * However, note that defaults may vary across different providers.
--- a/src/java.base/share/classes/java/security/KeyPairGeneratorSpi.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/security/KeyPairGeneratorSpi.java	Thu Jun 29 13:07:19 2017 -0700
@@ -40,8 +40,7 @@
  * (via a call to an {@code initialize} method), each provider must
  * supply (and document) a default initialization.
  * See the Keysize Restriction sections of the
- * <a href="{@docRoot}/../technotes/guides/security/SunProviders.html">
- * JDK Providers</a>
+ * {@extLink security_guide_jdk_providers JDK Providers}
  * document for information on the KeyPairGenerator defaults used by
  * JDK providers.
  * However, note that defaults may vary across different providers.
--- a/src/java.base/share/classes/java/security/Provider.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/security/Provider.java	Thu Jun 29 13:07:19 2017 -0700
@@ -94,9 +94,9 @@
  * The JDK implementation supports static registration of the security
  * providers via the {@code conf/security/java.security} file in the Java
  * installation directory. These providers are automatically installed by
- * the JDK runtime, see <a href =
- * "../../../technotes/guides/security/crypto/CryptoSpec.html#Provider">The Provider Class</a>
- * in the "Java Cryptography Architecture API Specification &amp; Reference"
+ * the JDK runtime, see {@extLink security_guide_jca_provider
+ * The Provider Class}
+ * in the Java Cryptography Architecture (JCA) Reference Guide
  * for information about how a particular type of provider, the cryptographic
  * service provider, works and is installed.
  *
@@ -1310,8 +1310,8 @@
      * it is replaced by the new service.
      * This method also places information about this service
      * in the provider's Hashtable values in the format described in the
-     * <a href="../../../technotes/guides/security/crypto/CryptoSpec.html">
-     * Java Cryptography Architecture API Specification &amp; Reference </a>.
+     * {@extLink security_guide_jca
+     * Java Cryptography Architecture (JCA) Reference Guide}.
      *
      * <p>Also, if there is a security manager, its
      * {@code checkSecurityAccess} method is called with the string
@@ -1593,8 +1593,8 @@
      * suitable services and instantiates them. The valid arguments to those
      * methods depend on the type of service. For the service types defined
      * within Java SE, see the
-     * <a href="../../../technotes/guides/security/crypto/CryptoSpec.html">
-     * Java Cryptography Architecture API Specification &amp; Reference </a>
+     * {@extLink security_guide_jca
+     * Java Cryptography Architecture (JCA) Reference Guide}
      * for the valid values.
      * Note that components outside of Java SE can define additional types of
      * services and their behavior.
@@ -1769,9 +1769,8 @@
          * instantiation in a different way.
          * For details and the values of constructorParameter that are
          * valid for the various types of services see the
-         * <a href="../../../technotes/guides/security/crypto/CryptoSpec.html">
-         * Java Cryptography Architecture API Specification &amp;
-         * Reference</a>.
+         * {@extLink security_guide_jca
+         * Java Cryptography Architecture (JCA) Reference Guide}.
          *
          * @param constructorParameter the value to pass to the constructor,
          * or null if this type of service does not use a constructorParameter.
@@ -1878,9 +1877,8 @@
          *
          * <p>For details and the values of parameter that are valid for the
          * various types of services see the top of this class and the
-         * <a href="../../../technotes/guides/security/crypto/CryptoSpec.html">
-         * Java Cryptography Architecture API Specification &amp;
-         * Reference</a>.
+         * {@extLink security_guide_jca
+         * Java Cryptography Architecture (JCA) Reference Guide}.
          * Security providers can override it to implement their own test.
          *
          * @param parameter the parameter to test
--- a/src/java.base/share/classes/java/security/Security.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/security/Security.java	Thu Jun 29 13:07:19 2017 -0700
@@ -1041,8 +1041,8 @@
      * an empty Set if there is no provider that supports the
      * specified service or if serviceName is null. For a complete list
      * of Java cryptographic services, please see the
-     * <a href="../../../technotes/guides/security/crypto/CryptoSpec.html">Java
-     * Cryptography Architecture API Specification &amp; Reference</a>.
+     * {@extLink security_guide_jca
+     * Java Cryptography Architecture (JCA) Reference Guide}.
      * Note: the returned set is immutable.
      *
      * @param serviceName the name of the Java cryptographic
--- a/src/java.base/share/classes/java/security/cert/CRL.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/security/cert/CRL.java	Thu Jun 29 13:07:19 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 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
@@ -52,9 +52,9 @@
      * Creates a CRL of the specified type.
      *
      * @param type the standard name of the CRL type.
-     * See Appendix A in the <a href=
-     * "../../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">
-     * Java Cryptography Architecture API Specification &amp; Reference </a>
+     * See the <a href=
+     * "{@docRoot}/../specs/security/standard-names.html">
+     * Java Security Standard Algorithm Names</a> document
      * for information about standard CRL types.
      */
     protected CRL(String type) {
--- a/src/java.base/share/classes/java/security/cert/package-info.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/security/cert/package-info.java	Thu Jun 29 13:07:19 2017 -0700
@@ -32,15 +32,14 @@
  * <h2>Package Specification</h2>
  *
  * <ul>
- *   <li><a href="{@docRoot}/../technotes/guides/security/crypto/CryptoSpec.html">
- *     <b>Java&trade;
- *     Cryptography Architecture (JCA) Reference Guide</b></a>
+ *   <li>{@extLink security_guide_jca
+ *     Java Cryptography Architecture (JCA) Reference Guide}
  *   <li>RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
  *     Certificate Revocation List (CRL) Profile
  *   <li>RFC 2560: X.509 Internet Public Key Infrastructure Online Certificate
  *     Status Protocol - OCSP
  *   <li><a href="{@docRoot}/../specs/security/standard-names.html">
- *     <b>Java&trade; Security Standard Algorithm Names Specification
+ *     <b>Java Security Standard Algorithm Names Specification
  *     </b></a></li>
  * </ul>
  *
@@ -50,12 +49,7 @@
  * <ul>
  *   <li><a href="http://www.ietf.org/rfc/rfc5280.txt">
  *     http://www.ietf.org/rfc/rfc5280.txt</a>
- *   <li><a href=
- *     "{@docRoot}/../technotes/guides/security/certpath/CertPathProgGuide.html">
- *     <b>Java&trade;
- *     PKI Programmer's Guide</b></a>
- *   <li><a href="{@docRoot}/../technotes/guides/security/cert3.html">
- *     <b>X.509 Certificates and Certificate Revocation Lists (CRLs)</b></a>
+ *   <li> {@extLink security_guide_pki Java PKI Programmer's Guide}
  * </ul>
  *
  * @since 1.2
--- a/src/java.base/share/classes/java/security/interfaces/package-info.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/security/interfaces/package-info.java	Thu Jun 29 13:07:19 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 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
@@ -42,11 +42,10 @@
  * {@code Key} classes for hardware devices, please refer
  * to these cryptographic provider developer guides:
  * <ul>
- *   <li><a href=
- *     "{@docRoot}/../technotes/guides/security/crypto/HowToImplAProvider.html">
- *     <b>How to Implement a Provider for the
- *     Java&trade; Cryptography Architecture
- *     </b></a></li>
+ *   <li>
+ *     {@extLink security_guide_impl_provider
+ *       How to Implement a Provider in the Java Cryptography Architecture}
+ *   </li>
  * </ul>
  *
  * <h2>Package Specification</h2>
@@ -61,12 +60,8 @@
  *
  * For further documentation, please see:
  * <ul>
- *   <li>
- *     <a href=
- *       "{@docRoot}/../technotes/guides/security/crypto/CryptoSpec.html">
- *       <b>Java&trade;
- *       Cryptography Architecture API Specification and Reference
- *       </b></a></li>
+ *   <li> {extLink security_guide_jca
+ *       Java Cryptography Architecture Reference Guide}</li>
  * </ul>
  *
  * @since 1.1
--- a/src/java.base/share/classes/java/security/package-info.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/security/package-info.java	Thu Jun 29 13:07:19 2017 -0700
@@ -46,63 +46,36 @@
  * <h2>Package Specification</h2>
  *
  * <ul>
- *   <li><a href="{@docRoot}/../technotes/guides/security/crypto/CryptoSpec.html">
- *     <b>Java&trade;
- *     Cryptography Architecture (JCA) Reference Guide</b></a></li>
+ *   <li> {@extLink security_guide_jca
+ *     Java Cryptography Architecture (JCA) Reference Guide}</li>
  *
  *   <li>PKCS #8: Private-Key Information Syntax Standard, Version 1.2,
  *     November 1993</li>
  *
  *   <li><a href="{@docRoot}/../specs/security/standard-names.html">
- *     <b>Java&trade; Security Standard Algorithm Names Specification
- *     </b></a></li>
+ *     Java Security Standard Algorithm Names Specification
+ *     </a></li>
  * </ul>
  *
  * <h2>Related Documentation</h2>
  *
  * For further documentation, please see:
  * <ul>
- *   <li><a href=
- *     "{@docRoot}/../technotes/guides/security/spec/security-spec.doc.html">
- *     <b>Java&trade;
- *     SE Platform Security Architecture</b></a></li>
+ *   <li> {@extLink security_guide_overview
+ *     Java Security Overview} </li>
  *
- *   <li><a href=
- *     "{@docRoot}/../technotes/guides/security/crypto/HowToImplAProvider.html">
- *     <b>How to Implement a Provider in the
- *     Java&trade; Cryptography Architecture
- *     </b></a></li>
+ *   <li> {@extLink security_guide_impl_provider
+ *     How to Implement a Provider in the Java Cryptography Architecture}</li>
  *
- *   <li><a href=
- *     "{@docRoot}/../technotes/guides/security/PolicyFiles.html"><b>
- *     Default Policy Implementation and Policy File Syntax
- *     </b></a></li>
+ *   <li> {@extLink security_guide_default_policy
+ *     Default Policy Implementation and Policy File Syntax}</li>
  *
- *   <li><a href=
- *     "{@docRoot}/../technotes/guides/security/permissions.html"><b>
- *     Permissions in the
- *     Java&trade; SE Development Kit (JDK)
- *     </b></a></li>
+ *   <li> {@extLink security_guide_permissions
+ *     Permissions in the Java Development Kit (JDK)}</li>
  *
- *   <li><a href=
- *     "{@docRoot}/../technotes/guides/security/SecurityToolsSummary.html"><b>
- *     Summary of Tools for
- *     Java&trade; Platform Security
- *     </b></a></li>
- *
- *   <li><b>keytool</b>
- *     (<a href="{@docRoot}/../technotes/tools/unix/keytool.html">
- *       for Solaris/Linux</a>)
- *     (<a href="{@docRoot}/../technotes/tools/windows/keytool.html">
- *       for Windows</a>)
- *     </li>
- *
- *   <li><b>jarsigner</b>
- *     (<a href="{@docRoot}/../technotes/tools/unix/jarsigner.html">
- *       for Solaris/Linux</a>)
- *     (<a href="{@docRoot}/../technotes/tools/windows/jarsigner.html">
- *       for Windows</a>)
- *     </li>
+ *   <li> {@extLink security_guide_tools
+ *     Summary of Tools for Java Platform Security}
+ *     (for example {@code keytool} and {@code jarsigner}),</li>
  *
  * </ul>
  *
--- a/src/java.base/share/classes/java/security/spec/package-info.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/security/spec/package-info.java	Thu Jun 29 13:07:19 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 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
@@ -54,18 +54,10 @@
  * For documentation that includes information about algorithm parameter
  * and key specifications, please see:
  * <ul>
- *   <li>
- *     <a href=
- *       "{@docRoot}/../technotes/guides/security/crypto/CryptoSpec.html">
- *       <b>Java&trade;
- *       Cryptography Architecture API Specification and Reference
- *       </b></a></li>
- *   <li>
- *     <a href=
- *       "{@docRoot}/../technotes/guides/security/crypto/HowToImplAProvider.html">
- *       <b>How to Implement a Provider for the
- *       Java&trade; Cryptography Architecture
- *       </b></a></li>
+ *   <li> {@extLink security_guide_jca
+ *       Java Cryptography Architecture (JCA) Reference Guide}</li>
+ *   <li> {@extLink security_guide_impl_provider
+ *       How to Implement a Provider in the Java Cryptography Architecture}</li>
  * </ul>
  *
  * @since 1.2
--- a/src/java.base/share/classes/java/util/Deque.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/util/Deque.java	Thu Jun 29 13:07:19 2017 -0700
@@ -72,24 +72,24 @@
  *  </tr>
  *  <tr>
  *    <td><b>Insert</b></td>
- *    <td>{@link Deque#addFirst addFirst(e)}</td>
- *    <td>{@link Deque#offerFirst offerFirst(e)}</td>
- *    <td>{@link Deque#addLast addLast(e)}</td>
- *    <td>{@link Deque#offerLast offerLast(e)}</td>
+ *    <td>{@link #addFirst(Object) addFirst(e)}</td>
+ *    <td>{@link #offerFirst(Object) offerFirst(e)}</td>
+ *    <td>{@link #addLast(Object) addLast(e)}</td>
+ *    <td>{@link #offerLast(Object) offerLast(e)}</td>
  *  </tr>
  *  <tr>
  *    <td><b>Remove</b></td>
- *    <td>{@link Deque#removeFirst removeFirst()}</td>
- *    <td>{@link Deque#pollFirst pollFirst()}</td>
- *    <td>{@link Deque#removeLast removeLast()}</td>
- *    <td>{@link Deque#pollLast pollLast()}</td>
+ *    <td>{@link #removeFirst() removeFirst()}</td>
+ *    <td>{@link #pollFirst() pollFirst()}</td>
+ *    <td>{@link #removeLast() removeLast()}</td>
+ *    <td>{@link #pollLast() pollLast()}</td>
  *  </tr>
  *  <tr>
  *    <td><b>Examine</b></td>
- *    <td>{@link Deque#getFirst getFirst()}</td>
- *    <td>{@link Deque#peekFirst peekFirst()}</td>
- *    <td>{@link Deque#getLast getLast()}</td>
- *    <td>{@link Deque#peekLast peekLast()}</td>
+ *    <td>{@link #getFirst() getFirst()}</td>
+ *    <td>{@link #peekFirst() peekFirst()}</td>
+ *    <td>{@link #getLast() getLast()}</td>
+ *    <td>{@link #peekLast() peekLast()}</td>
  *  </tr>
  * </table>
  *
@@ -106,28 +106,28 @@
  *    <td style="text-align:center"> <b>Equivalent {@code Deque} Method</b></td>
  *  </tr>
  *  <tr>
- *    <td>{@link java.util.Queue#add add(e)}</td>
- *    <td>{@link #addLast addLast(e)}</td>
+ *    <td>{@link #add(Object) add(e)}</td>
+ *    <td>{@link #addLast(Object) addLast(e)}</td>
  *  </tr>
  *  <tr>
- *    <td>{@link java.util.Queue#offer offer(e)}</td>
- *    <td>{@link #offerLast offerLast(e)}</td>
+ *    <td>{@link #offer(Object) offer(e)}</td>
+ *    <td>{@link #offerLast(Object) offerLast(e)}</td>
  *  </tr>
  *  <tr>
- *    <td>{@link java.util.Queue#remove remove()}</td>
- *    <td>{@link #removeFirst removeFirst()}</td>
+ *    <td>{@link #remove() remove()}</td>
+ *    <td>{@link #removeFirst() removeFirst()}</td>
  *  </tr>
  *  <tr>
- *    <td>{@link java.util.Queue#poll poll()}</td>
- *    <td>{@link #pollFirst pollFirst()}</td>
+ *    <td>{@link #poll() poll()}</td>
+ *    <td>{@link #pollFirst() pollFirst()}</td>
  *  </tr>
  *  <tr>
- *    <td>{@link java.util.Queue#element element()}</td>
- *    <td>{@link #getFirst getFirst()}</td>
+ *    <td>{@link #element() element()}</td>
+ *    <td>{@link #getFirst() getFirst()}</td>
  *  </tr>
  *  <tr>
- *    <td>{@link java.util.Queue#peek peek()}</td>
- *    <td>{@link #peek peekFirst()}</td>
+ *    <td>{@link #peek() peek()}</td>
+ *    <td>{@link #peekFirst() peekFirst()}</td>
  *  </tr>
  * </table>
  *
@@ -144,16 +144,16 @@
  *    <td style="text-align:center"> <b>Equivalent {@code Deque} Method</b></td>
  *  </tr>
  *  <tr>
- *    <td>{@link #push push(e)}</td>
- *    <td>{@link #addFirst addFirst(e)}</td>
+ *    <td>{@link #push(Object) push(e)}</td>
+ *    <td>{@link #addFirst(Object) addFirst(e)}</td>
  *  </tr>
  *  <tr>
- *    <td>{@link #pop pop()}</td>
- *    <td>{@link #removeFirst removeFirst()}</td>
+ *    <td>{@link #pop() pop()}</td>
+ *    <td>{@link #removeFirst() removeFirst()}</td>
  *  </tr>
  *  <tr>
- *    <td>{@link #peek peek()}</td>
- *    <td>{@link #peekFirst peekFirst()}</td>
+ *    <td>{@link #peek() peek()}</td>
+ *    <td>{@link #peekFirst() peekFirst()}</td>
  *  </tr>
  * </table>
  *
@@ -430,8 +430,8 @@
     /**
      * Retrieves and removes the head of the queue represented by this deque
      * (in other words, the first element of this deque).
-     * This method differs from {@link #poll poll} only in that it throws an
-     * exception if this deque is empty.
+     * This method differs from {@link #poll() poll()} only in that it
+     * throws an exception if this deque is empty.
      *
      * <p>This method is equivalent to {@link #removeFirst()}.
      *
@@ -477,6 +477,31 @@
      */
     E peek();
 
+    /**
+     * Adds all of the elements in the specified collection at the end
+     * of this deque, as if by calling {@link #addLast} on each one,
+     * in the order that they are returned by the collection's iterator.
+     *
+     * <p>When using a capacity-restricted deque, it is generally preferable
+     * to call {@link #offer(Object) offer} separately on each element.
+     *
+     * <p>An exception encountered while trying to add an element may result
+     * in only some of the elements having been successfully added when
+     * the associated exception is thrown.
+     *
+     * @param c the elements to be inserted into this deque
+     * @return {@code true} if this deque changed as a result of the call
+     * @throws IllegalStateException if not all the elements can be added at
+     *         this time due to insertion restrictions
+     * @throws ClassCastException if the class of an element of the specified
+     *         collection prevents it from being added to this deque
+     * @throws NullPointerException if the specified collection contains a
+     *         null element and this deque does not permit null elements,
+     *         or if the specified collection is null
+     * @throws IllegalArgumentException if some property of an element of the
+     *         specified collection prevents it from being added to this deque
+     */
+    boolean addAll(Collection<? extends E> c);
 
     // *** Stack methods ***
 
--- a/src/java.base/share/classes/java/util/ServiceConfigurationError.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/util/ServiceConfigurationError.java	Thu Jun 29 13:07:19 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 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
@@ -27,33 +27,12 @@
 
 
 /**
- * Error thrown when something goes wrong while loading a service provider.
- *
- * <p> This error will be thrown in the following situations:
- *
- * <ul>
- *
- *   <li> The format of a provider-configuration file violates the <a
- *   href="ServiceLoader.html#format">specification</a>; </li>
- *
- *   <li> An {@link java.io.IOException IOException} occurs while reading a
- *   provider-configuration file; </li>
- *
- *   <li> A concrete provider class named in a provider-configuration file
- *   cannot be found; </li>
- *
- *   <li> A concrete provider class is not a subclass of the service class;
- *   </li>
- *
- *   <li> A concrete provider class cannot be instantiated; or
- *
- *   <li> Some other kind of error occurs. </li>
- *
- * </ul>
- *
+ * Error thrown when something goes wrong while locating, loading, or
+ * instantiating a service provider.
  *
  * @author Mark Reinhold
  * @since 1.6
+ * @see ServiceLoader
  */
 
 public class ServiceConfigurationError
--- a/src/java.base/share/classes/java/util/ServiceLoader.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/util/ServiceLoader.java	Thu Jun 29 13:07:19 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 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
@@ -57,187 +57,309 @@
 
 
 /**
- * A simple service-provider loading facility.
+ * A facility to load implementations of a service.
  *
- * <p> A <i>service</i> is a well-known set of interfaces and (usually
- * abstract) classes.  A <i>service provider</i> is a specific implementation
- * of a service.  The classes in a provider typically implement the interfaces
- * and subclass the classes defined in the service itself.
- * Providers may be developed and deployed as modules and made available using
- * the application module path. Providers may alternatively be packaged as JAR
- * files and made available by adding them to the application class path. The
- * advantage of developing a provider as a module is that the provider can be
- * fully encapsulated to hide all details of its implementation.
+ * <p> A <i>service</i> is a well-known interface or class for which zero, one,
+ * or many service providers exist. A <i>service provider</i> (or just
+ * <i>provider</i>) is a class that implements or subclasses the well-known
+ * interface or class. A {@code ServiceLoader} is an object that locates and
+ * loads service providers deployed in the run time environment at a time of an
+ * application's choosing. Application code refers only to the service, not to
+ * service providers, and is assumed to be capable of differentiating between
+ * multiple service providers as well as handling the possibility that no service
+ * providers are located.
  *
- * <p> For the purpose of loading, a service is represented by a single type,
- * that is, a single interface or abstract class.  (A concrete class can be
- * used, but this is not recommended.)  A provider of a given service contains
- * one or more concrete classes that extend this <i>service type</i> with data
- * and code specific to the provider.  The <i>provider class</i> is typically
- * not the entire provider itself but rather a proxy which contains enough
- * information to decide whether the provider is able to satisfy a particular
- * request together with code that can create the actual provider on demand.
- * The details of provider classes tend to be highly service-specific; no
- * single class or interface could possibly unify them, so no such type is
- * defined here.
+ * <h3> Obtaining a service loader </h3>
  *
- * <p> Providers deployed as explicit modules on the module path are
- * instantiated by a <em>provider factory</em> or directly via the provider's
- * constructor. In the module declaration then the class name specified in the
- * <i>provides</i> clause is a provider factory if it is public and defines a
- * public static no-args method named "{@code provider}". The return type of
- * the method must be assignable to the <i>service</i> type. If the class is
- * not a provider factory then it is public with a public zero-argument
- * constructor. The requirement that the provider factory or provider class
- * be public helps to document the intent that the provider will be
- * instantiated by the service-provider loading facility.
+ * <p> An application obtains a service loader for a given service by invoking
+ * one of the static {@code load} methods of ServiceLoader. If the application
+ * is a module, then its module declaration must have a <i>uses</i> directive
+ * that specifies the service; this helps to locate providers and ensure they
+ * will execute reliably. In addition, if the service is not in the application
+ * module, then the module declaration must have a <i>requires</i> directive
+ * that specifies the module which exports the service.
  *
- * <p> As an example, suppose a module declares the following:
+ * <p> A service loader can be used to locate and instantiate providers of the
+ * service by means of the {@link #iterator() iterator} method. {@code ServiceLoader}
+ * also defines the {@link #stream() stream} method to obtain a stream of providers
+ * that can be inspected and filtered without instantiating them.
+ *
+ * <p> As an example, suppose the service is {@code com.example.CodecFactory}, an
+ * interface that defines methods for producing encoders and decoders:
  *
  * <pre>{@code
- *     provides com.example.CodecSet with com.example.impl.StandardCodecs;
- *     provides com.example.CodecSet with com.example.impl.ExtendedCodecsFactory;
+ *     package com.example;
+ *     public interface CodecFactory {
+ *         Encoder getEncoder(String encodingName);
+ *         Decoder getDecoder(String encodingName);
+ *     }
  * }</pre>
  *
- * <p> where {@code com.example.CodecSet} is the service type, {@code
- * com.example.impl.StandardCodecs} is a provider class that is public with a
- * public no-args constructor, {@code com.example.impl.ExtendedCodecsFactory}
- * is a public class that defines a public static no-args method named
- * "{@code provider}" with a return type that is {@code CodecSet} or a subtype
- * of. For this example then {@code StandardCodecs}'s no-arg constructor will
- * be used to instantiate {@code StandardCodecs}. {@code ExtendedCodecsFactory}
- * will be treated as a provider factory and {@code
- * ExtendedCodecsFactory.provider()} will be invoked to obtain the provider.
+ * <p> The following code obtains a service loader for the {@code CodecFactory}
+ * service, then uses its iterator (created automatically by the enhanced-for
+ * loop) to yield instances of the service providers that are located:
  *
- * <p> Providers deployed on the class path or as {@link
- * java.lang.module.ModuleDescriptor#isAutomatic automatic-modules} on the
- * module path must have a public zero-argument constructor.
+ * <pre>{@code
+ *     ServiceLoader<CodecFactory> loader = ServiceLoader.load(CodecFactory.class);
+ *     for (CodecFactory factory : loader) {
+ *         Encoder enc = factory.getEncoder("PNG");
+ *         if (enc != null)
+ *             ... use enc to encode a PNG file
+ *             break;
+ *         }
+ * }</pre>
  *
- * <p> An application or library using this loading facility and developed
- * and deployed as an explicit module must have an appropriate <i>uses</i>
- * clause in its <i>module descriptor</i> to declare that the module uses
- * implementations of the service. A corresponding requirement is that a
- * provider deployed as an explicit module must have an appropriate
- * <i>provides</i> clause in its module descriptor to declare that the module
- * provides an implementation of the service. The <i>uses</i> and
- * <i>provides</i> allow consumers of a service to be <i>linked</i> to modules
- * containing providers of the service.
+ * <p> If this code resides in a module, then in order to refer to the
+ * {@code com.example.CodecFactory} interface, the module declaration would
+ * require the module which exports the interface. The module declaration would
+ * also specify use of {@code com.example.CodecFactory}:
+ * <pre>{@code
+ *     requires com.example.codec.core;
+ *     uses com.example.CodecFactory;
+ * }</pre>
  *
- * <p> A service provider that is packaged as a JAR file for the class path is
- * identified by placing a <i>provider-configuration file</i> in the resource
- * directory {@code META-INF/services}. The file's name is the fully-qualified
- * <a href="../lang/ClassLoader.html#name">binary name</a> of the service's
- * type. The file contains a list of fully-qualified binary names of concrete
- * provider classes, one per line.  Space and tab characters surrounding each
- * name, as well as blank lines, are ignored.  The comment character is
- * {@code '#'} (<code>'&#92;u0023'</code>,
- * <span style="font-size:smaller;">NUMBER SIGN</span>); on
- * each line all characters following the first comment character are ignored.
- * The file must be encoded in UTF-8.
- * If a particular concrete provider class is named in more than one
- * configuration file, or is named in the same configuration file more than
- * once, then the duplicates are ignored.  The configuration file naming a
- * particular provider need not be in the same JAR file or other distribution
- * unit as the provider itself. The provider must be visible from the same
- * class loader that was initially queried to locate the configuration file;
- * note that this is not necessarily the class loader from which the file was
- * actually loaded.
+ * <p> Sometimes an application may wish to inspect a service provider before
+ * instantiating it, in order to determine if an instance of that service
+ * provider would be useful. For example, a service provider for {@code
+ * CodecFactory} that is capable of producing a "PNG" encoder may be annotated
+ * with {@code @PNG}. The following code uses service loader's {@code stream}
+ * method to yield instances of {@code Provider<CodecFactory>} in contrast to
+ * how the iterator yields instances of {@code CodecFactory}:
+ * <pre>{@code
+ *     ServiceLoader<CodecFactory> loader = ServiceLoader.load(CodecFactory.class);
+ *     Set<CodecFactory> pngFactories = loader
+ *            .stream()                                              // Note a below
+ *            .filter(p -> p.type().isAnnotationPresent(PNG.class))  // Note b
+ *            .map(Provider::get)                                    // Note c
+ *            .collect(Collectors.toSet());
+ * }</pre>
+ * <ol type="a">
+ *   <li> A stream of {@code Provider<CodecFactory>} objects </li>
+ *   <li> {@code p.type()} yields a {@code Class<CodecFactory>} </li>
+ *   <li> {@code get()} yields an instance of {@code CodecFactory} </li>
+ * </ol>
  *
- * <p> Providers are located and instantiated lazily, that is, on demand.  A
- * service loader maintains a cache of the providers that have been loaded so
- * far. Each invocation of the {@link #iterator iterator} method returns an
- * iterator that first yields all of the elements cached from previous
- * iteration, in instantiation order, and then lazily locates and instantiates
- * any remaining providers, adding each one to the cache in turn.  Similarly,
- * each invocation of the {@link #stream stream} method returns a stream that
- * first processes all providers loaded by previous stream operations, in load
- * order, and then lazily locates any remaining providers. Caches are cleared
- * via the {@link #reload reload} method.
+ * <h3> Designing services </h3>
  *
- * <h2> Locating providers </h2>
+ * <p> A service is a single type, usually an interface or abstract class. A
+ * concrete class can be used, but this is not recommended. The type may have
+ * any accessibility. The methods of a service are highly domain-specific, so
+ * this API specification cannot give concrete advice about their form or
+ * function. However, there are two general guidelines:
+ * <ol>
+ *   <li><p> A service should declare as many methods as needed to allow service
+ *   providers to communicate their domain-specific properties and other
+ *   quality-of-implementation factors. An application which obtains a service
+ *   loader for the service may then invoke these methods on each instance of
+ *   a service provider, in order to choose the best provider for the
+ *   application. </p></li>
+ *   <li><p> A service should express whether its service providers are intended
+ *   to be direct implementations of the service or to be an indirection
+ *   mechanism such as a "proxy" or a "factory". Service providers tend to be
+ *   indirection mechanisms when domain-specific objects are relatively
+ *   expensive to instantiate; in this case, the service should be designed
+ *   so that service providers are abstractions which create the "real"
+ *   implementation on demand. For example, the {@code CodecFactory} service
+ *   expresses through its name that its service providers are factories
+ *   for codecs, rather than codecs themselves, because it may be expensive
+ *   or complicated to produce certain codecs. </p></li>
+ * </ol>
  *
- * <p> The {@code load} methods locate providers using a class loader or module
- * {@link ModuleLayer layer}. When locating providers using a class loader then
- * providers in both named and unnamed modules may be located. When locating
- * providers using a module layer then only providers in named modules in
- * the layer (or parent layers) are located.
+ * <h3> <a id="developing-service-providers">Developing service providers</a> </h3>
  *
- * <p> When locating providers using a class loader then any providers in named
- * modules defined to the class loader, or any class loader that is reachable
- * via parent delegation, are located. Additionally, providers in module layers
- * other than the {@link ModuleLayer#boot() boot} layer, where the module layer
- * contains modules defined to the class loader, or any class loader reachable
- * via parent delegation, are also located. For example, suppose there is a
- * module layer where each module is defined to its own class loader (see {@link
- * ModuleLayer#defineModulesWithManyLoaders defineModulesWithManyLoaders}). If the
- * {@code load} method is invoked to locate providers using any of these class
- * loaders for this layer then it will locate all of the providers in that
- * layer, irrespective of their defining class loader.
+ * <p> A service provider is a single type, usually a concrete class. An
+ * interface or abstract class is permitted because it may declare a static
+ * provider method, discussed later. The type must be public and must not be
+ * an inner class.
  *
- * <p> In the case of unnamed modules then the service configuration files are
- * located using the class loader's {@link ClassLoader#getResources(String)
- * ClassLoader.getResources(String)} method. Any providers listed should be
- * visible via the class loader specified to the {@code load} method. If a
- * provider in a named module is listed then it is ignored - this is to avoid
- * duplicates that would otherwise arise when a module has both a
- * <i>provides</i> clause and a service configuration file in {@code
- * META-INF/services} that lists the same provider.
+ * <p> A service provider and its supporting code may be developed in a module,
+ * which is then deployed on the application module path or in a modular
+ * image. Alternatively, a service provider and its supporting code may be
+ * packaged as a JAR file and deployed on the application class path. The
+ * advantage of developing a service provider in a module is that the provider
+ * can be fully encapsulated to hide all details of its implementation.
  *
- * <h2> Ordering </h2>
+ * <p> An application that obtains a service loader for a given service is
+ * indifferent to whether providers of the service are deployed in modules or
+ * packaged as JAR files. The application instantiates service providers via
+ * the service loader's iterator, or via {@link Provider Provider} objects in
+ * the service loader's stream, without knowledge of the service providers'
+ * locations.
  *
- * <p> Service loaders created to locate providers using a {@code ClassLoader}
- * locate providers as follows:
+ * <h3> Deploying service providers as modules </h3>
+ *
+ * <p> A service provider that is developed in a module must be specified in a
+ * <i>provides</i> directive in the module declaration. The provides directive
+ * specifies both the service and the service provider; this helps to locate the
+ * provider when another module, with a <i>uses</i> directive for the service,
+ * obtains a service loader for the service. It is strongly recommended that the
+ * module does not export the package containing the service provider. There is
+ * no support for a module specifying, in a <i>provides</i> directive, a service
+ * provider in another module.
+
+ * <p> A service provider that is developed in a module has no control over when
+ * it is instantiated, since that occurs at the behest of the application, but it
+ * does have control over how it is instantiated:
+ *
  * <ul>
- *     <li> Providers in named modules are located before providers on the
- *     class path (or more generally, unnamed modules). </li>
  *
- *     <li> When locating providers in named modules then the service loader
- *     will locate providers in modules defined to the class loader, then its
- *     parent class loader, its parent parent, and so on to the bootstrap class
- *     loader. If a {@code ClassLoader}, or any class loader in the parent
- *     delegation chain, defines modules in a custom module {@link ModuleLayer} then
- *     all providers in that layer are located, irrespective of their class
- *     loader. The ordering of modules defined to the same class loader, or the
- *     ordering of modules in a layer, is not defined. </li>
+ *   <li> If the service provider declares a provider method, then the service
+ *   loader invokes that method to obtain an instance of the service provider. A
+ *   provider method is a public static method named "provider" with no formal
+ *   parameters and a return type that is assignable to the service's interface
+ *   or class.
+ *   <p> In this case, the service provider itself need not be assignable to the
+ *   service's interface or class. </li>
  *
- *     <li> If a named module declares more than one provider then the providers
- *     are located in the iteration order of the {@link
- *     java.lang.module.ModuleDescriptor.Provides#providers() providers} list.
- *     Providers added dynamically by instrumentation agents ({@link
- *     java.lang.instrument.Instrumentation#redefineModule redefineModule})
- *     are always located after providers declared by the module. </li>
+ *   <li> If the service provider does not declare a provider method, then the
+ *   service provider is instantiated directly, via its provider constructor. A
+ *   provider constructor is a public constructor with no formal parameters.
+ *   <p> In this case, the service provider must be assignable to the service's
+ *   interface or class </li>
  *
- *     <li> When locating providers in unnamed modules then the ordering is
- *     based on the order that the class loader's {@link
- *     ClassLoader#getResources(String) ClassLoader.getResources(String)}
- *     method finds the service configuration files. </li>
  * </ul>
  *
- * <p> Service loaders created to locate providers in a {@linkplain ModuleLayer
- * module layer} will first locate providers in the layer, before locating
- * providers in parent layers. Traversal of parent layers is depth-first with
- * each layer visited at most once. For example, suppose L0 is the boot layer,
- * L1 and L2 are custom layers with L0 as their parent. Now suppose that L3 is
- * created with L1 and L2 as the parents (in that order). Using a service
- * loader to locate providers with L3 as the content will locate providers
- * in the following order: L3, L1, L0, L2. The ordering of modules in a layer
- * is not defined.
+ * <p> A service provider that is deployed as an
+ * {@linkplain java.lang.module.ModuleDescriptor#isAutomatic automatic module} on
+ * the application module path must have a provider constructor. There is no
+ * support for a provider method in this case.
  *
- * <h2> Selection and filtering </h2>
- *
- * <p> Selecting a provider or filtering providers will usually involve invoking
- * a provider method. Where selection or filtering based on the provider class is
- * needed then it can be done using a {@link #stream() stream}. For example, the
- * following collects the providers that have a specific annotation:
+ * <p> As an example, suppose a module specifies the following directives:
  * <pre>{@code
- *     Set<CodecSet> providers = ServiceLoader.load(CodecSet.class)
- *            .stream()
- *            .filter(p -> p.type().isAnnotationPresent(Managed.class))
- *            .map(Provider::get)
- *            .collect(Collectors.toSet());
+ *     provides com.example.CodecFactory with com.example.impl.StandardCodecs;
+ *     provides com.example.CodecFactory with com.example.impl.ExtendedCodecsFactory;
  * }</pre>
  *
- * <h2> Security </h2>
+ * <p> where
+ *
+ * <ul>
+ *   <li> {@code com.example.CodecFactory} is the two-method service from
+ *   earlier. </li>
+ *
+ *   <li> {@code com.example.impl.StandardCodecs} is a public class that implements
+ *   {@code CodecFactory} and has a public no-args constructor. </li>
+ *
+ *   <li> {@code com.example.impl.ExtendedCodecsFactory} is a public class that
+ *   does not implement CodecFactory, but it declares a public static no-args
+ *   method named "provider" with a return type of {@code CodecFactory}. </li>
+ * </ul>
+ *
+ * <p> A service loader will instantiate {@code StandardCodecs} via its
+ * constructor, and will instantiate {@code ExtendedCodecsFactory} by invoking
+ * its {@code provider} method. The requirement that the provider constructor or
+ * provider method is public helps to document the intent that the class (that is,
+ * the service provider) will be instantiated by an entity (that is, a service
+ * loader) which is outside the class's package.
+ *
+ * <h3> Deploying service providers on the class path </h3>
+ *
+ * A service provider that is packaged as a JAR file for the class path is
+ * identified by placing a <i>provider-configuration file</i> in the resource
+ * directory {@code META-INF/services}. The name of the provider-configuration
+ * file is the fully qualified binary name of the service. The provider-configuration
+ * file contains a list of fully qualified binary names of service providers, one
+ * per line.
+ *
+ * <p> For example, suppose the service provider
+ * {@code com.example.impl.StandardCodecs} is packaged in a JAR file for the
+ * class path. The JAR file will contain a provider-configuration file named:
+ *
+ * <blockquote>{@code
+ *     META-INF/services/com.example.CodecFactory
+ * }</blockquote>
+ *
+ * that contains the line:
+ *
+ * <blockquote>{@code
+ *     com.example.impl.StandardCodecs # Standard codecs
+ * }</blockquote>
+ *
+ * <p><a id="format">The provider-configuration file must be encoded in UTF-8. </a>
+ * Space and tab characters surrounding each service provider's name, as well as
+ * blank lines, are ignored. The comment character is {@code '#'}
+ * ({@code '&#92;u0023'} <span style="font-size:smaller;">NUMBER SIGN</span>);
+ * on each line all characters following the first comment character are ignored.
+ * If a service provider class name is listed more than once in a
+ * provider-configuration file then the duplicate is ignored. If a service
+ * provider class is named in more than one configuration file then the duplicate
+ * is ignored.
+ *
+ * <p> A service provider that is mentioned in a provider-configuration file may
+ * be located in the same JAR file as the provider-configuration file or in a
+ * different JAR file. The service provider must be visible from the class loader
+ * that is initially queried to locate the provider-configuration file; this is
+ * not necessarily the class loader which ultimately locates the
+ * provider-configuration file.
+ *
+ * <h3> Timing of provider discovery </h3>
+ *
+ * <p> Service providers are loaded and instantiated lazily, that is, on demand.
+ * A service loader maintains a cache of the providers that have been loaded so
+ * far. Each invocation of the {@code iterator} method returns an {@code Iterator}
+ * that first yields all of the elements cached from previous iteration, in
+ * instantiation order, and then lazily locates and instantiates any remaining
+ * providers, adding each one to the cache in turn. Similarly, each invocation
+ * of the stream method returns a {@code Stream} that first processes all
+ * providers loaded by previous stream operations, in load order, and then lazily
+ * locates any remaining providers. Caches are cleared via the {@link #reload
+ * reload} method.
+ *
+ * <h3> <a id="errors">Errors</a> </h3>
+ *
+ * <p> When using the service loader's {@code iterator}, the {@link
+ * Iterator#hasNext() hasNext} and {@link Iterator#next() next} methods will
+ * fail with {@link ServiceConfigurationError} if an error occurs locating,
+ * loading or instantiating a service provider. When processing the service
+ * loader's stream then {@code ServiceConfigurationError} may be thrown by any
+ * method that causes a service provider to be located or loaded.
+ *
+ * <p> When loading or instantiating a service provider in a module, {@code
+ * ServiceConfigurationError} can be thrown for the following reasons:
+ *
+ * <ul>
+ *
+ *   <li> The service provider cannot be loaded. </li>
+ *
+ *   <li> The service provider does not declare a provider method, and either
+ *   it is not assignable to the service's interface/class or does not have a
+ *   provider constructor. </li>
+ *
+ *   <li> The service provider declares a public static no-args method named
+ *   "provider" with a return type that is not assignable to the service's
+ *   interface or class. </li>
+ *
+ *   <li> The service provider class file has more than one public static
+ *   no-args method named "{@code provider}". </li>
+ *
+ *   <li> The service provider declares a provider method and it fails by
+ *   returning {@code null} or throwing an exception. </li>
+ *
+ *   <li> The service provider does not declare a provider method, and its
+ *   provider constructor fails by throwing an exception. </li>
+ *
+ * </ul>
+ *
+ * <p> When reading a provider-configuration file, or loading or instantiating
+ * a provider class named in a provider-configuration file, then {@code
+ * ServiceConfigurationError} can be thrown for the following reasons:
+ *
+ * <ul>
+ *
+ *   <li> The format of the provider-configuration file violates the <a
+ *   href="ServiceLoader.html#format">format</a> specified above; </li>
+ *
+ *   <li> An {@link IOException IOException} occurs while reading the
+ *   provider-configuration file; </li>
+ *
+ *   <li> A service provider cannot be loaded; </li>
+ *
+ *   <li> A service provider is not assignable to the service's interface or
+ *   class, or does not define a provider constructor, or cannot be
+ *   instantiated. </li>
+ *
+ * </ul>
+ *
+ * <h3> Security </h3>
  *
  * <p> Service loaders always execute in the security context of the caller
  * of the iterator or stream methods and may also be restricted by the security
@@ -246,91 +368,16 @@
  * the methods of the iterators which they return, from within a privileged
  * security context.
  *
- * <h2> Concurrency </h2>
+ * <h3> Concurrency </h3>
  *
  * <p> Instances of this class are not safe for use by multiple concurrent
  * threads.
  *
- * <h2> Null handling </h2>
+ * <h3> Null handling </h3>
  *
  * <p> Unless otherwise specified, passing a {@code null} argument to any
  * method in this class will cause a {@link NullPointerException} to be thrown.
  *
- * <h2> Example </h2>
- * <p> Suppose we have a service type {@code com.example.CodecSet} which is
- * intended to represent sets of encoder/decoder pairs for some protocol.  In
- * this case it is an abstract class with two abstract methods:
- *
- * <blockquote><pre>
- * public abstract Encoder getEncoder(String encodingName);
- * public abstract Decoder getDecoder(String encodingName);</pre></blockquote>
- *
- * Each method returns an appropriate object or {@code null} if the provider
- * does not support the given encoding.  Typical providers support more than
- * one encoding.
- *
- * <p> The {@code CodecSet} class creates and saves a single service instance
- * at initialization:
- *
- * <pre>{@code
- * private static ServiceLoader<CodecSet> codecSetLoader
- *     = ServiceLoader.load(CodecSet.class);
- * }</pre>
- *
- * <p> To locate an encoder for a given encoding name it defines a static
- * factory method which iterates through the known and available providers,
- * returning only when it has located a suitable encoder or has run out of
- * providers.
- *
- * <pre>{@code
- * public static Encoder getEncoder(String encodingName) {
- *     for (CodecSet cp : codecSetLoader) {
- *         Encoder enc = cp.getEncoder(encodingName);
- *         if (enc != null)
- *             return enc;
- *     }
- *     return null;
- * }}</pre>
- *
- * <p> A {@code getDecoder} method is defined similarly.
- *
- * <p> If the code creating and using the service loader is developed as
- * a module then its module descriptor will declare the usage with:
- * <pre>{@code uses com.example.CodecSet;}</pre>
- *
- * <p> Now suppose that {@code com.example.impl.StandardCodecs} is an
- * implementation of the {@code CodecSet} service and developed as a module.
- * In that case then the module with the service provider module will declare
- * this in its module descriptor:
- * <pre>{@code provides com.example.CodecSet with com.example.impl.StandardCodecs;
- * }</pre>
- *
- * <p> On the other hand, suppose {@code com.example.impl.StandardCodecs} is
- * packaged in a JAR file for the class path then the JAR file will contain a
- * file named:
- * <pre>{@code META-INF/services/com.example.CodecSet}</pre>
- * that contains the single line:
- * <pre>{@code com.example.impl.StandardCodecs    # Standard codecs}</pre>
- *
- * <p><span style="font-weight: bold; padding-right: 1em">Usage Note</span> If
- * the class path of a class loader that is used for provider loading includes
- * remote network URLs then those URLs will be dereferenced in the process of
- * searching for provider-configuration files.
- *
- * <p> This activity is normal, although it may cause puzzling entries to be
- * created in web-server logs.  If a web server is not configured correctly,
- * however, then this activity may cause the provider-loading algorithm to fail
- * spuriously.
- *
- * <p> A web server should return an HTTP 404 (Not Found) response when a
- * requested resource does not exist.  Sometimes, however, web servers are
- * erroneously configured to return an HTTP 200 (OK) response along with a
- * helpful HTML error page in such cases.  This will cause a {@link
- * ServiceConfigurationError} to be thrown when this class attempts to parse
- * the HTML page as a provider-configuration file.  The best solution to this
- * problem is to fix the misconfigured web server to return the correct
- * response code (HTTP 404) along with the HTML error page.
- *
  * @param  <S>
  *         The type of the service to be loaded by this loader
  *
@@ -548,32 +595,83 @@
     }
 
     /**
-     * Uses Class.forName to load a provider class in a module.
+     * Returns {@code true} if the provider is in an explicit module
+     */
+    private boolean inExplicitModule(Class<?> clazz) {
+        Module module = clazz.getModule();
+        return module.isNamed() && !module.getDescriptor().isAutomatic();
+    }
+
+    /**
+     * Returns the public static "provider" method if found.
      *
-     * @throws ServiceConfigurationError
-     *         If the class cannot be loaded
+     * @throws ServiceConfigurationError if there is an error finding the
+     *         provider method or there is more than one public static
+     *         provider method
      */
-    private Class<?> loadProviderInModule(Module module, String cn) {
-        Class<?> clazz = null;
-        if (acc == null) {
-            try {
-                clazz = Class.forName(module, cn);
-            } catch (LinkageError e) {
-                fail(service, "Unable to load " + cn, e);
-            }
-        } else {
-            PrivilegedExceptionAction<Class<?>> pa = () -> Class.forName(module, cn);
-            try {
-                clazz = AccessController.doPrivileged(pa);
-            } catch (PrivilegedActionException pae) {
-                Throwable x = pae.getCause();
-                fail(service, "Unable to load " + cn, x);
-                return null;
+    private Method findStaticProviderMethod(Class<?> clazz) {
+        List<Method> methods = null;
+        try {
+            methods = LANG_ACCESS.getDeclaredPublicMethods(clazz, "provider");
+        } catch (Throwable x) {
+            fail(service, "Unable to get public provider() method", x);
+        }
+        if (methods.isEmpty()) {
+            // does not declare a public provider method
+            return null;
+        }
+
+        // locate the static methods, can be at most one
+        Method result = null;
+        for (Method method : methods) {
+            int mods = method.getModifiers();
+            assert Modifier.isPublic(mods);
+            if (Modifier.isStatic(mods)) {
+                if (result != null) {
+                    fail(service, clazz + " declares more than one"
+                         + " public static provider() method");
+                }
+                result = method;
             }
         }
-        if (clazz == null)
-            fail(service, "Provider " + cn  + " not found");
-        return clazz;
+        if (result != null) {
+            Method m = result;
+            PrivilegedAction<Void> pa = () -> {
+                m.setAccessible(true);
+                return null;
+            };
+            AccessController.doPrivileged(pa);
+        }
+        return result;
+    }
+
+    /**
+     * Returns the public no-arg constructor of a class.
+     *
+     * @throws ServiceConfigurationError if the class does not have
+     *         public no-arg constructor
+     */
+    private Constructor<?> getConstructor(Class<?> clazz) {
+        PrivilegedExceptionAction<Constructor<?>> pa
+            = new PrivilegedExceptionAction<>() {
+                @Override
+                public Constructor<?> run() throws Exception {
+                    Constructor<?> ctor = clazz.getConstructor();
+                    if (inExplicitModule(clazz))
+                        ctor.setAccessible(true);
+                    return ctor;
+                }
+            };
+        Constructor<?> ctor = null;
+        try {
+            ctor = AccessController.doPrivileged(pa);
+        } catch (Throwable x) {
+            if (x instanceof PrivilegedActionException)
+                x = x.getCause();
+            String cn = clazz.getName();
+            fail(service, cn + " Unable to get public no-arg constructor", x);
+        }
+        return ctor;
     }
 
     /**
@@ -581,65 +679,33 @@
      * permissions, the static factory to obtain the provider or the
      * provider's no-arg constructor.
      */
-    private final static class ProviderImpl<S> implements Provider<S> {
+    private static class ProviderImpl<S> implements Provider<S> {
         final Class<S> service;
+        final Class<? extends S> type;
+        final Method factoryMethod;  // factory method or null
+        final Constructor<? extends S> ctor; // public no-args constructor or null
         final AccessControlContext acc;
 
-        final Method factoryMethod;  // factory method or null
-        final Class<? extends S> type;
-        final Constructor<? extends S> ctor; // public no-args constructor or null
+        ProviderImpl(Class<S> service,
+                     Class<? extends S> type,
+                     Method factoryMethod,
+                     AccessControlContext acc) {
+            this.service = service;
+            this.type = type;
+            this.factoryMethod = factoryMethod;
+            this.ctor = null;
+            this.acc = acc;
+        }
 
-        /**
-         * Creates a Provider.
-         *
-         * @param service
-         *        The service type
-         * @param clazz
-         *        The provider (or provider factory) class
-         * @param acc
-         *        The access control context when running with security manager
-         *
-         * @throws ServiceConfigurationError
-         *         If the class is not public; If the class defines a public
-         *         static provider() method with a return type that is assignable
-         *         to the service type or the class is not a provider class with
-         *         a public no-args constructor.
-         */
-        @SuppressWarnings("unchecked")
-        ProviderImpl(Class<?> service, Class<?> clazz, AccessControlContext acc) {
-            this.service = (Class<S>) service;
+        ProviderImpl(Class<S> service,
+                     Class<? extends S> type,
+                     Constructor<? extends S> ctor,
+                     AccessControlContext acc) {
+            this.service = service;
+            this.type = type;
+            this.factoryMethod = null;
+            this.ctor = ctor;
             this.acc = acc;
-
-            int mods = clazz.getModifiers();
-            if (!Modifier.isPublic(mods)) {
-                fail(service, clazz + " is not public");
-            }
-
-            // if the class is in an explicit module then see if it is
-            // a provider factory class
-            Method factoryMethod = null;
-            if (inExplicitModule(clazz)) {
-                factoryMethod = findStaticProviderMethod(clazz);
-                if (factoryMethod != null) {
-                    Class<?> returnType = factoryMethod.getReturnType();
-                    if (!service.isAssignableFrom(returnType)) {
-                        fail(service, factoryMethod + " return type not a subtype");
-                    }
-                }
-            }
-            this.factoryMethod = factoryMethod;
-
-            if (factoryMethod == null) {
-                // no factory method so must have a public no-args constructor
-                if (!service.isAssignableFrom(clazz)) {
-                    fail(service, clazz.getName() + " not a subtype");
-                }
-                this.type = (Class<? extends S>) clazz;
-                this.ctor = (Constructor<? extends S>) getConstructor(clazz);
-            } else {
-                this.type = (Class<? extends S>) factoryMethod.getReturnType();
-                this.ctor = null;
-            }
         }
 
         @Override
@@ -657,72 +723,6 @@
         }
 
         /**
-         * Returns {@code true} if the provider is in an explicit module
-         */
-        private boolean inExplicitModule(Class<?> clazz) {
-            Module module = clazz.getModule();
-            return module.isNamed() && !module.getDescriptor().isAutomatic();
-        }
-
-        /**
-         * Returns the public static provider method if found.
-         *
-         * @throws ServiceConfigurationError if there is an error finding the
-         *         provider method
-         */
-        private Method findStaticProviderMethod(Class<?> clazz) {
-            Method method = null;
-            try {
-                method = LANG_ACCESS.getMethodOrNull(clazz, "provider");
-            } catch (Throwable x) {
-                fail(service, "Unable to get public provider() method", x);
-            }
-            if (method != null) {
-                int mods = method.getModifiers();
-                if (Modifier.isStatic(mods)) {
-                    assert Modifier.isPublic(mods);
-                    Method m = method;
-                    PrivilegedAction<Void> pa = () -> {
-                        m.setAccessible(true);
-                        return null;
-                    };
-                    AccessController.doPrivileged(pa);
-                    return method;
-                }
-            }
-            return null;
-        }
-
-        /**
-         * Returns the public no-arg constructor of a class.
-         *
-         * @throws ServiceConfigurationError if the class does not have
-         *         public no-arg constructor
-         */
-        private Constructor<?> getConstructor(Class<?> clazz) {
-            PrivilegedExceptionAction<Constructor<?>> pa
-                = new PrivilegedExceptionAction<>() {
-                    @Override
-                    public Constructor<?> run() throws Exception {
-                        Constructor<?> ctor = clazz.getConstructor();
-                        if (inExplicitModule(clazz))
-                            ctor.setAccessible(true);
-                        return ctor;
-                    }
-                };
-            Constructor<?> ctor = null;
-            try {
-                ctor = AccessController.doPrivileged(pa);
-            } catch (Throwable x) {
-                if (x instanceof PrivilegedActionException)
-                    x = x.getCause();
-                String cn = clazz.getName();
-                fail(service, cn + " Unable to get public no-arg constructor", x);
-            }
-            return ctor;
-        }
-
-        /**
          * Invokes the provider's "provider" method to instantiate a provider.
          * When running with a security manager then the method runs with
          * permissions that are restricted by the security context of whatever
@@ -808,7 +808,7 @@
 
         @Override
         public int hashCode() {
-            return Objects.hash(type, acc);
+            return Objects.hash(service, type, acc);
         }
 
         @Override
@@ -817,12 +817,84 @@
                 return false;
             @SuppressWarnings("unchecked")
             ProviderImpl<?> that = (ProviderImpl<?>)ob;
-            return this.type == that.type
+            return this.service == that.service
+                    && this.type == that.type
                     && Objects.equals(this.acc, that.acc);
         }
     }
 
     /**
+     * Loads a service provider in a module.
+     *
+     * Returns {@code null} if the service provider's module doesn't read
+     * the module with the service type.
+     *
+     * @throws ServiceConfigurationError if the class cannot be loaded or
+     *         isn't the expected sub-type (or doesn't define a provider
+     *         factory method that returns the expected type)
+     */
+    private Provider<S> loadProvider(ServiceProvider provider) {
+        Module module = provider.module();
+        if (!module.canRead(service.getModule())) {
+            // module does not read the module with the service type
+            return null;
+        }
+
+        String cn = provider.providerName();
+        Class<?> clazz = null;
+        if (acc == null) {
+            try {
+                clazz = Class.forName(module, cn);
+            } catch (LinkageError e) {
+                fail(service, "Unable to load " + cn, e);
+            }
+        } else {
+            PrivilegedExceptionAction<Class<?>> pa = () -> Class.forName(module, cn);
+            try {
+                clazz = AccessController.doPrivileged(pa);
+            } catch (PrivilegedActionException pae) {
+                Throwable x = pae.getCause();
+                fail(service, "Unable to load " + cn, x);
+                return null;
+            }
+        }
+        if (clazz == null) {
+            fail(service, "Provider " + cn + " not found");
+        }
+
+        int mods = clazz.getModifiers();
+        if (!Modifier.isPublic(mods)) {
+            fail(service, clazz + " is not public");
+        }
+
+        // if provider in explicit module then check for static factory method
+        if (inExplicitModule(clazz)) {
+            Method factoryMethod = findStaticProviderMethod(clazz);
+            if (factoryMethod != null) {
+                Class<?> returnType = factoryMethod.getReturnType();
+                if (!service.isAssignableFrom(returnType)) {
+                    fail(service, factoryMethod + " return type not a subtype");
+                }
+
+                @SuppressWarnings("unchecked")
+                Class<? extends S> type = (Class<? extends S>) returnType;
+                return new ProviderImpl<S>(service, type, factoryMethod, acc);
+            }
+        }
+
+        // no factory method so must be a subtype
+        if (!service.isAssignableFrom(clazz)) {
+            fail(service, clazz.getName() + " not a subtype");
+        }
+
+        @SuppressWarnings("unchecked")
+        Class<? extends S> type = (Class<? extends S>) clazz;
+        @SuppressWarnings("unchecked")
+        Constructor<? extends S> ctor = (Constructor<? extends S> ) getConstructor(clazz);
+        return new ProviderImpl<S>(service, type, ctor, acc);
+    }
+
+    /**
      * Implements lazy service provider lookup of service providers that
      * are provided by modules in a module layer (or parent layers)
      */
@@ -832,7 +904,9 @@
         Deque<ModuleLayer> stack = new ArrayDeque<>();
         Set<ModuleLayer> visited = new HashSet<>();
         Iterator<ServiceProvider> iterator;
-        ServiceProvider next;  // next provider to load
+
+        Provider<T> nextProvider;
+        ServiceConfigurationError nextError;
 
         LayerLookupIterator() {
             visited.add(layer);
@@ -846,33 +920,36 @@
 
         @Override
         public boolean hasNext() {
-            // already have the next provider cached
-            if (next != null)
-                return true;
+            while (nextProvider == null && nextError == null) {
+                // get next provider to load
+                while (iterator == null || !iterator.hasNext()) {
+                    // next layer (DFS order)
+                    if (stack.isEmpty())
+                        return false;
 
-            while (true) {
-
-                // next provider (or provider factory)
-                if (iterator != null && iterator.hasNext()) {
-                    next = iterator.next();
-                    return true;
+                    ModuleLayer layer = stack.pop();
+                    List<ModuleLayer> parents = layer.parents();
+                    for (int i = parents.size() - 1; i >= 0; i--) {
+                        ModuleLayer parent = parents.get(i);
+                        if (!visited.contains(parent)) {
+                            visited.add(parent);
+                            stack.push(parent);
+                        }
+                    }
+                    iterator = providers(layer);
                 }
 
-                // next layer (DFS order)
-                if (stack.isEmpty())
-                    return false;
-
-                ModuleLayer layer = stack.pop();
-                List<ModuleLayer> parents = layer.parents();
-                for (int i = parents.size() - 1; i >= 0; i--) {
-                    ModuleLayer parent = parents.get(i);
-                    if (!visited.contains(parent)) {
-                        visited.add(parent);
-                        stack.push(parent);
-                    }
+                // attempt to load provider
+                ServiceProvider provider = iterator.next();
+                try {
+                    @SuppressWarnings("unchecked")
+                    Provider<T> next = (Provider<T>) loadProvider(provider);
+                    nextProvider = next;
+                } catch (ServiceConfigurationError e) {
+                    nextError = e;
                 }
-                iterator = providers(layer);
             }
+            return true;
         }
 
         @Override
@@ -880,15 +957,16 @@
             if (!hasNext())
                 throw new NoSuchElementException();
 
-            // take next provider
-            ServiceProvider provider = next;
-            next = null;
-
-            // attempt to load provider
-            Module module = provider.module();
-            String cn = provider.providerName();
-            Class<?> clazz = loadProviderInModule(module, cn);
-            return new ProviderImpl<T>(service, clazz, acc);
+            Provider<T> provider = nextProvider;
+            if (provider != null) {
+                nextProvider = null;
+                return provider;
+            } else {
+                ServiceConfigurationError e = nextError;
+                assert e != null;
+                nextError = null;
+                throw e;
+            }
         }
     }
 
@@ -902,7 +980,9 @@
     {
         ClassLoader currentLoader;
         Iterator<ServiceProvider> iterator;
-        ServiceProvider next;  // next provider to load
+
+        Provider<T> nextProvider;
+        ServiceConfigurationError nextError;
 
         ModuleServicesLookupIterator() {
             this.currentLoader = loader;
@@ -919,13 +999,25 @@
         }
 
         /**
+         * Returns the class loader that a module is defined to
+         */
+        private ClassLoader loaderFor(Module module) {
+            SecurityManager sm = System.getSecurityManager();
+            if (sm == null) {
+                return module.getClassLoader();
+            } else {
+                PrivilegedAction<ClassLoader> pa = module::getClassLoader;
+                return AccessController.doPrivileged(pa);
+            }
+        }
+
+        /**
          * Returns an iterator to iterate over the implementations of {@code
          * service} in modules defined to the given class loader or in custom
          * layers with a module defined to this class loader.
          */
         private Iterator<ServiceProvider> iteratorFor(ClassLoader loader) {
-
-            // modules defined to this class loader
+            // modules defined to the class loader
             ServicesCatalog catalog;
             if (loader == null) {
                 catalog = BootLoader.getServicesCatalog();
@@ -939,17 +1031,20 @@
                 providers = catalog.findServices(serviceName);
             }
 
-            // modules in custom layers that define modules to the class loader
-            if (loader == null) {
+            // modules in layers that define modules to the class loader
+            ClassLoader platformClassLoader = ClassLoaders.platformClassLoader();
+            if (loader == null || loader == platformClassLoader) {
                 return providers.iterator();
             } else {
                 List<ServiceProvider> allProviders = new ArrayList<>(providers);
-                ModuleLayer bootLayer = ModuleLayer.boot();
                 Iterator<ModuleLayer> iterator = LANG_ACCESS.layers(loader).iterator();
                 while (iterator.hasNext()) {
                     ModuleLayer layer = iterator.next();
-                    if (layer != bootLayer) {
-                        allProviders.addAll(providers(layer));
+                    for (ServiceProvider sp : providers(layer)) {
+                        ClassLoader l = loaderFor(sp.module());
+                        if (l != null && l != platformClassLoader) {
+                            allProviders.add(sp);
+                        }
                     }
                 }
                 return allProviders.iterator();
@@ -958,24 +1053,28 @@
 
         @Override
         public boolean hasNext() {
-            // already have the next provider cached
-            if (next != null)
-                return true;
-
-            while (true) {
-                if (iterator.hasNext()) {
-                    next = iterator.next();
-                    return true;
+            while (nextProvider == null && nextError == null) {
+                // get next provider to load
+                while (!iterator.hasNext()) {
+                    if (currentLoader == null) {
+                        return false;
+                    } else {
+                        currentLoader = currentLoader.getParent();
+                        iterator = iteratorFor(currentLoader);
+                    }
                 }
 
-                // move to the next class loader if possible
-                if (currentLoader == null) {
-                    return false;
-                } else {
-                    currentLoader = currentLoader.getParent();
-                    iterator = iteratorFor(currentLoader);
+                // attempt to load provider
+                ServiceProvider provider = iterator.next();
+                try {
+                    @SuppressWarnings("unchecked")
+                    Provider<T> next = (Provider<T>) loadProvider(provider);
+                    nextProvider = next;
+                } catch (ServiceConfigurationError e) {
+                    nextError = e;
                 }
             }
+            return true;
         }
 
         @Override
@@ -983,15 +1082,16 @@
             if (!hasNext())
                 throw new NoSuchElementException();
 
-            // take next provider
-            ServiceProvider provider = next;
-            next = null;
-
-            // attempt to load provider
-            Module module = provider.module();
-            String cn = provider.providerName();
-            Class<?> clazz = loadProviderInModule(module, cn);
-            return new ProviderImpl<T>(service, clazz, acc);
+            Provider<T> provider = nextProvider;
+            if (provider != null) {
+                nextProvider = null;
+                return provider;
+            } else {
+                ServiceConfigurationError e = nextError;
+                assert e != null;
+                nextError = null;
+                throw e;
+            }
         }
     }
 
@@ -1008,8 +1108,9 @@
         Set<String> providerNames = new HashSet<>();  // to avoid duplicates
         Enumeration<URL> configs;
         Iterator<String> pending;
-        Class<?> nextClass;
-        String nextErrorMessage;  // when hasNext fails with CNFE
+
+        Provider<T> nextProvider;
+        ServiceConfigurationError nextError;
 
         LazyClassPathLookupIterator() { }
 
@@ -1068,51 +1169,71 @@
             return names.iterator();
         }
 
+        /**
+         * Loads and returns the next provider class.
+         */
+        private Class<?> nextProviderClass() {
+            if (configs == null) {
+                try {
+                    String fullName = PREFIX + service.getName();
+                    if (loader == null) {
+                        configs = ClassLoader.getSystemResources(fullName);
+                    } else if (loader == ClassLoaders.platformClassLoader()) {
+                        // The platform classloader doesn't have a class path,
+                        // but the boot loader might.
+                        if (BootLoader.hasClassPath()) {
+                            configs = BootLoader.findResources(fullName);
+                        } else {
+                            configs = Collections.emptyEnumeration();
+                        }
+                    } else {
+                        configs = loader.getResources(fullName);
+                    }
+                } catch (IOException x) {
+                    fail(service, "Error locating configuration files", x);
+                }
+            }
+            while ((pending == null) || !pending.hasNext()) {
+                if (!configs.hasMoreElements()) {
+                    return null;
+                }
+                pending = parse(configs.nextElement());
+            }
+            String cn = pending.next();
+            try {
+                return Class.forName(cn, false, loader);
+            } catch (ClassNotFoundException x) {
+                fail(service, "Provider " + cn + " not found");
+                return null;
+            }
+        }
+
+        @SuppressWarnings("unchecked")
         private boolean hasNextService() {
-            if (nextClass != null || nextErrorMessage != null) {
-                return true;
+            while (nextProvider == null && nextError == null) {
+                try {
+                    Class<?> clazz = nextProviderClass();
+                    if (clazz == null)
+                        return false;
+
+                    if (clazz.getModule().isNamed()) {
+                        // ignore class if in named module
+                        continue;
+                    }
+
+                    if (service.isAssignableFrom(clazz)) {
+                        Class<? extends S> type = (Class<? extends S>) clazz;
+                        Constructor<? extends S> ctor
+                            = (Constructor<? extends S>)getConstructor(clazz);
+                        ProviderImpl<S> p = new ProviderImpl<S>(service, type, ctor, acc);
+                        nextProvider = (ProviderImpl<T>) p;
+                    } else {
+                        fail(service, clazz.getName() + " not a subtype");
+                    }
+                } catch (ServiceConfigurationError e) {
+                    nextError = e;
+                }
             }
-
-            Class<?> clazz;
-            do {
-                if (configs == null) {
-                    try {
-                        String fullName = PREFIX + service.getName();
-                        if (loader == null) {
-                            configs = ClassLoader.getSystemResources(fullName);
-                        } else if (loader == ClassLoaders.platformClassLoader()) {
-                            // The platform classloader doesn't have a class path,
-                            // but the boot loader might.
-                            if (BootLoader.hasClassPath()) {
-                                configs = BootLoader.findResources(fullName);
-                            } else {
-                                configs = Collections.emptyEnumeration();
-                            }
-                        } else {
-                            configs = loader.getResources(fullName);
-                        }
-                    } catch (IOException x) {
-                        fail(service, "Error locating configuration files", x);
-                    }
-                }
-                while ((pending == null) || !pending.hasNext()) {
-                    if (!configs.hasMoreElements()) {
-                        return false;
-                    }
-                    pending = parse(configs.nextElement());
-                }
-                String cn = pending.next();
-                try {
-                    clazz = Class.forName(cn, false, loader);
-                } catch (ClassNotFoundException x) {
-                    // don't throw SCE here to long standing behavior
-                    nextErrorMessage = "Provider " + cn + " not found";
-                    return true;
-                }
-
-            } while (clazz.getModule().isNamed()); // ignore if in named module
-
-            nextClass = clazz;
             return true;
         }
 
@@ -1120,17 +1241,16 @@
             if (!hasNextService())
                 throw new NoSuchElementException();
 
-            // throw any SCE with error recorded by hasNext
-            if (nextErrorMessage != null) {
-                String msg = nextErrorMessage;
-                nextErrorMessage = null;
-                fail(service, msg);
+            Provider<T> provider = nextProvider;
+            if (provider != null) {
+                nextProvider = null;
+                return provider;
+            } else {
+                ServiceConfigurationError e = nextError;
+                assert e != null;
+                nextError = null;
+                throw e;
             }
-
-            // return next provider
-            Class<?> clazz = nextClass;
-            nextClass = null;
-            return new ProviderImpl<T>(service, clazz, acc);
         }
 
         @Override
@@ -1188,42 +1308,26 @@
     }
 
     /**
-     * Lazily load and instantiate the available providers of this loader's
-     * service.
-     *
-     * <p> The iterator returned by this method first yields all of the
-     * elements of the provider cache, in the order that they were loaded.
-     * It then lazily loads and instantiates any remaining providers,
-     * adding each one to the cache in turn.
+     * Returns an iterator to lazily load and instantiate the available
+     * providers of this loader's service.
      *
      * <p> To achieve laziness the actual work of locating and instantiating
-     * providers must be done by the iterator itself. Its {@link
-     * java.util.Iterator#hasNext hasNext} and {@link java.util.Iterator#next
-     * next} methods can therefore throw a {@link ServiceConfigurationError}
-     * if a provider class cannot be loaded, doesn't have an appropriate static
-     * factory method or constructor, can't be assigned to the service type or
-     * if any other kind of exception or error is thrown as the next provider
-     * is located and instantiated. To write robust code it is only necessary
-     * to catch {@link ServiceConfigurationError} when using a service iterator.
-     *
-     * <p> If such an error is thrown then subsequent invocations of the
+     * providers is done by the iterator itself. Its {@link Iterator#hasNext
+     * hasNext} and {@link Iterator#next next} methods can therefore throw a
+     * {@link ServiceConfigurationError} for any of the reasons specified in
+     * the <a href="#errors">Errors</a> section above. To write robust code it
+     * is only necessary to catch {@code ServiceConfigurationError} when using
+     * the iterator. If an error is thrown then subsequent invocations of the
      * iterator will make a best effort to locate and instantiate the next
      * available provider, but in general such recovery cannot be guaranteed.
      *
-     * <blockquote style="font-size: smaller; line-height: 1.2"><span
-     * style="padding-right: 1em; font-weight: bold">Design Note</span>
-     * Throwing an error in these cases may seem extreme.  The rationale for
-     * this behavior is that a malformed provider-configuration file, like a
-     * malformed class file, indicates a serious problem with the way the Java
-     * virtual machine is configured or is being used.  As such it is
-     * preferable to throw an error rather than try to recover or, even worse,
-     * fail silently.</blockquote>
-     *
-     * <p> If this loader's provider caches are cleared by invoking the {@link
-     * #reload() reload} method then existing iterators for this service
-     * loader should be discarded.
-     * The {@link java.util.Iterator#hasNext() hasNext} and {@link
-     * java.util.Iterator#next() next} methods of the iterator throw {@link
+     * <p> Caching: The iterator returned by this method first yields all of
+     * the elements of the provider cache, in the order that they were loaded.
+     * It then lazily loads and instantiates any remaining service providers,
+     * adding each one to the cache in turn. If this loader's provider caches are
+     * cleared by invoking the {@link #reload() reload} method then existing
+     * iterators for this service loader should be discarded.
+     * The {@code  hasNext} and {@code next} methods of the iterator throw {@link
      * java.util.ConcurrentModificationException ConcurrentModificationException}
      * if used after the provider cache has been cleared.
      *
@@ -1231,6 +1335,12 @@
      * Invoking its {@link java.util.Iterator#remove() remove} method will
      * cause an {@link UnsupportedOperationException} to be thrown.
      *
+     * @apiNote Throwing an error in these cases may seem extreme.  The rationale
+     * for this behavior is that a malformed provider-configuration file, like a
+     * malformed class file, indicates a serious problem with the way the Java
+     * virtual machine is configured or is being used.  As such it is preferable
+     * to throw an error rather than try to recover or, even worse, fail silently.
+     *
      * @return  An iterator that lazily loads providers for this loader's
      *          service
      *
@@ -1287,35 +1397,36 @@
     }
 
     /**
-     * Returns a stream that lazily loads the available providers of this
-     * loader's service. The stream elements are of type {@link Provider
-     * Provider}, the {@code Provider}'s {@link Provider#get() get} method
-     * must be invoked to get or instantiate the provider.
+     * Returns a stream to lazily load available providers of this loader's
+     * service. The stream elements are of type {@link Provider Provider}, the
+     * {@code Provider}'s {@link Provider#get() get} method must be invoked to
+     * get or instantiate the provider.
      *
-     * <p> When processing the stream then providers that were previously
+     * <p> To achieve laziness the actual work of locating providers is done
+     * when processing the stream. If a service provider cannot be loaded for any
+     * of the the reasons specified in the <a href="#errors">Errors</a> section
+     * above then {@link ServiceConfigurationError} is thrown by whatever method
+     * caused the service provider to be loaded. </p>
+     *
+     * <p> Caching: When processing the stream then providers that were previously
      * loaded by stream operations are processed first, in load order. It then
-     * lazily loads any remaining providers. If a provider class cannot be
-     * loaded, can't be assigned to the service type, or some other error is
-     * thrown when locating the provider then it is wrapped with a {@code
-     * ServiceConfigurationError} and thrown by whatever method caused the
-     * provider to be loaded. </p>
+     * lazily loads any remaining service providers. If this loader's provider
+     * caches are cleared by invoking the {@link #reload() reload} method then
+     * existing streams for this service loader should be discarded. The returned
+     * stream's source {@link Spliterator spliterator} is <em>fail-fast</em> and
+     * will throw {@link ConcurrentModificationException} if the provider cache
+     * has been cleared. </p>
      *
-     * <p> If this loader's provider caches are cleared by invoking the {@link
-     * #reload() reload} method then existing streams for this service loader
-     * should be discarded. The returned stream's source {@code Spliterator} is
-     * <em>fail-fast</em> and will throw {@link ConcurrentModificationException}
-     * if the provider cache has been cleared. </p>
-     *
-     * <p> The following examples demonstrate usage. The first example
-     * creates a stream of providers, the second example is the same except
-     * that it sorts the providers by provider class name (and so locate all
-     * providers).
+     * <p> The following examples demonstrate usage. The first example creates
+     * a stream of {@code CodecFactory} objects, the second example is the same
+     * except that it sorts the providers by provider class name (and so locate
+     * all providers).
      * <pre>{@code
-     *    Stream<CodecSet> providers = ServiceLoader.load(CodecSet.class)
+     *    Stream<CodecFactory> providers = ServiceLoader.load(CodecFactory.class)
      *            .stream()
      *            .map(Provider::get);
      *
-     *    Stream<CodecSet> providers = ServiceLoader.load(CodecSet.class)
+     *    Stream<CodecFactory> providers = ServiceLoader.load(CodecFactory.class)
      *            .stream()
      *            .sorted(Comparator.comparing(p -> p.type().getName()))
      *            .map(Provider::get);
@@ -1419,8 +1530,86 @@
     }
 
     /**
-     * Creates a new service loader for the given service type and class
-     * loader.
+     * Creates a new service loader for the given service. The service loader
+     * uses the given class loader as the starting point to locate service
+     * providers for the service. The service loader's {@link #iterator()
+     * iterator} and {@link #stream() stream} locate providers in both named
+     * and unnamed modules, as follows:
+     *
+     * <ul>
+     *   <li> <p> Step 1: Locate providers in named modules. </p>
+     *
+     *   <p> Service providers are located in all named modules of the class
+     *   loader or to any class loader reachable via parent delegation. </p>
+     *
+     *   <p> In addition, if the class loader is not the bootstrap or {@linkplain
+     *   ClassLoader#getPlatformClassLoader() platform class loader}, then service
+     *   providers may be located in the named modules of other class loaders.
+     *   Specifically, if the class loader, or any class loader reachable via
+     *   parent delegation, has a module in a {@linkplain ModuleLayer module
+     *   layer}, then service providers in all modules in the module layer are
+     *   located.  </p>
+     *
+     *   <p> For example, suppose there is a module layer where each module is
+     *   in its own class loader (see {@link ModuleLayer#defineModulesWithManyLoaders
+     *   defineModulesWithManyLoaders}). If this {@code ServiceLoader.load} method
+     *   is invoked to locate providers using any of the class loaders created for
+     *   the module layer, then it will locate all of the providers in the module
+     *   layer, irrespective of their defining class loader. </p>
+     *
+     *   <p> Ordering: The service loader will first locate any service providers
+     *   in modules defined to the class loader, then its parent class loader,
+     *   its parent parent, and so on to the bootstrap class loader. If a class
+     *   loader has modules in a module layer then all providers in that module
+     *   layer are located (irrespective of their class loader) before the
+     *   providers in the parent class loader are located. The ordering of
+     *   modules in same class loader, or the ordering of modules in a module
+     *   layer, is not defined. </p>
+     *
+     *   <p> If a module declares more than one provider then the providers
+     *   are located in the order that its module descriptor {@linkplain
+     *   java.lang.module.ModuleDescriptor.Provides#providers() lists the
+     *   providers}. Providers added dynamically by instrumentation agents (see
+     *   {@link java.lang.instrument.Instrumentation#redefineModule redefineModule})
+     *   are always located after providers declared by the module. </p> </li>
+     *
+     *   <li> <p> Step 2: Locate providers in unnamed modules. </p>
+     *
+     *   <p> Service providers in unnamed modules are located if their class names
+     *   are listed in provider-configuration files located by the class loader's
+     *   {@link ClassLoader#getResources(String) getResources} method. </p>
+     *
+     *   <p> The ordering is based on the order that the class loader's {@code
+     *   getResources} method finds the service configuration files and within
+     *   that, the order that the class names are listed in the file. </p>
+     *
+     *   <p> In a provider-configuration file, any mention of a service provider
+     *   that is deployed in a named module is ignored. This is to avoid
+     *   duplicates that would otherwise arise when a named module has both a
+     *   <i>provides</i> directive and a provider-configuration file that mention
+     *   the same service provider. </p>
+     *
+     *   <p> The provider class must be visible to the class loader. </p> </li>
+     *
+     * </ul>
+     *
+     * @apiNote If the class path of the class loader includes remote network
+     * URLs then those URLs may be dereferenced in the process of searching for
+     * provider-configuration files.
+     *
+     * <p> This activity is normal, although it may cause puzzling entries to be
+     * created in web-server logs.  If a web server is not configured correctly,
+     * however, then this activity may cause the provider-loading algorithm to fail
+     * spuriously.
+     *
+     * <p> A web server should return an HTTP 404 (Not Found) response when a
+     * requested resource does not exist.  Sometimes, however, web servers are
+     * erroneously configured to return an HTTP 200 (OK) response along with a
+     * helpful HTML error page in such cases.  This will cause a {@link
+     * ServiceConfigurationError} to be thrown when this class attempts to parse
+     * the HTML page as a provider-configuration file.  The best solution to this
+     * problem is to fix the misconfigured web server to return the correct
+     * response code (HTTP 404) along with the HTML error page.
      *
      * @param  <S> the class of the service type
      *
@@ -1457,13 +1646,13 @@
      *
      * <p> An invocation of this convenience method of the form
      * <pre>{@code
-     * ServiceLoader.load(service)
+     *     ServiceLoader.load(service)
      * }</pre>
      *
      * is equivalent to
      *
      * <pre>{@code
-     * ServiceLoader.load(service, Thread.currentThread().getContextClassLoader())
+     *     ServiceLoader.load(service, Thread.currentThread().getContextClassLoader())
      * }</pre>
      *
      * @apiNote Service loader objects obtained with this method should not be
@@ -1502,7 +1691,7 @@
      * <p> This convenience method is equivalent to: </p>
      *
      * <pre>{@code
-     * ServiceLoader.load(service, ClassLoader.getPlatformClassLoader())
+     *     ServiceLoader.load(service, ClassLoader.getPlatformClassLoader())
      * }</pre>
      *
      * <p> This method is intended for use when only installed providers are
@@ -1532,9 +1721,29 @@
     }
 
     /**
-     * Creates a new service loader for the given service type that loads
-     * service providers from modules in the given {@code ModuleLayer} and its
-     * ancestors.
+     * Creates a new service loader for the given service type to load service
+     * providers from modules in the given module layer and its ancestors. It
+     * does not locate providers in unnamed modules. The ordering that the service
+     * loader's {@link #iterator() iterator} and {@link #stream() stream} locate
+     * providers and yield elements is as follows:
+     *
+     * <ul>
+     *   <li><p> Providers are located in a module layer before locating providers
+     *   in parent layers. Traversal of parent layers is depth-first with each
+     *   layer visited at most once. For example, suppose L0 is the boot layer, L1
+     *   and L2 are modules layers with L0 as their parent. Now suppose that L3 is
+     *   created with L1 and L2 as the parents (in that order). Using a service
+     *   loader to locate providers with L3 as the context will locate providers
+     *   in the following order: L3, L1, L0, L2. </p></li>
+     *
+     *   <li><p> If a module declares more than one provider then the providers
+     *   are located in the order that its module descriptor
+     *   {@linkplain java.lang.module.ModuleDescriptor.Provides#providers()
+     *   lists the providers}. Providers added dynamically by instrumentation
+     *   agents are always located after providers declared by the module. </p></li>
+     *
+     *   <li><p> The ordering of modules in a module layer is not defined. </p></li>
+     * </ul>
      *
      * @apiNote Unlike the other load methods defined here, the service type
      * is the second parameter. The reason for this is to avoid source
@@ -1564,26 +1773,25 @@
     }
 
     /**
-     * Load the first available provider of this loader's service. This
+     * Load the first available service provider of this loader's service. This
      * convenience method is equivalent to invoking the {@link #iterator()
      * iterator()} method and obtaining the first element. It therefore
      * returns the first element from the provider cache if possible, it
      * otherwise attempts to load and instantiate the first provider.
      *
-     * <p> The following example loads the first available provider. If there
-     * are no providers deployed then it uses a default implementation.
+     * <p> The following example loads the first available service provider. If
+     * no service providers are located then it uses a default implementation.
      * <pre>{@code
-     *    CodecSet provider =
-     *        ServiceLoader.load(CodecSet.class).findFirst().orElse(DEFAULT_CODECSET);
+     *    CodecFactory factory = ServiceLoader.load(CodecFactory.class)
+     *                                        .findFirst()
+     *                                        .orElse(DEFAULT_CODECSET_FACTORY);
      * }</pre>
-     * @return The first provider or empty {@code Optional} if no providers
-     *         are located
+     * @return The first service provider or empty {@code Optional} if no
+     *         service providers are located
      *
      * @throws ServiceConfigurationError
-     *         If a provider class cannot be loaded, doesn't have the
-     *         appropriate static factory method or constructor, can't be
-     *         assigned to the service type, or if any other kind of exception
-     *         or error is thrown when locating or instantiating the provider.
+     *         If a provider class cannot be loaded for any of the reasons
+     *         specified in the <a href="#errors">Errors</a> section above.
      *
      * @since 9
      * @spec JPMS
@@ -1603,11 +1811,11 @@
      *
      * <p> After invoking this method, subsequent invocations of the {@link
      * #iterator() iterator} or {@link #stream() stream} methods will lazily
-     * look up providers (and instantiate in the case of {@code iterator})
-     * from scratch, just as is done by a newly-created loader.
+     * locate providers (and instantiate in the case of {@code iterator})
+     * from scratch, just as is done by a newly-created service loader.
      *
-     * <p> This method is intended for use in situations in which new providers
-     * can be installed into a running Java virtual machine.
+     * <p> This method is intended for use in situations in which new service
+     * providers can be installed into a running Java virtual machine.
      */
     public void reload() {
         lookupIterator1 = null;
--- a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicInteger.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicInteger.java	Thu Jun 29 13:07:19 2017 -0700
@@ -249,7 +249,8 @@
     }
 
     /**
-     * Atomically updates the current value with the results of
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the current value with the results of
      * applying the given function, returning the previous value. The
      * function should be side-effect-free, since it may be re-applied
      * when attempted updates fail due to contention among threads.
@@ -270,7 +271,8 @@
     }
 
     /**
-     * Atomically updates the current value with the results of
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the current value with the results of
      * applying the given function, returning the updated value. The
      * function should be side-effect-free, since it may be re-applied
      * when attempted updates fail due to contention among threads.
@@ -291,13 +293,14 @@
     }
 
     /**
-     * Atomically updates the current value with the results of
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the current value with the results of
      * applying the given function to the current and given values,
      * returning the previous value. The function should be
      * side-effect-free, since it may be re-applied when attempted
-     * updates fail due to contention among threads.  The function
-     * is applied with the current value as its first argument,
-     * and the given update as the second argument.
+     * updates fail due to contention among threads.  The function is
+     * applied with the current value as its first argument, and the
+     * given update as the second argument.
      *
      * @param x the update value
      * @param accumulatorFunction a side-effect-free function of two arguments
@@ -317,13 +320,14 @@
     }
 
     /**
-     * Atomically updates the current value with the results of
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the current value with the results of
      * applying the given function to the current and given values,
      * returning the updated value. The function should be
      * side-effect-free, since it may be re-applied when attempted
-     * updates fail due to contention among threads.  The function
-     * is applied with the current value as its first argument,
-     * and the given update as the second argument.
+     * updates fail due to contention among threads.  The function is
+     * applied with the current value as its first argument, and the
+     * given update as the second argument.
      *
      * @param x the update value
      * @param accumulatorFunction a side-effect-free function of two arguments
--- a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerArray.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerArray.java	Thu Jun 29 13:07:19 2017 -0700
@@ -260,10 +260,12 @@
     }
 
     /**
-     * Atomically updates the element at index {@code i} with the results
-     * of applying the given function, returning the previous value. The
-     * function should be side-effect-free, since it may be re-applied
-     * when attempted updates fail due to contention among threads.
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the element at index {@code i} with
+     * the results of applying the given function, returning the
+     * previous value. The function should be side-effect-free, since
+     * it may be re-applied when attempted updates fail due to
+     * contention among threads.
      *
      * @param i the index
      * @param updateFunction a side-effect-free function
@@ -282,10 +284,12 @@
     }
 
     /**
-     * Atomically updates the element at index {@code i} with the results
-     * of applying the given function, returning the updated value. The
-     * function should be side-effect-free, since it may be re-applied
-     * when attempted updates fail due to contention among threads.
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the element at index {@code i} with
+     * the results of applying the given function, returning the
+     * updated value. The function should be side-effect-free, since it
+     * may be re-applied when attempted updates fail due to contention
+     * among threads.
      *
      * @param i the index
      * @param updateFunction a side-effect-free function
@@ -304,10 +308,11 @@
     }
 
     /**
-     * Atomically updates the element at index {@code i} with the
-     * results of applying the given function to the current and given
-     * values, returning the previous value. The function should be
-     * side-effect-free, since it may be re-applied when attempted
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the element at index {@code i} with
+     * the results of applying the given function to the current and
+     * given values, returning the previous value. The function should
+     * be side-effect-free, since it may be re-applied when attempted
      * updates fail due to contention among threads.  The function is
      * applied with the current value of the element at index {@code i}
      * as its first argument, and the given update as the second
@@ -332,10 +337,11 @@
     }
 
     /**
-     * Atomically updates the element at index {@code i} with the
-     * results of applying the given function to the current and given
-     * values, returning the updated value. The function should be
-     * side-effect-free, since it may be re-applied when attempted
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the element at index {@code i} with
+     * the results of applying the given function to the current and
+     * given values, returning the updated value. The function should
+     * be side-effect-free, since it may be re-applied when attempted
      * updates fail due to contention among threads.  The function is
      * applied with the current value of the element at index {@code i}
      * as its first argument, and the given update as the second
--- a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java	Thu Jun 29 13:07:19 2017 -0700
@@ -46,6 +46,7 @@
 import jdk.internal.misc.Unsafe;
 import jdk.internal.reflect.CallerSensitive;
 import jdk.internal.reflect.Reflection;
+import java.lang.invoke.VarHandle;
 
 /**
  * A reflection-based utility that enables atomic updates to
@@ -275,10 +276,12 @@
     }
 
     /**
-     * Atomically updates the field of the given object managed by this updater
-     * with the results of applying the given function, returning the previous
-     * value. The function should be side-effect-free, since it may be
-     * re-applied when attempted updates fail due to contention among threads.
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the field of the given object managed
+     * by this updater with the results of applying the given
+     * function, returning the previous value. The function should be
+     * side-effect-free, since it may be re-applied when attempted
+     * updates fail due to contention among threads.
      *
      * @param obj An object whose field to get and set
      * @param updateFunction a side-effect-free function
@@ -295,10 +298,12 @@
     }
 
     /**
-     * Atomically updates the field of the given object managed by this updater
-     * with the results of applying the given function, returning the updated
-     * value. The function should be side-effect-free, since it may be
-     * re-applied when attempted updates fail due to contention among threads.
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the field of the given object managed
+     * by this updater with the results of applying the given
+     * function, returning the updated value. The function should be
+     * side-effect-free, since it may be re-applied when attempted
+     * updates fail due to contention among threads.
      *
      * @param obj An object whose field to get and set
      * @param updateFunction a side-effect-free function
@@ -315,13 +320,14 @@
     }
 
     /**
-     * Atomically updates the field of the given object managed by this
-     * updater with the results of applying the given function to the
-     * current and given values, returning the previous value. The
-     * function should be side-effect-free, since it may be re-applied
-     * when attempted updates fail due to contention among threads.  The
-     * function is applied with the current value as its first argument,
-     * and the given update as the second argument.
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the field of the given object managed
+     * by this updater with the results of applying the given function
+     * to the current and given values, returning the previous value.
+     * The function should be side-effect-free, since it may be
+     * re-applied when attempted updates fail due to contention among
+     * threads.  The function is applied with the current value as its
+     * first argument, and the given update as the second argument.
      *
      * @param obj An object whose field to get and set
      * @param x the update value
@@ -340,13 +346,14 @@
     }
 
     /**
-     * Atomically updates the field of the given object managed by this
-     * updater with the results of applying the given function to the
-     * current and given values, returning the updated value. The
-     * function should be side-effect-free, since it may be re-applied
-     * when attempted updates fail due to contention among threads.  The
-     * function is applied with the current value as its first argument,
-     * and the given update as the second argument.
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the field of the given object managed
+     * by this updater with the results of applying the given function
+     * to the current and given values, returning the updated value.
+     * The function should be side-effect-free, since it may be
+     * re-applied when attempted updates fail due to contention among
+     * threads.  The function is applied with the current value as its
+     * first argument, and the given update as the second argument.
      *
      * @param obj An object whose field to get and set
      * @param x the update value
--- a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLong.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLong.java	Thu Jun 29 13:07:19 2017 -0700
@@ -118,8 +118,7 @@
      * @param newValue the new value
      */
     public final void set(long newValue) {
-        // Use putLongVolatile instead of ordinary volatile store when
-        // using compareAndSetLong, for sake of some 32bit systems.
+        // See JDK-8180620: Clarify VarHandle mixed-access subtleties
         U.putLongVolatile(this, VALUE, newValue);
     }
 
@@ -265,7 +264,8 @@
     }
 
     /**
-     * Atomically updates the current value with the results of
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the current value with the results of
      * applying the given function, returning the previous value. The
      * function should be side-effect-free, since it may be re-applied
      * when attempted updates fail due to contention among threads.
@@ -286,7 +286,8 @@
     }
 
     /**
-     * Atomically updates the current value with the results of
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the current value with the results of
      * applying the given function, returning the updated value. The
      * function should be side-effect-free, since it may be re-applied
      * when attempted updates fail due to contention among threads.
@@ -307,13 +308,14 @@
     }
 
     /**
-     * Atomically updates the current value with the results of
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the current value with the results of
      * applying the given function to the current and given values,
      * returning the previous value. The function should be
      * side-effect-free, since it may be re-applied when attempted
-     * updates fail due to contention among threads.  The function
-     * is applied with the current value as its first argument,
-     * and the given update as the second argument.
+     * updates fail due to contention among threads.  The function is
+     * applied with the current value as its first argument, and the
+     * given update as the second argument.
      *
      * @param x the update value
      * @param accumulatorFunction a side-effect-free function of two arguments
@@ -333,13 +335,14 @@
     }
 
     /**
-     * Atomically updates the current value with the results of
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the current value with the results of
      * applying the given function to the current and given values,
      * returning the updated value. The function should be
      * side-effect-free, since it may be re-applied when attempted
-     * updates fail due to contention among threads.  The function
-     * is applied with the current value as its first argument,
-     * and the given update as the second argument.
+     * updates fail due to contention among threads.  The function is
+     * applied with the current value as its first argument, and the
+     * given update as the second argument.
      *
      * @param x the update value
      * @param accumulatorFunction a side-effect-free function of two arguments
--- a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongArray.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongArray.java	Thu Jun 29 13:07:19 2017 -0700
@@ -260,10 +260,12 @@
     }
 
     /**
-     * Atomically updates the element at index {@code i} with the results
-     * of applying the given function, returning the previous value. The
-     * function should be side-effect-free, since it may be re-applied
-     * when attempted updates fail due to contention among threads.
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the element at index {@code i} with
+     * the results of applying the given function, returning the
+     * previous value. The function should be side-effect-free, since
+     * it may be re-applied when attempted updates fail due to
+     * contention among threads.
      *
      * @param i the index
      * @param updateFunction a side-effect-free function
@@ -282,10 +284,12 @@
     }
 
     /**
-     * Atomically updates the element at index {@code i} with the results
-     * of applying the given function, returning the updated value. The
-     * function should be side-effect-free, since it may be re-applied
-     * when attempted updates fail due to contention among threads.
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the element at index {@code i} with
+     * the results of applying the given function, returning the
+     * updated value. The function should be side-effect-free, since it
+     * may be re-applied when attempted updates fail due to contention
+     * among threads.
      *
      * @param i the index
      * @param updateFunction a side-effect-free function
@@ -304,10 +308,11 @@
     }
 
     /**
-     * Atomically updates the element at index {@code i} with the
-     * results of applying the given function to the current and given
-     * values, returning the previous value. The function should be
-     * side-effect-free, since it may be re-applied when attempted
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the element at index {@code i} with
+     * the results of applying the given function to the current and
+     * given values, returning the previous value. The function should
+     * be side-effect-free, since it may be re-applied when attempted
      * updates fail due to contention among threads.  The function is
      * applied with the current value of the element at index {@code i}
      * as its first argument, and the given update as the second
@@ -332,10 +337,11 @@
     }
 
     /**
-     * Atomically updates the element at index {@code i} with the
-     * results of applying the given function to the current and given
-     * values, returning the updated value. The function should be
-     * side-effect-free, since it may be re-applied when attempted
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the element at index {@code i} with
+     * the results of applying the given function to the current and
+     * given values, returning the updated value. The function should
+     * be side-effect-free, since it may be re-applied when attempted
      * updates fail due to contention among threads.  The function is
      * applied with the current value of the element at index {@code i}
      * as its first argument, and the given update as the second
--- a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java	Thu Jun 29 13:07:19 2017 -0700
@@ -46,6 +46,7 @@
 import jdk.internal.misc.Unsafe;
 import jdk.internal.reflect.CallerSensitive;
 import jdk.internal.reflect.Reflection;
+import java.lang.invoke.VarHandle;
 
 /**
  * A reflection-based utility that enables atomic updates to
@@ -278,10 +279,12 @@
     }
 
     /**
-     * Atomically updates the field of the given object managed by this updater
-     * with the results of applying the given function, returning the previous
-     * value. The function should be side-effect-free, since it may be
-     * re-applied when attempted updates fail due to contention among threads.
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the field of the given object managed
+     * by this updater with the results of applying the given
+     * function, returning the previous value. The function should be
+     * side-effect-free, since it may be re-applied when attempted
+     * updates fail due to contention among threads.
      *
      * @param obj An object whose field to get and set
      * @param updateFunction a side-effect-free function
@@ -298,10 +301,12 @@
     }
 
     /**
-     * Atomically updates the field of the given object managed by this updater
-     * with the results of applying the given function, returning the updated
-     * value. The function should be side-effect-free, since it may be
-     * re-applied when attempted updates fail due to contention among threads.
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the field of the given object managed
+     * by this updater with the results of applying the given
+     * function, returning the updated value. The function should be
+     * side-effect-free, since it may be re-applied when attempted
+     * updates fail due to contention among threads.
      *
      * @param obj An object whose field to get and set
      * @param updateFunction a side-effect-free function
@@ -318,13 +323,14 @@
     }
 
     /**
-     * Atomically updates the field of the given object managed by this
-     * updater with the results of applying the given function to the
-     * current and given values, returning the previous value. The
-     * function should be side-effect-free, since it may be re-applied
-     * when attempted updates fail due to contention among threads.  The
-     * function is applied with the current value as its first argument,
-     * and the given update as the second argument.
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the field of the given object managed
+     * by this updater with the results of applying the given function
+     * to the current and given values, returning the previous value.
+     * The function should be side-effect-free, since it may be
+     * re-applied when attempted updates fail due to contention among
+     * threads.  The function is applied with the current value as its
+     * first argument, and the given update as the second argument.
      *
      * @param obj An object whose field to get and set
      * @param x the update value
@@ -343,13 +349,14 @@
     }
 
     /**
-     * Atomically updates the field of the given object managed by this
-     * updater with the results of applying the given function to the
-     * current and given values, returning the updated value. The
-     * function should be side-effect-free, since it may be re-applied
-     * when attempted updates fail due to contention among threads.  The
-     * function is applied with the current value as its first argument,
-     * and the given update as the second argument.
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the field of the given object managed
+     * by this updater with the results of applying the given function
+     * to the current and given values, returning the updated value.
+     * The function should be side-effect-free, since it may be
+     * re-applied when attempted updates fail due to contention among
+     * threads.  The function is applied with the current value as its
+     * first argument, and the given update as the second argument.
      *
      * @param obj An object whose field to get and set
      * @param x the update value
--- a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReference.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReference.java	Thu Jun 29 13:07:19 2017 -0700
@@ -170,7 +170,8 @@
     }
 
     /**
-     * Atomically updates the current value with the results of
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the current value with the results of
      * applying the given function, returning the previous value. The
      * function should be side-effect-free, since it may be re-applied
      * when attempted updates fail due to contention among threads.
@@ -191,7 +192,8 @@
     }
 
     /**
-     * Atomically updates the current value with the results of
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the current value with the results of
      * applying the given function, returning the updated value. The
      * function should be side-effect-free, since it may be re-applied
      * when attempted updates fail due to contention among threads.
@@ -212,13 +214,14 @@
     }
 
     /**
-     * Atomically updates the current value with the results of
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the current value with the results of
      * applying the given function to the current and given values,
      * returning the previous value. The function should be
      * side-effect-free, since it may be re-applied when attempted
-     * updates fail due to contention among threads.  The function
-     * is applied with the current value as its first argument,
-     * and the given update as the second argument.
+     * updates fail due to contention among threads.  The function is
+     * applied with the current value as its first argument, and the
+     * given update as the second argument.
      *
      * @param x the update value
      * @param accumulatorFunction a side-effect-free function of two arguments
@@ -238,13 +241,14 @@
     }
 
     /**
-     * Atomically updates the current value with the results of
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the current value with the results of
      * applying the given function to the current and given values,
      * returning the updated value. The function should be
      * side-effect-free, since it may be re-applied when attempted
-     * updates fail due to contention among threads.  The function
-     * is applied with the current value as its first argument,
-     * and the given update as the second argument.
+     * updates fail due to contention among threads.  The function is
+     * applied with the current value as its first argument, and the
+     * given update as the second argument.
      *
      * @param x the update value
      * @param accumulatorFunction a side-effect-free function of two arguments
--- a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceArray.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceArray.java	Thu Jun 29 13:07:19 2017 -0700
@@ -190,10 +190,12 @@
     }
 
     /**
-     * Atomically updates the element at index {@code i} with the results
-     * of applying the given function, returning the previous value. The
-     * function should be side-effect-free, since it may be re-applied
-     * when attempted updates fail due to contention among threads.
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the element at index {@code i} with
+     * the results of applying the given function, returning the
+     * previous value. The function should be side-effect-free, since
+     * it may be re-applied when attempted updates fail due to
+     * contention among threads.
      *
      * @param i the index
      * @param updateFunction a side-effect-free function
@@ -212,10 +214,12 @@
     }
 
     /**
-     * Atomically updates the element at index {@code i} with the results
-     * of applying the given function, returning the updated value. The
-     * function should be side-effect-free, since it may be re-applied
-     * when attempted updates fail due to contention among threads.
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the element at index {@code i} with
+     * the results of applying the given function, returning the
+     * updated value. The function should be side-effect-free, since it
+     * may be re-applied when attempted updates fail due to contention
+     * among threads.
      *
      * @param i the index
      * @param updateFunction a side-effect-free function
@@ -234,10 +238,11 @@
     }
 
     /**
-     * Atomically updates the element at index {@code i} with the
-     * results of applying the given function to the current and given
-     * values, returning the previous value. The function should be
-     * side-effect-free, since it may be re-applied when attempted
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the element at index {@code i} with
+     * the results of applying the given function to the current and
+     * given values, returning the previous value. The function should
+     * be side-effect-free, since it may be re-applied when attempted
      * updates fail due to contention among threads.  The function is
      * applied with the current value of the element at index {@code i}
      * as its first argument, and the given update as the second
@@ -262,10 +267,11 @@
     }
 
     /**
-     * Atomically updates the element at index {@code i} with the
-     * results of applying the given function to the current and given
-     * values, returning the updated value. The function should be
-     * side-effect-free, since it may be re-applied when attempted
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the element at index {@code i} with
+     * the results of applying the given function to the current and
+     * given values, returning the updated value. The function should
+     * be side-effect-free, since it may be re-applied when attempted
      * updates fail due to contention among threads.  The function is
      * applied with the current value of the element at index {@code i}
      * as its first argument, and the given update as the second
--- a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java	Thu Jun 29 13:07:19 2017 -0700
@@ -46,6 +46,7 @@
 import jdk.internal.misc.Unsafe;
 import jdk.internal.reflect.CallerSensitive;
 import jdk.internal.reflect.Reflection;
+import java.lang.invoke.VarHandle;
 
 /**
  * A reflection-based utility that enables atomic updates to
@@ -199,10 +200,12 @@
     }
 
     /**
-     * Atomically updates the field of the given object managed by this updater
-     * with the results of applying the given function, returning the previous
-     * value. The function should be side-effect-free, since it may be
-     * re-applied when attempted updates fail due to contention among threads.
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the field of the given object managed
+     * by this updater with the results of applying the given
+     * function, returning the previous value. The function should be
+     * side-effect-free, since it may be re-applied when attempted
+     * updates fail due to contention among threads.
      *
      * @param obj An object whose field to get and set
      * @param updateFunction a side-effect-free function
@@ -219,10 +222,12 @@
     }
 
     /**
-     * Atomically updates the field of the given object managed by this updater
-     * with the results of applying the given function, returning the updated
-     * value. The function should be side-effect-free, since it may be
-     * re-applied when attempted updates fail due to contention among threads.
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the field of the given object managed
+     * by this updater with the results of applying the given
+     * function, returning the updated value. The function should be
+     * side-effect-free, since it may be re-applied when attempted
+     * updates fail due to contention among threads.
      *
      * @param obj An object whose field to get and set
      * @param updateFunction a side-effect-free function
@@ -239,13 +244,14 @@
     }
 
     /**
-     * Atomically updates the field of the given object managed by this
-     * updater with the results of applying the given function to the
-     * current and given values, returning the previous value. The
-     * function should be side-effect-free, since it may be re-applied
-     * when attempted updates fail due to contention among threads.  The
-     * function is applied with the current value as its first argument,
-     * and the given update as the second argument.
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the field of the given object managed
+     * by this updater with the results of applying the given function
+     * to the current and given values, returning the previous value.
+     * The function should be side-effect-free, since it may be
+     * re-applied when attempted updates fail due to contention among
+     * threads.  The function is applied with the current value as its
+     * first argument, and the given update as the second argument.
      *
      * @param obj An object whose field to get and set
      * @param x the update value
@@ -264,13 +270,14 @@
     }
 
     /**
-     * Atomically updates the field of the given object managed by this
-     * updater with the results of applying the given function to the
-     * current and given values, returning the updated value. The
-     * function should be side-effect-free, since it may be re-applied
-     * when attempted updates fail due to contention among threads.  The
-     * function is applied with the current value as its first argument,
-     * and the given update as the second argument.
+     * Atomically updates (with memory effects as specified by {@link
+     * VarHandle#compareAndSet}) the field of the given object managed
+     * by this updater with the results of applying the given function
+     * to the current and given values, returning the updated value.
+     * The function should be side-effect-free, since it may be
+     * re-applied when attempted updates fail due to contention among
+     * threads.  The function is applied with the current value as its
+     * first argument, and the given update as the second argument.
      *
      * @param obj An object whose field to get and set
      * @param x the update value
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.base/share/classes/java/util/doc-files/coll-designfaq.html	Thu Jun 29 13:07:19 2017 -0700
@@ -0,0 +1,399 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<!--
+ Copyright (c) 1998, 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.
+-->
+
+<html lang="en-US" xmlns="http://www.w3.org/1999/xhtml" xml:lang=
+"en-US">
+<head>
+<title>Java Collections API Design FAQ</title>
+</head>
+<body>
+<h2>Java Collections API Design FAQ</h2>
+<!-- Body text begins here -->
+<hr />
+This document answers frequently asked questions concerning the
+design of the Java collections framework. It is derived from the
+large volume of traffic on the collections-comments alias. It
+serves as a design rationale for the collections framework.
+<h3>Core Interfaces - General Questions</h3>
+<ol>
+<li><a href="#a1"><b>Why don't you support immutability directly in
+the core collection interfaces so that you can do away with
+<em>optional operations</em> (and
+UnsupportedOperationException)?</b></a></li>
+<li><a href="#a2"><b>Won't programmers have to surround any code
+that calls optional operations with a try-catch clause in case they
+throw an UnsupportedOperationException?</b></a></li>
+<li><a href="#a3"><b>Why isn't there a core interface for "bags"
+(AKA multisets)?</b></a></li>
+<li><a href="#a28"><b>Why didn't you use "Beans-style names" for
+consistency?</b></a></li>
+</ol>
+<h3>Collection Interface</h3>
+<ol>
+<li><a href="#a5"><b>Why doesn't Collection extend Cloneable and
+Serializable?</b></a></li>
+<li><a href="#a6"><b>Why don't you provide an "apply" method in
+Collection to apply a given method ("upcall") to all the elements
+of the Collection?</b></a></li>
+<li><a href="#a7"><b>Why didn't you provide a "Predicate" interface,
+and related methods (e.g., a method to find the first element in
+the Collection satisfying the predicate)?</b></a></li>
+<li><a href="#a8"><b>Why don't you provide a form of the addAll
+method that takes an Enumeration (or an Iterator)?</b></a></li>
+<li><a href="#a9"><b>Why don't the concrete implementations in the
+JDK have Enumeration (or Iterator) constructors?</b></a></li>
+<li><a href="#a10"><b>Why don't you provide an Iterator.add
+method?</b></a></li>
+</ol>
+<h3>List Interface</h3>
+<ol>
+<li><a href="#a11"><b>Why don't you rename the List interface to
+Sequence; doesn't "list" generally suggest "linked list"? Also,
+doesn't it conflict with java.awt.List?</b></a></li>
+<li><a href="#a12"><b>Why don't you rename List's set method to
+replace, to avoid confusion with Set.</b></a></li>
+</ol>
+<h3>Map Interface</h3>
+<ol>
+<li><a href="#a14"><b>Why doesn't Map extend
+Collection?</b></a></li>
+</ol>
+<h3>Iterator Interface</h3>
+<ol>
+<li><a href="#a18"><b>Why doesn't Iterator extend
+Enumeration?</b></a></li>
+<li><a href="#a19"><b>Why don't you provide an Iterator.peek method
+that allows you to look at the next element in an iteration without
+advancing the iterator?</b></a></li>
+</ol>
+<h3>Miscellaneous</h3>
+<ol>
+<li><a href="#a23"><b>Why did you write a new collections framework
+instead of adopting JGL (a preexisting collections package from
+ObjectSpace, Inc.) into the JDK?</b></a></li>
+<li><a href="#a26"><b>Why don't you eliminate all of the methods and
+classes that return "views" (Collections backed by other
+collection-like objects). This would greatly reduce
+aliasing.</b></a></li>
+<li><a href="#a27"><b>Why don't you provide for "observable"
+collections that send out Events when they're
+modified?</b></a></li>
+</ol>
+<hr size="3" noshade="noshade" />
+<h3>Core Interfaces - General Questions</h3>
+<ol>
+<li><a name="a1" id="a1"><b>Why don't you support immutability
+directly in the core collection interfaces so that you can do away
+with <em>optional operations</em> (and
+UnsupportedOperationException)?</b></a>
+<p>This is the most controversial design decision in the whole API.
+Clearly, static (compile time) type checking is highly desirable,
+and is the norm in Java. We would have supported it if we believed
+it were feasible. Unfortunately, attempts to achieve this goal
+cause an explosion in the size of the interface hierarchy, and do
+not succeed in eliminating the need for runtime exceptions (though
+they reduce it substantially).</p>
+<p>Doug Lea, who wrote a popular Java collections package that did
+reflect mutability distinctions in its interface hierarchy, no
+longer believes it is a viable approach, based on user experience
+with his collections package. In his words (from personal
+correspondence) "Much as it pains me to say it, strong static
+typing does not work for collection interfaces in Java."</p>
+<p>To illustrate the problem in gory detail, suppose you want to
+add the notion of modifiability to the Hierarchy. You need four new
+interfaces: ModifiableCollection, ModifiableSet, ModifiableList,
+and ModifiableMap. What was previously a simple hierarchy is now a
+messy heterarchy. Also, you need a new Iterator interface for use
+with unmodifiable Collections, that does not contain the remove
+operation. Now can you do away with UnsupportedOperationException?
+Unfortunately not.</p>
+<p>Consider arrays. They implement most of the List operations, but
+not remove and add. They are "fixed-size" Lists. If you want to
+capture this notion in the hierarchy, you have to add two new
+interfaces: VariableSizeList and VariableSizeMap. You don't have to
+add VariableSizeCollection and VariableSizeSet, because they'd be
+identical to ModifiableCollection and ModifiableSet, but you might
+choose to add them anyway for consistency's sake. Also, you need a
+new variety of ListIterator that doesn't support the add and remove
+operations, to go along with unmodifiable List. Now we're up to ten
+or twelve interfaces, plus two new Iterator interfaces, instead of
+our original four. Are we done? No.</p>
+<p>Consider logs (such as error logs, audit logs and journals for
+recoverable data objects). They are natural append-only sequences,
+that support all of the List operations except for remove and set
+(replace). They require a new core interface, and a new
+iterator.</p>
+<p>And what about immutable Collections, as opposed to unmodifiable
+ones? (i.e., Collections that cannot be changed by the client AND
+will never change for any other reason). Many argue that this is
+the most important distinction of all, because it allows multiple
+threads to access a collection concurrently without the need for
+synchronization. Adding this support to the type hierarchy requires
+four more interfaces.</p>
+<p>Now we're up to twenty or so interfaces and five iterators, and
+it's almost certain that there are still collections arising in
+practice that don't fit cleanly into any of the interfaces. For
+example, the <em>collection-views</em> returned by Map are natural
+delete-only collections. Also, there are collections that will
+reject certain elements on the basis of their value, so we still
+haven't done away with runtime exceptions.</p>
+<p>When all was said and done, we felt that it was a sound
+engineering compromise to sidestep the whole issue by providing a
+very small set of core interfaces that can throw a runtime
+exception.</p>
+</li>
+<li><a name="a2" id="a2"><b>Won't programmers have to surround any
+code that calls optional operations with a try-catch clause in case
+they throw an UnsupportedOperationException?</b></a>
+<p>It was never our intention that programs should catch these
+exceptions: that's why they're unchecked (runtime) exceptions. They
+should only arise as a result of programming errors, in which case,
+your program will halt due to the uncaught exception.</p>
+</li>
+<li><a name="a3" id="a3"><b>Why isn't there a core interface for
+"bags" (AKA multisets)?</b></a>
+<p>The Collection interface provides this functionality. We are not
+providing any public implementations of this interface, as we think
+that it wouldn't be used frequently enough to "pull its weight." We
+occasionally return such Collections, which are implemented easily
+atop AbstractCollection (for example, the Collection returned by
+Map.values).</p>
+</li>
+<li><a name="a28" id="a28"><b>Why didn't you use "Beans-style
+names" for consistency?</b></a>
+<p>While the names of the new collections methods do not adhere to
+the "Beans naming conventions", we believe that they are
+reasonable, consistent and appropriate to their purpose. It should
+be remembered that the Beans naming conventions do not apply to the
+JDK as a whole; the AWT did adopt these conventions, but that
+decision was somewhat controversial. We suspect that the
+collections APIs will be used quite pervasively, often with
+multiple method calls on a single line of code, so it is important
+that the names be short. Consider, for example, the Iterator
+methods. Currently, a loop over a collection looks like this:</p>
+<pre>
+    for (Iterator i = c.iterator(); i.hasNext(); )
+        System.out.println(i.next());
+</pre>
+Everything fits neatly on one line, even if the Collection name is
+a long expression. If we named the methods "getIterator",
+"hasNextElement" and "getNextElement", this would no longer be the
+case. Thus, we adopted the "traditional" JDK style rather than the
+Beans style.</li>
+</ol>
+<hr />
+<h3>Collection Interface</h3>
+<ol>
+<li><a name="a5" id="a5"><b>Why doesn't Collection extend Cloneable
+and Serializable?</b></a>
+<p>Many Collection implementations (including all of the ones
+provided by the JDK) will have a public clone method, but it would
+be mistake to require it of all Collections. For example, what does
+it mean to clone a Collection that's backed by a terabyte SQL
+database? Should the method call cause the company to requisition a
+new disk farm? Similar arguments hold for serializable.</p>
+<p>If the client doesn't know the actual type of a Collection, it's
+much more flexible and less error prone to have the client decide
+what type of Collection is desired, create an empty Collection of
+this type, and use the addAll method to copy the elements of the
+original collection into the new one.</p>
+</li>
+<li><a name="a6" id="a6"><b>Why don't you provide an "apply" method
+in Collection to apply a given method ("upcall") to all the
+elements of the Collection?</b></a>
+<p>This is what is referred to as an "Internal Iterator" in the
+"Design Patterns" book (Gamma et al.). We considered providing it,
+but decided not to as it seems somewhat redundant to support
+internal and external iterators, and Java already has a precedent
+for external iterators (with Enumerations). The "throw weight" of
+this functionality is increased by the fact that it requires a
+public interface to describe upcalls.</p>
+</li>
+<li><a name="a7" id="a7"><b>Why didn't you provide a "Predicate"
+interface, and related methods (e.g., a method to find the first
+element in the Collection satisfying the predicate)?</b></a>
+<p>It's easy to implement this functionality atop Iterators, and
+the resulting code may actually look cleaner as the user can inline
+the predicate. Thus, it's not clear whether this facility pulls its
+weight. It could be added to the Collections class at a later date
+(implemented atop Iterator), if it's deemed useful.</p>
+</li>
+<li><a name="a8" id="a8"><b>Why don't you provide a form of the
+addAll method that takes an Enumeration (or an Iterator)?</b></a>
+<p>Because we don't believe in using Enumerations (or Iterators) as
+"poor man's collections." This was occasionally done in prior
+releases, but now that we have the Collection interface, it is the
+preferred way to pass around abstract collections of objects.</p>
+</li>
+<li><a name="a9" id="a9"><b>Why don't the concrete implementations
+in the JDK have Enumeration (or Iterator) constructors?</b></a>
+<p>Again, this is an instance of an Enumeration serving as a "poor
+man's collection" and we're trying to discourage that. Note
+however, that we strongly suggest that all concrete implementations
+should have constructors that take a Collection (and create a new
+Collection with the same elements).</p>
+</li>
+<li><a name="a10" id="a10"><b>Why don't you provide an Iterator.add
+method?</b></a>
+<p>The semantics are unclear, given that the contract for Iterator
+makes no guarantees about the order of iteration. Note, however,
+that ListIterator does provide an add operation, as it does
+guarantee the order of the iteration.</p>
+</li>
+</ol>
+<hr />
+<h3>List Interface</h3>
+<ol>
+<li><a name="a11" id="a11"><b>Why don't you rename the List
+interface to Sequence; doesn't "list" generally suggest "linked
+list"? Also, doesn't it conflict with java.awt.List?</b></a>
+<p>People were evenly divided as to whether List suggests linked
+lists. Given the implementation naming convention,
+&lt;<em>Implementation</em>&gt;&lt;<em>Interface</em>&gt;, there
+was a strong desire to keep the core interface names short. Also,
+several existing names (AbstractSequentialList, LinkedList) would
+have been decidedly worse if we changed List to Sequence. The
+naming conflict can be dealt with by the following incantation:</p>
+<pre>
+    import java.util.*;
+    import java.awt.*;
+    import java.util.List;   // Dictates interpretation of "List"
+</pre></li>
+<li><a name="a12" id="a12"><b>Why don't you rename List's set
+method to replace, to avoid confusion with Set.</b></a>
+<p>It was decided that the "set/get" naming convention was strongly
+enough enshrined in the language that we'd stick with it.</p>
+</li>
+</ol>
+<hr />
+<h3>Map Interface</h3>
+<ol>
+<li><a name="a14" id="a14"><b>Why doesn't Map extend
+Collection?</b></a>
+<p>This was by design. We feel that mappings are not collections
+and collections are not mappings. Thus, it makes little sense for
+Map to extend the Collection interface (or vice versa).</p>
+<p>If a Map is a Collection, what are the elements? The only
+reasonable answer is "Key-value pairs", but this provides a very
+limited (and not particularly useful) Map abstraction. You can't
+ask what value a given key maps to, nor can you delete the entry
+for a given key without knowing what value it maps to.</p>
+<p>Collection could be made to extend Map, but this raises the
+question: what are the keys? There's no really satisfactory answer,
+and forcing one leads to an unnatural interface.</p>
+<p>Maps can be <em>viewed</em> as Collections (of keys, values, or
+pairs), and this fact is reflected in the three "Collection view
+operations" on Maps (keySet, entrySet, and values). While it is, in
+principle, possible to view a List as a Map mapping indices to
+elements, this has the nasty property that deleting an element from
+the List changes the Key associated with every element before the
+deleted element. That's why we don't have a map view operation on
+Lists.</p>
+</li>
+</ol>
+<hr />
+<h3>Iterator Interface</h3>
+<ol>
+<li><a name="a18" id="a18"><b>Why doesn't Iterator extend
+Enumeration?</b></a>
+<p>We view the method names for Enumeration as unfortunate. They're
+very long, and very frequently used. Given that we were adding a
+method and creating a whole new framework, we felt that it would be
+foolish not to take advantage of the opportunity to improve the
+names. Of course we could support the new and old names in
+Iterator, but it doesn't seem worthwhile.</p>
+</li>
+<li><a name="a19" id="a19"><b>Why don't you provide an
+Iterator.peek method that allows you to look at the next element in
+an iteration without advancing the iterator?</b></a>
+<p>It can be implemented atop the current Iterators (a similar
+pattern to java.io.PushbackInputStream). We believe that its use
+would be rare enough that it isn't worth including in the interface
+that everyone has to implement.</p>
+</li>
+</ol>
+<hr />
+<h3>Miscellaneous</h3>
+<ol>
+<li><a name="a23" id="a23"><b>Why did you write a new collections
+framework instead of adopting JGL (a preexisting collections
+package from ObjectSpace, Inc.) into the JDK?</b></a>
+<p>If you examine the goals for our Collections framework (in the
+Overview), you'll see that we are not really "playing in the same
+space" as JGL. Quoting from the "Design Goals" Section of the Java
+Collections Overview: "Our main design goal was to produce an API
+that was reasonably small, both in size, and (more importantly) in
+'conceptual weight.'"</p>
+<p>JGL consists of approximately 130 classes and interfaces; its
+main goal was consistency with the C++ Standard Template Library
+(STL). This was <em>not</em> one of our goals. Java has
+traditionally stayed away from C++'s more complex features (e.g.,
+multiple inheritance, operator overloading). Our entire framework,
+including all infrastructure, contains approximately 25 classes and
+interfaces.</p>
+<p>While this may cause some discomfort for some C++ programmers,
+we feel that it will be good for Java in the long run. As the Java
+libraries mature, they inevitably grow, but we are trying as hard
+as we can to keep them small and manageable, so that Java continues
+to be an easy, fun language to learn and to use.</p>
+</li>
+<li><a name="a26" id="a26"><b>Why don't you eliminate all of the
+methods and classes that return "views" (Collections backed by
+other collection-like objects). This would greatly reduce
+aliasing.</b></a>
+<p>Given that we provide core collection interfaces behind which
+programmers can "hide" their own implementations, there will be
+aliased collections whether the JDK provides them or not.
+Eliminating all views from the JDK would greatly increase the cost
+of common operations like making a Collection out of an array, and
+would do away with many useful facilities (like synchronizing
+wrappers). One view that we see as being particularly useful is
+<a href=
+"../List.html#subList-int-int-">List.subList</a>.
+The existence of this method means that people who write methods
+taking List on input do not have to write secondary forms taking an
+offset and a length (as they do for arrays).</p>
+</li>
+<li><a name="a27" id="a27"><b>Why don't you provide for
+"observable" collections that send out Events when they're
+modified?</b></a>
+<p>Primarily, resource constraints. If we're going to commit to
+such an API, it has to be something that works for everyone, that
+we can live with for the long haul. We may provide such a facility
+some day. In the meantime, it's not difficult to implement such a
+facility on top of the public APIs.</p>
+</li>
+</ol>
+<hr />
+<p style="font-size:smaller">
+Copyright &copy; 1998, 2017, Oracle and/or its affiliates. 500 Oracle Parkway<br />
+    Redwood Shores, CA 94065 USA. All rights reserved.</p>
+<!-- Body text ends here -->
+</body>
+</html>
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.base/share/classes/java/util/doc-files/coll-index.html	Thu Jun 29 13:07:19 2017 -0700
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<!--
+ Copyright (c) 1998, 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.
+-->
+
+<html lang="en-US" xmlns="http://www.w3.org/1999/xhtml" xml:lang=
+"en-US">
+<head>
+<meta name="generator" content="HTML Tidy, see www.w3.org" />
+<title>The Collections Framework</title>
+
+<style type="text/css">
+/*<![CDATA[*/
+
+ul li, ul ul li {font-weight: normal;}
+pre             {margin-left: 42pt;}
+a               {font-weight: bold;}
+
+/*]]>*/
+</style>
+</head>
+<body>
+<h1>The Collections Framework</h1>
+<!-- Body text begins here -->
+<p>The collections framework is a unified architecture for
+representing and manipulating collections, enabling them to be
+manipulated independently of the details of their representation.
+It reduces programming effort while increasing performance. It
+enables interoperability among unrelated APIs, reduces effort in
+designing and learning new APIs, and fosters software reuse. The
+framework is based on more than a dozen collection interfaces. It
+includes implementations of these interfaces and algorithms to
+manipulate them.</p>
+<p>The documents in this section are non-normative portions of
+the Java&trade; Platform, Standard Edition API Specification.</p>
+<ul>
+<li><b><a href="coll-overview.html">Overview</a></b> - An overview of
+the collections framework.</li>
+</ul>
+<ul>
+<li><b><a href="coll-reference.html">Annotated API Outline</a></b> - An
+annotated outline of the classes and interfaces comprising the
+collections framework, with links into the API Specification.</li>
+</ul>
+<ul>
+<li><b><a href="coll-designfaq.html">Design FAQ</a></b> - Answers to
+frequently asked questions (FAQ) about the design of the
+collections framework.</li>
+</ul>
+<hr />
+<p style="font-size:smaller">
+Copyright &copy; 1998, 2017, Oracle and/or its affiliates. 500 Oracle Parkway<br />
+    Redwood Shores, CA 94065 USA. All rights reserved.</p>
+<!-- Body text ends here -->
+</body>
+</html>
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.base/share/classes/java/util/doc-files/coll-overview.html	Thu Jun 29 13:07:19 2017 -0700
@@ -0,0 +1,359 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<!--
+ Copyright (c) 1998, 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.
+-->
+
+<html lang="en-US" xmlns="http://www.w3.org/1999/xhtml" xml:lang=
+"en-US">
+<head>
+<title>Collections Framework Overview</title>
+</head>
+<body>
+<h1>Collections Framework Overview</h1>
+<!-- Body text begins here -->
+<h2>Introduction</h2>
+The Java platform includes a <i>collections framework</i>. A
+<i>collection</i> is an object that represents a group of objects
+(such as the classic <a href="../ArrayList.html">ArrayList</a> class).
+A collections framework is a unified architecture for representing
+and manipulating collections, enabling collections to be
+manipulated independently of implementation details.
+<p>The primary advantages of a collections framework are that
+it:</p>
+<ul>
+<li><strong>Reduces programming effort</strong> by providing data
+structures and algorithms so you don't have to write them
+yourself.</li>
+<li><strong>Increases performance</strong> by providing
+high-performance implementations of data structures and algorithms.
+Because the various implementations of each interface are
+interchangeable, programs can be tuned by switching
+implementations.</li>
+<li><strong>Provides interoperability between unrelated
+APIs</strong> by establishing a common language to pass collections
+back and forth.</li>
+<li><strong>Reduces the effort required to learn APIs</strong> by
+requiring you to learn multiple ad hoc collection APIs.</li>
+<li><strong>Reduces the effort required to design and implement
+APIs</strong> by not requiring you to produce ad hoc collections
+APIs.</li>
+<li><strong>Fosters software reuse</strong> by providing a standard
+interface for collections and algorithms with which to manipulate
+them.</li>
+</ul>
+<p>The collections framework consists of:</p>
+<ul>
+<li><strong>Collection interfaces</strong>. Represent different
+types of collections, such as sets, lists, and maps. These
+interfaces form the basis of the framework.</li>
+<li><strong>General-purpose implementations</strong>. Primary
+implementations of the collection interfaces.</li>
+<li><strong>Legacy implementations</strong>. The collection classes
+from earlier releases, <tt>Vector</tt> and <tt>Hashtable</tt>, were
+retrofitted to implement the collection interfaces.</li>
+<li><strong>Special-purpose implementations</strong>.
+Implementations designed for use in special situations. These
+implementations display nonstandard performance characteristics,
+usage restrictions, or behavior.</li>
+<li><strong>Concurrent implementations</strong>. Implementations
+designed for highly concurrent use.</li>
+<li><strong>Wrapper implementations</strong>. Add functionality,
+such as synchronization, to other implementations.</li>
+<li><strong>Convenience implementations</strong>. High-performance
+"mini-implementations" of the collection interfaces.</li>
+<li><strong>Abstract implementations</strong>. Partial
+implementations of the collection interfaces to facilitate custom
+implementations.</li>
+<li><strong>Algorithms</strong>. Static methods that perform useful
+functions on collections, such as sorting a list.</li>
+<li><strong>Infrastructure</strong>. Interfaces that provide
+essential support for the collection interfaces.</li>
+<li><strong>Array Utilities</strong>. Utility functions for arrays
+of primitive types and reference objects. Not, strictly speaking, a
+part of the collections framework, this feature was added to the
+Java platform at the same time as the collections framework and
+relies on some of the same infrastructure.</li>
+</ul>
+<hr />
+<h2>Collection Interfaces</h2>
+<p>The <i>collection interfaces</i> are divided into two groups.
+The most basic interface, <tt><a href=
+"../Collection.html">java.util.Collection</a></tt>,
+has the following descendants:</p>
+<ul>
+<li><tt><a href=
+"../Set.html">java.util.Set</a></tt></li>
+<li><tt><a href=
+"../SortedSet.html">java.util.SortedSet</a></tt></li>
+<li><tt><a href=
+"../NavigableSet.html">java.util.NavigableSet</a></tt></li>
+<li><tt><a href=
+"../Queue.html">java.util.Queue</a></tt></li>
+<li><tt><a href=
+"../concurrent/BlockingQueue.html">java.util.concurrent.BlockingQueue</a></tt></li>
+<li><tt><a href=
+"../concurrent/TransferQueue.html">java.util.concurrent.TransferQueue</a></tt></li>
+<li><tt><a href=
+"../Deque.html">java.util.Deque</a></tt></li>
+<li><tt><a href=
+"../concurrent/BlockingDeque.html">java.util.concurrent.BlockingDeque</a></tt></li>
+</ul>
+<p>The other collection interfaces are based on <tt><a href=
+"../Map.html">java.util.Map</a></tt> and are
+not true collections. However, these interfaces contain
+<i>collection-view</i> operations, which enable them to be
+manipulated as collections. <tt>Map</tt> has the following
+offspring:</p>
+<ul>
+<li><tt><a href=
+"../SortedMap.html">java.util.SortedMap</a></tt></li>
+<li><tt><a href=
+"../NavigableMap.html">java.util.NavigableMap</a></tt></li>
+<li><tt><a href=
+"../concurrent/ConcurrentMap.html">java.util.concurrent.ConcurrentMap</a></tt></li>
+<li><tt><a href=
+"../concurrent/ConcurrentNavigableMap.html">java.util.concurrent.ConcurrentNavigableMap</a></tt></li>
+</ul>
+<p>Many of the modification methods in the collection interfaces
+are labeled <i>optional</i>. Implementations are permitted to not
+perform one or more of these operations, throwing a runtime
+exception (<tt>UnsupportedOperationException</tt>) if they are
+attempted. The documentation for each implementation must specify
+which optional operations are supported. Several terms are
+introduced to aid in this specification:</p>
+<ul>
+<li>Collections that do not support modification operations (such
+as <tt>add</tt>, <tt>remove</tt> and <tt>clear</tt>) are referred
+to as <i>unmodifiable</i>. Collections that are not unmodifiable
+are <i>modifiable.</i></li>
+<li>Collections that additionally guarantee that no change in the
+<tt>Collection</tt> object will be visible are referred to as
+<i>immutable</i>. Collections that are not immutable are
+<i>mutable</i>.</li>
+<li>Lists that guarantee that their size remains constant even
+though the elements can change are referred to as
+<i>fixed-size</i>. Lists that are not fixed-size are referred to as
+<i>variable-size</i>.</li>
+<li>Lists that support fast (generally constant time) indexed
+element access are known as <i>random access</i> lists. Lists that
+do not support fast indexed element access are known as
+<i>sequential access</i> lists. The <tt><a href=
+"../RandomAccess.html">RandomAccess</a></tt>
+marker interface enables lists to advertise the fact that they
+support random access. This enables generic algorithms to change
+their behavior to provide good performance when applied to either
+random or sequential access lists.</li>
+</ul>
+<p>Some implementations restrict what elements (or in the case of
+<tt>Maps</tt>, keys and values) can be stored. Possible
+restrictions include requiring elements to:</p>
+<ul>
+<li>Be of a particular type.</li>
+<li>Be not null.</li>
+<li>Obey some arbitrary predicate.</li>
+</ul>
+<p>Attempting to add an element that violates an implementation's
+restrictions results in a runtime exception, typically a
+<tt>ClassCastException</tt>, an <tt>IllegalArgumentException</tt>,
+or a <tt>NullPointerException</tt>. Attempting to remove or test
+for the presence of an element that violates an implementation's
+restrictions can result in an exception. Some restricted
+collections permit this usage.</p>
+<hr />
+<h2>Collection Implementations</h2>
+<p>Classes that implement the collection interfaces typically have
+names in the form of
+&lt;<em>Implementation-style</em>&gt;&lt;<em>Interface</em>&gt;.
+The general purpose implementations are summarized in the following
+table:</p>
+<table border="2" summary=
+"general purpose implementations and interfaces" align="center">
+<thead>
+<tr>
+<th id="interfaces">Interface</th>
+<th id="hashtable">Hash Table</th>
+<th id="resizablearray">Resizable Array</th>
+<th id="balancedtree">Balanced Tree</th>
+<th id="linkedlist">Linked List</th>
+<th id="hashtableandlinkedlist">Hash Table + Linked List</th>
+</tr>
+<tr>
+<td headers="interfaces"><code>Set</code></td>
+<td headers="hashtable"><a href=
+"../HashSet.html"><tt>HashSet</tt></a></td>
+<td headers="resizablearray">&nbsp;</td>
+<td headers="balancedtree"><a href=
+"../TreeSet.html"><tt>TreeSet</tt></a></td>
+<td headers="linkedlist">&nbsp;</td>
+<td headers="hashtableandlinkedlist"><a href=
+"../LinkedHashSet.html"><tt>LinkedHashSet</tt></a></td>
+</tr>
+<tr>
+<td headers="interfaces"><code>List</code></td>
+<td headers="hashtable">&nbsp;</td>
+<td headers="resizablearray"><a href=
+"../ArrayList.html"><tt>ArrayList</tt></a></td>
+<td headers="balancedtree">&nbsp;</td>
+<td headers="linkedlist"><a href=
+"../LinkedList.html"><tt>LinkedList</tt></a></td>
+<td headers="hashtableandlinkedlist">&nbsp;</td>
+</tr>
+<tr>
+<td headers="interfaces"><code>Deque</code></td>
+<td headers="hashtable">&nbsp;</td>
+<td headers="resizablearray"><a href=
+"../ArrayDeque.html"><tt>ArrayDeque</tt></a></td>
+<td headers="balancedtree">&nbsp;</td>
+<td headers="linkedlist"><a href=
+"../LinkedList.html"><tt>LinkedList</tt></a></td>
+<td headers="hashtableandlinkedlist">&nbsp;</td>
+</tr>
+<tr>
+<td headers="interfaces"><code>Map</code></td>
+<td headers="hashtable"><a href=
+"../HashMap.html"><tt>HashMap</tt></a></td>
+<td headers="resizablearray">&nbsp;</td>
+<td headers="balancedtree"><a href=
+"../TreeMap.html"><tt>TreeMap</tt></a></td>
+<td headers="linkedlist">&nbsp;</td>
+<td headers="hashtableandlinkedlist"><a href=
+"../LinkedHashMap.html"><tt>LinkedHashMap</tt></a></td>
+</tr>
+</thead>
+</table>
+<p>The general-purpose implementations support all of the
+<i>optional operations</i> in the collection interfaces and have no
+restrictions on the elements they may contain. They are
+unsynchronized, but the <tt>Collections</tt> class contains static
+factories called <a href=
+"../Collections.html#synchronizedCollection-java.util.Collection-">
+<em>synchronization wrappers</em></a> that can be used to add
+synchronization to many unsynchronized collections. All of the new
+implementations have <i>fail-fast iterators</i>, which detect
+invalid concurrent modification, and fail quickly and cleanly
+(rather than behaving erratically).</p>
+<p>The <tt>AbstractCollection</tt>, <tt>AbstractSet</tt>,
+<tt>AbstractList</tt>, <tt>AbstractSequentialList</tt> and
+<tt>AbstractMap</tt> classes provide basic implementations of the
+core collection interfaces, to minimize the effort required to
+implement them. The API documentation for these classes describes
+precisely how each method is implemented so the implementer knows
+which methods must be overridden, given the performance of the
+basic operations of a specific implementation.</p>
+<hr />
+<h2>Concurrent Collections</h2>
+<p>Applications that use collections from more than one thread must
+be carefully programmed. In general, this is known as <i>concurrent
+programming</i>. The Java platform includes extensive support for
+concurrent programming. See <a href=
+"../concurrent/package-summary.html">Java Concurrency
+Utilities</a> for details.</p>
+<p>Collections are so frequently used that various concurrent
+friendly interfaces and implementations of collections are included
+in the APIs. These types go beyond the synchronization wrappers
+discussed previously to provide features that are frequently needed
+in concurrent programming.</p>
+<p>These concurrent-aware interfaces are available:</p>
+<ul>
+<li><tt><a href=
+"../concurrent/BlockingQueue.html">BlockingQueue</a></tt></li>
+<li><tt><a href=
+"../concurrent/TransferQueue.html">TransferQueue</a></tt></li>
+<li><tt><a href=
+"../concurrent/BlockingDeque.html">BlockingDeque</a></tt></li>
+<li><tt><a href=
+"../concurrent/ConcurrentMap.html">ConcurrentMap</a></tt></li>
+<li><tt><a href=
+"../concurrent/ConcurrentNavigableMap.html">ConcurrentNavigableMap</a></tt></li>
+</ul>
+<p>The following concurrent-aware implementation classes are
+available. See the API documentation for the correct usage of these
+implementations.</p>
+<ul>
+<li><tt><a href=
+"../concurrent/LinkedBlockingQueue.html">LinkedBlockingQueue</a></tt></li>
+<li><tt><a href=
+"../concurrent/ArrayBlockingQueue.html">ArrayBlockingQueue</a></tt></li>
+<li><tt><a href=
+"../concurrent/PriorityBlockingQueue.html">PriorityBlockingQueue</a></tt></li>
+<li><tt><a href=
+"../concurrent/DelayQueue.html">DelayQueue</a></tt></li>
+<li><tt><a href=
+"../concurrent/SynchronousQueue.html">SynchronousQueue</a></tt></li>
+<li><a href=
+"../concurrent/LinkedBlockingDeque.html"><tt>LinkedBlockingDeque</tt></a></li>
+<li><a href=
+"../concurrent/LinkedTransferQueue.html"><tt>LinkedTransferQueue</tt></a></li>
+<li><tt><a href=
+"../concurrent/CopyOnWriteArrayList.html">CopyOnWriteArrayList</a></tt></li>
+<li><tt><a href=
+"../concurrent/CopyOnWriteArraySet.html">CopyOnWriteArraySet</a></tt></li>
+<li><tt><a href=
+"../concurrent/ConcurrentSkipListSet.html">ConcurrentSkipListSet</a></tt></li>
+<li><tt><a href=
+"../concurrent/ConcurrentHashMap.html">ConcurrentHashMap</a></tt></li>
+<li><tt><a href=
+"../concurrent/ConcurrentSkipListMap.html">ConcurrentSkipListMap</a></tt></li>
+</ul>
+<hr />
+<h2>Design Goals</h2>
+<p>The main design goal was to produce an API that was small in
+size and, more importantly, in &quot;conceptual weight.&quot; It
+was critical that the new functionality not seem too different to
+current Java programmers; it had to augment current facilities,
+rather than replace them. At the same time, the new API had to be
+powerful enough to provide all the advantages described
+previously.</p>
+<p>To keep the number of core interfaces small, the interfaces do
+not attempt to capture such subtle distinctions as mutability,
+modifiability, and resizability. Instead, certain calls in the core
+interfaces are <i>optional</i>, enabling implementations to throw
+an <tt>UnsupportedOperationException</tt> to indicate that they do
+not support a specified optional operation. Collection implementers
+must clearly document which optional operations are supported by an
+implementation.</p>
+<p>To keep the number of methods in each core interface small, an
+interface contains a method only if either:</p>
+<ul>
+<li>It is a truly <i>fundamental operation</i>: a basic operations
+in terms of which others could be reasonably defined,</li>
+<li>There is a compelling performance reason why an important
+implementation would want to override it.</li>
+</ul>
+<p>It was critical that all reasonable representations of
+collections interoperate well. This included arrays, which cannot
+be made to implement the <tt>Collection</tt> interface directly
+without changing the language. Thus, the framework includes methods
+to enable collections to be moved into arrays, arrays to be viewed
+as collections, and maps to be viewed as collections.</p>
+<hr />
+<p style="font-size:smaller">
+Copyright &copy; 1998, 2017, Oracle and/or its affiliates. 500 Oracle Parkway<br />
+    Redwood Shores, CA 94065 USA. All rights reserved.</p>
+<!-- Body text ends here -->
+</body>
+</html>
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.base/share/classes/java/util/doc-files/coll-reference.html	Thu Jun 29 13:07:19 2017 -0700
@@ -0,0 +1,564 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<!--
+ Copyright (c) 1998, 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.
+-->
+
+<html lang="en-US" xmlns="http://www.w3.org/1999/xhtml" xml:lang=
+"en-US">
+<head>
+<title>Outline of the Collections Framework</title>
+</head>
+<body>
+<h1>Outline of the Collections Framework</h1>
+<!-- Body text begins here -->
+The collections framework consists of:
+<ul>
+<li><strong>Collection interfaces</strong> - The primary means by
+which collections are manipulated.
+<ul>
+<li><a href=
+"../Collection.html"><strong>Collection</strong></a>
+- A group of objects. No assumptions are made about the order of
+the collection (if any) or whether it can contain duplicate
+elements.</li>
+<li><a href=
+"../Set.html"><strong>Set</strong></a> - The
+familiar set abstraction. No duplicate elements permitted. May or
+may not be ordered. Extends the <tt>Collection</tt> interface.</li>
+<li><a href=
+"../List.html"><strong>List</strong></a> -
+Ordered collection, also known as a <i>sequence</i>. Duplicates are
+generally permitted. Allows positional access. Extends the
+<tt>Collection</tt> interface.</li>
+<li><a href=
+"../Queue.html"><strong>Queue</strong></a> - A
+collection designed for holding elements before processing. Besides
+basic <tt>Collection</tt> operations, queues provide additional
+insertion, extraction, and inspection operations.</li>
+<li><a href=
+"../Deque.html"><strong>Deque</strong></a> - A
+<em>double ended queue</em>, supporting element insertion and
+removal at both ends. Extends the <tt>Queue</tt> interface.</li>
+<li><a href=
+"../Map.html"><strong>Map</strong></a> - A
+mapping from keys to values. Each key can map to one value.</li>
+<li><a href=
+"../SortedSet.html"><strong>SortedSet</strong></a>
+- A set whose elements are automatically sorted, either in their
+<i>natural ordering</i> (see the <a href=
+"../../lang/Comparable.html"><tt>Comparable</tt></a>
+interface) or by a <a href=
+"../Comparator.html"><tt>Comparator</tt></a>
+object provided when a <tt>SortedSet</tt> instance is created.
+Extends the <tt>Set</tt> interface.</li>
+<li><a href=
+"../SortedMap.html"><strong>SortedMap</strong></a>
+- A map whose mappings are automatically sorted by key, either
+using the <i>natural ordering</i> of the keys or by a comparator
+provided when a <tt>SortedMap</tt> instance is created. Extends the
+<tt>Map</tt> interface.</li>
+<li><a href=
+"../NavigableSet.html"><strong>NavigableSet</strong></a>
+- A <tt>SortedSet</tt> extended with navigation methods reporting
+closest matches for given search targets. A <tt>NavigableSet</tt>
+may be accessed and traversed in either ascending or descending
+order.</li>
+<li><a href=
+"../NavigableMap.html"><strong>NavigableMap</strong></a>
+- A <tt>SortedMap</tt> extended with navigation methods returning
+the closest matches for given search targets. A
+<tt>NavigableMap</tt> can be accessed and traversed in either
+ascending or descending key order.</li>
+<li><a href=
+"../concurrent/BlockingQueue.html"><strong>BlockingQueue</strong></a>
+- A <tt>Queue</tt> with operations that wait for the queue to
+become nonempty when retrieving an element and that wait for space
+to become available in the queue when storing an element. (This
+interface is part of the <tt><a href=
+"../concurrent/package-summary.html">java.util.concurrent</a></tt>
+package.)</li>
+<li><a href=
+"../concurrent/TransferQueue.html"><strong>TransferQueue</strong></a>
+- A <tt>BlockingQueue</tt> in which producers can wait for
+consumers to receive elements. (This interface is part of the
+<tt><a href=
+"../concurrent/package-summary.html">java.util.concurrent</a></tt>
+package.)</li>
+<li><a href=
+"../concurrent/BlockingDeque.html"><strong>BlockingDeque</strong></a>
+- A <tt>Deque</tt> with operations that wait for the deque to
+become nonempty when retrieving an element and wait for space to
+become available in the deque when storing an element. Extends both
+the <tt>Deque</tt> and <tt>BlockingQueue</tt> interfaces. (This
+interface is part of the <tt><a href=
+"../concurrent/package-summary.html">java.util.concurrent</a></tt>
+package.)</li>
+<li><a href=
+"../concurrent/ConcurrentMap.html"><strong>ConcurrentMap</strong></a>
+- A <tt>Map</tt> with atomic <tt>putIfAbsent</tt>, <tt>remove</tt>,
+and <tt>replace</tt> methods. (This interface is part of the
+<tt>java.util.concurrent</tt> package.)</li>
+<li><a href=
+"../concurrent/ConcurrentNavigableMap.html"><strong>
+ConcurrentNavigableMap</strong></a> - A <tt>ConcurrentMap</tt> that
+is also a <tt>NavigableMap</tt>.</li>
+</ul>
+</li>
+<li><strong>General-purpose implementations</strong> - The primary
+implementations of the collection interfaces.
+<ul>
+<li><strong><a href=
+"../HashSet.html">HashSet</a></strong> - Hash
+table implementation of the <tt>Set</tt> interface. The best
+all-around implementation of the <tt>Set</tt> interface.</li>
+<li><a href=
+"../TreeSet.html"><strong>TreeSet</strong></a>
+- Red-black tree implementation of the <tt>NavigableSet</tt>
+interface.</li>
+<li><strong><a href=
+"../LinkedHashSet.html">LinkedHashSet</a></strong>
+- Hash table and linked list implementation of the <tt>Set</tt>
+interface. An insertion-ordered <tt>Set</tt> implementation that
+runs nearly as fast as <tt>HashSet</tt>.</li>
+<li><strong><a href=
+"../ArrayList.html">ArrayList</a></strong> -
+Resizable array implementation of the <tt>List</tt> interface (an
+unsynchronized <tt>Vector</tt>). The best all-around implementation
+of the <tt>List</tt> interface.</li>
+<li><strong><a href=
+"../ArrayDeque.html">ArrayDeque</a></strong> -
+Efficient, resizable array implementation of the <tt>Deque</tt>
+interface.</li>
+<li><a href=
+"../LinkedList.html"><strong>LinkedList</strong></a>
+- Doubly-linked list implementation of the <tt>List</tt> interface.
+Provides better performance than the <tt>ArrayList</tt>
+implementation if elements are frequently inserted or deleted
+within the list. Also implements the <tt>Deque</tt> interface. When
+accessed through the <tt>Queue</tt> interface, <tt>LinkedList</tt>
+acts as a FIFO queue.</li>
+<li><strong><a href=
+"../PriorityQueue.html">PriorityQueue</a></strong>
+- Heap implementation of an unbounded priority queue.</li>
+<li><strong><a href=
+"../HashMap.html">HashMap</a></strong> - Hash
+table implementation of the <tt>Map</tt> interface (an
+unsynchronized <tt>Hashtable</tt> that supports <tt>null</tt> keys
+and values). The best all-around implementation of the <tt>Map</tt>
+interface.</li>
+<li><a href=
+"../TreeMap.html"><strong>TreeMap</strong></a>
+Red-black tree implementation of the <tt>NavigableMap</tt>
+interface.</li>
+<li><strong><a href=
+"../LinkedHashMap.html">LinkedHashMap</a></strong>
+- Hash table and linked list implementation of the <tt>Map</tt>
+interface. An insertion-ordered <tt>Map</tt> implementation that
+runs nearly as fast as <tt>HashMap</tt>. Also useful for building
+caches (see <a href=
+"../LinkedHashMap.html#removeEldestEntry-java.util.Map.Entry-">
+removeEldestEntry(Map.Entry)</a> ).</li>
+</ul>
+</li>
+<li><strong>Wrapper implementations</strong> -
+Functionality-enhancing implementations for use with other
+implementations. Accessed solely through static factory methods.
+<ul>
+<li><a href=
+"../Collections.html#unmodifiableCollection-java.util.Collection-">
+<strong>Collections.unmodifiable<i>Interface</i></strong></a> -
+Returns an unmodifiable view of a specified collection that throws
+an <tt>UnsupportedOperationException</tt> if the user attempts to
+modify it.</li>
+<li><a name="synchWrappers" href=
+"../Collections.html#synchronizedCollection-java.util.Collection-"
+id=
+"synchWrappers"><strong>Collections.synchronized<i>Interface</i></strong></a>
+- Returns a synchronized collection that is backed by the specified
+(typically unsynchronized) collection. As long as all accesses to
+the backing collection are through the returned collection, thread
+safety is guaranteed.</li>
+<li><a href=
+"../Collections.html#checkedCollection-java.util.Collection-java.lang.Class-">
+<strong>Collections.checked<i>Interface</i></strong></a> - Returns
+a dynamically type-safe view of the specified collection, which
+throws a <tt>ClassCastException</tt> if a client attempts to add an
+element of the wrong type. The generics mechanism in the language
+provides compile-time (static) type checking, but it is possible to
+bypass this mechanism. Dynamically type-safe views eliminate this
+possibility.</li>
+</ul>
+</li>
+<li><strong>Adapter implementations</strong> - Implementations that
+adapt one collections interface to another:
+<ul>
+<li><strong><a href=
+"../Collections.html#newSetFromMap-java.util.Map-">
+newSetFromMap(Map)</a></strong> - Creates a general-purpose
+<tt>Set</tt> implementation from a general-purpose <tt>Map</tt>
+implementation.</li>
+<li><strong><a href=
+"../Collections.html#asLifoQueue-java.util.Deque-">
+asLifoQueue(Deque)</a></strong> - Returns a view of a
+<tt>Deque</tt> as a Last In First Out (LIFO) <tt>Queue</tt>.</li>
+</ul>
+</li>
+<li><strong>Convenience implementations</strong> - High-performance
+"mini-implementations" of the collection interfaces.
+<ul>
+<li><a href=
+"../Arrays.html#asList-T...-"><strong>Arrays.asList</strong></a>
+- Enables an array to be viewed as a list.</li>
+<li><strong><a href=
+"../Collections.html#emptySet--">emptySet</a>,
+<a href=
+"../Collections.html#emptyList--">emptyList</a>
+and <a href=
+"../Collections.html#emptyMap--">emptyMap</a></strong>
+- Return an immutable empty set, list, or map.</li>
+<li><strong><a href=
+"../Collections.html#singleton-java.lang.Object-">
+singleton</a>, <a href=
+"../Collections.html#singletonList-java.lang.Object-">
+singletonList</a>, and <a href=
+"../Collections.html#singletonMap-K-V-">singletonMap</a></strong>
+- Return an immutable singleton set, list, or map, containing only
+the specified object (or key-value mapping).</li>
+<li><a href=
+"../Collections.html#nCopies-int-T-"><strong>
+nCopies</strong></a> - Returns an immutable list consisting of n
+copies of a specified object.</li>
+</ul>
+</li>
+<li><strong>Legacy implementations</strong> - Older collection
+classes were retrofitted to implement the collection interfaces.
+<ul>
+<li><a href=
+"../Vector.html"><strong>Vector</strong></a> -
+Synchronized resizable array implementation of the <tt>List</tt>
+interface with additional legacy methods.</li>
+<li><a href=
+"../Hashtable.html"><strong>Hashtable</strong></a>
+- Synchronized hash table implementation of the <tt>Map</tt>
+interface that does not allow <tt>null</tt> keys or values, plus
+additional legacy methods.</li>
+</ul>
+</li>
+<li><strong>Special-purpose implementations</strong>
+<ul>
+<li><strong><a href=
+"../WeakHashMap.html">WeakHashMap</a></strong>
+- An implementation of the <tt>Map</tt> interface that stores only
+<a href="../../lang/ref/WeakReference.html"><i>weak
+references</i></a> to its keys. Storing only weak references
+enables key-value pairs to be garbage collected when the key is no
+longer referenced outside of the <tt>WeakHashMap</tt>. This class
+is the easiest way to use the power of weak references. It is
+useful for implementing registry-like data structures, where the
+utility of an entry vanishes when its key is no longer reachable by
+any thread.</li>
+<li><strong><a href=
+"../IdentityHashMap.html">IdentityHashMap</a></strong>
+- Identity-based <tt>Map</tt> implementation based on a hash table.
+This class is useful for topology-preserving object graph
+transformations (such as serialization or deep copying). To perform
+these transformations, you must maintain an identity-based "node
+table" that keeps track of which objects have already been seen.
+Identity-based maps are also used to maintain
+object-to-meta-information mappings in dynamic debuggers and
+similar systems. Finally, identity-based maps are useful in
+preventing "spoof attacks" resulting from intentionally perverse
+equals methods. (<tt>IdentityHashMap</tt> never invokes the equals
+method on its keys.) An added benefit of this implementation is
+that it is fast.</li>
+<li><strong><a href=
+"../concurrent/CopyOnWriteArrayList.html">CopyOnWriteArrayList</a></strong>
+- A <tt>List</tt> implementation backed by an copy-on-write array.
+All mutative operations (such as <tt>add</tt>, <tt>set</tt>, and
+<tt>remove</tt>) are implemented by making a new copy of the array.
+No synchronization is necessary, even during iteration, and
+iterators are guaranteed never to throw
+<tt>ConcurrentModificationException</tt>. This implementation is
+well-suited to maintaining event-handler lists (where change is
+infrequent, and traversal is frequent and potentially
+time-consuming).</li>
+<li><strong><a href=
+"../concurrent/CopyOnWriteArraySet.html">CopyOnWriteArraySet</a></strong>
+- A <tt>Set</tt> implementation backed by a copy-on-write array.
+This implementation is similar to <tt>CopyOnWriteArrayList</tt>.
+Unlike most <tt>Set</tt> implementations, the <tt>add</tt>,
+<tt>remove</tt>, and <tt>contains</tt> methods require time
+proportional to the size of the set. This implementation is well
+suited to maintaining event-handler lists that must prevent
+duplicates.</li>
+<li><strong><a href=
+"../EnumSet.html">EnumSet</a></strong> - A
+high-performance <tt>Set</tt> implementation backed by a bit
+vector. All elements of each <tt>EnumSet</tt> instance must be
+elements of a single enum type.</li>
+<li><strong><a href=
+"../EnumMap.html">EnumMap</a></strong> - A
+high-performance <tt>Map</tt> implementation backed by an array.
+All keys in each <tt>EnumMap</tt> instance must be elements of a
+single enum type.</li>
+</ul>
+</li>
+<li><strong>Concurrent implementations</strong> - These
+implementations are part of <tt>java.util.concurrent</tt>.
+<ul>
+<li><strong><a href=
+"../concurrent/ConcurrentLinkedQueue.html">ConcurrentLinkedQueue</a></strong>
+- An unbounded first in, first out (FIFO) queue based on linked
+nodes.</li>
+<li><a href=
+"../concurrent/LinkedBlockingQueue.html"><strong>
+LinkedBlockingQueue</strong></a> - An optionally bounded FIFO
+blocking queue backed by linked nodes.</li>
+<li><a href=
+"../concurrent/ArrayBlockingQueue.html"><strong>
+ArrayBlockingQueue</strong></a> - A bounded FIFO blocking queue
+backed by an array.</li>
+<li><a href=
+"../concurrent/PriorityBlockingQueue.html"><strong>
+PriorityBlockingQueue</strong></a> - An unbounded blocking priority
+queue backed by a priority heap.</li>
+<li><a href=
+"../concurrent/DelayQueue.html"><strong>DelayQueue</strong></a>
+- A time-based scheduling queue backed by a priority heap.</li>
+<li><a href=
+"../concurrent/SynchronousQueue.html"><strong>SynchronousQueue</strong></a>
+- A simple rendezvous mechanism that uses the
+<tt>BlockingQueue</tt> interface.</li>
+<li><a href=
+"../concurrent/LinkedBlockingDeque.html"><strong>
+LinkedBlockingDeque</strong></a> - An optionally bounded FIFO
+blocking deque backed by linked nodes.</li>
+<li><a href=
+"../concurrent/LinkedTransferQueue.html"><strong>
+LinkedTransferQueue</strong></a> - An unbounded
+<tt>TransferQueue</tt> backed by linked nodes.</li>
+<li><a href=
+"../concurrent/ConcurrentHashMap.html"><strong>ConcurrentHashMap</strong></a>
+- A highly concurrent, high-performance <tt>ConcurrentMap</tt>
+implementation based on a hash table. This implementation never
+blocks when performing retrievals and enables the client to select
+the concurrency level for updates. It is intended as a drop-in
+replacement for <tt><a href=
+"../Hashtable.html">Hashtable</a></tt>. In
+addition to implementing <tt>ConcurrentMap</tt>, it supports all of
+the legacy methods of <tt>Hashtable</tt>.</li>
+<li><a href=
+"../concurrent/ConcurrentSkipListSet.html"><strong>
+ConcurrentSkipListSet</strong></a> - Skips list implementation of
+the <tt>NavigableSet</tt> interface.</li>
+<li><a href=
+"../concurrent/ConcurrentSkipListMap.html"><strong>
+ConcurrentSkipListMap</strong></a> - Skips list implementation of
+the <tt>ConcurrentNavigableMap</tt> interface.</li>
+</ul>
+</li>
+<li><strong>Abstract implementations</strong> - Skeletal
+implementations of the collection interfaces to facilitate custom
+implementations.
+<ul>
+<li><a href=
+"../AbstractCollection.html"><strong>AbstractCollection</strong></a>
+- Skeletal <tt>Collection</tt> implementation that is neither a set
+nor a list (such as a "bag" or multiset).</li>
+<li><a href=
+"../AbstractSet.html"><strong>AbstractSet</strong></a>
+- Skeletal <tt>Set</tt> implementation.</li>
+<li><a href=
+"../AbstractList.html"><strong>AbstractList</strong></a>
+- Skeletal <tt>List</tt> implementation backed by a random access
+data store (such as an array).</li>
+<li><a href=
+"../AbstractSequentialList.html"><strong>AbstractSequentialList</strong></a>
+- Skeletal <tt>List</tt> implementation backed by a sequential
+access data store (such as a linked list).</li>
+<li><a href=
+"../AbstractQueue.html"><strong>AbstractQueue</strong></a>
+- Skeletal <tt>Queue</tt> implementation.</li>
+<li><a href=
+"../AbstractMap.html"><strong>AbstractMap</strong></a>
+- Skeletal <tt>Map</tt> implementation.</li>
+</ul>
+</li>
+<li><strong>Algorithms</strong> - The <a href=
+"../Collections.html"><strong>Collections</strong></a>
+class contains these useful static methods.
+<ul>
+<li><strong><a href=
+"../Collections.html#sort-java.util.List-">sort(List)</a></strong>
+- Sorts a list using a merge sort algorithm, which provides average
+case performance comparable to a high quality quicksort, guaranteed
+O(n*log n) performance (unlike quicksort), and <em>stability</em>
+(unlike quicksort). A stable sort is one that does not reorder
+equal elements.</li>
+<li><strong><a href=
+"../Collections.html#binarySearch-java.util.List-T-">
+binarySearch(List, Object)</a></strong> - Searches for an element
+in an ordered list using the binary search algorithm.</li>
+<li><strong><a href=
+"../Collections.html#reverse-java.util.List-">reverse(List)</a></strong>
+- Reverses the order of the elements in a list.</li>
+<li><strong><a href=
+"../Collections.html#shuffle-java.util.List-">shuffle(List)</a></strong>
+- Randomly changes the order of the elements in a list.</li>
+<li><strong><a href=
+"../Collections.html#fill-java.util.List-T-">
+fill(List, Object)</a></strong> - Overwrites every element in a
+list with the specified value.</li>
+<li><strong><a href=
+"../Collections.html#copy-java.util.List-java.util.List-">
+copy(List dest, List src)</a></strong> - Copies the source list
+into the destination list.</li>
+<li><strong><a href=
+"../Collections.html#min-java.util.Collection-">
+min(Collection)</a></strong> - Returns the minimum element in a
+collection.</li>
+<li><strong><a href=
+"../Collections.html#max-java.util.Collection-">
+max(Collection)</a></strong> - Returns the maximum element in a
+collection.</li>
+<li><strong><a href=
+"../Collections.html#rotate-java.util.List-int-">
+rotate(List list, int distance)</a></strong> - Rotates all of the
+elements in the list by the specified distance.</li>
+<li><strong><a href=
+"../Collections.html#replaceAll-java.util.List-T-T-">
+replaceAll(List list, Object oldVal, Object newVal)</a></strong> -
+Replaces all occurrences of one specified value with another.</li>
+<li><strong><a href=
+"../Collections.html#indexOfSubList-java.util.List-java.util.List-">
+indexOfSubList(List source, List target)</a></strong> - Returns the
+index of the first sublist of source that is equal to target.</li>
+<li><strong><a href=
+"../Collections.html#lastIndexOfSubList-java.util.List-java.util.List-">
+lastIndexOfSubList(List source, List target)</a></strong> - Returns
+the index of the last sublist of source that is equal to
+target.</li>
+<li><strong><a href=
+"../Collections.html#swap-java.util.List-int-int-">
+swap(List, int, int)</a></strong> - Swaps the elements at the
+specified positions in the specified list.</li>
+<li><strong><a href=
+"../Collections.html#frequency-java.util.Collection-java.lang.Object-">
+frequency(Collection, Object)</a></strong> - Counts the number of
+times the specified element occurs in the specified
+collection.</li>
+<li><strong><a href=
+"../Collections.html#disjoint-java.util.Collection-java.util.Collection-">
+disjoint(Collection, Collection)</a></strong> - Determines whether
+two collections are disjoint, in other words, whether they contain
+no elements in common.</li>
+<li><strong><a href=
+"../Collections.html#addAll-java.util.Collection-T...-">
+addAll(Collection&lt;? super T&gt;, T...)</a></strong> - Adds all
+of the elements in the specified array to the specified
+collection.</li>
+</ul>
+</li>
+<li><strong>Infrastructure</strong>
+<ul>
+<li><strong>Iterators</strong> - Similar to the familiar <a href=
+"../Enumeration.html">Enumeration</a>
+interface, but more powerful, and with improved method names.
+<ul>
+<li><a href=
+"../Iterator.html"><strong>Iterator</strong></a>
+- In addition to the functionality of the <tt>Enumeration</tt>
+interface, enables the user to remove elements from the backing
+collection with well-defined, useful semantics.</li>
+<li><a href=
+"../ListIterator.html"><strong>ListIterator</strong></a>
+- Iterator for use with lists. In addition to the functionality of
+the <tt>Iterator</tt> interface, supports bidirectional iteration,
+element replacement, element insertion, and index retrieval.</li>
+</ul>
+</li>
+<li><strong>Ordering</strong>
+<ul>
+<li><a href=
+"../../lang/Comparable.html"><strong>Comparable</strong></a>
+- Imparts a <i>natural ordering</i> to classes that implement it.
+The natural ordering can be used to sort a list or maintain order
+in a sorted set or map. Many classes were retrofitted to implement
+this interface.</li>
+<li><a href=
+"../Comparator.html"><strong>Comparator</strong></a>
+- Represents an order relation, which can be used to sort a list or
+maintain order in a sorted set or map. Can override a type's
+natural ordering or order objects of a type that does not implement
+the <tt>Comparable</tt> interface.</li>
+</ul>
+</li>
+<li><strong>Runtime exceptions</strong>
+<ul>
+<li><a href=
+"../../lang/UnsupportedOperationException.html"><strong>
+UnsupportedOperationException</strong></a> - Thrown by collections
+if an unsupported optional operation is called.</li>
+<li><a href=
+"../ConcurrentModificationException.html"><strong>
+ConcurrentModificationException</strong></a> - Thrown by iterators
+and list iterators if the backing collection is changed
+unexpectedly while the iteration is in progress. Also thrown by
+<i>sublist</i> views of lists if the backing list is changed
+unexpectedly.</li>
+</ul>
+</li>
+<li><strong>Performance</strong>
+<ul>
+<li><strong><a href=
+"../RandomAccess.html">RandomAccess</a></strong>
+- Marker interface that lets <tt>List</tt> implementations indicate
+that they support fast (generally constant time) random access.
+This lets generic algorithms change their behavior to provide good
+performance when applied to either random or sequential access
+lists.</li>
+</ul>
+</li>
+</ul>
+</li>
+<li><strong>Array Utilities</strong>
+<ul>
+<li><a href=
+"../Arrays.html"><strong>Arrays</strong></a> -
+Contains static methods to sort, search, compare, hash, copy,
+resize, convert to <tt>String</tt>, and fill arrays of primitives
+and objects.</li>
+</ul>
+</li>
+</ul>
+<hr />
+<p style="font-size:smaller">
+Copyright &copy; 1998, 2017, Oracle and/or its affiliates. 500 Oracle Parkway<br />
+    Redwood Shores, CA 94065 USA. All rights reserved.</p>
+<!-- Body text ends here -->
+</body>
+</html>
--- a/src/java.base/share/classes/java/util/jar/Attributes.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/util/jar/Attributes.java	Thu Jun 29 13:07:19 2017 -0700
@@ -44,7 +44,7 @@
  * the ASCII characters in the set [0-9a-zA-Z_-], and cannot exceed 70
  * characters in length. Attribute values can contain any characters and
  * will be UTF8-encoded when written to the output stream.  See the
- * <a href="../../../../technotes/guides/jar/jar.html">JAR File Specification</a>
+ * <a href="{@docRoot}/../specs/jar/jar.html">JAR File Specification</a>
  * for more information about valid attribute names and values.
  *
  * <p>This map and its views have a predictable iteration order, namely the
@@ -443,7 +443,7 @@
      * to the ASCII characters in the set [0-9a-zA-Z_-], and cannot exceed
      * 70 characters in length. Attribute values can contain any characters
      * and will be UTF8-encoded when written to the output stream.  See the
-     * <a href="../../../../technotes/guides/jar/jar.html">JAR File Specification</a>
+     * <a href="{@docRoot}/../specs/jar/jar.html">JAR File Specification</a>
      * for more information about valid attribute names and values.
      */
     public static class Name {
@@ -529,7 +529,7 @@
          * {@code Name} object for {@code Manifest-Version}
          * manifest attribute. This attribute indicates the version number
          * of the manifest standard to which a JAR file's manifest conforms.
-         * @see <a href="../../../../technotes/guides/jar/jar.html#JAR_Manifest">
+         * @see <a href="{@docRoot}/../specs/jar/jar.html#JAR_Manifest">
          *      Manifest and Signature Specification</a>
          */
         public static final Name MANIFEST_VERSION = new Name("Manifest-Version");
@@ -537,7 +537,7 @@
         /**
          * {@code Name} object for {@code Signature-Version}
          * manifest attribute used when signing JAR files.
-         * @see <a href="../../../../technotes/guides/jar/jar.html#JAR_Manifest">
+         * @see <a href="{@docRoot}/../specs/jar/jar.html#JAR_Manifest">
          *      Manifest and Signature Specification</a>
          */
         public static final Name SIGNATURE_VERSION = new Name("Signature-Version");
@@ -551,7 +551,7 @@
         /**
          * {@code Name} object for {@code Class-Path}
          * manifest attribute.
-         * @see <a href="../../../../technotes/guides/jar/jar.html#classpath">
+         * @see <a href="{@docRoot}/../specs/jar/jar.html#classpath">
          *      JAR file specification</a>
          */
         public static final Name CLASS_PATH = new Name("Class-Path");
@@ -568,7 +568,7 @@
         /**
          * {@code Name} object for {@code Sealed} manifest attribute
          * used for sealing.
-         * @see <a href="../../../../technotes/guides/jar/jar.html#sealing">
+         * @see <a href="{@docRoot}/../specs/jar/jar.html#sealing">
          *      Package Sealing</a>
          */
         public static final Name SEALED = new Name("Sealed");
--- a/src/java.base/share/classes/java/util/jar/Manifest.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/util/jar/Manifest.java	Thu Jun 29 13:07:19 2017 -0700
@@ -39,7 +39,7 @@
  * associated Attributes. There are main Manifest Attributes as well as
  * per-entry Attributes. For information on the Manifest format, please
  * see the
- * <a href="../../../../technotes/guides/jar/jar.html">
+ * <a href="{@docRoot}/../specs/jar/jar.html">
  * Manifest format specification</a>.
  *
  * @author  David Connelly
--- a/src/java.base/share/classes/java/util/jar/Pack200.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/util/jar/Pack200.java	Thu Jun 29 13:07:19 2017 -0700
@@ -34,8 +34,7 @@
 
 /**
  * Transforms a JAR file to or from a packed stream in Pack200 format.
- * Please refer to Network Transfer Format JSR 200 Specification at
- * <a href=http://jcp.org/aboutJava/communityprocess/review/jsr200/index.html>http://jcp.org/aboutJava/communityprocess/review/jsr200/index.html</a>
+ * Please refer to <a href="{@docRoot}/../specs/pack-spec.html">Network Transfer Format JSR 200 Specification</a>
  * <p>
  * Typically the packer engine is used by application developers
  * to deploy or host JAR files on a website.
--- a/src/java.base/share/classes/java/util/jar/package-info.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/util/jar/package-info.java	Thu Jun 29 13:07:19 2017 -0700
@@ -40,7 +40,7 @@
  *       <a href="../zip/package-summary.html#package_description">java.util.zip
  *       package description.</a> <p>
  *       In JAR files, all file names must be encoded in the UTF-8 encoding.
- *   <li><a href="../../../../technotes/guides/jar/jar.html">
+ *   <li><a href="{@docRoot}/../specs/jar/jar.html">
  *       Manifest and Signature Specification</a> - The manifest format specification.
  * </ul>
  *
--- a/src/java.base/share/classes/java/util/package-info.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/java/util/package-info.java	Thu Jun 29 13:07:19 2017 -0700
@@ -24,27 +24,24 @@
  */
 
 /**
- * Contains the collections framework, legacy collection classes,
- * event model, date and time facilities, internationalization, and
- * miscellaneous utility classes (a string tokenizer, a random-number
- * generator, and a bit array).
+ * Contains the collections framework, some internationalization support classes,
+ * a service loader, properties, random number generation, string parsing
+ * and scanning classes, base64 encoding and decoding, a bit array, and
+ * several miscellaneous utility classes. This package also contains
+ * legacy collection classes and legacy date and time classes.
  *
  * <h2><a id="CollectionsFramework"></a>{@index "Java Collections Framework"}</h2>
+ * <p>For an overview, API outline, and design rationale, please see:
  * <ul>
- *   <li><a href="../../../technotes/guides/collections/overview.html"><b>Collections Framework Overview</b></a>
- *   <li><a href="../../../technotes/guides/collections/reference.html"><b>
- *        Collections Framework Annotated Outline</b></a>
+ *   <li><a href="doc-files/coll-index.html">
+ *          <b>Collections Framework Documentation</b></a>
  * </ul>
  *
- * <h2>Related Documentation</h2>
- * For overviews, tutorials, examples, guides, and tool documentation,
- * please see:
+ * <p>For a tutorial and programming guide with examples of use
+ * of the collections framework, please see:
  * <ul>
- *     <li><a href="http://docs.oracle.com/javase/tutorial/collections/index.html">
- *        <b>Collections Framework Tutorial</b></a>
- *     <li><a
- *     href="../../../technotes/guides/collections/designfaq.html"><b>Collections
- *     Framework Design FAQ</b></a>
+ *   <li><a href="http://docs.oracle.com/javase/tutorial/collections/index.html">
+ *          <b>Collections Framework Tutorial</b></a>
  * </ul>
  *
  * @since 1.0
--- a/src/java.base/share/classes/javax/crypto/Cipher.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/javax/crypto/Cipher.java	Thu Jun 29 13:07:19 2017 -0700
@@ -2616,11 +2616,9 @@
      * according to the installed JCE jurisdiction policy files. If
      * JCE unlimited strength jurisdiction policy files are installed,
      * Integer.MAX_VALUE will be returned.
-     * For more information on default key size in JCE jurisdiction
-     * policy files, please see Appendix E in the
-     * <a href=
-     *   "{@docRoot}/../technotes/guides/security/crypto/CryptoSpec.html#AppC">
-     * Java Cryptography Architecture Reference Guide</a>.
+     * For more information on the default key sizes and the JCE jurisdiction
+     * policy files, please see the Cryptographic defaults and limitations in
+     * the {@extLink security_guide_jdk_providers JDK Providers Documentation}.
      *
      * @param transformation the cipher transformation.
      * @return the maximum key length in bits or Integer.MAX_VALUE.
--- a/src/java.base/share/classes/javax/crypto/EncryptedPrivateKeyInfo.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/javax/crypto/EncryptedPrivateKeyInfo.java	Thu Jun 29 13:07:19 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 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
@@ -116,10 +116,9 @@
      * e.g. EncryptedPrivateKeyInfo(AlgorithmParameters, byte[]),
      * should be used.
      *
-     * @param algName encryption algorithm name. See Appendix A in the
-     * <a href=
-     *   "{@docRoot}/../technotes/guides/security/crypto/CryptoSpec.html#AppA">
-     * Java Cryptography Architecture Reference Guide</a>
+     * @param algName encryption algorithm name. See the
+     * <a href="{@docRoot}/../specs/security/standard-names.html">
+     * Java Security Standard Algorithm Names</a> document
      * for information about standard Cipher algorithm names.
      * @param encryptedData encrypted data. The contents of
      * <code>encrypedData</code> are copied to protect against subsequent
@@ -199,10 +198,8 @@
      * Returns the encryption algorithm.
      * <p>Note: Standard name is returned instead of the specified one
      * in the constructor when such mapping is available.
-     * See Appendix A in the
-     * <a href=
-     *   "{@docRoot}/../technotes/guides/security/crypto/CryptoSpec.html#AppA">
-     * Java Cryptography Architecture Reference Guide</a>
+     * See the <a href="{@docRoot}/../specs/security/standard-names.html">
+     * Java Security Standard Algorithm Names</a> document
      * for information about standard Cipher algorithm names.
      *
      * @return the encryption algorithm name.
--- a/src/java.base/share/classes/javax/crypto/KeyGenerator.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/javax/crypto/KeyGenerator.java	Thu Jun 29 13:07:19 2017 -0700
@@ -84,8 +84,7 @@
  * (via a call to an {@code init} method), each provider must
  * supply (and document) a default initialization.
  * See the Keysize Restriction sections of the
- * <a href="{@docRoot}/../technotes/guides/security/SunProviders.html">
- * JDK Providers</a>
+ * {@extLink security_guide_jdk_providers JDK Providers}
  * document for information on the KeyGenerator defaults used by
  * JDK providers.
  * However, note that defaults may vary across different providers.
--- a/src/java.base/share/classes/javax/crypto/KeyGeneratorSpi.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/javax/crypto/KeyGeneratorSpi.java	Thu Jun 29 13:07:19 2017 -0700
@@ -39,8 +39,7 @@
  * (via a call to an {@code init} method), each provider must
  * supply (and document) a default initialization.
  * See the Keysize Restriction sections of the
- * <a href="{@docRoot}/../technotes/guides/security/SunProviders.html">
- * JDK Providers</a>
+ * {@extLink security_guide_jdk_providers JDK Providers}
  * document for information on the KeyGenerator defaults used by
  * JDK providers.
  * However, note that defaults may vary across different providers.
--- a/src/java.base/share/classes/javax/crypto/interfaces/package-info.java	Fri Jun 23 09:48:10 2017 -0700
+++ b/src/java.base/share/classes/javax/crypto/interfaces/package-info.java	Thu Jun 29 13:07:19 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2007, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 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
@@ -39,10 +39,8 @@
  * developer