javax.imageio.spi
クラス ServiceRegistry

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

直系の既知のサブクラス:

IIORegistry

public class ServiceRegistry
extends Object

サービスプロバイダインスタンスのレジストリです。

「サービス」とは、既知のインタフェースおよびクラス (通常は抽象クラス) のセットです。「サービスプロバイダ」とは、特定のサービスの実装です。プロバイダ内のクラスは通常、インタフェースを実装するか、またはサービス自体が定義されたクラスをサブクラス化します。

サービスプロバイダは 1 つまたは複数の「カテゴリ」に格納されます。各カテゴリは、そのすべてのメンバを実装する必要のあるクラスインタフェース (Class オブジェクトにより記述される) で定義されます。カテゴリセットは動的に変更できます。

指定されたリーフクラス (つまり、任意の継承されたクラスやインタフェースではなく、getClass() で返された実際のクラス) の 1 つのインスタンスのみが登録できます。ここで、com.mycompany.mypkg.GreenServiceProvider クラスが com.mycompany.mypkg.MyService インタフェースを実装すると仮定します。GreenServiceProvider インタフェースを登録する場合、これは MyService クラスにより定義されたカテゴリに格納されます。GreenServiceProvider の新しいインスタンスを登録する場合、これは以前のインスタンスを置き替えます。通常、サービスプロバイダオブジェクトは単体であるため、この動作は適切です。

サービスプロバイダを宣言するために、services サブディレクトリが各 JAR ファイルに存在する META-INF ディレクトリ内に配置されます。このディレクトリには、JAR ファイルに 1 つまたは複数の実装クラスを保持する各サービスプロバイダインタフェースに対して 1 つのファイルが含まれます。たとえば、JAR ファイルに javax.someapi.SomeService インタフェースを実装する com.mycompany.mypkg.MyServiceImpl というクラスが含まれる場合、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) 指定された ServiceRegistry.Filter オブジェクトの filter メソッドで設定された基準を満たす、指定されたカテゴリ内のサービスプロバイダオブジェクトを含む Iterator を返します。
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) 指定されたカテゴリ内の 2 つのサービスプロバイダオブジェクト間のペアの順序を設定します。
<T> boolean	unsetOrdering(Class<T> category, T firstProvider, T secondProvider) 指定されたカテゴリの 2 つのサービスプロバイダオブジェクト間のペアの順序を設定します。

クラス 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 インタフェースを実装する provider の各エントリの場合、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 - プロバイダが登録解除されるカテゴリ

戻り値:

プロバイダが以前に同じ 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)

指定された ServiceRegistry.Filter オブジェクトの filter メソッドで設定された基準を満たす、指定されたカテゴリ内のサービスプロバイダオブジェクトを含む Iterator を返します。

useOrdering 引数により、getServiceProviders(Class, boolean) と同じ規則を使用して結果の順序付けが制御されます。

パラメータ:

category - 取得元のカテゴリ

filter - filter メソッドが呼び出される ServiceRegistry.Filter インスタンス

useOrdering - 返されるオブジェクトの順番にペアの順序付けを反映する場合は true

戻り値:

指定されたカテゴリからのサービスプロバイダオブジェクトを含む Iterator (大抵はその順番通り)

例外:

IllegalArgumentException - category に対応するカテゴリが存在しない場合

getServiceProviderByClass

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

現在登録されている、指定されたクラス型のプロバイダオブジェクトを返します。一度に登録できる特定クラスのオブジェクトは 1 つだけです。登録されているオブジェクトが目的のクラス型でない場合は、null を返します。

パラメータ:

providerClass - 目的とするサービスプロバイダオブジェクトの Class

戻り値:

現在登録されている、目的の Class 型のサービスプロバイダオブジェクト。存在しない場合は null

例外:

IllegalArgumentException - providerClass が null の場合

setOrdering

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

指定されたカテゴリ内の 2 つのサービスプロバイダオブジェクト間のペアの順序を設定します。オブジェクトの内の 1 つまたは両方が、指定されたカテゴリ内に現在登録されていない場合、または目的の順序がすでに設定されている場合は、何も実行せずに false を返します。プロバイダが以前に逆方向に順序付けされた場合、その順序は削除されます。

順序は、useOrdering 引数が true の場合に、getServiceProviders メソッドにより使用されます。

パラメータ:

category - 優先度を設定するカテゴリを示す Class オブジェクト

firstProvider - 優先されるプロバイダ

secondProvider - firstProvider が優先されるプロバイダ

戻り値:

以前に設定されなかった順序が設定された場合は true

例外:

IllegalArgumentException - プロバイダが null か、または同じオブジェクトの場合

IllegalArgumentException - category に対応するカテゴリが存在しない場合

unsetOrdering

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

指定されたカテゴリの 2 つのサービスプロバイダオブジェクト間のペアの順序を設定します。オブジェクトの 1 つまたは両方が指定されたカテゴリ内に現在登録されていない場合、またはその間の順序付けが現在設定されていない場合は、何も実行せずに false を返します。

順序は、useOrdering 引数が true の場合に、getServiceProviders メソッドにより使用されます。

パラメータ:

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 - スーパークラスのファイナライズ時にエラーが発生した場合