com.sun.jdi

インタフェース ObjectReference

すべてのスーパーインタフェース:

Mirror, Value

既知のすべてのサブインタフェース:

ArrayReference, ClassLoaderReference, ClassObjectReference, StringReference, ThreadGroupReference, ThreadReference

public interface ObjectReference
extends Value

ターゲット VM に現在存在するオブジェクトです。ObjectReference は、そのオブジェクトだけをミラー化します。ObjectReference は、現在割り当てられている Field や LocalVariable に固有のオブジェクトではありません。ObjectReference は、いくつかのフィールドまたは変数、あるいはその両方から 0 または 1 つ以上の参照を持つことができます。

ターゲット VM が切断された場合、ObjectReference を直接的または間接的にパラメータとして取る ObjectReference 上の任意のメソッドは、VMDisconnectedException をスローし、VMDisconnectEvent が EventQueue から読み出せるようになります。

ObjectReference を直接的または間接的にパラメータとして取る ObjectReference 上の任意のメソッドは、ターゲット VM のメモリーが不足すると VMOutOfMemoryException をスローします。

ObjectReference を直接的または間接的にパラメータに取る ObjectReference 上の任意のメソッドは、ミラーオブジェクトがガベージコレクトされた場合に ObjectCollectedException をスローします。

導入されたバージョン:

1.3

フィールドのサマリー

フィールド

修飾子と型	フィールドと説明
static int	INVOKE_NONVIRTUAL 非仮想メソッドの呼び出しを実行します。
static int	INVOKE_SINGLE_THREADED 呼び出し側のスレッドだけを再開してメソッドの呼び出しを実行します。

メソッドのサマリー

メソッド

修飾子と型	メソッドと説明
void	disableCollection() このオブジェクトに対するガベージコレクションを回避します。
void	enableCollection() このオブジェクトのガベージコレクションを許可します。
int	entryCount() 現在所有しているスレッドが、このオブジェクトのモニターにエントリした回数を返します。
boolean	equals(Object obj) 指定された Object がこの ObjectReference と等しいかどうか比較します。
Value	getValue(Field sig) このオブジェクトの指定されたインスタンスまたは static フィールドの値を取得します。
Map<Field,Value>	getValues(List<? extends Field> fields) このオブジェクトの複数のインスタンスまたは static フィールド、あるいはその両方の値を取得します。
int	hashCode() この ObjectReference のハッシュコード値を返します。
Value	invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) ターゲット VM 内のこのオブジェクトで指定された Method を呼び出します。
boolean	isCollected() ターゲット VM でこのオブジェクトがガベージコレクトされているかどうかを判定します。
ThreadReference	owningThread() このオブジェクトのモニターを現在所有するスレッドがある場合は、そのスレッドの ThreadReference を返します。
ReferenceType	referenceType() このオブジェクトの型をミラー化する ReferenceType を取得します。
List<ObjectReference>	referringObjects(long maxReferrers) このオブジェクトを直接参照するオブジェクトを返します。
void	setValue(Field field, Value value) このオブジェクトのインスタンスフィールドまたは static フィールドの値を設定します。
long	uniqueID() この ObjectReference の一意の識別子を返します。
List<ThreadReference>	waitingThreads() このオブジェクトのモニターを現在待機している各スレッドの ThreadReference を含むリストを返します。

インタフェース com.sun.jdi.Value から継承されたメソッド

type

インタフェース com.sun.jdi.Mirror から継承されたメソッド

toString, virtualMachine

フィールドの詳細

INVOKE_SINGLE_THREADED

static final int INVOKE_SINGLE_THREADED

呼び出し側のスレッドだけを再開してメソッドの呼び出しを実行します。

関連項目:

定数フィールド値

INVOKE_NONVIRTUAL

static final int INVOKE_NONVIRTUAL

非仮想メソッドの呼び出しを実行します。

関連項目:

定数フィールド値

メソッドの詳細

referenceType

ReferenceType referenceType()

このオブジェクトの型をミラー化する ReferenceType を取得します。この型は、現在この型を保持するフィールドまたは変数の、宣言された型のサブクラスまたは実装元になります。たとえば、次の文の直後で使用します。

