JPDA の接続および呼び出し

JPDA では、デバッガアプリケーションは Java Debug Interface (JDI) インタフェースとコネクタ抽象を使用してターゲット VM との接続を確立します。デバッガアプリケーションによって使用されるコネクタは、トランスポートをカプセル化します。ターゲット VM では、デバッガとの通信に Java^TM Debug Wire Protocol をサポートするエージェントが使用されます。このエージェント (ターゲット VM に組み込むか、実行時ライブラリからロード可能) は、デバッガと通信するためにトランスポートをカプセル化します。

Sun では、TCP/IP に基づくソケットトランスポートと共用メモリトランスポートの 2 つのトランスポート実装を、リファレンス実装とともに出荷しています。仕様では、特定のトランスポートの実装を必要としません。この実装とともに提供されるトランスポートのほかにも、アーキテクチャに含まれるサービスプロバイダインタフェースを使用して、別のトランスポートを開発および配置することができます。

ソケットトランスポート

ソケットトランスポートは、dt_socket という一意の文字列で識別されます。この名前は、ターゲット VM を呼び出すときに、ソケットトランスポートを選択するために使用できます。デバッガアプリケーションでは、対応するコネクタによってソケットトランスポートがカプセル化されます。

クライアントがサーバに接続しているコンテキストでは、ソケットトランスポートアドレスの形式は、「<name>:<port>」になります。<name> はホスト名です。また、<port> は接続または待機しているソケットポート番号です。サーバがクライアントとの接続を待機しているコンテキストでは、アドレスはポート番号だけで構成されます (ホスト名は明示されない)。

共用メモリトランスポート

共用メモリトランスポートは、dt_shmem という一意の文字列で識別されます。この名前は、ターゲット VM を呼び出すときに、ソケットトランスポートを選択するために使用できます。デバッガアプリケーションでは、対応するコネクタによって共用メモリトランスポートがカプセル化されます。

共用メモリのトランスポートアドレスは、Microsoft Windows のファイルマッピングオブジェクトの名前として使用することができます。この名前の文字列には、バックスラッシュを除く任意の文字を含めることができます。

コネクタ

実装されるコネクタをユーザが選択および構成できるように、JDI クライアントアプリケーションを作成することもできますが、特定のコネクタに関する情報をデバッガに組み込んでおくと、ユーザが使いやすい構成になります。JPDA で提供されている JDB の実装例では、この方法が採用されています。

JDI リファレンス実装では、使用可能なトランスポートの種類および接続モード (起動、待機、および接続) に対応するいくつかのコネクタが提供されています。それらのコネクタについて、これから説明します。これらのコネクタのリストは、JDI メソッド VirtualMachineManager.allConnectors() によって返されます。また、各接続コネクタ、待機コネクタ、および起動コネクタは、対応する VirtualMachineManager メソッド attachingConnectors()、listeningConnectors()、および launchingConnectors() によって返されるリストに含まれます。

Sun コマンド行起動コネクタ

このコネクタは、「com.sun.jdi.CommandLineLaunch」という名前で一意に識別されます。

Raw コマンド行起動コネクタ

Sun コマンド行起動コネクタの引数
名前	必須	デフォルト値	説明
`home`	いいえ	現在の `java.home` のプロパティ値	ターゲット VM の呼び出しに使用される Java 2 Runtime Environment の場所
`options`	いいえ	""	VM を呼び出すときに使用するオプション。標準のデバッグオプションを含む
`main`	はい	""	デバッグするアプリケーションのメインクラスおよびコマンド行の引数
`suspend`	いいえ	「true」	メインクラスがロードされる直前にターゲット VM が中断される場合は true、そうでない場合は false
`quote`	はい	「\"」	コマンド行上で、空白で区切られたテキストを結合するときに使用する文字
`vmexec`	はい	「java」	VM 起動用ウィンドウの実行可能ファイル。デバッグ時には、javaw または java_g に変更できる (それらの起動用ウィンドウが使用可能な場合)

このコネクタは、「com.sun.jdi.RawCommandLineLaunch」という名前で一意に識別されます。

ソケット接続コネクタ

Raw コマンド行起動コネクタの引数
名前	必須	デフォルト値	説明
`command`	はい	""	デバッグするアプリケーションからターゲット VM を呼び出すときに使用するコマンド行全体
`address`	はい	""	新しく起動されたターゲット VM の接続を待機するトランスポートアドレス。この値は、通常は raw コマンドの引数として使用される。ただし、接続先のトランスポートアドレスを、ターゲット VM で独自に識別できる場合は必須ではない
`quote`	はい	「\"」	コマンド行上で、空白で区切られたテキストを結合するときに使用する文字

