javax.imageio.spi
类 ServiceRegistry

java.lang.Object
  javax.imageio.spi.ServiceRegistry

直接已知子类：

IIORegistry

public class ServiceRegistry
extends Object

用于服务提供者实例的注册表。

服务 是一组熟知的接口和类（通常为抽象类）。服务提供者 是服务的具体实现。提供者中的类通常实现由服务自身定义的类的接口或子类。

服务提供者存储在一个或多个类别 中，每个类别都由所有成员都必须实现的（由一个 Class 对象描述）一个接口的类定义。类别集可动态更改。

只能注册给定叶类的单一实例（即，由 getClass() 返回的实际类，相对于继承的类或接口而言）。即，假定 com.mycompany.mypkg.GreenServiceProvider 类实现 com.mycompany.mypkg.MyService 接口。如果注册了 GreenServiceProvider 实例，则其将存储在由 MyService 类定义的类别中。如果注册了 GreenServiceProvider 的新实例，它将替换以前的实例。在实践中，服务提供者对象通常只有一个，所有此行为是适当的。

为声明服务提供者，在每个 JAR 文件都有的 META-INF 目录中加入一个 services 子目录。此目录针对每个在 JAR 文件中具有一个或多个实现类的服务提供者接口都包含一个文件。例如，假设 JAR 文件包含了一个名称为 com.mycompany.mypkg.MyServiceImpl 的类，它实现 javax.someapi.SomeService 接口，则此 JAR 将包含一个名称如下所示的文件：

 META-INF/services/javax.someapi.SomeService 

包含行：

 com.mycompany.mypkg.MyService
 

服务提供者类应为轻量级的，可快速加载。这些接口的实现应避免复杂化其他类和本地代码的依赖关系。更复杂的服务的常用模式是为重量级服务注册一个轻量级的代理。

只要具有适当的运行时权限，应用程序即可根据需要定制注册表的内容。

有关声明服务提供者和通用 JAR 格式的更详细的信息，请参见 JAR File Specification。

另请参见：

RegisterableService

嵌套类摘要

static interface

ServiceRegistry.Filter ServiceRegistry.getServiceProviders 使用的一个简单过滤器接口，用来选择与任意条件匹配的提供者。

构造方法摘要

ServiceRegistry(Iterator<Class<?>> categories)
使用取自 categories 参数的一组类别构造 ServiceRegistry 实例。

方法摘要

boolean	contains(Object provider) 如果当前注册了 provider，则返回 true。
void	deregisterAll() 从所有类别注销所有当前注册的服务提供者。
void	deregisterAll(Class<?> category) 注销给定类别下当前注册的所有服务提供者对象。
void	deregisterServiceProvider(Object provider) 从包含它的所有类别中移除服务提供者对象。
<T> boolean	deregisterServiceProvider(T provider, Class<T> category) 从给定的类别中移除服务提供者对象。
void	finalize() 在垃圾回收前终止此对象。
Iterator<Class<?>>	getCategories() 返回指示当前类别集的 Class 对象的 Iterator。
<T> T	getServiceProviderByClass(Class<T> providerClass) 返回当前注册的属于给定类类型的服务提供者对象。
<T> Iterator<T>	getServiceProviders(Class<T> category, boolean useOrdering) 返回一个包含给定类别中的所有已注册的服务提供者的 Iterator。
<T> Iterator<T>	getServiceProviders(Class<T> category, ServiceRegistry.Filter filter, boolean useOrdering) 返回一个 Iterator，其包含给定类别中满足由指定的 ServiceRegistry.Filter 对象的 filter 方法定义的条件的服务提供者对象。
static <T> Iterator<T>	lookupProviders(Class<T> providerClass) 使用上下文类加载器定位和递增地实例化给定服务的可用的提供者。
static <T> Iterator<T>	lookupProviders(Class<T> providerClass, ClassLoader loader) 使用给定的类加载器搜索特定服务类的实现。
void	registerServiceProvider(Object provider) 将一个服务提供者对象添加到注册表。
<T> boolean	registerServiceProvider(T provider, Class<T> category) 将一个服务提供者对象添加到注册表。
void	registerServiceProviders(Iterator<?> providers) 将一组取自 Iterator 的服务提供者对象添加到注册表。
<T> boolean	setOrdering(Class<T> category, T firstProvider, T secondProvider) 为给定类别中的两个服务提供者对象设置配对排序。
<T> boolean	unsetOrdering(Class<T> category, T firstProvider, T secondProvider) 为给定类别中的两个服务提供者对象设置配对排序。

从类 java.lang.Object 继承的方法

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

构造方法详细信息

ServiceRegistry

public ServiceRegistry(Iterator<Class<?>> categories)

使用取自 categories 参数的一组类别构造 ServiceRegistry 实例。

参数：

categories - 包含将用于定义类别的 Class 对象的 Iterator。