Object obj = new String("Hello, world!");

obj の ReferenceType は、java.lang.Object ではなく、java.lang.String をミラー化します。

オブジェクトの型は不変なので、このメソッドはミラー化されたオブジェクトの寿命の間は常に同じ ReferenceType を返します。

返される ReferenceType は、ClassType または ArrayType です。InterfaceType は返されません。

戻り値:

このオブジェクトの ReferenceType。

getValue

Value getValue(Field sig)

このオブジェクトの指定されたインスタンスまたは static フィールドの値を取得します。Field は、この ObjectReference に対して有効である必要があります。つまり、Field は、ミラー化されたオブジェクトのクラスのフィールド、またはそのクラスのスーパークラスのフィールドである必要があります。

パラメータ:

sig - 要求された値を含むフィールド

戻り値:

インスタンスフィールドの Value。

例外:

IllegalArgumentException - フィールドがこのオブジェクトのクラスにとって有効でない場合。

getValues

Map<Field,Value> getValues(List<? extends Field> fields)

このオブジェクトの複数のインスタンスまたは static フィールド、あるいはその両方の値を取得します。Field は、この ObjectReference に対して有効である必要があります。つまり、Field は、ミラー化されたオブジェクトのクラスのフィールド、またはそのクラスのスーパークラスのフィールドである必要があります。

パラメータ:

fields - 要求された値を含む Field オブジェクトのリスト。

戻り値:

Value を含む、要求された Field オブジェクトのマップ。

例外:

IllegalArgumentException - このオブジェクトのクラスにとって無効なフィールドがある場合。

setValue

void setValue(Field field,
            Value value)
              throws InvalidTypeException,
                     ClassNotLoadedException

このオブジェクトのインスタンスフィールドまたは static フィールドの値を設定します。Field は、この ObjectReference に対して有効である必要があります。つまり、Field は、ミラー化されたオブジェクトのクラスのフィールド、またはそのクラスのスーパークラスのフィールドである必要があります。static の場合は、フィールドは final ではあってはいけません。

オブジェクトの値は、このフィールドの型への代入互換性を持たなければいけません (これは、このフィールド型は、囲むクラスのクラスローダーによってロードする必要があることを意味する)。プリミティブ値は、このフィールドの型への代入互換性を持つか、情報を失わずにこのフィールドの型に変換できる必要があります。代入互換性の詳細は、「Java™ 言語仕様」のセクション 5.2 を参照してください。

パラメータ:

field - 要求された値を含むフィールド

value - 代入する新しい値

例外:

IllegalArgumentException - フィールドがこのオブジェクトのクラスにとって有効でない場合。

InvalidTypeException - 値の型がフィールドの型に一致しない場合。

ClassNotLoadedException - value が null でなく、適切なクラスローダーによるフィールドの型のロードがまだ行われていない場合。

VMCannotBeModifiedException - VirtualMachine が読み取り専用の場合 (VirtualMachine.canBeModified() を参照)。

invokeMethod

Value invokeMethod(ThreadReference thread,
                 Method method,
                 List<? extends Value> arguments,
                 int options)
                   throws InvalidTypeException,
                          ClassNotLoadedException,
                          IncompatibleThreadStateException,
                          InvocationException

ターゲット VM 内のこのオブジェクトで指定された Method を呼び出します。指定するメソッドは、このオブジェクトのクラス、このオブジェクトのクラスのスーパークラス、またはこのオブジェクトによって実装されたインタフェース内で定義できます。このメソッドには、static メソッドまたはインスタンスメソッドを指定できますが、static 初期化子や static コンストラクタを指定することはできません。新規オブジェクトを作成し、そのコンストラクタを実行するには、ClassType.newInstance(com.sun.jdi.ThreadReference, com.sun.jdi.Method, java.util.List<? extends com.sun.jdi.Value>, int) を使用します。

メソッド呼び出しは、指定されたスレッドで実行されます。指定されたスレッドがそのスレッド内で発生したイベントにより中断される場合にのみ、メソッドの呼び出しを行います。ターゲット VM が VirtualMachine.suspend() によって中断された場合、または指定されたスレッドが ThreadReference.suspend() によって中断された場合、メソッドの呼び出しはサポートされません。

