java.lang.reflect

クラス Proxy

java.lang.Object

java.lang.reflect.Proxy

すべての実装されたインタフェース:

Serializable

public class Proxy
extends Object
implements Serializable

Proxy は、動的プロキシのクラスおよびインスタンスを作成する static メソッドを提供し、また、それらのメソッドによって作成された動的プロキシクラスすべてのスーパークラスでもあります。

インタフェース Foo のプロキシを生成するには、次のように設定します。

     InvocationHandler handler = new MyInvocationHandler(...);
     Class proxyClass = Proxy.getProxyClass(
         Foo.class.getClassLoader(), new Class[] { Foo.class });
     Foo f = (Foo) proxyClass.
         getConstructor(new Class[] { InvocationHandler.class }).
         newInstance(new Object[] { handler });
 

あるいはもっと単純に、次のように設定します。

     Foo f = (Foo) Proxy.newProxyInstance(Foo.class.getClassLoader(),
                                          new Class[] { Foo.class },
                                          handler);
 

動的プロキシクラス (以下単にプロキシクラスと呼ぶ) は、クラス生成の実行時に指定されたインタフェースのリストを実装するクラスで、以下に述べる動作をします。 プロキシインタフェースは、プロキシクラスが実装するインタフェースです。 プロキシインスタンスは、プロキシクラスのインスタンスです。 各プロキシインスタンスには関連付けられた呼び出しハンドラオブジェクトがあり、それにはインタフェース InvocationHandler が実装されています。プロキシインタフェースの 1 つを使ったプロキシインスタンスでのメソッド呼び出しは、インスタンスの呼び出しハンドラの invoke メソッドにディスパッチされ、呼び出されたメソッドを識別する java.lang.reflect.Method オブジェクト、および引数を格納する Object 型の配列をプロキシインスタンスに引き渡します。呼び出しハンドラは符号化されたメソッド呼び出しを適切に処理し、呼び出しハンドラが返す結果が、プロキシインスタンスでのメソッド呼び出しの結果として返されます。

プロキシクラスには以下のプロパティーがあります。

• プロキシクラスは public であり final であって、abstract ではありません。
• プロキシクラスの修飾されていない名前は指定されません。ただし文字列「$Proxy」で始まるクラス名の領域をプロキシクラスのために確保しておく必要があります。
• プロキシクラスは java.lang.reflect.Proxy を継承します。
• プロキシクラスはその生成時に指定されたとおりのインタフェースを、同じ順序で実装します。
• public 以外のインタフェースを実装する場合は、そのインタフェースと同じパッケージに定義されます。public インタフェースを実装する場合は、プロキシクラスのパッケージは指定されません。パッケージのシーリングは、プロキシクラスが実行時に特定のパッケージで定義される妨げにはなりません。特定の署名者を持つ同じクラスローダーと同じパッケージですでに定義されているクラスについても同様です。
• プロキシクラスはその生成時に指定されたインタフェースをすべて実装しているため、その Class オブジェクトで getInterfaces を呼び出すと、同じインタフェースのリストを生成時に指定された順序で格納する配列が返されます。Class オブジェクトで getMethods を呼び出すと、それらのインタフェースのメソッドすべてを含む Method オブジェクトの配列が返されます。getMethod を呼び出すと、予想されるメソッドがプロキシインタフェースで見つかります。
• Proxy.isProxyClass メソッドは、プロキシクラス (Proxy.getProxyClass から返されたクラス、または Proxy.newProxyInstance から返されたオブジェクトのクラス) を渡された場合は true を返し、それ以外の場合は false を返します。
• プロキシクラスの java.security.ProtectionDomain は、java.lang.Object などの、ブートストラップクラスローダによってロードされるシステムクラスの java.security.ProtectionDomain と同じです。プロキシクラスのコードは、信頼されたシステムコードによって生成されるためです。標準では、この保護ドメインに対して java.security.AllPermission が与えられます。
• 各プロキシクラスには、プロキシインスタンスの呼び出しハンドラを設定するために、1 つの引数つまりインタフェース InvocationHandler の実装を取る 1 つの public コンストラクタがあります。プロキシインスタンスは、リフレクション API を介して public コンストラクタにアクセスしなくても、Proxy.newProxyInstance メソッドを呼び出すことによっても作成できます。このメソッドでは、Proxy.getProxyClass を呼び出すアクションと、呼び出しハンドラを使用してコンストラクタを呼び出すアクションが行われます。

プロキシインスタンスには以下のプロパティーがあります。

• プロキシクラス Foo がプロキシインスタンス proxy およびインタフェースの 1 つを実装している場合、次の式が true を返します。

       proxy instanceof Foo
   

  また、次のキャスト操作が成功します (ClassCastException をスローする場合を除く)。

       (Foo) proxy
   

