changeset 17389:851ad3507030

Merge
author henryjen
date Mon, 26 Jun 2017 16:00:42 -0700
parents 88f666ee4523 f3cf7fd26baa
children 47ec9f818908
files
diffstat 50 files changed, 668 insertions(+), 611 deletions(-) [+]
line wrap: on
line diff
--- a/.hgtags	Mon Jun 19 17:38:33 2017 -0400
+++ b/.hgtags	Mon Jun 26 16:00:42 2017 -0700
@@ -417,3 +417,4 @@
 0ff9ad7d067cd4fa14450cf208bf019175a0aaba jdk-9+172
 a5506b425f1bf91530d8417b57360e5d89328c0c jdk-9+173
 42f18c931bd4fae5c206ccf6d8e591e4c4e69d31 jdk-9+174
+e6c4f6ef717d104dba880e2dae538690c993b46f jdk-9+175
--- a/src/java.base/share/classes/java/lang/ClassLoader.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/lang/ClassLoader.java	Mon Jun 26 16:00:42 2017 -0700
@@ -2165,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/Package.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/lang/Package.java	Mon Jun 26 16:00:42 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	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/lang/SecurityManager.java	Mon Jun 26 16:00:42 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
--- a/src/java.base/share/classes/java/lang/module/package-info.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/lang/module/package-info.java	Mon Jun 26 16:00:42 2017 -0700
@@ -159,21 +159,28 @@
  *
  * <h2> Observable modules </h2>
  *
- * <p> The set of observable modules at both compile-time and run-time is determined
- * by searching an abstract module path. The module path is typically composed
- * of search paths that are searched in order: </p>
+ * <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>
  *
- * <ul>
- *   <li><p> At compile-time only, a compilation module path that contains module
- *   definitions in source form. </p></li>
- *   <li><p> The upgrade module path containing compiled definitions of modules
- *   intended to be used in place of upgradeable modules built-in to the
- *   environment. </p></li>
- *   <li><p> The system modules which are the compiled modules built-in to the
- *   environment. </p></li>
- *   <li><p> The application module path which contains compiled definitions of
- *   library and application modules. </p></li>
- * </ul>
+ * <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>
  *