抛出：

IllegalArgumentException - 如果 categories 为 null。

方法详细信息

lookupProviders

public static <T> Iterator<T> lookupProviders(Class<T> providerClass,
                                              ClassLoader loader)

使用给定的类加载器搜索特定服务类的实现。

此方法根据类注释的描述将给定服务类的名称转换为一个提供者配置文件名，然后使用给定类加载器的 getResources 方法查找所有可用的具有此名称的文件。然后读取并分析这些文件以生成一个提供者类名称列表。返回的迭代器使用给定的类加载器查找并实例化列表中的每个元素。

由于能将扩展安装到一个运行的 Java 虚拟机中，此方法在每次调用时可能返回不同的结果。

参数：

providerClass - 指示所检测的服务提供者的类或接口的 Class 对象。

loader - 将用于加载提供者配置文件和实例化提供者类的类加载器，如果将使用系统类加载器（或，系统类加载器失败时使用引导类加载器），则为 null。

返回：

以任意顺序生成给定服务的提供者对象的 Iterator。如果提供者配置文件违反指定的格式，或者无法找到和实例化提供者类，则迭代器将抛出一个 Error。

抛出：

IllegalArgumentException - 如果 providerClass 为 null。

lookupProviders

public static <T> Iterator<T> lookupProviders(Class<T> providerClass)

使用上下文类加载器定位和递增地实例化给定服务的可用的提供者。此便捷方法等效于：

   ClassLoader cl = Thread.currentThread().getContextClassLoader();
   return Service.providers(service, cl);
 

参数：

providerClass - 指示所检测的服务提供者的类或接口的 Class 对象。

返回：

以任意顺序生成给定服务的提供者对象的 Iterator。如果提供者配置文件违反指定的格式，或者无法找到和实例化提供者类，则迭代器将抛出一个 Error。

抛出：

IllegalArgumentException - 如果 providerClass 为 null。

getCategories

public Iterator<Class<?>> getCategories()

返回指示当前类别集的 Class 对象的 Iterator。如果不存在任何类别，则此迭代器将为空。

返回：

包含 Class 对象的 Iterator。

registerServiceProvider

public <T> boolean registerServiceProvider(T provider,
                                           Class<T> category)

将一个服务提供者对象添加到注册表。此提供者与给定的类别关联。

如果 provider 实现了 RegisterableService 接口，则将调用其 onRegistration 方法。每次将提供者从某个类别注销时都将调用其 onDeregistration 方法，例如，移除类别或垃圾回收注册表时都要调用该方法。

参数：

provider - 要注册的服务提供者对象。

category - 要在其中注册提供者的类别。

返回：

如果相同的类别中以前未注册相同类的提供者，则返回 true。

抛出：

IllegalArgumentException - 如果 provider 为 null。

IllegalArgumentException - 如果没有与 category 对应的类别。

ClassCastException - 如果提供者未实现由 category 定义的 Class。

registerServiceProvider

public void registerServiceProvider(Object provider)

将一个服务提供者对象添加到注册表。此提供者与注册表中出现的实现了其 Class 的每个类别关联。

如果 provider 实现了 RegisterableService 接口，则将对其注册的每个类别调用一次 onRegistration 方法。每次当提供者从类别注销或注册表终止时，将调用提供者的 onDeregistration 方法。

参数：

provider - 要注册的服务提供者对象。

抛出：

IllegalArgumentException - 如果 provider 为 null。

registerServiceProviders

public void registerServiceProviders(Iterator<?> providers)

将一组取自 Iterator 的服务提供者对象添加到注册表。每个提供者与注册表中出现的实现了其 Class 的每个类别关联。

对于实现了 RegisterableService 接口的每个 providers 项，将对其注册的每个类别调用一次 onRegistration 方法。每次当提供者从类别注销或注册表终止时，将调用提供者的 onDeregistration 方法。

参数：

providers - 包含要注册的服务提供者对象的迭代器。

抛出：

IllegalArgumentException - 如果 providers 为 null，或包含一个 null 项。

deregisterServiceProvider

public <T> boolean deregisterServiceProvider(T provider,
                                             Class<T> category)

从给定的类别中移除服务提供者对象。如果以前未注册提供者，则不执行任何操作并返回 false。否则，返回 true。如果注册了与 provider 具有相同的类但又不等于（使用 ==）provider 的对象，则不注销此对象。

如果 provider 实现了 RegisterableService 接口，则将调用其 onDeregistration 方法。

参数：

provider - 要注销的服务提供者对象。

category - 要从其注销提供者的类别。

返回：

如果提供者以前已注册在相同的类别中，则返回 true，否则返回 false。

抛出：

IllegalArgumentException - 如果 provider 为 null。

IllegalArgumentException - 如果没有与 category 对应的类别。

ClassCastException - 如果提供者未实现由 category 定义的类。

deregisterServiceProvider

