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ファイルの仕様」を参照してください。

関連項目:

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仮想マシンに拡張機能をインストールすることが可能であるため、このメソッドは呼び出されるたびに異なる結果を返す場合があります。

型パラメータ:

T - providerClassの型。

パラメータ:

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);
 

型パラメータ:

T - providerClassの型。

パラメータ:

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メソッドは、カテゴリの削除やレジストリのガベージ・コレクトなど、カテゴリから登録解除されるたびに呼び出されます。

型パラメータ:

T - プロバイダの型。

パラメータ:

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メソッドが呼び出されます。

型パラメータ:

T - プロバイダの型。

パラメータ:

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の場合、イテレータはすべてのサービス・プロバイダ・オブジェクトを任意の順序で返します。それ以外の場合、順番は設定されたペアの順序付けすべてを反映します。ペアの順序付けのグラフにサイクルが含まれる場合、サイクルに所属するプロバイダはどれも返されません。

型パラメータ:

T - カテゴリの型。

パラメータ:

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)と同じルールを使用して結果の順序付けが制御されます。

型パラメータ:

T - カテゴリの型。

パラメータ:

category - 取得元のカテゴリ。

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

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

戻り値:

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

例外:

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

getServiceProviderByClass

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

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

型パラメータ:

T - プロバイダの型。

パラメータ:

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によって使用されます。

型パラメータ:

T - カテゴリの型。

パラメータ:

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によって使用されます。

型パラメータ:

T - カテゴリの型。

パラメータ:

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メソッドを呼び出して、現在登録されているサービス・プロバイダをすべて登録解除します。このメソッドを、アプリケーション・コードから呼び出してはいけません。

オーバーライド:

finalize、クラス: Object

例外:

Throwable - スーパー・クラスのファイナライズ時にエラーが発生した場合。

関連項目:

WeakReference, PhantomReference