--- a/src/java.base/share/classes/java/security/AlgorithmParameterGenerator.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/security/AlgorithmParameterGenerator.java	Mon Jun 26 16:00:42 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	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/security/AlgorithmParameterGeneratorSpi.java	Mon Jun 26 16:00:42 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	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/security/Key.java	Mon Jun 26 16:00:42 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	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/security/KeyPairGenerator.java	Mon Jun 26 16:00:42 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	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/security/KeyPairGeneratorSpi.java	Mon Jun 26 16:00:42 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	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/security/Provider.java	Mon Jun 26 16:00:42 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	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/security/Security.java	Mon Jun 26 16:00:42 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	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/security/cert/CRL.java	Mon Jun 26 16:00:42 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	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/security/cert/package-info.java	Mon Jun 26 16:00:42 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	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/security/interfaces/package-info.java	Mon Jun 26 16:00:42 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	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/security/package-info.java	Mon Jun 26 16:00:42 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	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/security/spec/package-info.java	Mon Jun 26 16:00:42 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/ServiceLoader.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/util/ServiceLoader.java	Mon Jun 26 16:00:42 2017 -0700
@@ -57,215 +57,290 @@
 
 
 /**
- * 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> A service loader is created by invoking one of the static {@code load}
- * methods that {@code ServiceLoader} defines. The resulting service loader
- * can be used to locate and instantiate service provider implementations by
- * means of its {@link #iterator() iterator} ({@code ServiceLoader} implements
- * {@code Iterable}) or by consuming elements from its {@link #stream() stream}.
+ * <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 the service type is {@code com.example.CodecSet}
- * and it defines two abstract methods to obtain encoders and decoders:
+ * <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
  *     package com.example;
- *     public interface CodecSet {
+ *     public interface CodecFactory {
  *         Encoder getEncoder(String encodingName);
  *         Decoder getDecoder(String encodingName);
  *     }
  * }</pre>
- * With this example, the following uses the service loader's iterator to find
- * a provider that supports a specific encoding:
+ *
+ * <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:
+ *
  * <pre>{@code
- *     public Encoder getEncoder(String encodingName) {
- *         ServiceLoader<CodeSet> loader = ServiceLoader.load(CodeSet.class);
- *         for (CodecSet cs : loader) {
- *             Encoder encoder = cs.getEncoder(encodingName);
- *             if (encoder != null)
- *                 return encoder;
+ *     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;
  *         }
- *         return null;
- *    }
  * }</pre>
  *
- * <p> Selecting a provider or filtering providers will usually involve invoking
- * a provider method. In the {@code CodeSet} example, the {@code getEncoder}
- * method is used to select the implementation. Where selection or filtering based
- * on the provider class is needed then it can be done when consuming the elements
- * of the service loader's stream. As an example, the following collects the
- * {@code CodeSet} implementations that have a specific annotation:
+ * <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
- *     Set<CodecSet> providers = ServiceLoader.load(CodecSet.class)
- *            .stream()
- *            .filter(p -> p.type().isAnnotationPresent(Managed.class))
- *            .map(Provider::get)
+ *     requires com.example.codec.core;
+ *     uses com.example.CodecFactory;
+ * }</pre>
+ *
+ * <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 {@code iterator} method returns an iterator that
- * first yields all of the elements cached from previous iteration, in
+ * <h3> Designing services </h3>
+ *
+ * <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>
+ *
+ * <h3> <a id="developing-service-providers">Developing service providers</a> </h3>
+ *
+ * <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> 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.
+ *
+ * <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.
+ *
+ * <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> 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 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>
+ *
+ * </ul>
+ *
+ * <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.
+ *
+ * <p> As an example, suppose a module specifies the following directives:
+ * <pre>{@code
+ *     provides com.example.CodecFactory with com.example.impl.StandardCodecs;
+ *     provides com.example.CodecFactory with com.example.impl.ExtendedCodecsFactory;
+ * }</pre>
+ *
+ * <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 {@code stream} method returns a stream that first processes all
+ * 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> Deploying provider classes in modules  </h3>
+ * <h3> <a id="errors">Errors</a> </h3>
  *
- * <p> 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.
+ * <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> A provider deployed as an explicit module is 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 explicitly declares 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> Providers deployed as {@link
- * java.lang.module.ModuleDescriptor#isAutomatic automatic-modules} on the
- * module path must have a public zero-argument constructor. If the provider
- * also declares a public static method named  "{@code provider}" then it is
- * ignored.
- *
- * <p> As an example, suppose a module declares the following:
- *
- * <pre>{@code
- *     provides com.example.CodecSet with com.example.impl.StandardCodecs;
- *     provides com.example.CodecSet with com.example.impl.ExtendedCodecsFactory;
- * }</pre>
- *
- * where
- * <ul>
- *     <li> {@code com.example.CodecSet} is the service type as above </li>
- *     <li> {@code com.example.impl.StandardCodecs} is a provider class
- *     (implements {@code CodecSet}) that is public with a public no-args
- *     constructor </li>
- *     <li> {@code com.example.impl.ExtendedCodecsFactory} is a public class
- *     that explicitly declares a public static no-args method named
- *     "{@code provider}" with a return type that is {@code CodecSet} or a
- *     subtype of. </li>
- * </ul>
- *
- * <p> 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.
- *
- * <h3> Deploying provider classes on the class path </h3>
- *
- * <p><a id="format">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}.</a> 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 located.
- *
- * <p> For the example, then 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:
- * <blockquote>{@code
- *     META-INF/services/com.example.CodecSet
- * }</blockquote>
- * that contains the line:
- * <blockquote>{@code
- *     com.example.impl.StandardCodecs    # Standard codecs
- * }</blockquote>
- *
- * <h3> Using ServiceLoader from code in modules </h3>
- *
- * <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. Combined with the requirement is that a
- * provider deployed as an explicit module must have an appropriate
- * <i>provides</i> clause allows consumers of a service to be <i>linked</i>
- * to modules containing providers of the service.
- *
- * <p> For the example, if code in a module uses a service loader to load
- * implementations of {@code com.example.CodecSet} then its module will declare
- * the usage with: <pre>{@code    uses com.example.CodecSet; }</pre>
- *
- * <h3> Errors </h3>
- *
- * <p>  When using the service loader's {@code iterator} then its {@link
- * Iterator#hasNext() hasNext} and {@link Iterator#next() next} methods will
- * fail with {@link ServiceConfigurationError} if an error occurs locating or
- * instantiating a provider. When processing the service loader's stream then
- * {@code ServiceConfigurationError} is thrown by whatever method causes a
- * provider class to be loaded.
- *
- * <p> When loading or instantiating a provider class in a named module then
- * {@code ServiceConfigurationError} can be thrown for the following reasons: </p>
+ * <p> When loading or instantiating a service provider in a module, {@code
+ * ServiceConfigurationError} can be thrown for the following reasons:
  *
  * <ul>
  *
- *   <li> The provider class cannot be loaded. </li>
+ *   <li> The service provider cannot be loaded. </li>
  *
- *   <li> The provider class is not a provider factory or is not a subclass of
- *   the service type with a public zero-argument constructor. </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 provider class explicitly declares a public static no-args method
- *   named "{@code provider}" with a return type that is not a subclass of the
- *   service type. </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 provider class explicitly declares more than one public static
+ *   <li> The service provider class file has more than one public static
  *   no-args method named "{@code provider}". </li>
  *
- *   <li> The provider class is a provider factory and its public static no-args
- *   method "{@code provider}" method returns {@code null} or throws an
- *   exception. </li>
+ *   <li> The service provider declares a provider method and it fails by
+ *   returning {@code null} or throwing an exception. </li>
  *
- *   <li> The provider class is not a provider factory and cannot be instantiated
- *   with its public zero-argument constructor. </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
+ * <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>
@@ -276,10 +351,11 @@
  *   <li> An {@link IOException IOException} occurs while reading the
  *   provider-configuration file; </li>
  *
- *   <li> The provider class cannot be loaded; </li>
+ *   <li> A service provider cannot be loaded; </li>
  *
- *   <li> The provider class is not a subclass of the service type, does not
- *   define a public zero-argument constructor, or cannot be instantiated; </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>
  *
@@ -1232,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.
      *
@@ -1275,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
      *
@@ -1331,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);
@@ -1463,68 +1530,67 @@
     }
 
     /**
-     * Creates a new service loader for the given service type and class
-     * loader. The service loader locates service providers in both named and
-     * unnamed modules:
+     * 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> Service providers are located in named modules defined to the
-     *   class loader, or any class loader that is reachable via parent
-     *   delegation. </p>
+     *   <li> <p> Step 1: Locate providers in named modules. </p>
      *
-     *   <p> Additionally, and with the exception of the bootstrap and {@linkplain
-     *   ClassLoader#getPlatformClassLoader() platform} class loaders, if the
-     *   class loader, or any class loader reachable via parent delegation,
-     *   defines modules in a module layer then the providers in the module layer
-     *   are 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 this {@code ServiceLoader.load} method is invoked to locate providers
-     *   using any of the class loaders created for this layer then it will locate
-     *   all of the providers in that layer, irrespective of their defining class
-     *   loader. </p></li>
+     *   <p> Service providers are located in all named modules of the class
+     *   loader or to any class loader reachable via parent delegation. </p>
      *
-     *   <li><p> A provider is an unnamed modules is located if its class
-     *   name is listed in a service configuration file located by the the class
-     *   loader's {@link ClassLoader#getResources(String) getResources} method.
-     *   The provider class must be visible to the class loader. If a provider
-     *   class is 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> </li>
-     * </ul>
+     *   <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> The ordering that the service loader's iterator and stream locate
-     * providers and yield elements is as follows:
+     *   <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>
      *
-     * <ul>
-     *     <li><p> Providers in named modules are located before service
-     *     providers in unnamed modules.</p></li>
+     *   <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>
      *
-     *     <li><p> When locating providers in named modules then 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 or any
-     *     class loader in the parent delegation chain, defines modules in a
-     *     module layer then all providers in that layer are located
-     *     (irrespective of their class loader) before providers in the parent
-     *     class loader are located. The ordering of modules defined to the
-     *     same class loader, or the ordering of modules in a layer, is not
-     *     defined. </p></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 (see
+     *   {@link java.lang.instrument.Instrumentation#redefineModule redefineModule})
+     *   are always located after providers declared by the module. </p> </li>
      *
-     *     <li><p> If a named 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>
      *
-     *     <li><p> When locating providers in unnamed modules then the
-     *     ordering is based on the order that the class loader's {@link
-     *     ClassLoader#getResources(String) getResources} method finds the
-     *     service configuration files and within that, the order that the class
-     *     names are listed in the file. </p></li>
+     *   <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
@@ -1657,9 +1723,8 @@
     /**
      * 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.
-     *
-     * <p> The ordering that the service loader's iterator and stream locate
+     * 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>
@@ -1671,8 +1736,8 @@
      *   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 named module declares more than one provider then the
-     *   providers are located in the order that its module descriptor
+     *   <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>
@@ -1708,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
@@ -1747,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/jar/Attributes.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/util/jar/Attributes.java	Mon Jun 26 16:00:42 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	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/util/jar/Manifest.java	Mon Jun 26 16:00:42 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/package-info.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/java/util/jar/package-info.java	Mon Jun 26 16:00:42 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/javax/crypto/Cipher.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/javax/crypto/Cipher.java	Mon Jun 26 16:00:42 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	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/javax/crypto/EncryptedPrivateKeyInfo.java	Mon Jun 26 16:00:42 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	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/javax/crypto/KeyGenerator.java	Mon Jun 26 16:00:42 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	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/javax/crypto/KeyGeneratorSpi.java	Mon Jun 26 16:00:42 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	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/javax/crypto/interfaces/package-info.java	Mon Jun 26 16:00:42 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 guide:
  *
  * <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>
@@ -57,10 +55,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>
+ *     {@extLink security_guide_jca
+ *       Java Cryptography Architecture (JCA) Reference Guide}</li>
  * </ul>
  *
  * @since 1.4
--- a/src/java.base/share/classes/javax/crypto/package-info.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/javax/crypto/package-info.java	Mon Jun 26 16:00:42 2017 -0700
@@ -43,7 +43,7 @@
  *
  * <ul>
  *   <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>
  *
@@ -52,15 +52,11 @@
  * For further documentation, please see:
  * <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>
  *   <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>
+ *     {@extLink security_guide_impl_provider
+ *       How to Implement a Provider in the Java Cryptography Architecture}</li>
  * </ul>
  *
  * @since 1.4
--- a/src/java.base/share/classes/javax/crypto/spec/SecretKeySpec.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/javax/crypto/spec/SecretKeySpec.java	Mon Jun 26 16:00:42 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2015, 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
@@ -81,9 +81,8 @@
      * the array are copied to protect against subsequent modification.
      * @param algorithm the name of the secret-key algorithm to be associated
      * with the given key material.
-     * 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 algorithm names.
      * @exception IllegalArgumentException if <code>algorithm</code>
      * is null or <code>key</code> is null or empty.
@@ -126,9 +125,8 @@
      * @param len the length of the key material.
      * @param algorithm the name of the secret-key algorithm to be associated
      * with the given key material.
-     * 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 algorithm names.
      * @exception IllegalArgumentException if <code>algorithm</code>
      * is null or <code>key</code> is null, empty, or too short,
--- a/src/java.base/share/classes/javax/crypto/spec/package-info.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/javax/crypto/spec/package-info.java	Mon Jun 26 16:00:42 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
@@ -57,16 +57,11 @@
  *
  * <ul>
  * <li>
- *  <a href=
- *    "{@docRoot}/../technotes/guides/security/crypto/CryptoSpec.html">
- *    <b>Java&trade; Cryptography Architecture API Specification and Reference
- *    </b></a></li>
+ *    {@extLink security_guide_jca
+ *      Java Cryptography Architecture (JCA) Reference Guide} </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>
+ *    {@extLink security_guide_impl_provider
+ *      How to Implement a Provider in the Java Cryptography Architecture}</li>
  * </ul>
  *
  * @since 1.4
--- a/src/java.base/share/classes/javax/net/ssl/ExtendedSSLSession.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/javax/net/ssl/ExtendedSSLSession.java	Mon Jun 26 16:00:42 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 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
@@ -44,9 +44,9 @@
      * <p>
      * The signature algorithm name must be a standard Java Security
      * name (such as "SHA1withRSA", "SHA256withECDSA", and so on).
-     * See Appendix A in the <a href=
-     * "{@docRoot}/../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 algorithm names.
      * <p>
      * Note: the local supported signature algorithms should conform to
@@ -72,9 +72,9 @@
      * <p>
      * The signature algorithm name must be a standard Java Security
      * name (such as "SHA1withRSA", "SHA256withECDSA", and so on).
-     * See Appendix A in the <a href=
-     * "{@docRoot}/../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 algorithm names.
      *
      * @return An array of supported signature algorithms, in descending
--- a/src/java.base/share/classes/javax/net/ssl/KeyManagerFactory.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/javax/net/ssl/KeyManagerFactory.java	Mon Jun 26 16:00:42 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2016, 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
@@ -127,8 +127,8 @@
      *
      * @param algorithm the standard name of the requested algorithm.
      *          See the <a href=
-     *  "{@docRoot}/../technotes/guides/security/jsse/JSSERefGuide.html">
-     *          Java Secure Socket Extension Reference Guide </a>
+     *          "{@docRoot}/../specs/security/standard-names.html">
+     *          Java Security Standard Algorithm Names</a> document
      *          for information about standard algorithm names.
      *
      * @return the new {@code KeyManagerFactory} object
@@ -165,8 +165,8 @@
 
      * @param algorithm the standard name of the requested algorithm.
      *          See the <a href=
-     *  "{@docRoot}/../technotes/guides/security/jsse/JSSERefGuide.html">
-     *          Java Secure Socket Extension Reference Guide </a>
+     *          "{@docRoot}/../specs/security/standard-names.html">
+     *          Java Security Standard Algorithm Names</a> document
      *          for information about standard algorithm names.
      *
      * @param provider the name of the provider.
@@ -209,8 +209,8 @@
      *
      * @param algorithm the standard name of the requested algorithm.
      *          See the <a href=
-     *  "{@docRoot}/../technotes/guides/security/jsse/JSSERefGuide.html">
-     *          Java Secure Socket Extension Reference Guide </a>
+     *          "{@docRoot}/../specs/security/standard-names.html">
+     *          Java Security Standard Algorithm Names</a> document
      *          for information about standard algorithm names.
      *
      * @param provider an instance of the provider.
--- a/src/java.base/share/classes/javax/net/ssl/SSLParameters.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/javax/net/ssl/SSLParameters.java	Mon Jun 26 16:00:42 2017 -0700
@@ -294,9 +294,10 @@
      * SSL/TLS/DTLS handshaking.  This is to prevent man-in-the-middle attacks.
      *
      * @param algorithm The standard string name of the endpoint
-     *     identification algorithm (or null).  See Appendix A in the <a href=
-     *   "{@docRoot}/../technotes/guides/security/crypto/CryptoSpec.html#AppA">
-     *     Java Cryptography Architecture API Specification &amp; Reference </a>
+     *     identification algorithm (or null).
+     *     See the <a href=
+     *     "{@docRoot}/../specs/security/standard-names.html">
+     *     Java Security Standard Algorithm Names</a> document
      *     for information about standard algorithm names.
      *
      * @see X509ExtendedTrustManager
--- a/src/java.base/share/classes/javax/net/ssl/TrustManagerFactory.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.base/share/classes/javax/net/ssl/TrustManagerFactory.java	Mon Jun 26 16:00:42 2017 -0700
@@ -141,8 +141,8 @@
      *
      * @param algorithm the standard name of the requested trust management
      *          algorithm.  See the <a href=
-     *  "{@docRoot}/../technotes/guides/security/jsse/JSSERefGuide.html">
-     *          Java Secure Socket Extension Reference Guide </a>
+     *          "{@docRoot}/../specs/security/standard-names.html">
+     *          Java Security Standard Algorithm Names</a> document
      *          for information about standard algorithm names.
      *
      * @return the new {@code TrustManagerFactory} object
@@ -179,8 +179,8 @@
      *
      * @param algorithm the standard name of the requested trust management
      *          algorithm.  See the <a href=
-     *  "{@docRoot}/../technotes/guides/security/jsse/JSSERefGuide.html">
-     *          Java Secure Socket Extension Reference Guide </a>
+     *          "{@docRoot}/../specs/security/standard-names.html">
+     *          Java Security Standard Algorithm Names</a> document
      *          for information about standard algorithm names.
      *
      * @param provider the name of the provider.
@@ -223,8 +223,8 @@
      *
      * @param algorithm the standard name of the requested trust management
      *          algorithm.  See the <a href=
-     *  "{@docRoot}/../technotes/guides/security/jsse/JSSERefGuide.html">
-     *          Java Secure Socket Extension Reference Guide </a>
+     *          "{@docRoot}/../specs/security/standard-names.html">
+     *          Java Security Standard Algorithm Names</a> document
      *          for information about standard algorithm names.
      *
      * @param provider an instance of the provider.
--- a/src/java.management/share/classes/javax/management/remote/JMXConnectorFactory.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.management/share/classes/javax/management/remote/JMXConnectorFactory.java	Mon Jun 26 16:00:42 2017 -0700
@@ -136,10 +136,9 @@
  * <code><em>protocol</em></code>, or it will throw a
  * <code>MalformedURLException</code> if there is none.  An
  * implementation may choose to find providers by other means.  For
- * example, it may support the <a
- * href="{@docRoot}/../technotes/guides/jar/jar.html#Service%20Provider">
- * JAR conventions for service providers</a>, where the service
- * interface is <code>JMXConnectorProvider</code>.</p>
+ * example, it may support <a
+ * href="{@docRoot}/../java/util/ServiceLoader.html#developing-service-providers">service providers</a>,
+ * where the service interface is <code>JMXConnectorProvider</code>.</p>
  *
  * <p>Every implementation must support the RMI connector protocol with
  * the default RMI transport, specified with string <code>rmi</code>.
--- a/src/java.management/share/classes/javax/management/remote/JMXConnectorServerFactory.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.management/share/classes/javax/management/remote/JMXConnectorServerFactory.java	Mon Jun 26 16:00:42 2017 -0700
@@ -127,10 +127,9 @@
  * <code><em>protocol</em></code>, or it will throw a
  * <code>MalformedURLException</code> if there is none.  An
  * implementation may choose to find providers by other means.  For
- * example, it may support the <a
- * href="{@docRoot}/../technotes/guides/jar/jar.html#Service%20Provider">
- * JAR conventions for service providers</a>, where the service
- * interface is <code>JMXConnectorServerProvider</code>.</p>
+ * example, it may support <a
+ * href="{@docRoot}/../java/util/ServiceLoader.html#developing-service-providers">service providers</a>,
+ * where the service interface is <code>JMXConnectorServerProvider</code>.</p>
  *
  * <p>Every implementation must support the RMI connector protocol with
  * the default RMI transport, specified with string <code>rmi</code>.
--- a/src/java.security.jgss/share/classes/javax/security/auth/kerberos/KerberosPrincipal.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.security.jgss/share/classes/javax/security/auth/kerberos/KerberosPrincipal.java	Mon Jun 26 16:00:42 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 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
@@ -100,9 +100,9 @@
      * <p>If the input name does not contain a realm, the default realm
      * is used. The default realm can be specified either in a Kerberos
      * configuration file or via the java.security.krb5.realm
-     * system property. For more information, see
-     * <a href="../../../../../technotes/guides/security/jgss/tutorials/index.html">
-     * Kerberos Requirements</a>. Additionally, if a security manager is
+     * system property. For more information, see the
+     * {@extLink security_guide_jgss_tutorial Kerberos Requirements}.
+     * Additionally, if a security manager is
      * installed, a {@link ServicePermission} must be granted and the service
      * principal of the permission must minimally be inside the
      * {@code KerberosPrincipal}'s realm. For example, if the result of
@@ -140,9 +140,9 @@
      * <p>If the input name does not contain a realm, the default realm
      * is used. The default realm can be specified either in a Kerberos
      * configuration file or via the java.security.krb5.realm
-     * system property. For more information, see
-     * <a href="../../../../../technotes/guides/security/jgss/tutorials/index.html">
-     * Kerberos Requirements</a>. Additionally, if a security manager is
+     * system property. For more information, see the
+     * {@extLink security_guide_jgss_tutorial Kerberos Requirements}.
+     * Additionally, if a security manager is
      * installed, a {@link ServicePermission} must be granted and the service
      * principal of the permission must minimally be inside the
      * {@code KerberosPrincipal}'s realm. For example, if the result of
--- a/src/java.security.jgss/share/classes/org/ietf/jgss/package.html	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.security.jgss/share/classes/org/ietf/jgss/package.html	Mon Jun 26 16:00:42 2017 -0700
@@ -100,7 +100,8 @@
 <h2>Related Documentation</h2>
 <p>
 For an online tutorial on using Java GSS-API, please see
-<a href="../../../../technotes/guides/security/jgss/tutorials/index.html">Introduction to JAAS and Java GSS-API</a>.
+{@extLink security_guide_jgss_tutorial
+Introduction to JAAS and Java GSS-API}.
 </p>
 
 <!--
--- a/src/java.security.sasl/share/classes/javax/security/sasl/Sasl.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.security.sasl/share/classes/javax/security/sasl/Sasl.java	Mon Jun 26 16:00:42 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2016, 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
@@ -280,8 +280,9 @@
      * Creates a {@code SaslClient} using the parameters supplied.
      *
      * This method uses the
-<a href="{@docRoot}/../technotes/guides/security/crypto/CryptoSpec.html#Provider">JCA Security Provider Framework</a>, described in the
-     * "Java Cryptography Architecture API Specification &amp; Reference", for
+     * {@extLink security_guide_jca JCA Security Provider Framework},
+     * described in the
+     * "Java Cryptography Architecture (JCA) Reference Guide", for
      * locating and selecting a {@code SaslClient} implementation.
      *
      * First, it
@@ -429,10 +430,10 @@
      * Creates a {@code SaslServer} for the specified mechanism.
      *
      * This method uses the
-<a href="{@docRoot}/../technotes/guides/security/crypto/CryptoSpec.html#Provider">JCA Security Provider Framework</a>,
+     * {@extLink security_guide_jca JCA Security Provider Framework},
      * described in the
-     * "Java Cryptography Architecture API Specification &amp; Reference", for
-     * locating and selecting a {@code SaslServer} implementation.
+     * "Java Cryptography Architecture (JCA) Reference Guide", for
+     * locating and selecting a {@code SaslClient} implementation.
      *
      * First, it
      * obtains an ordered list of {@code SaslServerFactory} instances from
--- a/src/java.security.sasl/share/classes/javax/security/sasl/package-info.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.security.sasl/share/classes/javax/security/sasl/package-info.java	Mon Jun 26 16:00:42 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2013, 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
@@ -95,8 +95,8 @@
  * <h2>Related Documentation</h2>
  *
  * Please refer to the
- * <a href="../../../../technotes/guides/security/sasl/sasl-refguide.html">Java
- * SASL Programming Guide</a> for information on how to use this API.
+ * {@extLink security_guide_sasl Java SASL Programming Guide}
+ * for information on how to use this API.
  *
  * @since 1.5
  */
