ServiceLoader - [ Java参考文档 ] - 在线原生手册

目录搜索

文字

概述

软件包

类

使用

树

已过时

索引

帮助

Java^TM 2 Platform
Standard Ed. 6

上一个类 下一个类

框架 无框架

摘要：嵌套 | 字段 | 构造方法 | 方法

详细信息：字段 | 构造方法 | 方法

java.util
类 ServiceLoader<S>

java.lang.Object
  java.util.ServiceLoader<S>


类型参数：: S - 要被此加载器加载的服务类型。

所有已实现的接口：: Iterable<S>

public final class ServiceLoader<S>
extends Object
implements Iterable<S>

一个简单的服务提供者加载设施。

服务是一个熟知的接口和类（通常为抽象类）集合。服务提供者 是服务的特定实现。提供者中的类通常实现接口，并子类化在服务本身中定义的子类。服务提供者可以以扩展的形式安装在 Java 平台的实现中，也就是将 jar 文件放入任意常用的扩展目录中。也可通过将提供者加入应用程序类路径，或者通过其他某些特定于平台的方式使其可用。

为了加载，服务由单个类型表示，也就是单个接口或抽象类。（可以使用具体类，但建议不要这样做。）一个给定服务的提供者包含一个或多个具体类，这些类扩展了此服务类型，具有特定于提供者的数据和代码。提供者类 通常不是整个提供者本身而是一个代理，它包含足够的信息来决定提供者是否能满足特定请求，还包含可以根据需要创建实际提供者的代码。提供者类的详细信息高度特定于服务；任何单个类或接口都不能统一它们，因此这里没有定义任何这种类型。此设施唯一强制要求的是，提供者类必须具有不带参数的构造方法，以便它们可以在加载中被实例化。

通过在资源目录 META-INF/services 中放置提供者配置文件 来标识服务提供者。文件名称是服务类型的完全限定二进制名称。该文件包含一个具体提供者类的完全限定二进制名称列表，每行一个。忽略各名称周围的空格、制表符和空行。注释字符为 '#' ('\u0023', NUMBER SIGN)；忽略每行第一个注释字符后面的所有字符。文件必须使用 UTF-8 编码。

如果在多个配置文件中指定了一个特定的具体提供者类，或在同一配置文件中多次被指定，则忽略重复的指定。指定特定提供者的配置文件不必像提供者本身一样位于同一个 jar 文件或其他的分布式单元中。提供者必须可以从最初为了定位配置文件而查询的类加载器访问；注意，这不一定是实际加载文件的类加载器。

以延迟方式查找和实例化提供者，也就是说根据需要进行。服务加载器维护到目前为止已经加载的提供者缓存。每次调用 iterator 方法返回一个迭代器，它首先按照实例化顺序生成缓存的所有元素，然后以延迟方式查找和实例化所有剩余的提供者，依次将每个提供者添加到缓存。可以通过 reload 方法清除缓存。

服务加载器始终在调用者的安全上下文中执行。受信任的系统代码通常应当从特权安全上下文内部调用此类中的方法，以及它们返回的迭代器的方法。

此类的实例用于多个并发线程是不安全的。

除非另有指定，否则将 null 参数传递给此类中的任何方法都会导致抛出 NullPointerException。

示例假定服务类型为 com.example.CodecSet，它用来表示某些协议的编码器/解码器对集合。在这种情况下，它是一个具有两种抽象方法的抽象类：

public abstract Encoder getEncoder(String encodingName);
public abstract Decoder getDecoder(String encodingName);

每种方法都返回一个相应的对象；如果提供者不支持给定编码，则返回 null。典型的提供者支持一种以上的编码。

如果 com.example.impl.StandardCodecs 是 CodecSet 服务的实现，则其 jar 文件还包含一个指定如下的文件：

META-INF/services/com.example.CodecSet

此文件包含一行：

com.example.impl.StandardCodecs    # Standard codecs

CodecSet 类在初始化时创建并保存一个服务实例：

private static ServiceLoader<CodecSet> codecSetLoader
= ServiceLoader.load(CodecSet.class);

为了查找给定编码名称的编码器，它定义了一个静态工厂方法，该方法迭代所有已知并可用的提供者，只在找到适当的编码器或迭代完提供者时返回。

public static Encoder getEncoder(String encodingName) {
for (CodecSet cp :codecSetLoader) {
Encoder enc = cp.getEncoder(encodingName);
if (enc != null)
return enc;
     }
return null;
 }

getDecoder 方法的定义类似。

使用注意事项如果用于提供者加载的类加载器的类路径包含远程网络 URL，则这些 URL 将在搜索提供者配置文件的过程中被取消引用。

此活动是正常的，尽管它可能导致在 Web 服务器日志中创建一些令人迷惑的条目。但是，如果 Web 服务器配置不正确，那么此活动可能导致提供者加载算法意外失败。

