Hi Alan, The changes read well
Best Lance > On Jul 17, 2018, at 6:46 AM, Alan Bateman <alan.bate...@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.ander...@oracle.com <mailto:lance.ander...@oracle.com>
