java.lang.Object javax.imageio.spi.ServiceRegistry
public class ServiceRegistry
用于服务提供者实例的注册表。
服务 是一组熟知的接口和类(通常为抽象类)。服务提供者 是服务的具体实现。提供者中的类通常实现由服务自身定义的类的接口或子类。
服务提供者存储在一个或多个类别 中,每个类别都由所有成员都必须实现的(由一个 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) 从包含它的所有类别中移除服务提供者对象。 |
|
|
deregisterServiceProvider(T provider, Class<T> category) 从给定的类别中移除服务提供者对象。 |
|
void |
finalize() 在垃圾回收前终止此对象。 |
|
Iterator<Class<?>> |
getCategories() 返回指示当前类别集的 Class 对象的 Iterator 。 |
|
|
getServiceProviderByClass(Class<T> providerClass) 返回当前注册的属于给定类类型的服务提供者对象。 |
|
|
getServiceProviders(Class<T> category, boolean useOrdering) 返回一个包含给定类别中的所有已注册的服务提供者的 Iterator 。 |
|
|
getServiceProviders(Class<T> category, ServiceRegistry.Filter filter, boolean useOrdering) 返回一个 Iterator ,其包含给定类别中满足由指定的 ServiceRegistry.Filter 对象的 filter 方法定义的条件的服务提供者对象。 |
|
static
|
lookupProviders(Class<T> providerClass) 使用上下文类加载器定位和递增地实例化给定服务的可用的提供者。 |
|
static
|
lookupProviders(Class<T> providerClass, ClassLoader loader) 使用给定的类加载器搜索特定服务类的实现。 |
|
void |
registerServiceProvider(Object provider) 将一个服务提供者对象添加到注册表。 |
|
|
registerServiceProvider(T provider, Class<T> category) 将一个服务提供者对象添加到注册表。 |
|
void |
registerServiceProviders(Iterator<?> providers) 将一组取自 Iterator 的服务提供者对象添加到注册表。 |
|
|
setOrdering(Class<T> category, T firstProvider, T secondProvider) 为给定类别中的两个服务提供者对象设置配对排序。 |
|
|
unsetOrdering(Class<T> category, T firstProvider, T secondProvider) 为给定类别中的两个服务提供者对象设置配对排序。 |
从类 java.lang.Object 继承的方法 |
---|
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
构造方法详细信息 |
---|
public ServiceRegistry(Iterator<Class<?>> categories)
categories
参数的一组类别构造
ServiceRegistry
实例。
categories
- 包含将用于定义类别的
Class
对象的
Iterator
。
IllegalArgumentException
- 如果
categories
为
null
。
方法详细信息 |
---|
public static <T> Iterator<T> lookupProviders(Class<T> providerClass, ClassLoader loader)
此方法根据类注释的描述将给定服务类的名称转换为一个提供者配置文件名,然后使用给定类加载器的 getResources
方法查找所有可用的具有此名称的文件。然后读取并分析这些文件以生成一个提供者类名称列表。返回的迭代器使用给定的类加载器查找并实例化列表中的每个元素。
由于能将扩展安装到一个运行的 Java 虚拟机中,此方法在每次调用时可能返回不同的结果。
providerClass
- 指示所检测的服务提供者的类或接口的
Class
对象。
loader
- 将用于加载提供者配置文件和实例化提供者类的类加载器,如果将使用系统类加载器(或,系统类加载器失败时使用引导类加载器),则为
null
。
Iterator
。如果提供者配置文件违反指定的格式,或者无法找到和实例化提供者类,则迭代器将抛出一个
Error
。
IllegalArgumentException
- 如果
providerClass
为
null
。
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
。
public Iterator<Class<?>> getCategories()
Class
对象的
Iterator
。如果不存在任何类别,则此迭代器将为空。
Class
对象的
Iterator
。
public <T> boolean registerServiceProvider(T provider, Class<T> category)
如果 provider
实现了 RegisterableService
接口,则将调用其 onRegistration
方法。每次将提供者从某个类别注销时都将调用其 onDeregistration
方法,例如,移除类别或垃圾回收注册表时都要调用该方法。
provider
- 要注册的服务提供者对象。
category
- 要在其中注册提供者的类别。
IllegalArgumentException
- 如果
provider
为
null
。
IllegalArgumentException
- 如果没有与
category
对应的类别。
ClassCastException
- 如果提供者未实现由
category
定义的
Class
。
public void registerServiceProvider(Object provider)
Class
的每个类别关联。
如果 provider
实现了 RegisterableService
接口,则将对其注册的每个类别调用一次 onRegistration
方法。每次当提供者从类别注销或注册表终止时,将调用提供者的 onDeregistration
方法。
provider
- 要注册的服务提供者对象。
IllegalArgumentException
- 如果
provider
为
null
。
public void registerServiceProviders(Iterator<?> providers)
Iterator
的服务提供者对象添加到注册表。每个提供者与注册表中出现的实现了其
Class
的每个类别关联。
对于实现了 RegisterableService
接口的每个 providers
项,将对其注册的每个类别调用一次 onRegistration
方法。每次当提供者从类别注销或注册表终止时,将调用提供者的 onDeregistration
方法。
providers
- 包含要注册的服务提供者对象的迭代器。
IllegalArgumentException
- 如果
providers
为
null
,或包含一个
null
项。
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
定义的类。
public void deregisterServiceProvider(Object provider)
provider
- 要注销的服务提供者对象。
IllegalArgumentException
- 如果
provider
为
null
。
public boolean contains(Object provider)
provider
,则返回
true
。
provider
- 要查询的服务提供者对象。
true
。
IllegalArgumentException
- 如果
provider
为
null
。
public <T> Iterator<T> getServiceProviders(Class<T> category, boolean useOrdering)
Iterator
。如果
useOrdering
为
false
,则迭代器将以任意顺序返回所有的服务提供者对象。否则,排序将遵照已设置的任何配对顺序。如果配对顺序的图形包含圆,则将不返回任何属于圆的提供者。
category
- 将从其检索的类别。
useOrdering
- 如果在对返回对象排序时应考虑配对顺序,则为
true
。
Iterator
(有可能按顺序返回)。
IllegalArgumentException
- 如果没有与
category
对应的类别。
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
对应的类别。
public <T> T getServiceProviderByClass(Class<T> providerClass)
null
。
providerClass
- 需要的服务提供者对象的
Class
。
Class
类型的服务提供者对象,如果没有,则返回
null
。
IllegalArgumentException
- 如果
providerClass
为
null
。
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
对应的类别。
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
对应的类别。
public void deregisterAll(Class<?> category)
category
- 将清空的类别。
IllegalArgumentException
- 如果没有与
category
对应的类别。
public void deregisterAll()
public void finalize() throws Throwable