changeset 51111:99a7d10f248c

8207393: ServiceLoader class description improvements Reviewed-by: alanb, lancea Contributed-by: alex.buckley@oracle.com
author alanb
date Wed, 18 Jul 2018 07:39:54 +0100
parents 03f2bfdcb636
children e43f36744522
files src/java.base/share/classes/java/util/ServiceLoader.java
diffstat 1 files changed, 12 insertions(+), 10 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.base/share/classes/java/util/ServiceLoader.java	Tue Jul 17 17:36:27 2018 -0700
+++ b/src/java.base/share/classes/java/util/ServiceLoader.java	Wed Jul 18 07:39:54 2018 +0100
@@ -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}