• 各プロキシインスタンスには、そのコンストラクタに引き渡された、関連する呼び出しハンドラがあります。static Proxy.getInvocationHandler メソッドは、その引数として渡されたプロキシインスタンスに関連付けられた呼び出しハンドラを返します。
• プロキシインスタンスでのインタフェースメソッドの呼び出しは、そのメソッドのドキュメントで述べられているように符号化され、呼び出しハンドラの invoke メソッドにディスパッチされます。
• プロキシインスタンス上の java.lang.Object に宣言されている hashCode、equals または toString の呼び出しは、前述したようにインタフェースメソッド呼び出しと同じ方法で、符号化され、呼び出しハンドラの invoke メソッドにディスパッチされます。invoke に渡される Method オブジェクトの宣言クラスは、java.lang.Object です。java.lang.Object から継承されるプロキシインスタンスのその他の public メソッドは、プロキシクラスによってオーバーライドされません。このため、これらのメソッドの呼び出しは、java.lang.Object のインスタンスに対する呼び出しと同様に行われます。

複数のプロキシインタフェースで重複するメソッド

複数のインタフェースに、同じ名前とパラメータシグニチャーを持つメソッドが含まれる場合は、プロキシクラスのインタフェースの順番が区別されます。プロキシインスタンス上で重複するメソッドが呼び出された場合、呼び出しハンドラに渡される Method オブジェクトで、プロキシメソッドの呼び出しに使用されたインタフェースの参照型から宣言クラスを割り当てることができないことがあります。このような制約が存在するのは、生成されたプロキシクラス内の対応するメソッドの実装から、その実装が呼び出されたときに使用されたインタフェースを特定できないためです。このため、プロキシインスタンス上で重複するメソッドが呼び出された場合は、メソッド呼び出しに使用された参照型にかかわりなく、プロキシクラスのインタフェースリストでそのメソッド (直接またはスーパーインタフェースから継承) を含むインタフェースのうち、最初のインタフェースのメソッドの Method オブジェクトが呼び出しハンドラの invoke メソッドに渡されます。

プロキシインタフェースに、java.lang.Object の hashCode、equals、または toString メソッドと同じ名前およびパラメータシグニチャーを持つメソッドが含まれる場合は、プロキシインスタンス上でそのメソッドが呼び出されると、呼び出しハンドラに渡される Method オブジェクトの宣言クラスは java.lang.Object になります。つまり、public で非 final である java.lang.Object のメソッドは、呼び出しハンドラに渡す Method オブジェクトを決定するときに、論理的にほかのプロキシインタフェースより優先されます。

重複するメソッドが呼び出しハンドラにディスパッチされた場合は、invoke メソッドからスローできるチェック例外の型は、チェックされる型のうち、呼び出されるすべてのプロキシインタフェースのメソッドに指定されている、throws 句の例外の型に割り当てることができるものに限定されます。invoke メソッドが、呼び出しに使えるプロキシインタフェースの 1 つのメソッドで宣言された例外タイプのどれにも割り当てできないチェック例外をスローした場合、チェックされない UndeclaredThrowableException がプロキシインスタンスでの呼び出しによってスローされます。つまり、invoke メソッドに渡された Method オブジェクト上で、getExceptionTypes を呼び出して例外の型を取得しても、invoke メソッドから正常にスローされないことがあります。

導入されたバージョン:

1.3

関連項目:

InvocationHandler, 直列化された形式

フィールドのサマリー

フィールド

修飾子と型	フィールドと説明
protected InvocationHandler	h このプロキシインスタンスの呼び出しハンドラです。

コンストラクタのサマリー

コンストラクタ

修飾子	コンストラクタと説明
protected	Proxy(InvocationHandler h) 指定された値で、サブクラス (通常は動的プロキシクラス) からその呼び出しハンドラに新しい Proxy インスタンスを構築します。

メソッドのサマリー

メソッド

修飾子と型	メソッドと説明
static InvocationHandler	getInvocationHandler(Object proxy) 指定されたプロキシインスタンスの呼び出しハンドラを返します。
static Class<?>	getProxyClass(ClassLoader loader, Class<?>... interfaces) クラスローダーとインタフェースの配列の指定されたプロキシクラスの java.lang.Class オブジェクトを返します。
static boolean	isProxyClass(Class<?> cl) 指定されたクラスが getProxyClass メソッドまたは newProxyInstance メソッドを使って動的に生成されてプロキシクラスとなる場合にだけ、true を返します。
static Object	newProxyInstance(ClassLoader loader, Class<?>[] interfaces, InvocationHandler h) 指定された呼び出しハンドラに対してメソッド呼び出しをディスパッチする、指定されたインタフェースのプロキシクラスのインスタンスを返します。

クラス java.lang.Object から継承されたメソッド

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

フィールドの詳細

h

protected InvocationHandler h

このプロキシインスタンスの呼び出しハンドラです。

コンストラクタの詳細

Proxy

protected Proxy(InvocationHandler h)

指定された値で、サブクラス (通常は動的プロキシクラス) からその呼び出しハンドラに新しい Proxy インスタンスを構築します。

パラメータ:

h - このプロキシインスタンスの呼び出しハンドラ

メソッドの詳細

getProxyClass

public static Class<?> getProxyClass(ClassLoader loader,
                     Class<?>... interfaces)
                              throws IllegalArgumentException

