javax.imageio.spi

クラス ServiceRegistry

java.lang.Object

javax.imageio.spi.ServiceRegistry

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

IIORegistry

public class ServiceRegistry
extends Object

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

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

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

パラメータ:

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 - プロバイダが登録解除されるカテゴリ。

戻り値:

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

オーバーライド:

finalize、クラス: Object

例外:

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