1 /*
2 * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.util;
27
28 import java.io.BufferedReader;
29 import java.io.IOException;
30 import java.io.InputStream;
31 import java.io.InputStreamReader;
32 import java.lang.reflect.Constructor;
33 import java.lang.reflect.InvocationTargetException;
34 import java.lang.reflect.Method;
35 import java.lang.reflect.Modifier;
36 import java.net.URL;
37 import java.net.URLConnection;
38 import java.security.AccessControlContext;
39 import java.security.AccessController;
40 import java.security.PrivilegedAction;
41 import java.security.PrivilegedActionException;
42 import java.security.PrivilegedExceptionAction;
43 import java.util.function.Consumer;
44 import java.util.function.Supplier;
45 import java.util.stream.Stream;
46 import java.util.stream.StreamSupport;
47
48 import jdk.internal.loader.BootLoader;
49 import jdk.internal.loader.ClassLoaders;
50 import jdk.internal.misc.JavaLangAccess;
51 import jdk.internal.misc.SharedSecrets;
52 import jdk.internal.misc.VM;
53 import jdk.internal.module.ServicesCatalog;
54 import jdk.internal.module.ServicesCatalog.ServiceProvider;
55 import jdk.internal.reflect.CallerSensitive;
56 import jdk.internal.reflect.Reflection;
57
58
59 /**
60 * A facility to load implementations of a service.
61 *
62 * <p> A <i>service</i> is a well-known interface or class for which zero, one,
63 * or many service providers exist. A <i>service provider</i> (or just
64 * <i>provider</i>) is a class that implements or subclasses the well-known
65 * interface or class. A {@code ServiceLoader} is an object that locates and
66 * loads service providers deployed in the run time environment at a time of an
67 * application's choosing. Application code refers only to the service, not to
68 * service providers, and is assumed to be capable of differentiating between
69 * multiple service providers as well as handling the possibility that no service
70 * providers are located.
71 *
72 * <h3> Obtaining a service loader </h3>
73 *
74 * <p> An application obtains a service loader for a given service by invoking
75 * one of the static {@code load} methods of ServiceLoader. If the application
76 * is a module, then its module declaration must have a <i>uses</i> directive
77 * that specifies the service; this helps to locate providers and ensure they
78 * will execute reliably. In addition, if the service is not in the application
79 * module, then the module declaration must have a <i>requires</i> directive
80 * that specifies the module which exports the service.
81 *
82 * <p> A service loader can be used to locate and instantiate providers of the
83 * service by means of the {@link #iterator() iterator} method. {@code ServiceLoader}
84 * also defines the {@link #stream() stream} method to obtain a stream of providers
85 * that can be inspected and filtered without instantiating them.
86 *
87 * <p> As an example, suppose the service is {@code com.example.CodecFactory}, an
88 * interface that defines methods for producing encoders and decoders:
89 *
90 * <pre>{@code
91 * package com.example;
92 * public interface CodecFactory {
93 * Encoder getEncoder(String encodingName);
94 * Decoder getDecoder(String encodingName);
95 * }
96 * }</pre>
97 *
98 * <p> The following code obtains a service loader for the {@code CodecFactory}
99 * service, then uses its iterator (created automatically by the enhanced-for
100 * loop) to yield instances of the service providers that are located:
101 *
102 * <pre>{@code
103 * ServiceLoader<CodecFactory> loader = ServiceLoader.load(CodecFactory.class);
104 * for (CodecFactory factory : loader) {
105 * Encoder enc = factory.getEncoder("PNG");
106 * if (enc != null)
107 * ... use enc to encode a PNG file
108 * break;
109 * }
110 * }</pre>
111 *
112 * <p> If this code resides in a module, then in order to refer to the
113 * {@code com.example.CodecFactory} interface, the module declaration would
114 * require the module which exports the interface. The module declaration would
115 * also specify use of {@code com.example.CodecFactory}:
116 * <pre>{@code
117 * requires com.example.codec.core;
118 * uses com.example.CodecFactory;
119 * }</pre>
120 *
121 * <p> Sometimes an application may wish to inspect a service provider before
122 * instantiating it, in order to determine if an instance of that service
123 * provider would be useful. For example, a service provider for {@code
124 * CodecFactory} that is capable of producing a "PNG" encoder may be annotated
125 * with {@code @PNG}. The following code uses service loader's {@code stream}
126 * method to yield instances of {@code Provider<CodecFactory>} in contrast to
127 * how the iterator yields instances of {@code CodecFactory}:
128 * <pre>{@code
129 * ServiceLoader<CodecFactory> loader = ServiceLoader.load(CodecFactory.class);
130 * Set<CodecFactory> pngFactories = loader
131 * .stream() // Note a below
132 * .filter(p -> p.type().isAnnotationPresent(PNG.class)) // Note b
133 * .map(Provider::get) // Note c
134 * .collect(Collectors.toSet());
135 * }</pre>
136 * <ol type="a">
137 * <li> A stream of {@code Provider<CodecFactory>} objects </li>
138 * <li> {@code p.type()} yields a {@code Class<CodecFactory>} </li>
139 * <li> {@code get()} yields an instance of {@code CodecFactory} </li>
140 * </ol>
141 *
142 * <h3> Designing services </h3>
143 *
144 * <p> A service is a single type, usually an interface or abstract class. A
145 * concrete class can be used, but this is not recommended. The type may have
146 * any accessibility. The methods of a service are highly domain-specific, so
147 * this API specification cannot give concrete advice about their form or
148 * function. However, there are two general guidelines:
149 * <ol>
150 * <li><p> A service should declare as many methods as needed to allow service
151 * providers to communicate their domain-specific properties and other
152 * quality-of-implementation factors. An application which obtains a service
153 * loader for the service may then invoke these methods on each instance of
154 * a service provider, in order to choose the best provider for the
155 * application. </p></li>
156 * <li><p> A service should express whether its service providers are intended
157 * to be direct implementations of the service or to be an indirection
158 * mechanism such as a "proxy" or a "factory". Service providers tend to be
159 * indirection mechanisms when domain-specific objects are relatively
160 * expensive to instantiate; in this case, the service should be designed
161 * so that service providers are abstractions which create the "real"
162 * implementation on demand. For example, the {@code CodecFactory} service
163 * expresses through its name that its service providers are factories
164 * for codecs, rather than codecs themselves, because it may be expensive
165 * or complicated to produce certain codecs. </p></li>
166 * </ol>
167 *
168 * <h3> <a id="developing-service-providers">Developing service providers</a> </h3>
169 *
170 * <p> A service provider is a single type, usually a concrete class. An
171 * interface or abstract class is permitted because it may declare a static
172 * provider method, discussed later. The type must be public and must not be
173 * an inner class.
174 *
175 * <p> A service provider and its supporting code may be developed in a module,
176 * which is then deployed on the application module path or in a modular
177 * image. Alternatively, a service provider and its supporting code may be
178 * packaged as a JAR file and deployed on the application class path. The
179 * advantage of developing a service provider in a module is that the provider
180 * can be fully encapsulated to hide all details of its implementation.
181 *
182 * <p> An application that obtains a service loader for a given service is
183 * indifferent to whether providers of the service are deployed in modules or
184 * packaged as JAR files. The application instantiates service providers via
185 * the service loader's iterator, or via {@link Provider Provider} objects in
186 * the service loader's stream, without knowledge of the service providers'
187 * locations.
188 *
189 * <h3> Deploying service providers as modules </h3>
190 *
191 * <p> A service provider that is developed in a module must be specified in a
192 * <i>provides</i> directive in the module declaration. The provides directive
193 * specifies both the service and the service provider; this helps to locate the
194 * provider when another module, with a <i>uses</i> directive for the service,
195 * obtains a service loader for the service. It is strongly recommended that the
196 * module does not export the package containing the service provider. There is
197 * no support for a module specifying, in a <i>provides</i> directive, a service
198 * provider in another module.
199
200 * <p> A service provider that is developed in a module has no control over when
201 * it is instantiated, since that occurs at the behest of the application, but it
202 * does have control over how it is instantiated:
203 *
204 * <ul>
205 *
206 * <li> If the service provider declares a provider method, then the service
207 * loader invokes that method to obtain an instance of the service provider. A
208 * provider method is a public static method named "provider" with no formal
209 * parameters and a return type that is assignable to the service's interface
210 * or class.
211 * <p> In this case, the service provider itself need not be assignable to the
212 * service's interface or class. </li>
213 *
214 * <li> If the service provider does not declare a provider method, then the
215 * service provider is instantiated directly, via its provider constructor. A
216 * provider constructor is a public constructor with no formal parameters.
217 * <p> In this case, the service provider must be assignable to the service's
218 * interface or class </li>
219 *
220 * </ul>
221 *
222 * <p> A service provider that is deployed as an
223 * {@linkplain java.lang.module.ModuleDescriptor#isAutomatic automatic module} on
224 * the application module path must have a provider constructor. There is no
225 * support for a provider method in this case.
226 *
227 * <p> As an example, suppose a module specifies the following directives:
228 * <pre>{@code
229 * provides com.example.CodecFactory with com.example.impl.StandardCodecs;
230 * provides com.example.CodecFactory with com.example.impl.ExtendedCodecsFactory;
231 * }</pre>
232 *
233 * <p> where
234 *
235 * <ul>
236 * <li> {@code com.example.CodecFactory} is the two-method service from
237 * earlier. </li>
238 *
239 * <li> {@code com.example.impl.StandardCodecs} is a public class that implements
240 * {@code CodecFactory} and has a public no-args constructor. </li>
241 *
242 * <li> {@code com.example.impl.ExtendedCodecsFactory} is a public class that
243 * does not implement CodecFactory, but it declares a public static no-args
244 * method named "provider" with a return type of {@code CodecFactory}. </li>
245 * </ul>
246 *
247 * <p> A service loader will instantiate {@code StandardCodecs} via its
248 * constructor, and will instantiate {@code ExtendedCodecsFactory} by invoking
249 * its {@code provider} method. The requirement that the provider constructor or
250 * provider method is public helps to document the intent that the class (that is,
251 * the service provider) will be instantiated by an entity (that is, a service
252 * loader) which is outside the class's package.
253 *
254 * <h3> Deploying service providers on the class path </h3>
255 *
256 * A service provider that is packaged as a JAR file for the class path is
257 * identified by placing a <i>provider-configuration file</i> in the resource
258 * directory {@code META-INF/services}. The name of the provider-configuration
259 * file is the fully qualified binary name of the service. The provider-configuration
260 * file contains a list of fully qualified binary names of service providers, one
261 * per line.
262 *
263 * <p> For example, suppose the service provider
264 * {@code com.example.impl.StandardCodecs} is packaged in a JAR file for the
265 * class path. The JAR file will contain a provider-configuration file named:
266 *
267 * <blockquote>{@code
268 * META-INF/services/com.example.CodecFactory
269 * }</blockquote>
270 *
271 * that contains the line:
272 *
273 * <blockquote>{@code
274 * com.example.impl.StandardCodecs # Standard codecs
275 * }</blockquote>
276 *
277 * <p><a id="format">The provider-configuration file must be encoded in UTF-8. </a>
278 * Space and tab characters surrounding each service provider's name, as well as
279 * blank lines, are ignored. The comment character is {@code '#'}
280 * ({@code '\u0023'} <span style="font-size:smaller;">NUMBER SIGN</span>);
281 * on each line all characters following the first comment character are ignored.
282 * If a service provider class name is listed more than once in a
283 * provider-configuration file then the duplicate is ignored. If a service
284 * provider class is named in more than one configuration file then the duplicate
285 * is ignored.
286 *
287 * <p> A service provider that is mentioned in a provider-configuration file may
288 * be located in the same JAR file as the provider-configuration file or in a
289 * different JAR file. The service provider must be visible from the class loader
290 * that is initially queried to locate the provider-configuration file; this is
291 * not necessarily the class loader which ultimately locates the
292 * provider-configuration file.
293 *
294 * <h3> Timing of provider discovery </h3>
295 *
296 * <p> Service providers are loaded and instantiated lazily, that is, on demand.
297 * A service loader maintains a cache of the providers that have been loaded so
298 * far. Each invocation of the {@code iterator} method returns an {@code Iterator}
299 * that first yields all of the elements cached from previous iteration, in
300 * instantiation order, and then lazily locates and instantiates any remaining
301 * providers, adding each one to the cache in turn. Similarly, each invocation
302 * of the stream method returns a {@code Stream} that first processes all
303 * providers loaded by previous stream operations, in load order, and then lazily
304 * locates any remaining providers. Caches are cleared via the {@link #reload
305 * reload} method.
306 *
307 * <h3> <a id="errors">Errors</a> </h3>
308 *
309 * <p> When using the service loader's {@code iterator}, the {@link
310 * Iterator#hasNext() hasNext} and {@link Iterator#next() next} methods will
311 * fail with {@link ServiceConfigurationError} if an error occurs locating,
312 * loading or instantiating a service provider. When processing the service
313 * loader's stream then {@code ServiceConfigurationError} may be thrown by any
314 * method that causes a service provider to be located or loaded.
315 *
316 * <p> When loading or instantiating a service provider in a module, {@code
317 * ServiceConfigurationError} can be thrown for the following reasons:
318 *
319 * <ul>
320 *
321 * <li> The service provider cannot be loaded. </li>
322 *
323 * <li> The service provider does not declare a provider method, and either
324 * it is not assignable to the service's interface/class or does not have a
325 * provider constructor. </li>
326 *
327 * <li> The service provider declares a public static no-args method named
328 * "provider" with a return type that is not assignable to the service's
329 * interface or class. </li>
330 *
331 * <li> The service provider class file has more than one public static
332 * no-args method named "{@code provider}". </li>
333 *
334 * <li> The service provider declares a provider method and it fails by
335 * returning {@code null} or throwing an exception. </li>
336 *
337 * <li> The service provider does not declare a provider method, and its
338 * provider constructor fails by throwing an exception. </li>
339 *
340 * </ul>
341 *
342 * <p> When reading a provider-configuration file, or loading or instantiating
343 * a provider class named in a provider-configuration file, then {@code
344 * ServiceConfigurationError} can be thrown for the following reasons:
345 *
346 * <ul>
347 *
348 * <li> The format of the provider-configuration file violates the <a
349 * href="ServiceLoader.html#format">format</a> specified above; </li>
350 *
351 * <li> An {@link IOException IOException} occurs while reading the
352 * provider-configuration file; </li>
353 *
354 * <li> A service provider cannot be loaded; </li>
355 *
356 * <li> A service provider is not assignable to the service's interface or
357 * class, or does not define a provider constructor, or cannot be
358 * instantiated. </li>
359 *
360 * </ul>
361 *
362 * <h3> Security </h3>
363 *
364 * <p> Service loaders always execute in the security context of the caller
365 * of the iterator or stream methods and may also be restricted by the security
366 * context of the caller that created the service loader.
367 * Trusted system code should typically invoke the methods in this class, and
368 * the methods of the iterators which they return, from within a privileged
369 * security context.
370 *
371 * <h3> Concurrency </h3>
372 *
373 * <p> Instances of this class are not safe for use by multiple concurrent
374 * threads.
375 *
376 * <h3> Null handling </h3>
377 *
378 * <p> Unless otherwise specified, passing a {@code null} argument to any
379 * method in this class will cause a {@link NullPointerException} to be thrown.
380 *
381 * @param <S>
382 * The type of the service to be loaded by this loader
383 *
384 * @author Mark Reinhold
385 * @since 1.6
386 * @revised 9
387 * @spec JPMS
388 */
389
390 public final class ServiceLoader<S>
391 implements Iterable<S>
392 {
393 // The class or interface representing the service being loaded
394 private final Class<S> service;
395
396 // The class of the service type
397 private final String serviceName;
398
399 // The module layer used to locate providers; null when locating
400 // providers using a class loader
401 private final ModuleLayer layer;
402
403 // The class loader used to locate, load, and instantiate providers;
404 // null when locating provider using a module layer
405 private final ClassLoader loader;
406
407 // The access control context taken when the ServiceLoader is created
408 private final AccessControlContext acc;
409
410 // The lazy-lookup iterator for iterator operations
411 private Iterator<Provider<S>> lookupIterator1;
412 private final List<S> instantiatedProviders = new ArrayList<>();
413
414 // The lazy-lookup iterator for stream operations
415 private Iterator<Provider<S>> lookupIterator2;
416 private final List<Provider<S>> loadedProviders = new ArrayList<>();
417 private boolean loadedAllProviders; // true when all providers loaded
418
419 // Incremented when reload is called
420 private int reloadCount;
421
422 private static JavaLangAccess LANG_ACCESS;
423 static {
424 LANG_ACCESS = SharedSecrets.getJavaLangAccess();
425 }
426
427 /**
428 * Represents a service provider located by {@code ServiceLoader}.
429 *
430 * <p> When using a loader's {@link ServiceLoader#stream() stream()} method
431 * then the elements are of type {@code Provider}. This allows processing
432 * to select or filter on the provider class without instantiating the
433 * provider. </p>
434 *
435 * @param <S> The service type
436 * @since 9
437 * @spec JPMS
438 */
439 public static interface Provider<S> extends Supplier<S> {
440 /**
441 * Returns the provider type. There is no guarantee that this type is
442 * accessible or that it has a public no-args constructor. The {@link
443 * #get() get()} method should be used to obtain the provider instance.
444 *
445 * <p> When a module declares that the provider class is created by a
446 * provider factory then this method returns the return type of its
447 * public static "{@code provider()}" method.
448 *
449 * @return The provider type
450 */
451 Class<? extends S> type();
452
453 /**
454 * Returns an instance of the provider.
455 *
456 * @return An instance of the provider.
457 *
458 * @throws ServiceConfigurationError
459 * If the service provider cannot be instantiated, or in the
460 * case of a provider factory, the public static
461 * "{@code provider()}" method returns {@code null} or throws
462 * an error or exception. The {@code ServiceConfigurationError}
463 * will carry an appropriate cause where possible.
464 */
465 @Override S get();
466 }
467
468 /**
469 * Initializes a new instance of this class for locating service providers
470 * in a module layer.
471 *
472 * @throws ServiceConfigurationError
473 * If {@code svc} is not accessible to {@code caller} or the caller
474 * module does not use the service type.
475 */
476 private ServiceLoader(Class<?> caller, ModuleLayer layer, Class<S> svc) {
477 Objects.requireNonNull(caller);
478 Objects.requireNonNull(layer);
479 Objects.requireNonNull(svc);
480 checkCaller(caller, svc);
481
482 this.service = svc;
483 this.serviceName = svc.getName();
484 this.layer = layer;
485 this.loader = null;
486 this.acc = (System.getSecurityManager() != null)
487 ? AccessController.getContext()
488 : null;
489 }
490
491 /**
492 * Initializes a new instance of this class for locating service providers
493 * via a class loader.
494 *
495 * @throws ServiceConfigurationError
496 * If {@code svc} is not accessible to {@code caller} or the caller
497 * module does not use the service type.
498 */
499 private ServiceLoader(Class<?> caller, Class<S> svc, ClassLoader cl) {
500 Objects.requireNonNull(svc);
501
502 if (VM.isBooted()) {
503 checkCaller(caller, svc);
504 if (cl == null) {
505 cl = ClassLoader.getSystemClassLoader();
506 }
507 } else {
508
509 // if we get here then it means that ServiceLoader is being used
510 // before the VM initialization has completed. At this point then
511 // only code in the java.base should be executing.
512 Module callerModule = caller.getModule();
513 Module base = Object.class.getModule();
514 Module svcModule = svc.getModule();
515 if (callerModule != base || svcModule != base) {
516 fail(svc, "not accessible to " + callerModule + " during VM init");
517 }
518
519 // restricted to boot loader during startup
520 cl = null;
521 }
522
523 this.service = svc;
524 this.serviceName = svc.getName();
525 this.layer = null;
526 this.loader = cl;
527 this.acc = (System.getSecurityManager() != null)
528 ? AccessController.getContext()
529 : null;
530 }
531
532 /**
533 * Initializes a new instance of this class for locating service providers
534 * via a class loader.
535 *
536 * @apiNote For use by ResourceBundle
537 *
538 * @throws ServiceConfigurationError
539 * If the caller module does not use the service type.
540 */
541 private ServiceLoader(Module callerModule, Class<S> svc, ClassLoader cl) {
542 if (!callerModule.canUse(svc)) {
543 fail(svc, callerModule + " does not declare `uses`");
544 }
545
546 this.service = Objects.requireNonNull(svc);
547 this.serviceName = svc.getName();
548 this.layer = null;
549 this.loader = cl;
550 this.acc = (System.getSecurityManager() != null)
551 ? AccessController.getContext()
552 : null;
553 }
554
555 /**
556 * Checks that the given service type is accessible to types in the given
557 * module, and check that the module declares that it uses the service type.
558 */
559 private static void checkCaller(Class<?> caller, Class<?> svc) {
560 if (caller == null) {
561 fail(svc, "no caller to check if it declares `uses`");
562 }
563
564 // Check access to the service type
565 Module callerModule = caller.getModule();
566 int mods = svc.getModifiers();
567 if (!Reflection.verifyMemberAccess(caller, svc, null, mods)) {
568 fail(svc, "service type not accessible to " + callerModule);
569 }
570
571 // If the caller is in a named module then it should "uses" the
572 // service type
573 if (!callerModule.canUse(svc)) {
574 fail(svc, callerModule + " does not declare `uses`");
575 }
576 }
577
578 private static void fail(Class<?> service, String msg, Throwable cause)
579 throws ServiceConfigurationError
580 {
581 throw new ServiceConfigurationError(service.getName() + ": " + msg,
582 cause);
583 }
584
585 private static void fail(Class<?> service, String msg)
586 throws ServiceConfigurationError
587 {
588 throw new ServiceConfigurationError(service.getName() + ": " + msg);
589 }
590
591 private static void fail(Class<?> service, URL u, int line, String msg)
592 throws ServiceConfigurationError
593 {
594 fail(service, u + ":" + line + ": " + msg);
595 }
596
597 /**
598 * Returns {@code true} if the provider is in an explicit module
599 */
600 private boolean inExplicitModule(Class<?> clazz) {
601 Module module = clazz.getModule();
602 return module.isNamed() && !module.getDescriptor().isAutomatic();
603 }
604
605 /**
606 * Returns the public static "provider" method if found.
607 *
608 * @throws ServiceConfigurationError if there is an error finding the
609 * provider method or there is more than one public static
610 * provider method
611 */
612 private Method findStaticProviderMethod(Class<?> clazz) {
613 List<Method> methods = null;
614 try {
615 methods = LANG_ACCESS.getDeclaredPublicMethods(clazz, "provider");
616 } catch (Throwable x) {
617 fail(service, "Unable to get public provider() method", x);
618 }
619 if (methods.isEmpty()) {
620 // does not declare a public provider method
621 return null;
622 }
623
624 // locate the static methods, can be at most one
625 Method result = null;
626 for (Method method : methods) {
627 int mods = method.getModifiers();
628 assert Modifier.isPublic(mods);
629 if (Modifier.isStatic(mods)) {
630 if (result != null) {
631 fail(service, clazz + " declares more than one"
632 + " public static provider() method");
633 }
634 result = method;
635 }
636 }
637 if (result != null) {
638 Method m = result;
639 PrivilegedAction<Void> pa = () -> {
640 m.setAccessible(true);
641 return null;
642 };
643 AccessController.doPrivileged(pa);
644 }
645 return result;
646 }
647
648 /**
649 * Returns the public no-arg constructor of a class.
650 *
651 * @throws ServiceConfigurationError if the class does not have
652 * public no-arg constructor
653 */
654 private Constructor<?> getConstructor(Class<?> clazz) {
655 PrivilegedExceptionAction<Constructor<?>> pa
656 = new PrivilegedExceptionAction<>() {
657 @Override
658 public Constructor<?> run() throws Exception {
659 Constructor<?> ctor = clazz.getConstructor();
660 if (inExplicitModule(clazz))
661 ctor.setAccessible(true);
662 return ctor;
663 }
664 };
665 Constructor<?> ctor = null;
666 try {
667 ctor = AccessController.doPrivileged(pa);
668 } catch (Throwable x) {
669 if (x instanceof PrivilegedActionException)
670 x = x.getCause();
671 String cn = clazz.getName();
672 fail(service, cn + " Unable to get public no-arg constructor", x);
673 }
674 return ctor;
675 }
676
677 /**
678 * A Provider implementation that supports invoking, with reduced
679 * permissions, the static factory to obtain the provider or the
680 * provider's no-arg constructor.
681 */
682 private static class ProviderImpl<S> implements Provider<S> {
683 final Class<S> service;
684 final Class<? extends S> type;
685 final Method factoryMethod; // factory method or null
686 final Constructor<? extends S> ctor; // public no-args constructor or null
687 final AccessControlContext acc;
688
689 ProviderImpl(Class<S> service,
690 Class<? extends S> type,
691 Method factoryMethod,
692 AccessControlContext acc) {
693 this.service = service;
694 this.type = type;
695 this.factoryMethod = factoryMethod;
696 this.ctor = null;
697 this.acc = acc;
698 }
699
700 ProviderImpl(Class<S> service,
701 Class<? extends S> type,
702 Constructor<? extends S> ctor,
703 AccessControlContext acc) {
704 this.service = service;
705 this.type = type;
706 this.factoryMethod = null;
707 this.ctor = ctor;
708 this.acc = acc;
709 }
710
711 @Override
712 public Class<? extends S> type() {
713 return type;
714 }
715
716 @Override
717 public S get() {
718 if (factoryMethod != null) {
719 return invokeFactoryMethod();
720 } else {
721 return newInstance();
722 }
723 }
724
725 /**
726 * Invokes the provider's "provider" method to instantiate a provider.
727 * When running with a security manager then the method runs with
728 * permissions that are restricted by the security context of whatever
729 * created this loader.
730 */
731 private S invokeFactoryMethod() {
732 Object result = null;
733 Throwable exc = null;
734 if (acc == null) {
735 try {
736 result = factoryMethod.invoke(null);
737 } catch (Throwable x) {
738 exc = x;
739 }
740 } else {
741 PrivilegedExceptionAction<?> pa = new PrivilegedExceptionAction<>() {
742 @Override
743 public Object run() throws Exception {
744 return factoryMethod.invoke(null);
745 }
746 };
747 // invoke factory method with permissions restricted by acc
748 try {
749 result = AccessController.doPrivileged(pa, acc);
750 } catch (Throwable x) {
751 if (x instanceof PrivilegedActionException)
752 x = x.getCause();
753 exc = x;
754 }
755 }
756 if (exc != null) {
757 if (exc instanceof InvocationTargetException)
758 exc = exc.getCause();
759 fail(service, factoryMethod + " failed", exc);
760 }
761 if (result == null) {
762 fail(service, factoryMethod + " returned null");
763 }
764 @SuppressWarnings("unchecked")
765 S p = (S) result;
766 return p;
767 }
768
769 /**
770 * Invokes Constructor::newInstance to instantiate a provider. When running
771 * with a security manager then the constructor runs with permissions that
772 * are restricted by the security context of whatever created this loader.
773 */
774 private S newInstance() {
775 S p = null;
776 Throwable exc = null;
777 if (acc == null) {
778 try {
779 p = ctor.newInstance();
780 } catch (Throwable x) {
781 exc = x;
782 }
783 } else {
784 PrivilegedExceptionAction<S> pa = new PrivilegedExceptionAction<>() {
785 @Override
786 public S run() throws Exception {
787 return ctor.newInstance();
788 }
789 };
790 // invoke constructor with permissions restricted by acc
791 try {
792 p = AccessController.doPrivileged(pa, acc);
793 } catch (Throwable x) {
794 if (x instanceof PrivilegedActionException)
795 x = x.getCause();
796 exc = x;
797 }
798 }
799 if (exc != null) {
800 if (exc instanceof InvocationTargetException)
801 exc = exc.getCause();
802 String cn = ctor.getDeclaringClass().getName();
803 fail(service,
804 "Provider " + cn + " could not be instantiated", exc);
805 }
806 return p;
807 }
808
809 // For now, equals/hashCode uses the access control context to ensure
810 // that two Providers created with different contexts are not equal
811 // when running with a security manager.
812
813 @Override
814 public int hashCode() {
815 return Objects.hash(service, type, acc);
816 }
817
818 @Override
819 public boolean equals(Object ob) {
820 if (!(ob instanceof ProviderImpl))
821 return false;
822 @SuppressWarnings("unchecked")
823 ProviderImpl<?> that = (ProviderImpl<?>)ob;
824 return this.service == that.service
825 && this.type == that.type
826 && Objects.equals(this.acc, that.acc);
827 }
828 }
829
830 /**
831 * Loads a service provider in a module.
832 *
833 * Returns {@code null} if the service provider's module doesn't read
834 * the module with the service type.
835 *
836 * @throws ServiceConfigurationError if the class cannot be loaded or
837 * isn't the expected sub-type (or doesn't define a provider
838 * factory method that returns the expected type)
839 */
840 private Provider<S> loadProvider(ServiceProvider provider) {
841 Module module = provider.module();
842 if (!module.canRead(service.getModule())) {
843 // module does not read the module with the service type
844 return null;
845 }
846
847 String cn = provider.providerName();
848 Class<?> clazz = null;
849 if (acc == null) {
850 try {
851 clazz = Class.forName(module, cn);
852 } catch (LinkageError e) {
853 fail(service, "Unable to load " + cn, e);
854 }
855 } else {
856 PrivilegedExceptionAction<Class<?>> pa = () -> Class.forName(module, cn);
857 try {
858 clazz = AccessController.doPrivileged(pa);
859 } catch (Throwable x) {
860 if (x instanceof PrivilegedActionException)
861 x = x.getCause();
862 fail(service, "Unable to load " + cn, x);
863 return null;
864 }
865 }
866 if (clazz == null) {
867 fail(service, "Provider " + cn + " not found");
868 }
869
870 int mods = clazz.getModifiers();
871 if (!Modifier.isPublic(mods)) {
872 fail(service, clazz + " is not public");
873 }
874
875 // if provider in explicit module then check for static factory method
876 if (inExplicitModule(clazz)) {
877 Method factoryMethod = findStaticProviderMethod(clazz);
878 if (factoryMethod != null) {
879 Class<?> returnType = factoryMethod.getReturnType();
880 if (!service.isAssignableFrom(returnType)) {
881 fail(service, factoryMethod + " return type not a subtype");
882 }
883
884 @SuppressWarnings("unchecked")
885 Class<? extends S> type = (Class<? extends S>) returnType;
886 return new ProviderImpl<S>(service, type, factoryMethod, acc);
887 }
888 }
889
890 // no factory method so must be a subtype
891 if (!service.isAssignableFrom(clazz)) {
892 fail(service, clazz.getName() + " not a subtype");
893 }
894
895 @SuppressWarnings("unchecked")
896 Class<? extends S> type = (Class<? extends S>) clazz;
897 @SuppressWarnings("unchecked")
898 Constructor<? extends S> ctor = (Constructor<? extends S> ) getConstructor(clazz);
899 return new ProviderImpl<S>(service, type, ctor, acc);
900 }
901
902 /**
903 * Implements lazy service provider lookup of service providers that
904 * are provided by modules in a module layer (or parent layers)
905 */
906 private final class LayerLookupIterator<T>
907 implements Iterator<Provider<T>>
908 {
909 Deque<ModuleLayer> stack = new ArrayDeque<>();
910 Set<ModuleLayer> visited = new HashSet<>();
911 Iterator<ServiceProvider> iterator;
912
913 Provider<T> nextProvider;
914 ServiceConfigurationError nextError;
915
916 LayerLookupIterator() {
917 visited.add(layer);
918 stack.push(layer);
919 }
920
921 private Iterator<ServiceProvider> providers(ModuleLayer layer) {
922 ServicesCatalog catalog = LANG_ACCESS.getServicesCatalog(layer);
923 return catalog.findServices(serviceName).iterator();
924 }
925
926 @Override
927 public boolean hasNext() {
928 while (nextProvider == null && nextError == null) {
929 // get next provider to load
930 while (iterator == null || !iterator.hasNext()) {
931 // next layer (DFS order)
932 if (stack.isEmpty())
933 return false;
934
935 ModuleLayer layer = stack.pop();
936 List<ModuleLayer> parents = layer.parents();
937 for (int i = parents.size() - 1; i >= 0; i--) {
938 ModuleLayer parent = parents.get(i);
939 if (!visited.contains(parent)) {
940 visited.add(parent);
941 stack.push(parent);
942 }
943 }
944 iterator = providers(layer);
945 }
946
947 // attempt to load provider
948 ServiceProvider provider = iterator.next();
949 try {
950 @SuppressWarnings("unchecked")
951 Provider<T> next = (Provider<T>) loadProvider(provider);
952 nextProvider = next;
953 } catch (ServiceConfigurationError e) {
954 nextError = e;
955 }
956 }
957 return true;
958 }
959
960 @Override
961 public Provider<T> next() {
962 if (!hasNext())
963 throw new NoSuchElementException();
964
965 Provider<T> provider = nextProvider;
966 if (provider != null) {
967 nextProvider = null;
968 return provider;
969 } else {
970 ServiceConfigurationError e = nextError;
971 assert e != null;
972 nextError = null;
973 throw e;
974 }
975 }
976 }
977
978 /**
979 * Implements lazy service provider lookup of service providers that
980 * are provided by modules defined to a class loader or to modules in
981 * layers with a module defined to the class loader.
982 */
983 private final class ModuleServicesLookupIterator<T>
984 implements Iterator<Provider<T>>
985 {
986 ClassLoader currentLoader;
987 Iterator<ServiceProvider> iterator;
988
989 Provider<T> nextProvider;
990 ServiceConfigurationError nextError;
991
992 ModuleServicesLookupIterator() {
993 this.currentLoader = loader;
994 this.iterator = iteratorFor(loader);
995 }
996
997 /**
998 * Returns iterator to iterate over the implementations of {@code
999 * service} in the given layer.
1000 */
1001 private List<ServiceProvider> providers(ModuleLayer layer) {
1002 ServicesCatalog catalog = LANG_ACCESS.getServicesCatalog(layer);
1003 return catalog.findServices(serviceName);
1004 }
1005
1006 /**
1007 * Returns the class loader that a module is defined to
1008 */
1009 private ClassLoader loaderFor(Module module) {
1010 SecurityManager sm = System.getSecurityManager();
1011 if (sm == null) {
1012 return module.getClassLoader();
1013 } else {
1014 PrivilegedAction<ClassLoader> pa = module::getClassLoader;
1015 return AccessController.doPrivileged(pa);
1016 }
1017 }
1018
1019 /**
1020 * Returns an iterator to iterate over the implementations of {@code
1021 * service} in modules defined to the given class loader or in custom
1022 * layers with a module defined to this class loader.
1023 */
1024 private Iterator<ServiceProvider> iteratorFor(ClassLoader loader) {
1025 // modules defined to the class loader
1026 ServicesCatalog catalog;
1027 if (loader == null) {
1028 catalog = BootLoader.getServicesCatalog();
1029 } else {
1030 catalog = ServicesCatalog.getServicesCatalogOrNull(loader);
1031 }
1032 List<ServiceProvider> providers;
1033 if (catalog == null) {
1034 providers = List.of();
1035 } else {
1036 providers = catalog.findServices(serviceName);
1037 }
1038
1039 // modules in layers that define modules to the class loader
1040 ClassLoader platformClassLoader = ClassLoaders.platformClassLoader();
1041 if (loader == null || loader == platformClassLoader) {
1042 return providers.iterator();
1043 } else {
1044 List<ServiceProvider> allProviders = new ArrayList<>(providers);
1045 Iterator<ModuleLayer> iterator = LANG_ACCESS.layers(loader).iterator();
1046 while (iterator.hasNext()) {
1047 ModuleLayer layer = iterator.next();
1048 for (ServiceProvider sp : providers(layer)) {
1049 ClassLoader l = loaderFor(sp.module());
1050 if (l != null && l != platformClassLoader) {
1051 allProviders.add(sp);
1052 }
1053 }
1054 }
1055 return allProviders.iterator();
1056 }
1057 }
1058
1059 @Override
1060 public boolean hasNext() {
1061 while (nextProvider == null && nextError == null) {
1062 // get next provider to load
1063 while (!iterator.hasNext()) {
1064 if (currentLoader == null) {
1065 return false;
1066 } else {
1067 currentLoader = currentLoader.getParent();
1068 iterator = iteratorFor(currentLoader);
1069 }
1070 }
1071
1072 // attempt to load provider
1073 ServiceProvider provider = iterator.next();
1074 try {
1075 @SuppressWarnings("unchecked")
1076 Provider<T> next = (Provider<T>) loadProvider(provider);
1077 nextProvider = next;
1078 } catch (ServiceConfigurationError e) {
1079 nextError = e;
1080 }
1081 }
1082 return true;
1083 }
1084
1085 @Override
1086 public Provider<T> next() {
1087 if (!hasNext())
1088 throw new NoSuchElementException();
1089
1090 Provider<T> provider = nextProvider;
1091 if (provider != null) {
1092 nextProvider = null;
1093 return provider;
1094 } else {
1095 ServiceConfigurationError e = nextError;
1096 assert e != null;
1097 nextError = null;
1098 throw e;
1099 }
1100 }
1101 }
1102
1103 /**
1104 * Implements lazy service provider lookup where the service providers are
1105 * configured via service configuration files. Service providers in named
1106 * modules are silently ignored by this lookup iterator.
1107 */
1108 private final class LazyClassPathLookupIterator<T>
1109 implements Iterator<Provider<T>>
1110 {
1111 static final String PREFIX = "META-INF/services/";
1112
1113 Set<String> providerNames = new HashSet<>(); // to avoid duplicates
1114 Enumeration<URL> configs;
1115 Iterator<String> pending;
1116
1117 Provider<T> nextProvider;
1118 ServiceConfigurationError nextError;
1119
1120 LazyClassPathLookupIterator() { }
1121
1122 /**
1123 * Parse a single line from the given configuration file, adding the
1124 * name on the line to set of names if not already seen.
1125 */
1126 private int parseLine(URL u, BufferedReader r, int lc, Set<String> names)
1127 throws IOException
1128 {
1129 String ln = r.readLine();
1130 if (ln == null) {
1131 return -1;
1132 }
1133 int ci = ln.indexOf('#');
1134 if (ci >= 0) ln = ln.substring(0, ci);
1135 ln = ln.trim();
1136 int n = ln.length();
1137 if (n != 0) {
1138 if ((ln.indexOf(' ') >= 0) || (ln.indexOf('\t') >= 0))
1139 fail(service, u, lc, "Illegal configuration-file syntax");
1140 int cp = ln.codePointAt(0);
1141 if (!Character.isJavaIdentifierStart(cp))
1142 fail(service, u, lc, "Illegal provider-class name: " + ln);
1143 int start = Character.charCount(cp);
1144 for (int i = start; i < n; i += Character.charCount(cp)) {
1145 cp = ln.codePointAt(i);
1146 if (!Character.isJavaIdentifierPart(cp) && (cp != '.'))
1147 fail(service, u, lc, "Illegal provider-class name: " + ln);
1148 }
1149 if (providerNames.add(ln)) {
1150 names.add(ln);
1151 }
1152 }
1153 return lc + 1;
1154 }
1155
1156 /**
1157 * Parse the content of the given URL as a provider-configuration file.
1158 */
1159 private Iterator<String> parse(URL u) {
1160 Set<String> names = new LinkedHashSet<>(); // preserve insertion order
1161 try {
1162 URLConnection uc = u.openConnection();
1163 uc.setUseCaches(false);
1164 try (InputStream in = uc.getInputStream();
1165 BufferedReader r
1166 = new BufferedReader(new InputStreamReader(in, "utf-8")))
1167 {
1168 int lc = 1;
1169 while ((lc = parseLine(u, r, lc, names)) >= 0);
1170 }
1171 } catch (IOException x) {
1172 fail(service, "Error accessing configuration file", x);
1173 }
1174 return names.iterator();
1175 }
1176
1177 /**
1178 * Loads and returns the next provider class.
1179 */
1180 private Class<?> nextProviderClass() {
1181 if (configs == null) {
1182 try {
1183 String fullName = PREFIX + service.getName();
1184 if (loader == null) {
1185 configs = ClassLoader.getSystemResources(fullName);
1186 } else if (loader == ClassLoaders.platformClassLoader()) {
1187 // The platform classloader doesn't have a class path,
1188 // but the boot loader might.
1189 if (BootLoader.hasClassPath()) {
1190 configs = BootLoader.findResources(fullName);
1191 } else {
1192 configs = Collections.emptyEnumeration();
1193 }
1194 } else {
1195 configs = loader.getResources(fullName);
1196 }
1197 } catch (IOException x) {
1198 fail(service, "Error locating configuration files", x);
1199 }
1200 }
1201 while ((pending == null) || !pending.hasNext()) {
1202 if (!configs.hasMoreElements()) {
1203 return null;
1204 }
1205 pending = parse(configs.nextElement());
1206 }
1207 String cn = pending.next();
1208 try {
1209 return Class.forName(cn, false, loader);
1210 } catch (ClassNotFoundException x) {
1211 fail(service, "Provider " + cn + " not found");
1212 return null;
1213 }
1214 }
1215
1216 @SuppressWarnings("unchecked")
1217 private boolean hasNextService() {
1218 while (nextProvider == null && nextError == null) {
1219 try {
1220 Class<?> clazz = nextProviderClass();
1221 if (clazz == null)
1222 return false;
1223
1224 if (clazz.getModule().isNamed()) {
1225 // ignore class if in named module
1226 continue;
1227 }
1228
1229 if (service.isAssignableFrom(clazz)) {
1230 Class<? extends S> type = (Class<? extends S>) clazz;
1231 Constructor<? extends S> ctor
1232 = (Constructor<? extends S>)getConstructor(clazz);
1233 ProviderImpl<S> p = new ProviderImpl<S>(service, type, ctor, acc);
1234 nextProvider = (ProviderImpl<T>) p;
1235 } else {
1236 fail(service, clazz.getName() + " not a subtype");
1237 }
1238 } catch (ServiceConfigurationError e) {
1239 nextError = e;
1240 }
1241 }
1242 return true;
1243 }
1244
1245 private Provider<T> nextService() {
1246 if (!hasNextService())
1247 throw new NoSuchElementException();
1248
1249 Provider<T> provider = nextProvider;
1250 if (provider != null) {
1251 nextProvider = null;
1252 return provider;
1253 } else {
1254 ServiceConfigurationError e = nextError;
1255 assert e != null;
1256 nextError = null;
1257 throw e;
1258 }
1259 }
1260
1261 @Override
1262 public boolean hasNext() {
1263 if (acc == null) {
1264 return hasNextService();
1265 } else {
1266 PrivilegedAction<Boolean> action = new PrivilegedAction<>() {
1267 public Boolean run() { return hasNextService(); }
1268 };
1269 return AccessController.doPrivileged(action, acc);
1270 }
1271 }
1272
1273 @Override
1274 public Provider<T> next() {
1275 if (acc == null) {
1276 return nextService();
1277 } else {
1278 PrivilegedAction<Provider<T>> action = new PrivilegedAction<>() {
1279 public Provider<T> run() { return nextService(); }
1280 };
1281 return AccessController.doPrivileged(action, acc);
1282 }
1283 }
1284 }
1285
1286 /**
1287 * Returns a new lookup iterator.
1288 */
1289 private Iterator<Provider<S>> newLookupIterator() {
1290 assert layer == null || loader == null;
1291 if (layer != null) {
1292 return new LayerLookupIterator<>();
1293 } else {
1294 Iterator<Provider<S>> first = new ModuleServicesLookupIterator<>();
1295 Iterator<Provider<S>> second = new LazyClassPathLookupIterator<>();
1296 return new Iterator<Provider<S>>() {
1297 @Override
1298 public boolean hasNext() {
1299 return (first.hasNext() || second.hasNext());
1300 }
1301 @Override
1302 public Provider<S> next() {
1303 if (first.hasNext()) {
1304 return first.next();
1305 } else if (second.hasNext()) {
1306 return second.next();
1307 } else {
1308 throw new NoSuchElementException();
1309 }
1310 }
1311 };
1312 }
1313 }
1314
1315 /**
1316 * Returns an iterator to lazily load and instantiate the available
1317 * providers of this loader's service.
1318 *
1319 * <p> To achieve laziness the actual work of locating and instantiating
1320 * providers is done by the iterator itself. Its {@link Iterator#hasNext
1321 * hasNext} and {@link Iterator#next next} methods can therefore throw a
1322 * {@link ServiceConfigurationError} for any of the reasons specified in
1323 * the <a href="#errors">Errors</a> section above. To write robust code it
1324 * is only necessary to catch {@code ServiceConfigurationError} when using
1325 * the iterator. If an error is thrown then subsequent invocations of the
1326 * iterator will make a best effort to locate and instantiate the next
1327 * available provider, but in general such recovery cannot be guaranteed.
1328 *
1329 * <p> Caching: The iterator returned by this method first yields all of
1330 * the elements of the provider cache, in the order that they were loaded.
1331 * It then lazily loads and instantiates any remaining service providers,
1332 * adding each one to the cache in turn. If this loader's provider caches are
1333 * cleared by invoking the {@link #reload() reload} method then existing
1334 * iterators for this service loader should be discarded.
1335 * The {@code hasNext} and {@code next} methods of the iterator throw {@link
1336 * java.util.ConcurrentModificationException ConcurrentModificationException}
1337 * if used after the provider cache has been cleared.
1338 *
1339 * <p> The iterator returned by this method does not support removal.
1340 * Invoking its {@link java.util.Iterator#remove() remove} method will
1341 * cause an {@link UnsupportedOperationException} to be thrown.
1342 *
1343 * @apiNote Throwing an error in these cases may seem extreme. The rationale
1344 * for this behavior is that a malformed provider-configuration file, like a
1345 * malformed class file, indicates a serious problem with the way the Java
1346 * virtual machine is configured or is being used. As such it is preferable
1347 * to throw an error rather than try to recover or, even worse, fail silently.
1348 *
1349 * @return An iterator that lazily loads providers for this loader's
1350 * service
1351 *
1352 * @revised 9
1353 * @spec JPMS
1354 */
1355 public Iterator<S> iterator() {
1356
1357 // create lookup iterator if needed
1358 if (lookupIterator1 == null) {
1359 lookupIterator1 = newLookupIterator();
1360 }
1361
1362 return new Iterator<S>() {
1363
1364 // record reload count
1365 final int expectedReloadCount = ServiceLoader.this.reloadCount;
1366
1367 // index into the cached providers list
1368 int index;
1369
1370 /**
1371 * Throws ConcurrentModificationException if the list of cached
1372 * providers has been cleared by reload.
1373 */
1374 private void checkReloadCount() {
1375 if (ServiceLoader.this.reloadCount != expectedReloadCount)
1376 throw new ConcurrentModificationException();
1377 }
1378
1379 @Override
1380 public boolean hasNext() {
1381 checkReloadCount();
1382 if (index < instantiatedProviders.size())
1383 return true;
1384 return lookupIterator1.hasNext();
1385 }
1386
1387 @Override
1388 public S next() {
1389 checkReloadCount();
1390 S next;
1391 if (index < instantiatedProviders.size()) {
1392 next = instantiatedProviders.get(index);
1393 } else {
1394 next = lookupIterator1.next().get();
1395 instantiatedProviders.add(next);
1396 }
1397 index++;
1398 return next;
1399 }
1400
1401 };
1402 }
1403
1404 /**
1405 * Returns a stream to lazily load available providers of this loader's
1406 * service. The stream elements are of type {@link Provider Provider}, the
1407 * {@code Provider}'s {@link Provider#get() get} method must be invoked to
1408 * get or instantiate the provider.
1409 *
1410 * <p> To achieve laziness the actual work of locating providers is done
1411 * when processing the stream. If a service provider cannot be loaded for any
1412 * of the reasons specified in the <a href="#errors">Errors</a> section
1413 * above then {@link ServiceConfigurationError} is thrown by whatever method
1414 * caused the service provider to be loaded. </p>
1415 *
1416 * <p> Caching: When processing the stream then providers that were previously
1417 * loaded by stream operations are processed first, in load order. It then
1418 * lazily loads any remaining service providers. If this loader's provider
1419 * caches are cleared by invoking the {@link #reload() reload} method then
1420 * existing streams for this service loader should be discarded. The returned
1421 * stream's source {@link Spliterator spliterator} is <em>fail-fast</em> and
1422 * will throw {@link ConcurrentModificationException} if the provider cache
1423 * has been cleared. </p>
1424 *
1425 * <p> The following examples demonstrate usage. The first example creates
1426 * a stream of {@code CodecFactory} objects, the second example is the same
1427 * except that it sorts the providers by provider class name (and so locate
1428 * all providers).
1429 * <pre>{@code
1430 * Stream<CodecFactory> providers = ServiceLoader.load(CodecFactory.class)
1431 * .stream()
1432 * .map(Provider::get);
1433 *
1434 * Stream<CodecFactory> providers = ServiceLoader.load(CodecFactory.class)
1435 * .stream()
1436 * .sorted(Comparator.comparing(p -> p.type().getName()))
1437 * .map(Provider::get);
1438 * }</pre>
1439 *
1440 * @return A stream that lazily loads providers for this loader's service
1441 *
1442 * @since 9
1443 * @spec JPMS
1444 */
1445 public Stream<Provider<S>> stream() {
1446 // use cached providers as the source when all providers loaded
1447 if (loadedAllProviders) {
1448 return loadedProviders.stream();
1449 }
1450
1451 // create lookup iterator if needed
1452 if (lookupIterator2 == null) {
1453 lookupIterator2 = newLookupIterator();
1454 }
1455
1456 // use lookup iterator and cached providers as source
1457 Spliterator<Provider<S>> s = new ProviderSpliterator<>(lookupIterator2);
1458 return StreamSupport.stream(s, false);
1459 }
1460
1461 private class ProviderSpliterator<T> implements Spliterator<Provider<T>> {
1462 final int expectedReloadCount = ServiceLoader.this.reloadCount;
1463 final Iterator<Provider<T>> iterator;
1464 int index;
1465
1466 ProviderSpliterator(Iterator<Provider<T>> iterator) {
1467 this.iterator = iterator;
1468 }
1469
1470 @Override
1471 public Spliterator<Provider<T>> trySplit() {
1472 return null;
1473 }
1474
1475 @Override
1476 @SuppressWarnings("unchecked")
1477 public boolean tryAdvance(Consumer<? super Provider<T>> action) {
1478 if (ServiceLoader.this.reloadCount != expectedReloadCount)
1479 throw new ConcurrentModificationException();
1480 Provider<T> next = null;
1481 if (index < loadedProviders.size()) {
1482 next = (Provider<T>) loadedProviders.get(index++);
1483 } else if (iterator.hasNext()) {
1484 next = iterator.next();
1485 loadedProviders.add((Provider<S>)next);
1486 index++;
1487 } else {
1488 loadedAllProviders = true;
1489 }
1490 if (next != null) {
1491 action.accept(next);
1492 return true;
1493 } else {
1494 return false;
1495 }
1496 }
1497
1498 @Override
1499 public int characteristics() {
1500 // not IMMUTABLE as structural interference possible
1501 // not NOTNULL so that the characteristics are a subset of the
1502 // characteristics when all Providers have been located.
1503 return Spliterator.ORDERED;
1504 }
1505
1506 @Override
1507 public long estimateSize() {
1508 return Long.MAX_VALUE;
1509 }
1510 }
1511
1512 /**
1513 * Creates a new service loader for the given service type, class
1514 * loader, and caller.
1515 *
1516 * @param <S> the class of the service type
1517 *
1518 * @param service
1519 * The interface or abstract class representing the service
1520 *
1521 * @param loader
1522 * The class loader to be used to load provider-configuration files
1523 * and provider classes, or {@code null} if the system class
1524 * loader (or, failing that, the bootstrap class loader) is to be
1525 * used
1526 *
1527 * @param callerModule
1528 * The caller's module for which a new service loader is created
1529 *
1530 * @return A new service loader
1531 */
1532 static <S> ServiceLoader<S> load(Class<S> service,
1533 ClassLoader loader,
1534 Module callerModule)
1535 {
1536 return new ServiceLoader<>(callerModule, service, loader);
1537 }
1538
1539 /**
1540 * Creates a new service loader for the given service. The service loader
1541 * uses the given class loader as the starting point to locate service
1542 * providers for the service. The service loader's {@link #iterator()
1543 * iterator} and {@link #stream() stream} locate providers in both named
1544 * and unnamed modules, as follows:
1545 *
1546 * <ul>
1547 * <li> <p> Step 1: Locate providers in named modules. </p>
1548 *
1549 * <p> Service providers are located in all named modules of the class
1550 * loader or to any class loader reachable via parent delegation. </p>
1551 *
1552 * <p> In addition, if the class loader is not the bootstrap or {@linkplain
1553 * ClassLoader#getPlatformClassLoader() platform class loader}, then service
1554 * providers may be located in the named modules of other class loaders.
1555 * Specifically, if the class loader, or any class loader reachable via
1556 * parent delegation, has a module in a {@linkplain ModuleLayer module
1557 * layer}, then service providers in all modules in the module layer are
1558 * located. </p>
1559 *
1560 * <p> For example, suppose there is a module layer where each module is
1561 * in its own class loader (see {@link ModuleLayer#defineModulesWithManyLoaders
1562 * defineModulesWithManyLoaders}). If this {@code ServiceLoader.load} method
1563 * is invoked to locate providers using any of the class loaders created for
1564 * the module layer, then it will locate all of the providers in the module
1565 * layer, irrespective of their defining class loader. </p>
1566 *
1567 * <p> Ordering: The service loader will first locate any service providers
1568 * in modules defined to the class loader, then its parent class loader,
1569 * its parent parent, and so on to the bootstrap class loader. If a class
1570 * loader has modules in a module layer then all providers in that module
1571 * layer are located (irrespective of their class loader) before the
1572 * providers in the parent class loader are located. The ordering of
1573 * modules in same class loader, or the ordering of modules in a module
1574 * layer, is not defined. </p>
1575 *
1576 * <p> If a module declares more than one provider then the providers
1577 * are located in the order that its module descriptor {@linkplain
1578 * java.lang.module.ModuleDescriptor.Provides#providers() lists the
1579 * providers}. Providers added dynamically by instrumentation agents (see
1580 * {@link java.lang.instrument.Instrumentation#redefineModule redefineModule})
1581 * are always located after providers declared by the module. </p> </li>
1582 *
1583 * <li> <p> Step 2: Locate providers in unnamed modules. </p>
1584 *
1585 * <p> Service providers in unnamed modules are located if their class names
1586 * are listed in provider-configuration files located by the class loader's
1587 * {@link ClassLoader#getResources(String) getResources} method. </p>
1588 *
1589 * <p> The ordering is based on the order that the class loader's {@code
1590 * getResources} method finds the service configuration files and within
1591 * that, the order that the class names are listed in the file. </p>
1592 *
1593 * <p> In a provider-configuration file, any mention of a service provider
1594 * that is deployed in a named module is ignored. This is to avoid
1595 * duplicates that would otherwise arise when a named module has both a
1596 * <i>provides</i> directive and a provider-configuration file that mention
1597 * the same service provider. </p>
1598 *
1599 * <p> The provider class must be visible to the class loader. </p> </li>
1600 *
1601 * </ul>
1602 *
1603 * @apiNote If the class path of the class loader includes remote network
1604 * URLs then those URLs may be dereferenced in the process of searching for
1605 * provider-configuration files.
1606 *
1607 * <p> This activity is normal, although it may cause puzzling entries to be
1608 * created in web-server logs. If a web server is not configured correctly,
1609 * however, then this activity may cause the provider-loading algorithm to fail
1610 * spuriously.
1611 *
1612 * <p> A web server should return an HTTP 404 (Not Found) response when a
1613 * requested resource does not exist. Sometimes, however, web servers are
1614 * erroneously configured to return an HTTP 200 (OK) response along with a
1615 * helpful HTML error page in such cases. This will cause a {@link
1616 * ServiceConfigurationError} to be thrown when this class attempts to parse
1617 * the HTML page as a provider-configuration file. The best solution to this
1618 * problem is to fix the misconfigured web server to return the correct
1619 * response code (HTTP 404) along with the HTML error page.
1620 *
1621 * @param <S> the class of the service type
1622 *
1623 * @param service
1624 * The interface or abstract class representing the service
1625 *
1626 * @param loader
1627 * The class loader to be used to load provider-configuration files
1628 * and provider classes, or {@code null} if the system class
1629 * loader (or, failing that, the bootstrap class loader) is to be
1630 * used
1631 *
1632 * @return A new service loader
1633 *
1634 * @throws ServiceConfigurationError
1635 * if the service type is not accessible to the caller or the
1636 * caller is in an explicit module and its module descriptor does
1637 * not declare that it uses {@code service}
1638 *
1639 * @revised 9
1640 * @spec JPMS
1641 */
1642 @CallerSensitive
1643 public static <S> ServiceLoader<S> load(Class<S> service,
1644 ClassLoader loader)
1645 {
1646 return new ServiceLoader<>(Reflection.getCallerClass(), service, loader);
1647 }
1648
1649 /**
1650 * Creates a new service loader for the given service type, using the
1651 * current thread's {@linkplain java.lang.Thread#getContextClassLoader
1652 * context class loader}.
1653 *
1654 * <p> An invocation of this convenience method of the form
1655 * <pre>{@code
1656 * ServiceLoader.load(service)
1657 * }</pre>
1658 *
1659 * is equivalent to
1660 *
1661 * <pre>{@code
1662 * ServiceLoader.load(service, Thread.currentThread().getContextClassLoader())
1663 * }</pre>
1664 *
1665 * @apiNote Service loader objects obtained with this method should not be
1666 * cached VM-wide. For example, different applications in the same VM may
1667 * have different thread context class loaders. A lookup by one application
1668 * may locate a service provider that is only visible via its thread
1669 * context class loader and so is not suitable to be located by the other
1670 * application. Memory leaks can also arise. A thread local may be suited
1671 * to some applications.
1672 *
1673 * @param <S> the class of the service type
1674 *
1675 * @param service
1676 * The interface or abstract class representing the service
1677 *
1678 * @return A new service loader
1679 *
1680 * @throws ServiceConfigurationError
1681 * if the service type is not accessible to the caller or the
1682 * caller is in an explicit module and its module descriptor does
1683 * not declare that it uses {@code service}
1684 *
1685 * @revised 9
1686 * @spec JPMS
1687 */
1688 @CallerSensitive
1689 public static <S> ServiceLoader<S> load(Class<S> service) {
1690 ClassLoader cl = Thread.currentThread().getContextClassLoader();
1691 return new ServiceLoader<>(Reflection.getCallerClass(), service, cl);
1692 }
1693
1694 /**
1695 * Creates a new service loader for the given service type, using the
1696 * {@linkplain ClassLoader#getPlatformClassLoader() platform class loader}.
1697 *
1698 * <p> This convenience method is equivalent to: </p>
1699 *
1700 * <pre>{@code
1701 * ServiceLoader.load(service, ClassLoader.getPlatformClassLoader())
1702 * }</pre>
1703 *
1704 * <p> This method is intended for use when only installed providers are
1705 * desired. The resulting service will only find and load providers that
1706 * have been installed into the current Java virtual machine; providers on
1707 * the application's module path or class path will be ignored.
1708 *
1709 * @param <S> the class of the service type
1710 *
1711 * @param service
1712 * The interface or abstract class representing the service
1713 *
1714 * @return A new service loader
1715 *
1716 * @throws ServiceConfigurationError
1717 * if the service type is not accessible to the caller or the
1718 * caller is in an explicit module and its module descriptor does
1719 * not declare that it uses {@code service}
1720 *
1721 * @revised 9
1722 * @spec JPMS
1723 */
1724 @CallerSensitive
1725 public static <S> ServiceLoader<S> loadInstalled(Class<S> service) {
1726 ClassLoader cl = ClassLoader.getPlatformClassLoader();
1727 return new ServiceLoader<>(Reflection.getCallerClass(), service, cl);
1728 }
1729
1730 /**
1731 * Creates a new service loader for the given service type to load service
1732 * providers from modules in the given module layer and its ancestors. It
1733 * does not locate providers in unnamed modules. The ordering that the service
1734 * loader's {@link #iterator() iterator} and {@link #stream() stream} locate
1735 * providers and yield elements is as follows:
1736 *
1737 * <ul>
1738 * <li><p> Providers are located in a module layer before locating providers
1739 * in parent layers. Traversal of parent layers is depth-first with each
1740 * layer visited at most once. For example, suppose L0 is the boot layer, L1
1741 * and L2 are modules layers with L0 as their parent. Now suppose that L3 is
1742 * created with L1 and L2 as the parents (in that order). Using a service
1743 * loader to locate providers with L3 as the context will locate providers
1744 * in the following order: L3, L1, L0, L2. </p></li>
1745 *
1746 * <li><p> If a module declares more than one provider then the providers
1747 * are located in the order that its module descriptor
1748 * {@linkplain java.lang.module.ModuleDescriptor.Provides#providers()
1749 * lists the providers}. Providers added dynamically by instrumentation
1750 * agents are always located after providers declared by the module. </p></li>
1751 *
1752 * <li><p> The ordering of modules in a module layer is not defined. </p></li>
1753 * </ul>
1754 *
1755 * @apiNote Unlike the other load methods defined here, the service type
1756 * is the second parameter. The reason for this is to avoid source
1757 * compatibility issues for code that uses {@code load(S, null)}.
1758 *
1759 * @param <S> the class of the service type
1760 *
1761 * @param layer
1762 * The module layer
1763 *
1764 * @param service
1765 * The interface or abstract class representing the service
1766 *
1767 * @return A new service loader
1768 *
1769 * @throws ServiceConfigurationError
1770 * if the service type is not accessible to the caller or the
1771 * caller is in an explicit module and its module descriptor does
1772 * not declare that it uses {@code service}
1773 *
1774 * @since 9
1775 * @spec JPMS
1776 */
1777 @CallerSensitive
1778 public static <S> ServiceLoader<S> load(ModuleLayer layer, Class<S> service) {
1779 return new ServiceLoader<>(Reflection.getCallerClass(), layer, service);
1780 }
1781
1782 /**
1783 * Load the first available service provider of this loader's service. This
1784 * convenience method is equivalent to invoking the {@link #iterator()
1785 * iterator()} method and obtaining the first element. It therefore
1786 * returns the first element from the provider cache if possible, it
1787 * otherwise attempts to load and instantiate the first provider.
1788 *
1789 * <p> The following example loads the first available service provider. If
1790 * no service providers are located then it uses a default implementation.
1791 * <pre>{@code
1792 * CodecFactory factory = ServiceLoader.load(CodecFactory.class)
1793 * .findFirst()
1794 * .orElse(DEFAULT_CODECSET_FACTORY);
1795 * }</pre>
1796 * @return The first service provider or empty {@code Optional} if no
1797 * service providers are located
1798 *
1799 * @throws ServiceConfigurationError
1800 * If a provider class cannot be loaded for any of the reasons
1801 * specified in the <a href="#errors">Errors</a> section above.
1802 *
1803 * @since 9
1804 * @spec JPMS
1805 */
1806 public Optional<S> findFirst() {
1807 Iterator<S> iterator = iterator();
1808 if (iterator.hasNext()) {
1809 return Optional.of(iterator.next());
1810 } else {
1811 return Optional.empty();
1812 }
1813 }
1814
1815 /**
1816 * Clear this loader's provider cache so that all providers will be
1817 * reloaded.
1818 *
1819 * <p> After invoking this method, subsequent invocations of the {@link
1820 * #iterator() iterator} or {@link #stream() stream} methods will lazily
1821 * locate providers (and instantiate in the case of {@code iterator})
1822 * from scratch, just as is done by a newly-created service loader.
1823 *
1824 * <p> This method is intended for use in situations in which new service
1825 * providers can be installed into a running Java virtual machine.
1826 */
1827 public void reload() {
1828 lookupIterator1 = null;
1829 instantiatedProviders.clear();
1830
1831 lookupIterator2 = null;
1832 loadedProviders.clear();
1833 loadedAllProviders = false;
1834
1835 // increment count to allow CME be thrown
1836 reloadCount++;
1837 }
1838
1839 /**
1840 * Returns a string describing this service.
1841 *
1842 * @return A descriptive string
1843 */
1844 public String toString() {
1845 return "java.util.ServiceLoader[" + service.getName() + "]";
1846 }
1847
1848 }
1849