8207393: ServiceLoader class description improvements

[Lance Andersen]

Hi Alan,

The changes read well

Best
Lance
> On Jul 17, 2018, at 6:46 AM, Alan Bateman <Alan.Bateman at oracle.com> wrote:
> 
> [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}
> 

 <http://oracle.com/us/design/oracle-email-sig-198324.gif>
 <http://oracle.com/us/design/oracle-email-sig-198324.gif> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
 <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering 
1 Network Drive 
Burlington, MA 01803
Lance.Andersen at oracle.com <mailto:Lance.Andersen at oracle.com>