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 - 如果在父級類別終止過程中發生錯誤。