8207393: ServiceLoader class description improvements

[Alan Bateman]

[1] JDK-8207393 is suggestions from Alex Buckley to improve 
ServiceLoader's class description and specifically to add a strong 
recommendation that an application should not require the modules that 
provide implementations of the service.

The diffs for jdk/jdk are inlined below. I have already Reviewed the 
changes.

-Alan

[1] https://bugs.openjdk.java.net/browse/JDK-8207393


diff --git a/src/java.base/share/classes/java/util/ServiceLoader.java 
b/src/java.base/share/classes/java/util/ServiceLoader.java
--- a/src/java.base/share/classes/java/util/ServiceLoader.java
+++ b/src/java.base/share/classes/java/util/ServiceLoader.java
@@ -1,5 +1,5 @@
  /*
- * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights 
reserved.
+ * Copyright (c) 2005, 2018, 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
@@ -65,19 +65,21 @@
   * 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.
+ * service providers, and is assumed to be capable of choosing between 
multiple
+ * service providers (based on the functionality they expose through 
the service),
+ * and handling the possibility that no service providers are located.
   *
   * <h3> Obtaining a service loader </h3>
   *
   * <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.
+ * one of the static {@code load} methods of {@code 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 application module 
does not
+ * contain the service, then its module declaration must have a 
<i>requires</i>
+ * directive that specifies the module which exports the service. It is 
strongly
+ * recommended that the application module does <b>not</b> require 
modules which
+ * contain providers of the service.
   *
   * <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}