指定されたメソッドは、指定された引数リスト内の引数を使って呼び出されます。メソッドの呼び出しは、同期をとられます。呼び出されたメソッドがターゲット VM で復帰するまで、このメソッドは復帰しません。呼び出されたメソッドが例外をスローする場合、このメソッドはスローされた例外オブジェクトに対するミラーを含む InvocationException をスローします。

オブジェクト引数は、この引数型への代入互換性を持たなければいけません (これは、この引数型は、囲むクラスのクラスローダーによってロードする必要があることを意味する)。プリミティブ引数は、この引数型への代入互換性を持っているか、情報を失わずにこの引数型に変換できる必要がある。呼び出されているメソッドが引数の可変数を受け取る場合、最後の引数型が特定の要素型の配列になります。一致する位置にある引数は、省略される (つまり null となる) 可能性や、あるいは、同じ要素型の配列になる (つまり、同じ型のほかの引数の任意の数が続く要素型の引数となる) 可能性があります。引数が省略される場合は、配列の長さがゼロである要素型が渡されます。要素型はプリミティブ型である可能性もあります。自動ボックス化はサポートされていません。 代入互換性の詳細は、「Java™ 言語仕様」のセクション 5.2 を参照してください。

デフォルトでは、このメソッドは、動的ルックアップを使用して呼び出されます (「Java™ 言語仕様」のセクション 15.12.4.4 を参照)。特に、この ObjectReference によってミラー化されたオブジェクトの、実行時の型に基づいてオーバーライドが発生します。この動作を変更するには、options 引数に INVOKE_NONVIRTUAL ビットフラグを指定します。このフラグを設定すると、このオブジェクトの実行時の型に対してオーバーライドが発生するかどうかにかかわらず、指定されたメソッドが呼び出されます。この場合、メソッドは、インタフェースに属していたり、abstract であったりしてはいけません。このオプションは、Java プログラミング言語の super キーワードで実行されるようなメソッドの呼び出しに使用します。

デフォルトでは、ターゲット VM 内のすべてのスレッドがメソッドの呼び出し中に再開されます (イベントや VirtualMachine.suspend() または ThreadReference.suspend() によって以前に中断されたスレッドの場合)。これは、いずれかのスレッドが、呼び出し先メソッドが必要とするモニターを所有している場合に、デッドロックが発生するのを防ぎます。ただし、この暗黙の再開は、ThreadReference.resume() とまったく同様に行われるため、スレッドの中断カウントが 1 を超える場合は、呼び出し中にスレッドが再開されません。このため、デッドロックが発生する可能性があることに留意してください。デフォルトでは、ターゲット VM 内のすべてのスレッドは、呼び出しの完了時に中断します (呼び出し前のスレッドの状態とは無関係)。ブレークポイントまたはほかのイベントが、呼び出し中に発生する可能性があります。この場合、前述したデッドロックが発生することがあります。また、invokeMethod がクライアントのイベントハンドラスレッドから呼び出された場合も、デッドロックが発生することがあります。この場合、このスレッドは invokeMethod が完了するまで待機するので、新規イベントの発生に伴う EventSet の読み取りを行いません。この新規 EventSet が SUSPEND_ALL である場合、EventSet が再開されないので、デッドロックが発生します。この状況を避けるには、invokeMethod の実行前にすべての EventRequest を無効にするか、invokeMethod をクライアントのイベントハンドラスレッドから呼び出さないようにしてください。

options 引数に INVOKE_SINGLE_THREADED ビットフラグを指定することにより、呼び出し中にほかのスレッドが再開しないようにできます。ただし、前述のようなデッドロックに対する保護や、デッドロックからの回復ができなくなるため、このオプションはよく注意して利用してください。指定されたスレッドだけが再開されます (前述したすべてのスレッドの場合と同様)。シングルスレッド呼び出しが完了すると、呼び出し元スレッドはふたたび中断されます。シングルスレッド呼び出し中に開始されたすべてのスレッドは、呼び出し完了時にも中断されません。

呼び出し中に VirtualMachine.dispose() などによってターゲット VM が切断された場合でも、メソッドの呼び出しは続行されます。

