compact1、compact2、compact3

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(), Foo.class);
     Foo f = (Foo) proxyClass.getConstructor(InvocationHandler.class).
                     newInstance(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ではありません(すべてのプロキシ・インタフェースがpublicである場合)。
• プロキシ・クラスは非publicでありfinalであって、abstractではありません(プロキシ・インタフェースのいずれかが非publicである場合)。
• プロキシ・クラスの修飾されていない名前は指定されません。ただし文字列「$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 - このプロキシ・インスタンスの呼出しハンドラ

例外:

NullPointerException - 指定された呼び出しハンドラhがnullの場合

メソッドの詳細

getProxyClass

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

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

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に引き渡されるパラメータに関する制約のどれかが守られなかった場合

SecurityException - セキュリティ・マネージャsが存在し、次の条件のどれかが満たされる場合:

• 指定されたloaderがnullで、呼出し側のクラス・ローダーがnullではなく、RuntimePermission("getClassLoader")のアクセス権を使用したs.checkPermissionの呼出しがアクセスを許可しない。
• 各プロキシ・インタフェースintfについて、呼出し側のクラス・ローダーがintfのクラス・ローダーと同じでもその祖先でもなく、s.checkPackageAccess()の呼出しがintfへのアクセスを許可しない。

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

newProxyInstance

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

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

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

パラメータ:

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

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

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

戻り値:

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

例外:

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

SecurityException - セキュリティ・マネージャsが存在し、次の条件のどれかが満たされる場合:

• 指定されたloaderがnullで、呼出し側のクラス・ローダーがnullではなく、RuntimePermission("getClassLoader")のアクセス権を使用したs.checkPermissionの呼出しがアクセスを許可しない。
• 各プロキシ・インタフェースintfについて、呼出し側のクラス・ローダーがintfのクラス・ローダーと同じでもその祖先でもなく、s.checkPackageAccess()の呼出しがintfへのアクセスを許可しない。
• 指定されたプロキシ・インタフェースのいずれかが非publicであり、呼出し側のクラスが非publicインタフェースと同じ実行時パッケージ内にはなく、ReflectPermission("newProxyInPackage.{package name}")のアクセス権を使用したs.checkPermissionの呼出しがアクセスを許可しない。

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 - 引数がプロキシ・インスタンスではない場合

SecurityException - セキュリティ・マネージャsが存在し、呼出し側のクラス・ローダーが呼出しハンドラのクラス・ローダーと同じでもその祖先でもなく、s.checkPackageAccess()の呼出しが呼出しハンドラのクラスのアクセスを許可しない。