Java Debug Interface

com.sun.jdi
インタフェース StackFrame

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

public interface StackFrame
extends Mirror, Locatable

スレッドの呼び出しスタック上での、特定のメソッド呼び出しの状態です。スレッドの実行中にスタックフレームのプッシュとポップが行われますが、この処理はメソッドが呼び出されてから復帰するまでに呼び出しスタックから行われます。StackFrame は、スレッドの実行時の特定の時点に、ターゲット VM のスタックフレームをミラー化します。つまり、呼び出しスタックは StackFrame オブジェクトの List になります。呼び出しスタックは、スレッドが中断している間は ThreadReference.frames() を呼び出して取得できます。

StackFrame を使用して、メソッドの局所変数およびその現在の値にアクセスすることができます。

StackFrame には寿命があります。StackFrame は、スレッドが中断しているときにだけ使用でき、スレッドが再開されると無効になります。

ターゲット VM が切断された場合、StackFrame を引数に取る StackFrame 上の任意のメソッドは、VMDisconnectedException をスローし、VMDisconnectEventEventQueue から読み出せるようになります。

StackFrame を引数に取る StackFrame 上の任意のメソッドは、ターゲット VM のメモリが不足すると VMOutOfMemoryException をスローします。

導入されたバージョン:
1.3

メソッドの概要
 Value getValue(LocalVariable variable)
          このフレーム内の LocalVariableValue を取得します。
 Map<LocalVariable,Value> getValues(List<? extends LocalVariable> variables)
          このフレーム内の複数の局所変数の値を返します。
 Location location()
          フレーム内の現在の命令の Location を返します。
 void setValue(LocalVariable variable, Value value)
          このフレーム内の LocalVariableValue を設定します。
 ObjectReference thisObject()
          現在のフレームの this の値を返します。
 ThreadReference thread()
          このフレームのメソッドが実行されているスレッドを返します。
 LocalVariable visibleVariableByName(String name)
          LocalVariable のうち、指定された名前と一致し、現在のフレーム位置で可視なものを検索します。
 List<LocalVariable> visibleVariables()
          このフレームの位置からアクセスできるすべての LocalVariable のリストを返します。
 
インタフェース com.sun.jdi.Mirror から継承されたメソッド
toString, virtualMachine
 

メソッドの詳細

location

Location location()
フレーム内の現在の命令の Location を返します。このフレームを作成したメソッドには、返された位置からアクセスすることもできます。スタック内の最上位のフレームでは、次に実行される命令の位置を返します。その他のすべてのフレームでは、次のフレームのメソッドが呼び出し元の命令の位置を返します。フレームが native メソッドの呼び出しを表す場合は、返される位置はクラスとメソッドを示していますが、コードインデックスは無効 (-1) です。

定義:
インタフェース Locatable 内の location
戻り値:
現在の命令の Location
例外:
InvalidStackFrameException - このスタックフレームが無効になった場合。フレームのスレッドが再開されると、スタックフレームは無効になる

thread

ThreadReference thread()
このフレームのメソッドが実行されているスレッドを返します。

戻り値:
フレームのスレッドをミラー化する ThreadReference
例外:
InvalidStackFrameException - このスタックフレームが無効になった場合。フレームのスレッドが再開されると、スタックフレームは無効になる

thisObject

ObjectReference thisObject()
現在のフレームの this の値を返します。this に対する ObjectReference は、非 native のインスタンスメソッドに対してだけ使用できます。

戻り値:
ObjectReference。フレームが native または static メソッドを表している場合は null
例外:
InvalidStackFrameException - このスタックフレームが無効になった場合。フレームのスレッドが再開されると、スタックフレームは無効になる

visibleVariables

List<LocalVariable> visibleVariables()
                                     throws AbsentInformationException
このフレームの位置からアクセスできるすべての LocalVariable のリストを返します。

