JavaTM 2 Platform
Standard Ed. 5.0

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 - categoriesnull の場合
メソッドの詳細

lookupProviders

public static <T> Iterator<T> lookupProviders(Class<T> providerClass,
                                              ClassLoader loader)
指定されたクラスローダを使用して特定のサービスクラスの実装を検索します。

このメソッドは、指定されたサービスクラスの名前を、クラスコメントの記述に従ってプロバイダ構成のファイル名に変換し、指定されたクラスローダの getResources メソッドを使用してその名前を持つ使用可能なファイルすべてを検索します。これらのファイルは次に読み込まれて構文解析され、プロバイダクラス名のリストが作成されます。返された反復子は指定されたクラスローダを使用して、リストの各要素を参照しインスタンス化します。

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

パラメータ:
providerClass - 検出中のサービスプロバイダのクラスまたはインタフェースを示す Class オブジェクト
loader - プロバイダ構成ファイルのロードおよびプロバイダクラスのインスタンス化に使用するクラスローダ。システムクラスローダを使用する場合、またはブートストラップクラスローダで失敗した場合は null
戻り値:
指定されたサービスのプロバイダオブジェクトを、任意の順番で生成する Iterator。プロバイダ構成のファイルが指定された形式に違反するか、またはプロバイダクラスを検出してインスタンス化できない場合、反復子により Error がスローされる
例外:
IllegalArgumentException - providerClassnull の場合

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 - providerClassnull の場合

getCategories

public Iterator<Class<?>> getCategories()
現在のカテゴリセットを示す Class オブジェクトの Iterator を返します。カテゴリが存在しない場合、反復子は空です。

戻り値:
Class オブジェクトを含む Iterator

registerServiceProvider

public <T> boolean registerServiceProvider(T provider,
                                           Class<T> category)
サービスプロバイダオブジェクトをレジストリに追加します。プロバイダは指定されたカテゴリに関連付けされます。

providerRegisterableService インタフェースを実装する場合、onRegistration メソッドが呼び出されます。その onDeregistration メソッドは、カテゴリの削除やレジストリのガベージコレクトなど、カテゴリから登録解除されるたびに呼び出されます。

パラメータ:
provider - 登録されるサービスプロバイダオブジェクト
category - プロバイダが登録されるカテゴリ
戻り値:
以前に同じカテゴリに同じクラスのプロバイダが登録されていなかった場合は true
例外:
IllegalArgumentException - providernull の場合
IllegalArgumentException - category に対応するカテゴリが存在しない場合
ClassCastException - プロバイダが category で定義された Class を実装しない場合

registerServiceProvider

public void registerServiceProvider(Object provider)
サービスプロバイダオブジェクトをレジストリに追加します。プロバイダは、Class を実装するレジストリに存在する各カテゴリ内で関連付けされます。

providerRegisterableService インタフェースを実装する場合、onRegistration メソッドが登録されるカテゴリごとに一度呼び出されます。その onDeregistration メソッドは、カテゴリから登録解除されるたび、またはレジストリがファイナライズされる際に呼び出されます。

パラメータ:
provider - 登録されるサービスプロバイダオブジェクト
例外:
IllegalArgumentException - providernull の場合

registerServiceProviders

public void registerServiceProviders(Iterator<?> providers)
Iterator から取り込んだ一連のサービスプロバイダオブジェクトをレジストリに追加します。各プロバイダは、Class を実装するレジストリに存在する各カテゴリ内で関連付けされます。

RegisterableService インタフェースを実装する provider の各エントリの場合、onRegistration メソッドが登録されるカテゴリごとに一度呼び出されます。その onDeregistration メソッドは、カテゴリから登録解除されるたび、またはレジストリがファイナライズされる際に呼び出されます。

パラメータ:
providers - 登録されるサービスプロバイダオブジェクトを含む反復子
例外:
IllegalArgumentException - providersnull であるか、null エントリを含む場合

deregisterServiceProvider

public <T> boolean deregisterServiceProvider(T provider,
                                             Class<T> category)
指定されたカテゴリからサービスプロバイダオブジェクトを削除します。このプロバイダが以前に登録されていない場合は、何も実行せずに false を返します。そうでない場合は、true を返します。provider と同じクラスのオブジェクトであっても provider と等しくない (== で比較) 場合、登録は解除されません。

providerRegisterableService インスタンスを実装する場合、その onDeregistration メソッドが呼び出されます。

パラメータ:
provider - 登録解除されるサービスプロバイダオブジェクト
category - プロバイダが登録解除されるカテゴリ
戻り値:
プロバイダが以前に同じ category カテゴリに登録された場合は true、そうでない場合は false
例外:
IllegalArgumentException - providernull の場合
IllegalArgumentException - category に対応するカテゴリが存在しない場合
ClassCastException - プロバイダが category で定義されたクラスを実装しない場合

deregisterServiceProvider

public void deregisterServiceProvider(Object provider)
サービスプロバイダオブジェクトを、それを含むすべてのカテゴリから削除します。

パラメータ:
provider - 登録解除されるサービスプロバイダオブジェクト
例外:
IllegalArgumentException - providernull の場合

contains

public boolean contains(Object provider)
provider が現在登録されている場合は true を返します。

パラメータ:
provider - 照会されるサービスプロバイダオブジェクト
戻り値:
指定されたプロバイダが登録済みの場合は true
例外:
IllegalArgumentException - providernull の場合

getServiceProviders

public <T> Iterator<T> getServiceProviders(Class<T> category,
                                           boolean useOrdering)
指定されたカテゴリ内の登録済みサービスプロバイダをすべて含む Iterator を返します。useOrderingfalse の場合、反復子はすべてのサービスプロバイダオブジェクトを任意の順序で返します。それ以外の場合、順番は設定されたペアの順序付けすべてを反映します。ペアの順序付けのグラフにサイクルが含まれる場合、サイクルに所属するプロバイダはどれも返されません。

パラメータ:
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 - providerClassnull の場合

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

JavaTM 2 Platform
Standard Ed. 5.0

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java 2 SDK SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。