51 * extensions, that is, jar files placed into any of the usual extension
52 * directories. Providers can also be made available by adding them to the
53 * application's class path or by some other platform-specific means.
54 *
55 * <p> For the purpose of loading, a service is represented by a single type,
56 * that is, a single interface or abstract class. (A concrete class can be
57 * used, but this is not recommended.) A provider of a given service contains
58 * one or more concrete classes that extend this <i>service type</i> with data
59 * and code specific to the provider. The <i>provider class</i> is typically
60 * not the entire provider itself but rather a proxy which contains enough
61 * information to decide whether the provider is able to satisfy a particular
62 * request together with code that can create the actual provider on demand.
63 * The details of provider classes tend to be highly service-specific; no
64 * single class or interface could possibly unify them, so no such type is
65 * defined here. The only requirement enforced by this facility is that
66 * provider classes must have a zero-argument constructor so that they can be
67 * instantiated during loading.
68 *
69 * <p><a name="format"> A service provider is identified by placing a
70 * <i>provider-configuration file</i> in the resource directory
71 * <tt>META-INF/services</tt>. The file's name is the fully-qualified <a
72 * href="../lang/ClassLoader.html#name">binary name</a> of the service's type.
73 * The file contains a list of fully-qualified binary names of concrete
74 * provider classes, one per line. Space and tab characters surrounding each
75 * name, as well as blank lines, are ignored. The comment character is
76 * <tt>'#'</tt> (<tt>'\u0023'</tt>, <font size="-1">NUMBER SIGN</font>); on
77 * each line all characters following the first comment character are ignored.
78 * The file must be encoded in UTF-8.
79 *
80 * <p> If a particular concrete provider class is named in more than one
81 * configuration file, or is named in the same configuration file more than
82 * once, then the duplicates are ignored. The configuration file naming a
83 * particular provider need not be in the same jar file or other distribution
84 * unit as the provider itself. The provider must be accessible from the same
85 * class loader that was initially queried to locate the configuration file;
86 * note that this is not necessarily the class loader from which the file was
87 * actually loaded.
88 *
89 * <p> Providers are located and instantiated lazily, that is, on demand. A
90 * service loader maintains a cache of the providers that have been loaded so
91 * far. Each invocation of the {@link #iterator iterator} method returns an
92 * iterator that first yields all of the elements of the cache, in
93 * instantiation order, and then lazily locates and instantiates any remaining
94 * providers, adding each one to the cache in turn. The cache can be cleared
95 * via the {@link #reload reload} method.
96 *
467 return lookupIterator.hasNext();
468 }
469
470 public S next() {
471 if (knownProviders.hasNext())
472 return knownProviders.next().getValue();
473 return lookupIterator.next();
474 }
475
476 public void remove() {
477 throw new UnsupportedOperationException();
478 }
479
480 };
481 }
482
483 /**
484 * Creates a new service loader for the given service type and class
485 * loader.
486 *
487 * @param service
488 * The interface or abstract class representing the service
489 *
490 * @param loader
491 * The class loader to be used to load provider-configuration files
492 * and provider classes, or <tt>null</tt> if the system class
493 * loader (or, failing that, the bootstrap class loader) is to be
494 * used
495 *
496 * @return A new service loader
497 */
498 public static <S> ServiceLoader<S> load(Class<S> service,
499 ClassLoader loader)
500 {
501 return new ServiceLoader<>(service, loader);
502 }
503
504 /**
505 * Creates a new service loader for the given service type, using the
506 * current thread's {@linkplain java.lang.Thread#getContextClassLoader
507 * context class loader}.
508 *
509 * <p> An invocation of this convenience method of the form
510 *
511 * <blockquote><pre>
512 * ServiceLoader.load(<i>service</i>)</pre></blockquote>
513 *
514 * is equivalent to
515 *
516 * <blockquote><pre>
517 * ServiceLoader.load(<i>service</i>,
518 * Thread.currentThread().getContextClassLoader())</pre></blockquote>
519 *
520 * @param service
521 * The interface or abstract class representing the service
522 *
523 * @return A new service loader
524 */
525 public static <S> ServiceLoader<S> load(Class<S> service) {
526 ClassLoader cl = Thread.currentThread().getContextClassLoader();
527 return ServiceLoader.load(service, cl);
528 }
529
530 /**
531 * Creates a new service loader for the given service type, using the
532 * extension class loader.
533 *
534 * <p> This convenience method simply locates the extension class loader,
535 * call it <tt><i>extClassLoader</i></tt>, and then returns
536 *
537 * <blockquote><pre>
538 * ServiceLoader.load(<i>service</i>, <i>extClassLoader</i>)</pre></blockquote>
539 *
540 * <p> If the extension class loader cannot be found then the system class
541 * loader is used; if there is no system class loader then the bootstrap
542 * class loader is used.
543 *
544 * <p> This method is intended for use when only installed providers are
545 * desired. The resulting service will only find and load providers that
546 * have been installed into the current Java virtual machine; providers on
547 * the application's class path will be ignored.
548 *
549 * @param service
550 * The interface or abstract class representing the service
551 *
552 * @return A new service loader
553 */
554 public static <S> ServiceLoader<S> loadInstalled(Class<S> service) {
555 ClassLoader cl = ClassLoader.getSystemClassLoader();
556 ClassLoader prev = null;
557 while (cl != null) {
558 prev = cl;
559 cl = cl.getParent();
560 }
561 return ServiceLoader.load(service, prev);
562 }
563
564 /**
565 * Returns a string describing this service.
566 *
567 * @return A descriptive string
568 */
|
51 * extensions, that is, jar files placed into any of the usual extension
52 * directories. Providers can also be made available by adding them to the
53 * application's class path or by some other platform-specific means.
54 *
55 * <p> For the purpose of loading, a service is represented by a single type,
56 * that is, a single interface or abstract class. (A concrete class can be
57 * used, but this is not recommended.) A provider of a given service contains
58 * one or more concrete classes that extend this <i>service type</i> with data
59 * and code specific to the provider. The <i>provider class</i> is typically
60 * not the entire provider itself but rather a proxy which contains enough
61 * information to decide whether the provider is able to satisfy a particular
62 * request together with code that can create the actual provider on demand.
63 * The details of provider classes tend to be highly service-specific; no
64 * single class or interface could possibly unify them, so no such type is
65 * defined here. The only requirement enforced by this facility is that
66 * provider classes must have a zero-argument constructor so that they can be
67 * instantiated during loading.
68 *
69 * <p><a name="format"> A service provider is identified by placing a
70 * <i>provider-configuration file</i> in the resource directory
71 * <tt>META-INF/services</tt>.</a> The file's name is the fully-qualified <a
72 * href="../lang/ClassLoader.html#name">binary name</a> of the service's type.
73 * The file contains a list of fully-qualified binary names of concrete
74 * provider classes, one per line. Space and tab characters surrounding each
75 * name, as well as blank lines, are ignored. The comment character is
76 * <tt>'#'</tt> (<tt>'\u0023'</tt>,
77 * <font style="font-size:smaller;">NUMBER SIGN</font>); on
78 * each line all characters following the first comment character are ignored.
79 * The file must be encoded in UTF-8.
80 *
81 * <p> If a particular concrete provider class is named in more than one
82 * configuration file, or is named in the same configuration file more than
83 * once, then the duplicates are ignored. The configuration file naming a
84 * particular provider need not be in the same jar file or other distribution
85 * unit as the provider itself. The provider must be accessible from the same
86 * class loader that was initially queried to locate the configuration file;
87 * note that this is not necessarily the class loader from which the file was
88 * actually loaded.
89 *
90 * <p> Providers are located and instantiated lazily, that is, on demand. A
91 * service loader maintains a cache of the providers that have been loaded so
92 * far. Each invocation of the {@link #iterator iterator} method returns an
93 * iterator that first yields all of the elements of the cache, in
94 * instantiation order, and then lazily locates and instantiates any remaining
95 * providers, adding each one to the cache in turn. The cache can be cleared
96 * via the {@link #reload reload} method.
97 *
468 return lookupIterator.hasNext();
469 }
470
471 public S next() {
472 if (knownProviders.hasNext())
473 return knownProviders.next().getValue();
474 return lookupIterator.next();
475 }
476
477 public void remove() {
478 throw new UnsupportedOperationException();
479 }
480
481 };
482 }
483
484 /**
485 * Creates a new service loader for the given service type and class
486 * loader.
487 *
488 * @param <S> the class of the service type
489 *
490 * @param service
491 * The interface or abstract class representing the service
492 *
493 * @param loader
494 * The class loader to be used to load provider-configuration files
495 * and provider classes, or <tt>null</tt> if the system class
496 * loader (or, failing that, the bootstrap class loader) is to be
497 * used
498 *
499 * @return A new service loader
500 */
501 public static <S> ServiceLoader<S> load(Class<S> service,
502 ClassLoader loader)
503 {
504 return new ServiceLoader<>(service, loader);
505 }
506
507 /**
508 * Creates a new service loader for the given service type, using the
509 * current thread's {@linkplain java.lang.Thread#getContextClassLoader
510 * context class loader}.
511 *
512 * <p> An invocation of this convenience method of the form
513 *
514 * <blockquote><pre>
515 * ServiceLoader.load(<i>service</i>)</pre></blockquote>
516 *
517 * is equivalent to
518 *
519 * <blockquote><pre>
520 * ServiceLoader.load(<i>service</i>,
521 * Thread.currentThread().getContextClassLoader())</pre></blockquote>
522 *
523 * @param <S> the class of the service type
524 *
525 * @param service
526 * The interface or abstract class representing the service
527 *
528 * @return A new service loader
529 */
530 public static <S> ServiceLoader<S> load(Class<S> service) {
531 ClassLoader cl = Thread.currentThread().getContextClassLoader();
532 return ServiceLoader.load(service, cl);
533 }
534
535 /**
536 * Creates a new service loader for the given service type, using the
537 * extension class loader.
538 *
539 * <p> This convenience method simply locates the extension class loader,
540 * call it <tt><i>extClassLoader</i></tt>, and then returns
541 *
542 * <blockquote><pre>
543 * ServiceLoader.load(<i>service</i>, <i>extClassLoader</i>)</pre></blockquote>
544 *
545 * <p> If the extension class loader cannot be found then the system class
546 * loader is used; if there is no system class loader then the bootstrap
547 * class loader is used.
548 *
549 * <p> This method is intended for use when only installed providers are
550 * desired. The resulting service will only find and load providers that
551 * have been installed into the current Java virtual machine; providers on
552 * the application's class path will be ignored.
553 *
554 * @param <S> the class of the service type
555 *
556 * @param service
557 * The interface or abstract class representing the service
558 *
559 * @return A new service loader
560 */
561 public static <S> ServiceLoader<S> loadInstalled(Class<S> service) {
562 ClassLoader cl = ClassLoader.getSystemClassLoader();
563 ClassLoader prev = null;
564 while (cl != null) {
565 prev = cl;
566 cl = cl.getParent();
567 }
568 return ServiceLoader.load(service, prev);
569 }
570
571 /**
572 * Returns a string describing this service.
573 *
574 * @return A descriptive string
575 */
|