パラメータ:

thread - 呼び出しを行うスレッド。

method - 呼び出す Method。

arguments - 呼び出されたメソッドにバインドされた Value 引数のリスト。リストから取得した値は、メソッドシグニチャーに指定されている順序で引数に代入される。

options - 整数ビットフラグオプション。

戻り値:

呼び出されたメソッドの戻り値の Value ミラー。

例外:

IllegalArgumentException - メソッドがこのオブジェクトのクラスのメンバーでない場合、引数リストのサイズがこのメソッドに対して宣言された引数の数に一致しない場合、このメソッドがコンストラクタまたは static 初期化子である場合、あるいは INVOKE_NONVIRTUAL が指定され、メソッドが abstract またはインタフェースメンバーである場合。

{@link - InvalidTypeException} 対応するメソッドの引数型に代入できない引数が引数リストにある場合。

ClassNotLoadedException - 引数型が、適切なクラスローダーによってロードされていない場合。

IncompatibleThreadStateException - 指定されたスレッドが、イベントによって中断されていない場合。

InvocationException - メソッドの呼び出しにより、ターゲット VM で例外が発生した場合。

InvalidTypeException - 引数が次の条件を満たさない場合 -- オブジェクト引数は、この引数型への代入互換性を持たなければなりません。(これは、囲むクラスのクラスローダーによってこの引数型をロードする必要があることを意味する)。プリミティブ引数は、この引数型への代入互換性を持っているか、情報を失わずにこの引数型に変換できる必要がある。代入互換性の詳細は、「Java 言語仕様」のセクション 5.2 を参照してください。

VMCannotBeModifiedException - VirtualMachine が読み取り専用の場合 (VirtualMachine.canBeModified() を参照)。

disableCollection

void disableCollection()

このオブジェクトに対するガベージコレクションを回避します。デフォルトでは、JDI により返されるすべての ObjectReference 値は、ターゲット VM の実行中にいつでもガベージコレクトが可能です。このメソッドを呼び出すと、オブジェクトがガベージコレクトされないことが保証されます。ガベージコレクトを再度有効にするには、enableCollection() を使用します。

このメソッドの呼び出しは、カウントされます。このメソッドを呼び出すたびに、enableCollection() を呼び出して、ガベージコレクトを再度有効にする必要があります。

ターゲット VM の中断中は、すべてのスレッドが中断しているため、ガベージコレクションは行われません。中断中に変数、フィールド、および配列を調べるという一般的な操作の場合は、明示的にガベージコレクションを無効にしなくても安全です。

このメソッドを使用すると、ターゲット VM 内のガベージコレクションのパターンが変わるため、アプリケーションの動作がデバッガ実行時とデバッガ非実行時とで異なる結果になる可能性があります。そのため、このメソッドの使用には慎重を期してください。

例外:

VMCannotBeModifiedException - VirtualMachine が読み取り専用の場合 (VirtualMachine.canBeModified() を参照)。

enableCollection

void enableCollection()

このオブジェクトのガベージコレクションを許可します。デフォルトでは、JDI により返されるすべての ObjectReference 値は、ターゲット VM の実行中にいつでもガベージコレクトが可能です。このメソッドの呼び出しは、disableCollection() によってガベージコレクトが無効になっている場合にかぎり必要です。

例外:

VMCannotBeModifiedException - VirtualMachine が読み取り専用の場合 (VirtualMachine.canBeModified() を参照)。

isCollected

boolean isCollected()

ターゲット VM でこのオブジェクトがガベージコレクトされているかどうかを判定します。

戻り値:

この ObjectReference がガベージコレクトされている場合は true、そうでない場合は false。

例外:

VMCannotBeModifiedException - VirtualMachine が読み取り専用の場合 (VirtualMachine.canBeModified() を参照)。

uniqueID

long uniqueID()

この ObjectReference の一意の識別子を返します。この識別子によって、同じ VM の破棄されていないすべての ObjectReference が一意であることが保証されます。これは、この ObjectReference が破棄されるまで保証されます。

戻り値:

long 型の一意の ID

waitingThreads