クラスローダーとインタフェースの配列の指定されたプロキシクラスの java.lang.Class オブジェクトを返します。プロキシクラスは指定されたクラスローダーにより定義され、指定されたインタフェースをすべて実装します。インタフェースの同じ順列のプロキシクラスがすでにクラスローダーにより定義されている場合、既存のプロキシクラスが返されます。 そうでない場合は、これらのインタフェースのプロキシクラスが動的に生成され、クラスローダーにより定義されます。

Proxy.getProxyClass に引き渡されるパラメータには、いくつかの制約があります。

• interfaces 配列の Class オブジェクトはすべて、クラスまたはプリミティブ型ではなくインタフェースを表す必要がある。
• interfaces 配列の 2 つの要素が同一の Class オブジェクトを参照することはできない。
• すべての型のインタフェースは、対応するクラスローダから名前で参照できなければならない。つまり、クラスローダが cl、各インタフェースが i の場合は、次の式が true でなければならない。

       Class.forName(i.getName(), false, cl) == i
   

• public でないインタフェースはすべて同じパッケージになければならない。そうでない場合、プロキシクラスがどのパッケージで定義されているかにかかわらず、プロキシクラスがインタフェースをすべて実装することは不可能である
• 指定されたインタフェースが同じ署名を持つ場合、そのようなメソッドの任意の組に対して
  • 任意のメソッドの戻り値の型がプリミティブ型または void の場合、それらのメソッドはすべて戻り値の型が同じでなければならない
  • そうでない場合、いずれかのメソッドによる戻り値の型は、残りのメソッドによる戻り値の型すべてに対して割り当て可能でなければならない
• プロキシクラスを作成するときは、Virtual Machine に定義されているクラスの制限を超えてはならない。たとえば、VM が、クラスが実装できるインタフェース数を 65535 に制限している場合は、interfaces 配列のサイズは 65535 を超えてはならない。

これらの制約に対して違反が発生した場合は、Proxy.getProxyClass によって IllegalArgumentException がスローされます。interfaces 配列引数またはそのいずれかの要素が null の場合、NullPointerException がスローされます。

プロキシインタフェースは、順番が区別されます。プロキシクラスを 2 回要求したときに、インタフェースの組み合わせが同じで順番が異なる場合は、2 つの異なるプロキシクラスが作成されます。

パラメータ:

loader - プロキシクラスを定義するクラスローダー

interfaces - プロキシクラスが実装するインタフェースのリスト

戻り値:

指定されたクラスローダで定義され、指定されたインタフェースを実装するプロキシクラス

例外:

IllegalArgumentException - getProxyClass に引き渡されるパラメータに関する制約のどれかが守られなかった場合

NullPointerException - interfaces 配列の引数またはその要素のいずれかが null の場合

newProxyInstance

public static Object newProxyInstance(ClassLoader loader,
                      Class<?>[] interfaces,
                      InvocationHandler h)
                               throws IllegalArgumentException

指定された呼び出しハンドラに対してメソッド呼び出しをディスパッチする、指定されたインタフェースのプロキシクラスのインスタンスを返します。このメソッドは、次と同等です。

     Proxy.getProxyClass(loader, interfaces).
         getConstructor(new Class[] { InvocationHandler.class }).
         newInstance(new Object[] { handler });
 

Proxy.getProxyClass の場合と同じ理由で、Proxy.newProxyInstance は IllegalArgumentException をスローします。

パラメータ:

loader - プロキシクラスを定義するクラスローダー

interfaces - プロキシクラスが実装するインタフェースのリスト

h - メソッド呼び出しのディスパッチ先の呼び出しハンドラ

戻り値:

指定されたクラスローダで定義され、指定されたインタフェースを実装するプロキシクラスの、指定された呼び出しハンドラを持つプロキシインスタンス

例外:

IllegalArgumentException - getProxyClass に引き渡されるパラメータに関する制約のどれかが守られなかった場合

NullPointerException - interfaces 配列の引数またはその要素のいずれかが null の場合、または呼び出しハンドラ h が null の場合

isProxyClass

public static boolean isProxyClass(Class<?> cl)

指定されたクラスが getProxyClass メソッドまたは newProxyInstance メソッドを使って動的に生成されてプロキシクラスとなる場合にだけ、true を返します。

セキュリティーを判定するときにこのメソッドを使用する場合は、信頼性が重要になります。このため、渡されたクラスが Proxy を継承しているかどうかを検査してから、追加の検査を行う必要があります。

パラメータ:

cl - テストするクラス

戻り値:

クラスがプロキシクラスの場合は true、そうでない場合は false

例外:

NullPointerException - cl が null である場合

getInvocationHandler

public static InvocationHandler getInvocationHandler(Object proxy)
                                              throws IllegalArgumentException

指定されたプロキシインスタンスの呼び出しハンドラを返します。

パラメータ:

proxy - 呼び出しハンドラを返すプロキシインスタンス

戻り値:

プロキシインスタンスの呼び出しハンドラ

例外:

IllegalArgumentException - 引数がプロキシインスタンスではない場合