如果请求的资源不存在，则 Web 服务器应返回 HTTP 404 (Not Found) 响应。但有时会错误地将 Web 服务器配置为返回 HTTP 200 (OK) 响应，并伴有这种情况下的 HTML 错误帮助页面。这会导致在此类尝试将 HTML 页面作为提供者配置文件进行解析时抛出 ServiceConfigurationError。此问题的最佳解决方案是修复配置错误的 Web 服务器，以返回正确的响应代码 (HTTP 404) 以及 HTML 错误页面。

从以下版本开始：: 1.6

方法摘要

Iterator<S> iterator()
以延迟方式加载此加载器服务的可用提供者。

static


<S> ServiceLoader<S>

load(Class<S> service)
针对给定服务类型创建新的服务加载器，使用当前线程的上下文类加载器。

static


<S> ServiceLoader<S>

load(Class<S> service,
     ClassLoader loader)

针对给定服务类型和类加载器创建新的服务加载器。

static


<S> ServiceLoader<S>

loadInstalled(Class<S> service)
针对给定服务类型创建新的服务加载器，使用扩展类加载器。

void reload()
清除此加载器的服务者缓存，以重载所有服务者。

String toString()
返回一个描述此服务的字符串。

从类 java.lang.Object 继承的方法
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

方法详细信息

reload

public void reload()

清除此加载器的服务者缓存，以重载所有服务者。

调用此方法后，后续 iterator 方法的调用将以延迟方式从头开始查询和实例化提供者，正如新创建的加载器所做的一样。

此方法用于新提供者可以被装入运行的 Java 虚拟机的情况。

iterator

public Iterator<S> iterator()

以延迟方式加载此加载器服务的可用提供者。

此方法返回的迭代器首先按实例化顺序生成提供者缓存的所有元素。然后以延迟方式加载和实例化所有剩余的提供者，依次将每个提供者添加到缓存。

要实现延迟，解析可用提供者配置文件和实例化提供者的实际工作必须由迭代器本身完成。因此，如果提供者配置文件违背指定的格式、指定了无法找到和实例化的提供者类、实例化类的结果不能分配服务类型、因为查找和实例化下一个提供者而抛出任何其他异常或错误，那么迭代器的 hasNext 和 next 方法将抛出 ServiceConfigurationError。要编写健壮的代码，只需要在使用服务迭代器时捕获 ServiceConfigurationError。

如果抛出此类错误，那么迭代器的后续调用将尽力查找和实例化下一个可用提供者，但通常无法保证此类恢复操作。

设计注意事项在那些情况下抛出错误显得有些极端。此行为的基本原理是，错误的提供者配置文件（如错误的类文件）表示 Java 虚拟机配置和使用的方式存在严重的问题。因此，最好抛出一个错误而不是试图恢复它，或者直接失败（这样更糟）。

此方法返回的迭代器不支持移除操作。调用其 remove 方法将导致抛出 UnsupportedOperationException。

指定者：: 接口 Iterable<S> 中的 iterator

返回：: 以延迟方式加载此加载器服务提供者的迭代器

load

public static <S> ServiceLoader<S> load(Class<S> service,
                                        ClassLoader loader)

针对给定服务类型和类加载器创建新的服务加载器。

参数：: service - 表示服务的接口或抽象类; loader - 用来加载提供者配置文件和提供者类的类加载器；如果要使用系统类加载器（如果没有，则使用引导类加载器），则为 null

返回：

新的服务加载器

load

public static <S> ServiceLoader<S> load(Class<S> service)

针对给定服务类型创建新的服务加载器，使用当前线程的上下文类加载器。

调用以下形式的此便捷方法

ServiceLoader.load(service)

等价于：

ServiceLoader.load(service,
Thread.currentThread().getContextClassLoader())

参数：: service - 表示服务的接口或抽象类
返回：: 新的服务加载器

loadInstalled

public static <S> ServiceLoader<S> loadInstalled(Class<S> service)

针对给定服务类型创建新的服务加载器，使用扩展类加载器。

此便捷方法查询扩展类加载器，称其为 extClassLoader，然后返回

ServiceLoader.load(service, extClassLoader)

如果无法找到扩展类加载器，则使用系统类加载器；如果没有系统类加载器，则使用引导类加载器。

此方法仅供安装所需的提供者时使用。所得服务只查找和加载已经装入当前 Java 虚拟机的提供者；忽略应用程序类路径上的提供者。

参数：: service - 表示服务的接口或抽象方法
返回：: 新的服务加载器

toString

public String toString()

返回一个描述此服务的字符串。

覆盖：: 类 Object 中的 toString

返回：: 一个描述字符串

概述

软件包

类

使用

树

已过时

索引

帮助

Java^TM 2 Platform
Standard Ed. 6

上一个类 下一个类

框架 无框架

摘要：嵌套 | 字段 | 构造方法 | 方法

详细信息：字段 | 构造方法 | 方法

提交错误或意见
有关更多的 API 参考资料和开发人员文档，请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述，以及总体概述、术语定义、使用技巧和工作代码示例。

java.util 类 ServiceLoader<S>

reload

iterator

load

load

loadInstalled

toString

java.util
类 ServiceLoader<S>