--- a/src/java.xml.crypto/share/classes/javax/xml/crypto/dsig/TransformService.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.xml.crypto/share/classes/javax/xml/crypto/dsig/TransformService.java	Mon Jun 26 16:00:42 2017 -0700
@@ -69,11 +69,10 @@
  * <code>TransformService</code> implementations that support the DOM
  * mechanism type must abide by the DOM interoperability requirements defined
  * in the
- * <a href="../../../../../technotes/guides/security/xmldsig/overview.html#DOM%20Mechanism%20Requirements">
- * DOM Mechanism Requirements</a> section of the API overview. See the
- * <a href="../../../../../technotes/guides/security/xmldsig/overview.html#Service%20Provider">
- * Service Providers</a> section of the API overview for a list of standard
- * mechanism types.
+ * {@extLink security_guide_xmldsig_rqmts DOM Mechanism Requirements} section
+ * of the API overview. See the
+ * {@extLink security_guide_xmldsig_provider Service Providers} section of
+ * the API overview for a list of standard mechanism types.
  * <p>
  * Once a <code>TransformService</code> has been created, it can be used
  * to process <code>Transform</code> or <code>CanonicalizationMethod</code>
--- a/src/java.xml.crypto/share/classes/javax/xml/crypto/dsig/XMLSignatureFactory.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.xml.crypto/share/classes/javax/xml/crypto/dsig/XMLSignatureFactory.java	Mon Jun 26 16:00:42 2017 -0700
@@ -66,11 +66,10 @@
  *
  * <p>The objects that this factory produces will be based
  * on DOM and abide by the DOM interoperability requirements as defined in the