可視性は、この StackFrame の現在の命令のコードインデックスによって決定されます。各変数には、アクセスできるバイトコードインデックスの範囲が設定されています。スタックフレームのメソッドと変数のメソッドが一致し、StackFrame のコードインデックスが変数のバイトコードの範囲内に存在する場合は、この変数にアクセスすることができます。

変数のバイトコードの範囲は、変数のスコープ以下ですが、次の特定の環境ではスコープを超えることもできます。

範囲を拡張すると、最近終了したスコープ内の変数を引き続き検査することができます。これは特に、ループインデックスの場合に便利です。範囲を拡張した結果、現在のフレーム位置が同じ名前の複数の局所変数の範囲に含まれている場合は、返されるリストでは、範囲の開始位置がもっとも大きい変数が選択されています。

戻り値:
現在アクセス可能な LocalVariable オブジェクトのリスト。可視変数がない場合は空のリスト。特に、native メソッド内のフレームは常に長さゼロのリストを返す
例外:
AbsentInformationException - このメソッドのローカル変数情報がない場合
InvalidStackFrameException - このスタックフレームが無効になった場合。フレームのスレッドが再開されると、スタックフレームは無効になる
NativeMethodException - 現在のメソッドが native の場合

visibleVariableByName

LocalVariable visibleVariableByName(String name)
                                    throws AbsentInformationException
LocalVariable のうち、指定された名前と一致し、現在のフレーム位置で可視なものを検索します。可視性についての詳細は、visibleVariables() を参照してください。

パラメータ:
name - 検索する変数名
戻り値:
一致する LocalVariable。指定された名前の可視変数がない場合は null。native メソッド内のフレームは常に null を返す
例外:
AbsentInformationException - このメソッドのローカル変数情報がない場合
InvalidStackFrameException - このスタックフレームが無効になった場合。フレームのスレッドが再開されると、スタックフレームは無効になる
NativeMethodException - 現在のメソッドが native の場合

getValue

Value getValue(LocalVariable variable)
このフレーム内の LocalVariableValue を取得します。各変数は、このフレームのメソッドに対して有効で、visibleVariables() に明記されている規則に基づく可視変数でなければなりません。

パラメータ:
variable - アクセスする LocalVariable
戻り値:
インスタンスのフィールドの Value
例外:
IllegalArgumentException - 変数がこのフレームのメソッドに対して無効な場合、または可視変数でない場合
InvalidStackFrameException - このスタックフレームが無効になった場合。フレームのスレッドが再開されると、スタックフレームは無効になる

getValues

Map<LocalVariable,Value> getValues(List<? extends LocalVariable> variables)
このフレーム内の複数の局所変数の値を返します。各変数は、このフレームのメソッドに対して有効で、visibleVariables() に明記されている規則に基づく可視変数でなければなりません。

パラメータ:
variables - アクセスする LocalVariable オブジェクトのリスト
戻り値:
LocalVariable をその Value に関連したマップ
例外:
IllegalArgumentException - このフレームのメソッドに対して無効な場合、または可視変数でない場合
InvalidStackFrameException - このスタックフレームが無効になった場合。フレームのスレッドが再開されると、スタックフレームは無効になる

setValue

void setValue(LocalVariable variable,
              Value value)
              throws InvalidTypeException,
                     ClassNotLoadedException
このフレーム内の LocalVariableValue を設定します。変数は、このフレームのメソッドに対して有効で、visibleVariables() に明記されている規則に基づく可視変数でなければなりません。

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

パラメータ:
variable - 要求された値を含むフィールド
value - 代入する新しい値
例外:
IllegalArgumentException - フィールドがこのオブジェクトのクラスとして有効でない場合
InvalidTypeException - 値の型が変数の型に一致しない場合
ClassNotLoadedException - 変数の型が、適切なクラスローダによってロードされていない場合
InvalidStackFrameException - このスタックフレームが無効になった場合。フレームのスレッドが再開されると、スタックフレームは無効になる
VMCannotBeModifiedException - 仮想マシンが読み取り専用の場合は、VirtualMachine.canBeModified() を参照

Java Debug Interface