public void deregisterServiceProvider(Object provider)

从包含它的所有类别中移除服务提供者对象。

参数：

provider - 要注销的服务提供者对象。

抛出：

IllegalArgumentException - 如果 provider 为 null。

contains

public boolean contains(Object provider)

如果当前注册了 provider，则返回 true。

参数：

provider - 要查询的服务提供者对象。

返回：

如果给定的提供者已注册，则返回 true。

抛出：

IllegalArgumentException - 如果 provider 为 null。

getServiceProviders

public <T> Iterator<T> getServiceProviders(Class<T> category,
                                           boolean useOrdering)

返回一个包含给定类别中的所有已注册的服务提供者的 Iterator。如果 useOrdering 为 false，则迭代器将以任意顺序返回所有的服务提供者对象。否则，排序将遵照已设置的任何配对顺序。如果配对顺序的图形包含圆，则将不返回任何属于圆的提供者。

参数：

category - 将从其检索的类别。

useOrdering - 如果在对返回对象排序时应考虑配对顺序，则为 true。

返回：

包含给定类别的服务提供者的 Iterator（有可能按顺序返回）。

抛出：

IllegalArgumentException - 如果没有与 category 对应的类别。

getServiceProviders

public <T> Iterator<T> getServiceProviders(Class<T> category,
                                           ServiceRegistry.Filter filter,
                                           boolean useOrdering)

返回一个 Iterator，其包含给定类别中满足由指定的 ServiceRegistry.Filter 对象的 filter 方法定义的条件的服务提供者对象。

useOrdering 参数使用与 getServiceProviders(Class, boolean) 相同的规则控制着结果的排序。

参数：

category - 将从其检索的类别。

filter - 将调用其 filter 方法的 ServiceRegistry.Filter 的实例。

useOrdering - 如果在对返回对象排序时应考虑配对顺序，则为 true。

返回：

包含给定类别的服务提供者的 Iterator（有可能按顺序返回）。

抛出：

IllegalArgumentException - 如果没有与 category 对应的类别。

getServiceProviderByClass

public <T> T getServiceProviderByClass(Class<T> providerClass)

返回当前注册的属于给定类类型的服务提供者对象。任何给定时间最多只允许注册给定类的一个对象。如果没有注册的对象具有需要的类类型，则返回 null。

参数：

providerClass - 需要的服务提供者对象的 Class。

返回：

当前注册的具有所需 Class 类型的服务提供者对象，如果没有，则返回 null。

抛出：

IllegalArgumentException - 如果 providerClass 为 null。

setOrdering

public <T> boolean setOrdering(Class<T> category,
                               T firstProvider,
                               T secondProvider)

为给定类别中的两个服务提供者对象设置配对排序。如果其中一个或两个对象当前都未在给定的类别中注册，或者需要的排序已设置，则不执行任何操作并返回 false。如果提供者以前以相反的顺序排序，则将此排序移除。

此排序将由 getServiceProviders 方法在其 useOrdering 参数为 true 时使用。

参数：

category - 指示将在其中建立首选项的类别的 Class 对象。

firstProvider - 首选提供者。

secondProvider - 与其比较而言，firstProvider 为首选提供者。

返回：

如果建立了以前取消设置的排序，则返回 true。

抛出：

IllegalArgumentException - 如果提供者为 null 或为相同的对象。

IllegalArgumentException - 如果没有与 category 对应的类别。

unsetOrdering

public <T> boolean unsetOrdering(Class<T> category,
                                 T firstProvider,
                                 T secondProvider)

为给定类别中的两个服务提供者对象设置配对排序。如果其中一个或两个对象当前都未在给定的类别中注册，或者它们之间当前未设置任何排序，则不执行任何操作并返回 false。

此排序将由 getServiceProviders 方法在其 useOrdering 参数为 true 时使用。

参数：

category - 指示将在其中取消建立首选项的类别的 Class 对象。

firstProvider - 以前的首选提供者。

secondProvider - 与其比较而言，firstProvider 为以前的首选提供者。

返回：

如果取消建立以前设置的排序，则返回 true。

抛出：

IllegalArgumentException - 如果提供者为 null 或为相同的对象。

IllegalArgumentException - 如果没有与 category 对应的类别。

deregisterAll

public void deregisterAll(Class<?> category)

注销给定类别下当前注册的所有服务提供者对象。

参数：

category - 将清空的类别。

抛出：

IllegalArgumentException - 如果没有与 category 对应的类别。

deregisterAll

public void deregisterAll()

从所有类别注销所有当前注册的服务提供者。

finalize

public void finalize()
              throws Throwable

在垃圾回收前终止此对象。调用 deregisterAll 方法注销所有当前注册的服务提供者。不应该从应用程序代码中调用此方法。

覆盖：

类 Object 中的 finalize

抛出：

Throwable - 如果在超类终止过程中发生错误。