このコネクタは、「com.sun.jdi.SocketAttach」という名前で一意に識別されます。

共用メモリ接続コネクタ

ソケット接続コネクタの引数
名前	必須	デフォルト値	説明
`hostname`	いいえ	ローカルホスト名	接続先のホストマシン名
`port`	はい	""	接続先のホストマシン上のポート番号
`timeout`	いいえ	""	ターゲット VM への接続時に使用するタイムアウト (ミリ秒単位)

このコネクタは、「com.sun.jdi.SharedMemoryAttach」という名前で一意に識別されます。

ソケット待機コネクタ

このコネクタでは、複数のターゲット VM からの接続を受け入れることができます。

共用メモリ接続コネクタの引数
名前	必須	デフォルト値	説明
`name`	はい	""	ターゲット VM が待機中の共用メモリのトランスポートアドレス
`timeout`	いいえ	""	ターゲット VM に接続するときに使用するタイムアウト (ミリ秒単位)

このコネクタは、「com.sun.jdi.SocketListen」という名前で一意に識別されます。

共用メモリ待機コネクタ

このコネクタでは、複数のターゲット VM からの接続を受け入れることができます。

ソケット待機コネクタの引数
名前	必須	デフォルト値	説明
`port`	いいえ	一時的なポート番号 (TCP/IP スタックによって割り当てられるポート)	接続を待機するポート番号
`localAddress`	いいえ	ホストに割り当てられるすべてのアドレス	ホストに割り当てられる IP アドレス
`timeout`	いいえ	""	ターゲット VM の接続を待機する間に使用するタイムアウト (ミリ秒単位)

このコネクタは、「com.sun.jdi.SharedMemoryListen」という名前で一意に識別されます。

SA コア接続コネクタ

共用メモリ待機コネクタの引数
名前	必須	デフォルト値	説明
`name`	はい	""	ターゲット VM の接続を待機する共用メモリのトランスポートアドレス
`timeout`	いいえ	""	ターゲット VM の接続を待機する間に使用するタイムアウト (ミリ秒単位)

SA コア接続コネクタの引数
名前	必須	デフォルト値	説明
core	いいえ	「core」	デバッグするコアファイルのパス名
javaExecutable	はい	""	コアファイルを生成した Java 実行ファイルのパス名

SA PID 接続コネクタ

このコネクタは、プロセスをデバッグするときに、デバッガアプリケーションから使用できます。 Microsoft Windows プラットフォームおよび Linux Itanium プラットフォームでは使用できません。利用可能なすべてのデバッグ操作を実行できるとは限らないため、プロセスが破損する可能性があります。

このコネクタの attach() メソッドによって返される VirtualMachine オブジェクトは、読み取り専用です。つまり、次のメソッド、
vm.canBeModified()
は false を返し、この場合、JDI クライアントは VMCannotBeModifiedException をスローするように定義されている JDI メソッドを呼び出しません。

デバッグするプロセスが、デバッグモードで (つまり、-agentlib:jdwp または -Xrunjdwp を使用して) 開始されている必要はありません。プロセスがハングアップしても問題ありません。デバッガとデバッグ対象のワードサイズ (つまり 32 ビットまたは 64 ビット) およびバージョン (5.0、5.1 など) は、同じでなければなりません。プロセスは、このコネクタの接続時に中断され、分離時に再開されます。1 つのプロセスに複数の SAPIDAttachingConnector を同時に接続することはできません。

このコネクタは、「sun.jvm.hotspot.jdi.SAPIDAttachingConnector」という名前で一意に識別されます。

SA PID 接続コネクタの引数

名前	必須	デフォルト値	説明
`pid`	はい	""	デバッグするプロセスのプロセス ID

SA デバッグサーバ接続コネクタ

このコネクタは、デバッガが実行されているマシン以外のマシン上でプロセスまたはコアファイルをデバッグするときに、デバッガアプリケーションから使用できます。Microsoft Windows プラットフォームおよび Linux Itanium プラットフォームでは使用できません。利用可能なすべてのデバッグ操作を実行できるとは限らないため、リモートプロセスまたはコアファイルが破損する可能性があります。

このコネクタの attach() メソッドによって返される VirtualMachine オブジェクトは、読み取り専用です。つまり、次のメソッド、
vm.canBeModified()
は false を返し、この場合、JDI クライアントは VMCannotBeModifiedException をスローするように定義されている JDI メソッドを呼び出しません。

このコネクタは、RMI を使用してリモートマシンを実行する「デバッグサーバ」と通信します。
このコネクタの attach() メソッドを呼び出す前に、デバッグサーバをリモートマシンで起動し、
デバッグするプロセスまたはコアファイルをデバッグサーバに指定する必要があります。次の操作をリモートマシンで実行する必要があります。