- * <a href="../../../../../technotes/guides/security/xmldsig/overview.html#DOM%20Mechanism%20Requirements">
- * DOM Mechanism Requirements</a> section of the API overview. See the
- * <a href="../../../../../technotes/guides/security/xmldsig/overview.html#Service%20Provider">
- * Service Providers</a> section of the API overview for a list of standard
- * mechanism types.
+ * {@extLink security_guide_xmldsig_rqmts DOM Mechanism Requirements} section
+ * of the API overview. See the
+ * {@extLink security_guide_xmldsig_provider Service Providers} section of
+ * the API overview for a list of standard mechanism types.
  *
  * <p><code>XMLSignatureFactory</code> implementations are registered and loaded
  * using the {@link java.security.Provider} mechanism.
@@ -181,9 +180,8 @@
      * {@link Security#getProviders() Security.getProviders()}.
      *
      * @param mechanismType the type of the XML processing mechanism and
-     *    representation. See the <a
-     *    href="../../../../../technotes/guides/security/xmldsig/overview.html#Service%20Provider">
-     *    Service Providers</a> section of the API overview for a list of
+     *    representation. See the {@extLink security_guide_xmldsig_provider
+     *    Service Providers} section of the API overview for a list of
      *    standard mechanism types.
      * @return a new <code>XMLSignatureFactory</code>
      * @throws NullPointerException if <code>mechanismType</code> is
@@ -227,9 +225,8 @@
      * provider list.
      *
      * @param mechanismType the type of the XML processing mechanism and
-     *    representation. See the <a
-     *    href="../../../../../technotes/guides/security/xmldsig/overview.html#Service%20Provider">
-     *    Service Providers</a> section of the API overview for a list of
+     *    representation. See the {@extLink security_guide_xmldsig_provider
+     *    Service Providers} section of the API overview for a list of
      *    standard mechanism types.
      * @param provider the <code>Provider</code> object
      * @return a new <code>XMLSignatureFactory</code>
@@ -279,9 +276,8 @@
      * the {@link Security#getProviders() Security.getProviders()} method.
      *
      * @param mechanismType the type of the XML processing mechanism and
-     *    representation. See the <a
-     *    href="../../../../../technotes/guides/security/xmldsig/overview.html#Service%20Provider">
-     *    Service Providers</a> section of the API overview for a list of
+     *    representation. See the {@extLink security_guide_xmldsig_provider
+     *    Service Providers} section of the API overview for a list of
      *    standard mechanism types.
      * @param provider the string name of the provider
      * @return a new <code>XMLSignatureFactory</code>
--- a/src/java.xml.crypto/share/classes/javax/xml/crypto/dsig/keyinfo/KeyInfoFactory.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/java.xml.crypto/share/classes/javax/xml/crypto/dsig/keyinfo/KeyInfoFactory.java	Mon Jun 26 16:00:42 2017 -0700
@@ -61,11 +61,11 @@
  *
  * <p>The objects that this factory produces will be based
  * on DOM and abide by the DOM interoperability requirements as defined in the
- * <a href="../../../../../../technotes/guides/security/xmldsig/overview.html#DOM%20Mechanism%20Requirements">
- * DOM Mechanism Requirements</a> section of the API overview. See the
- * <a href="../../../../../../technotes/guides/security/xmldsig/overview.html#Service%20Provider">
- * Service Providers</a> section of the API overview for a list of standard
- * mechanism types.
+ * {@extLink security_guide_xmldsig_rqmts DOM Mechanism Requirements} section
+ * of the API overview.  See the <a href=
+ * "{@docRoot}/../specs/security/standard-names.html#xml-signature-xmlsignaturefactorykeyinfofactorytransformservice-mechanisms">
+ * Java Security Standard Algorithm Names</a> document
+ * for more information.
  *
  * <p><code>KeyInfoFactory</code> implementations are registered and loaded
  * using the {@link java.security.Provider} mechanism.
@@ -137,10 +137,10 @@
      * {@link Security#getProviders() Security.getProviders()}.
      *
      * @param mechanismType the type of the XML processing mechanism and
-     *    representation. See the <a
-     *    href="../../../../../../technotes/guides/security/xmldsig/overview.html#Service%20Provider">
-     *    Service Providers</a> section of the API overview for a list of
-     *    standard mechanism types.
+     *    representation.  See the <a href=
+     *    "{@docRoot}/../specs/security/standard-names.html#xml-signature-xmlsignaturefactorykeyinfofactorytransformservice-mechanisms">
+     *    Java Security Standard Algorithm Names</a> document
+     * for more information.
      * @return a new <code>KeyInfoFactory</code>
      * @throws NullPointerException if <code>mechanismType</code> is
      *    <code>null</code>
@@ -182,10 +182,10 @@
      * provider list.
      *
      * @param mechanismType the type of the XML processing mechanism and
-     *    representation. See the <a
-     *    href="../../../../../../technotes/guides/security/xmldsig/overview.html#Service%20Provider">
-     *    Service Providers</a> section of the API overview for a list of
-     *    standard mechanism types.
+     *    representation.  See the <a href=
+     *    "{@docRoot}/../specs/security/standard-names.html#xml-signature-xmlsignaturefactorykeyinfofactorytransformservice-mechanisms">
+     *    Java Security Standard Algorithm Names</a> document
+     *    for more information.
      * @param provider the <code>Provider</code> object
      * @return a new <code>KeyInfoFactory</code>
      * @throws NullPointerException if <code>mechanismType</code> or
@@ -233,10 +233,10 @@
      * the {@link Security#getProviders() Security.getProviders()} method.
      *
      * @param mechanismType the type of the XML processing mechanism and
-     *    representation. See the <a
-     *    href="../../../../../../technotes/guides/security/xmldsig/overview.html#Service%20Provider">
-     *    Service Providers</a> section of the API overview for a list of
-     *    standard mechanism types.
+     *    representation.  See the <a href=
+     *    "{@docRoot}/../specs/security/standard-names.html#xml-signature-xmlsignaturefactorykeyinfofactorytransformservice-mechanisms">
+     *    Java Security Standard Algorithm Names</a> document
+     *    for more information.
      * @param provider the string name of the provider
      * @return a new <code>KeyInfoFactory</code>
      * @throws NoSuchProviderException if the specified provider is not
--- a/src/jdk.attach/share/classes/com/sun/tools/attach/VirtualMachine.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/jdk.attach/share/classes/com/sun/tools/attach/VirtualMachine.java	Mon Jun 26 16:00:42 2017 -0700
@@ -59,9 +59,9 @@
  * {@link java.lang.instrument} for a detailed description on how these agents
  * are loaded and started). The {@link #loadAgentLibrary loadAgentLibrary} and
  * {@link #loadAgentPath loadAgentPath} methods are used to load agents that
- * are deployed either in a dynamic library or statically linked into the VM and make use of the <a
- * href="../../../../../../../../technotes/guides/jvmti/index.html">JVM Tools
- * Interface</a>. </p>
+ * are deployed either in a dynamic library or statically linked into the VM and
+ * make use of the <a href="{@docRoot}/../specs/jvmti.html">JVM Tools Interface</a>.
+ * </p>
  *
  * <p> In addition to loading agents a VirtualMachine provides read access to the
  * {@link java.lang.System#getProperties() system properties} in the target VM.
@@ -289,8 +289,8 @@
     /**
      * Loads an agent library.
      *
-     * <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
-     * TI</a> client is called an <i>agent</i>. It is developed in a native language.
+     * <p> A <a href="{@docRoot}/../specs/jvmti.html">JVM TI</a>
+     * client is called an <i>agent</i>. It is developed in a native language.
      * A JVM TI agent is deployed in a platform specific manner but it is typically the
      * platform equivalent of a dynamic library. Alternatively, it may be statically linked into the VM.
      * This method causes the given agent library to be loaded into the target
@@ -298,8 +298,8 @@
      * It then causes the target VM to invoke the {@code Agent_OnAttach} function
      * or, for a statically linked agent named 'L', the {@code Agent_OnAttach_L} function
      * as specified in the
-     * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
-     * Interface</a> specification. Note that the {@code Agent_OnAttach[_L]}
+     * <a href="{@docRoot}/../specs/jvmti.html">JVM Tools Interface</a> specification.
+     * Note that the {@code Agent_OnAttach[_L]}
      * function is invoked even if the agent library was loaded prior to invoking
      * this method.
      *
@@ -380,8 +380,8 @@
     /**
      * Load a native agent library by full pathname.
      *
-     * <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
-     * TI</a> client is called an <i>agent</i>. It is developed in a native language.
+     * <p> A <a href="{@docRoot}/../specs/jvmti.html">JVM TI</a>
+     * client is called an <i>agent</i>. It is developed in a native language.
      * A JVM TI agent is deployed in a platform specific manner but it is typically the
      * platform equivalent of a dynamic library. Alternatively, the native
      * library specified by the agentPath parameter may be statically
@@ -397,8 +397,7 @@
      * It then causes the target VM to invoke the {@code Agent_OnAttach}
      * function or, for a statically linked agent named 'L', the
      * {@code Agent_OnAttach_L} function as specified in the
-     * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
-     * Interface</a> specification.
+     * <a href="{@docRoot}/../specs/jvmti.html">JVM Tools Interface</a> specification.
      * Note that the {@code Agent_OnAttach[_L]}
      * function is invoked even if the agent library was loaded prior to invoking
      * this method.
@@ -611,9 +610,9 @@
      * way as on the command line, you need to specify at least the
      * {@code com.sun.management.jmxremote.port} property.
      *
-     * <p> See the online documentation for <a
-     * href="../../../../../../../../technotes/guides/management/agent.html">
-     * Monitoring and Management Using JMX Technology</a> for further details.
+     * <p> See the online documentation for
+     * {@extLink monitoring_and_management_using_jmx_technology
+     * Monitoring and Management Using JMX Technology} for further details.
      *
      * @param   agentProperties
      *          A Properties object containing the configuration properties
@@ -642,9 +641,9 @@
     /**
      * Starts the local JMX management agent in the target virtual machine.
      *
-     * <p> See the online documentation for <a
-     * href="../../../../../../../../technotes/guides/management/agent.html">
-     * Monitoring and Management Using JMX Technology</a> for further details.
+     * <p> See the online documentation for
+     * {@extLink monitoring_and_management_using_jmx_technology
+     * Monitoring and Management Using JMX Technology} for further details.
      *
      * @return  The String representation of the local connector's service address.
      *          The value can be parsed by the
--- a/src/jdk.crypto.ec/share/legal/ecc.md	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/jdk.crypto.ec/share/legal/ecc.md	Mon Jun 26 16:00:42 2017 -0700
@@ -1,7 +1,6 @@
 ## Mozilla Elliptic Curve Cryptography (ECC)
 
 ### Mozilla ECC Notice
-<pre>
 
 This notice is provided with respect to Elliptic Curve Cryptography,
 which is included with JRE, JDK, and OpenJDK.
@@ -10,7 +9,7 @@
 of the Elliptic Curve Cryptography library in source
 form with the JDK and OpenJDK source distributions, and as object code in
 the JRE & JDK runtimes.
-
+<pre>
 In the case of the JRE & JDK runtimes, the terms of the Oracle license do
 NOT apply to the Elliptic Curve Cryptography library; it is licensed under the
 following license, separately from Oracle's JDK & JRE.  If you do not wish to
@@ -22,6 +21,54 @@
 
 </pre>
 
+### Written Offer for Source Code
+<pre>
+
+For third party technology that you receive from Oracle in binary form 
+which is licensed under an open source license that gives you the right
+to receive the source code for that binary, you can obtain a copy of 
+the applicable source code from this page:
+    http://hg.openjdk.java.net/jdk9/jdk9/jdk/file/tip/src/jdk.crypto.ec/share/native/libsunec/impl
+
+If the source code for the technology was not provided to you with the 
+binary, you can also receive a copy of the source code on physical 
+media by submitting a written request to:
+
+   Oracle America, Inc.
+   Attn: Associate General Counsel,
+   Development and Engineering Legal
+   500 Oracle Parkway, 10th Floor
+   Redwood Shores, CA 94065
+
+Or, you may send an email to Oracle using the form at:
+
+http://www.oracle.com/goto/opensourcecode/request
+
+Your request should include:
+
+  - The name of the component or binary file(s) for which you are requesting the source code
+
+  - The name and version number of the Oracle product containing the binary
+
+  - The date you received the Oracle product
+
+  - Your name
+
+  - Your company name (if applicable)
+
+  - Your return mailing address and email and
+
+  - A telephone number in the event we need to reach you.
+
+We may charge you a fee to cover the cost of physical media and processing. 
+Your request must be sent (i) within three (3) years of the date you 
+received the Oracle product that included the component or binary 
+file(s) that are the subject of your request, or (ii) in the case of 
+code licensed under the GPL v3, for as long as Oracle offers spare 
+parts or customer support for that product model.
+
+</pre>
+
 ### LGPL 2.1
 <pre>
 
--- a/src/jdk.jdi/share/classes/module-info.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/jdk.jdi/share/classes/module-info.java	Mon Jun 26 16:00:42 2017 -0700
@@ -39,12 +39,13 @@
  * creation, etc. The ability to inspect a suspended thread's state, local
  * variables, stack backtrace, etc.
  * <p>
- * JDI is the highest-layer of the Java Platform Debugger Architecture (JPDA).
- * For more information on the Java Platform Debugger Architecture, see the <a
- * href="{@docRoot}/../../../../technotes/guides/jpda/index.html"> Java
- * Platform Debugger Architecture documentation</a> for this release and the <a
- * href="http://java.sun.com/products/jpda">Java Platform Debugger Architecture
- * website</a>.
+ * JDI is the highest-layer of the
+ * <a href="{@docRoot}/../specs/jpda/jpda.html">
+ * Java Platform Debugger Architecture (JPDA)</a>.
+ * <p>
+ * This module includes a simple command-line debugger,
+ * <em>{@index jdb jdb tool}</em>.
+ *
  * <h3>Global Exceptions</h3>
  * <p>
  * This section documents exceptions which apply to the entire API and are thus
@@ -102,10 +103,6 @@
  *   unloaded.
  * </blockquote>
  *
- * <h3>jdb</h3>
- *
- * <em>{@index jdb jdb tool}</em> is a simple command-line debugger provided
- * in this module.
  *
  * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
  * <dt class="simpleTagLabel">Tool Guides:
@@ -119,6 +116,8 @@
  *
  * @moduleGraph
  * @since 9
+ * @see <a href="{@docRoot}/../specs/jpda/jpda.html">
+ * Java Platform Debugger Architecture (JPDA)</a>
  */
 module jdk.jdi {
     requires jdk.attach;
--- a/src/jdk.security.auth/share/classes/com/sun/security/auth/callback/package-info.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/jdk.security.auth/share/classes/com/sun/security/auth/callback/package-info.java	Mon Jun 26 16:00:42 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -23,4 +23,10 @@
  * questions.
  */
 
+/**
+ * Provides an implementation of
+ * {@link javax.security.auth.callback.CallbackHandler}.
+ *
+ * @since 1.4
+ */
 package com.sun.security.auth.callback;
--- a/src/jdk.security.auth/share/classes/com/sun/security/auth/login/package-info.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/jdk.security.auth/share/classes/com/sun/security/auth/login/package-info.java	Mon Jun 26 16:00:42 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -23,4 +23,9 @@
  * questions.
  */
 
+/**
+ * Provides an implementation of {@link javax.security.auth.login.Configuration}.
+ *
+ * @since 1.4
+ */
 package com.sun.security.auth.login;
--- a/src/jdk.security.auth/share/classes/com/sun/security/auth/module/package-info.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/jdk.security.auth/share/classes/com/sun/security/auth/module/package-info.java	Mon Jun 26 16:00:42 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -23,4 +23,9 @@
  * questions.
  */
 
+/**
+ * Provides implementations of {@link javax.security.auth.spi.LoginModule}.
+ *
+ * @since 1.4
+ */
 package com.sun.security.auth.module;
--- a/src/jdk.security.auth/share/classes/com/sun/security/auth/package-info.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/jdk.security.auth/share/classes/com/sun/security/auth/package-info.java	Mon Jun 26 16:00:42 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -23,4 +23,9 @@
  * questions.
  */
 
+/**
+ * Provides implementations of {@link java.security.Principal}.
+ *
+ * @since 1.4
+ */
 package com.sun.security.auth;
--- a/src/jdk.security.auth/share/classes/module-info.java	Mon Jun 19 17:38:33 2017 -0400
+++ b/src/jdk.security.auth/share/classes/module-info.java	Mon Jun 26 16:00:42 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -24,7 +24,7 @@
  */
 
 /**
- * Provides the implementation of the {@code javax.security.auth.*}
+ * Provides implementations of the {@code javax.security.auth.*}
  * interfaces and various authentication modules.
  *
  * @provides javax.security.auth.spi.LoginModule