List<ThreadReference> waitingThreads()
                                     throws IncompatibleThreadStateException

このオブジェクトのモニターを現在待機している各スレッドの ThreadReference を含むリストを返します。モニターを待機していると見なされるスレッドの状態については、ThreadReference.currentContendedMonitor() を参照してください。

この操作は、ターゲット VM でサポートされていないことがあります。この操作がサポートされているかどうかを確認するには、VirtualMachine#canGetMonitorInfo を参照してください。

戻り値:

ThreadReference オブジェクトのリスト。モニターを待機しているスレッドが存在しない場合、リストの長さはゼロになる。

例外:

UnsupportedOperationException - ターゲット VM でこの操作がサポートされていない場合。

IncompatibleThreadStateException - ターゲット VM に中断されていない待機中のスレッドがある場合

owningThread

ThreadReference owningThread()
                             throws IncompatibleThreadStateException

このオブジェクトのモニターを現在所有するスレッドがある場合は、そのスレッドの ThreadReference を返します。所有権の定義については、ThreadReference.ownedMonitors() を参照してください。

この操作は、ターゲット VM でサポートされていないことがあります。この操作がサポートされているかどうかを確認するには、VirtualMachine#canGetMonitorInfo を参照してください。

戻り値:

モニターを現在所有する ThreadReference。モニターが所有されていない場合は null。

例外:

UnsupportedOperationException - ターゲット VM でこの操作がサポートされていない場合。

IncompatibleThreadStateException - 所有するスレッドがターゲット VM で中断されていない場合

entryCount

int entryCount()
               throws IncompatibleThreadStateException

現在所有しているスレッドが、このオブジェクトのモニターにエントリした回数を返します。所有権の定義については、ThreadReference.ownedMonitors() を参照してください。

この操作は、ターゲット VM でサポートされていないことがあります。この操作がサポートされているかどうかを確認するには、VirtualMachine#canGetMonitorInfo を参照してください。

戻り値:

整数型のエントリカウント。

例外:

UnsupportedOperationException - ターゲット VM でこの操作がサポートされていない場合。

IncompatibleThreadStateException - 所有するスレッドがターゲット VM で中断されていない場合

関連項目:

owningThread()

referringObjects

List<ObjectReference> referringObjects(long maxReferrers)

このオブジェクトを直接参照するオブジェクトを返します。ガベージコレクト目的で到達可能なオブジェクトだけが返されます。オブジェクトは、その他の方法でも参照可能です。たとえばスタックフレーム内でローカル変数を使用する方法、JNI グローバル参照を使用する方法などがあります。このメソッドでは、このような、オブジェクトを参照しないオブジェクトは返されません。

この操作は、ターゲット仮想マシンでサポートされていないことがあります。この操作がサポートされているかどうかを確認するには、VirtualMachine.canGetInstanceInfo() を使用します。

パラメータ:

maxReferrers - 返される参照オブジェクトの最大数。負でない数値。ゼロの場合、すべての参照オブジェクトが返される。

戻り値:

ObjectReference オブジェクトのリスト。このオブジェクトを参照するオブジェクトが存在しない場合は、長さゼロのリストを返す。

例外:

UnsupportedOperationException - ターゲット仮想マシンがこの操作をサポートしていない場合 (次を参照)。 canGetInstanceInfo()

IllegalArgumentException - maxReferrers がゼロ未満の場合。

導入されたバージョン:

1.6

関連項目:

VirtualMachine.instanceCounts(List), ReferenceType.instances(long)

equals

boolean equals(Object obj)

指定された Object がこの ObjectReference と等しいかどうか比較します。

オーバーライド:

equals 、クラス: Object

パラメータ:

obj - 比較対象の参照オブジェクト。

戻り値:

Object が ObjectReference である場合、両方の ObjectReference が同じ VM に属している場合、およびその VM でミラー化されたオブジェクトに対して「==」演算子を適用したときの評価が true の場合は true。

関連項目:

Object.hashCode(), HashMap

hashCode

int hashCode()

この ObjectReference のハッシュコード値を返します。

オーバーライド:

hashCode 、クラス: Object

戻り値:

整数のハッシュコード

関連項目:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)