クラスパスの sa-jdi.jar で RMI レジストリを起動する

${JAVA_HOME}/bin/rmiregistry \
-J-Xbootclasspath/p:${JAVA_HOME}/lib/sa-jdi.jar

デバッグするプロセスまたはコアファイルを指定して、リモートマシンで「デバッグサーバ」を起動する

         ${JAVA_HOME}/bin/java \
             -classpath ${JAVA_HOME}/lib/sa-jdi.jar \
             sun.jvm.hotspot.jdi.SADebugServer \
             <pid> \
    [uniqueID]

     または

         ${JAVA_HOME}/bin/java \
               -classpath ${JAVA_HOME}/lib/sa-jdi.jar \
               sun.jvm.hotspot.jdi.SADebugServer \
               <pathname to the java executable that produced the core file> \
               <pathname of the corefile to debug> \
            [uniqueID]

上記の 2 つの手順の代わりに jsadebugd コマンドを使用し、リモートマシンで RMI レジストリとデバッグサーバをを起動する方法もあります。

「uniqueID」はオプションの文字列です。同じマシンで複数のデバッグサーバを同時に実行する場合は、各サーバに異なる「uniqueID」文字列を指定する必要があります。

上の例の JAVA_HOME には、デバッグ対象で使用されるバージョンと同じビットサイズ (つまり 32 ビットまたは 64 ビット) および同じバージョン (5.0、5.1 など) の Java インストールのパス名が含まれていなければなりません。ただし、デバッガは同じビットサイズおよびバージョンである必要はありません。

デバッグするプロセスが、デバッグモードで (つまり、-agentlib:jdwp または -Xrunjdwp を使用して) 開始されている必要はありません。というのも、プロセスがハングアップしても問題はないからです。プロセスは、デバッグサーバの接続時に中断されます。プロセスに接続されているデバッグサーバを (^C またはほかの方法で) 終了すると、デバッグ対象プロセスは再開されます。コアファイルに複数のデバッグサーバを接続することはできますが、プロセスに接続できるデバッグサーバは 1 つだけです。
このコネクタでは、同じデバッグサーバに複数のデバッグセッションを接続できます。
このコネクタは、「sun.jvm.hotspot.jdi.SADebugServerAttachingConnector」という名前で一意に識別されます。

SA DebugServer 接続コネクタの引数

名前	必須	デフォルト値	説明
`debugServerName`	はい	""	デバッグサーバが実行されているマシンの IP アドレスまたは名前。マシンに複数のデバッグサーバが含まれている場合、この名前は次の形式を使用する必要がある uniqueID@IPAddress または uniqueID@hostname 「uniqueID」は対応するデバッグサーバの起動に使用される文字列

Sun VM の呼び出しオプション

Sun の VM 実装には、デバッグ用の JDWP エージェントをロードするコマンド行オプションが必要です。5.0 以降では、JDWP エージェントのロードおよびオプションの指定に -agentlib:jdwp オプションが使用されます。5.0 より前のリリースでは、-Xdebug および -Xrunjdwp オプションが使用されます。5.0 の実装では、-Xdebug および -Xrunjdwp オプションもサポートされますが、5.0 の JDWP エージェントは、VM に対して以前の JVMDI インタフェースではなく JVMTI インタフェースを使用するため、新しい -agentlib:jdwp オプションの使用をお勧めします。

デバッガアプリケーションで JDI の Sun コマンド行起動コネクタを使用する場合、5.0 より前のターゲット VM との接続にこのコネクタが使用される可能性があるため、-Xdebug および -Xrunjdwp オプションがコネクタで使用されます。

ターゲット VM が 5.0 以降の場合、-agentlib:jdwp オプションは次のように指定します。

5.0 より前のリリースの場合、-Xdebug および -Xrunjdwp オプションが使用されます。

-agentlib:jdwp および -Xrunjdwp サブオプション

例

-Xrunjdwp のサブオプション
名前	必須	デフォルト値	説明
`help`	いいえ	適用なし	簡単なヘルプメッセージを表示して VM を終了する
`transport`	はい	なし	デバッガアプリケーションに接続するときに使用するトランスポートの名前
`server`	いいえ	「n」	「y」の場合は、デバッガアプリケーションの接続を待機する。そうでない場合は、指定されたアドレスのデバッガアプリケーションに接続する「y」が指定されているときにアドレスが指定されていない場合は、デバッガアプリケーションを待機するトランスポートアドレスを選択し、標準出力ストリームにそのアドレスを出力する
`address`	`server=n` の場合は、必須。 `server=y` の場合は、オプション	""	接続用のトランスポートアドレス。server=n の場合は、このアドレスのデバッガアプリケーションに対して接続する。server=y の場合は、このアドレスで接続を待機する
`timeout`	いいえ	""	server=y の場合は、デバッガからの接続を待機するときに使用するタイムアウト (ミリ秒単位)を指定する。server=n の場合は、デバッガへの接続時に使用するタイムアウト (ミリ秒単位)を指定する。一部のトランスポート実装では、タイムアウトオプションが無視される場合がある
`launch`	いいえ	なし	JDWP の初期化が完了したときに、この文字列に指定されたプロセスを起動する。このオプションは、「Just-In-Time デバッグ」を行うときに、`onthrow` または `onuncaught`、あるいはその両方のオプションと組み合わせて使用する。「Just-In-Time デバッグ」では、この VM で特定のイベントが発生したときにデバッガプロセスが起動する起動されるプロセスは、自身のウィンドウでは起動されないことに注意。ほとんどの場合、起動されるプロセスは小さなアプリケーションで、起動後にデバッガアプリケーションが自身のウィンドウで起動されるこの引数に指定した文字列には、空白で区切られた次の文字列が追加される。これらの文字列は、起動されたデバッガがこの VM との接続を確立するために使われる。こうして生成された文字列が実行される `transport` サブオプションの値 `address` サブオプションの値。指定されない場合は、生成されたアドレス
`onthrow`	いいえ	なし	特定のクラスの例外がこの VM にスローされるまで、JDWP ライブラリの初期化を遅延する。例外クラス名は、パッケージで修飾されていなければならない。JDWP が初期化されたときに接続が確立されるため、この例外がスローされるまで接続は確立されない
`onuncaught`	いいえ	「n」	「y」の場合は、uncaught 例外がこの VM にスローされるまで、JDWP ライブラリの初期化を遅延する。JDWP が初期化されたときに接続が確立されるため、この例外がスローされるまで接続は確立されない。uncaught 例外の定義については、JDI 仕様の com.sun.jdi.ExceptionEvent を参照
`suspend`	いいえ	「y」	「y」の場合、VMStartEvent は中断ポリシーが SUSPEND_ALL になる。「n」の場合、VMStartEvent の中断ポリシーは SUSPEND_NONE になる

Plug-in アプレットのデバッグ

JDI の起動コネクタは、Plug-in アプレットのデバッグには使用できません。

JDB との接続

JDB では、-attach オプションを指定すると、リファレンス実装の接続コネクタ (Microsoft Windows 上では共用メモリ、Solaris および Linux プラットフォーム上ではソケット) にアクセスすることができます。-listen オプションを指定すると、リファレンス実装の待機コネクタ (Microsoft Windows 上では共用メモリ、Solaris および Linux プラットフォーム上ではソケット) にアクセスすることができます。コマンド行にクラス名と引数を直接指定すると、Sun コマンド行起動コネクタにアクセスすることができます。

上のように入力すると、ソケット接続コネクタを使用して簡単にターゲット VM に接続できます (Solaris オペレーティング環境の場合)。

上のように入力すると、Sun コマンド行起動コネクタを使用して簡単にターゲット VM を起動できます。

また、JDB には、-connect オプションも提供されています。コネクタ名を指定し、さらに引数として名前と値の任意の組み合わせを指定することによって、任意のコネクタを使用することもできます。たとえば、上記の 2 つのコマンド行は、次のコマンド行と同じことです。

jdb -connect com.sun.jdi.SocketAttach:hostname=myhost,port=8000
jdb -connect "com.sun.jdi.CommandLineLaunch:main=Hello 1 2 3"

これらのコマンド行は、最初の例よりも複雑ですが、-connect オプションを指定すれば任意のコネクタを使用できます。これらの操作から、JDI デバッガでは、任意のコネクタを使用できることがわかります。また、よく使われるコネクタを使用するための簡単なインタフェースも提供されています。

サービスプロバイダインタフェース

JPDA に含まれているサービスプロバイダインタフェースを使うと、コネクタやトランスポートの実装を開発および配置できます。これらのサービスプロバイダインタフェースにより、デバッガやほかのツールベンダーで新しいコネクタ実装を開発し、Sun が提供するソケットおよび共用メモリトランスポートを超える別のトランスポート機構を提供することができます。JDI のサービスプロバイダインタフェースは、com.sun.jdi.connect.spi パッケージで指定されます。

JDI のサービスプロバイダインタフェースに加え、Sun の実装には Java ^TMDebug Wire Protocol Transport Interface というトランスポートライブラリインタフェースも含まれています。トランスポートライブラリは、ターゲット VM の JDWP エージェントによってロードされ、デバッガとの接続の確立、およびデバッガと VM 間の JDWP パケットのトランスポートに使用されます。

接続および呼び出しの詳細

目次

トランスポート