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

public interface VirtualMachineManager

public interface com.sun.jdi.VirtualMachineManager ターゲット仮想マシンへの接続を管理するマネージャです。VirtualMachineManager を使用すると、1 つのアプリケーションから複数のターゲット VM をデバッグすることができます。ただし、この逆はサポートされていません。つまり、ターゲット VM は、複数のデバッガアプリケーションからデバッグすることはできません。このインタフェースには、リモートターゲット VM への接続を管理するメソッド、および使用可能なターゲット VM の VirtualMachine ミラーを取得するメソッドが組み込まれています。

接続の確立に使用するオブジェクトは、いくつかの Connector オブジェクトから選択できます。各コネクタには、デバッガをターゲット VM に接続する方法がカプセル化されています。

VirtualMachineManager では、デバッガを仮想マシンに接続するための複数の方法がサポートされています。次の表に、4 つの例を示します。これらの例では、Sun の実装で採用されていたコマンド行構文を使用します。Connector の実装を使用する場合は、これらの例とは異なる操作が必要になります。

シナリオ	説明
デバッガからターゲット VM を起動する (もっとも簡単で一般的な方法)	デフォルトのコネクタの LaunchingConnector.launch(java.util.Map) メソッドを呼び出す。デフォルトのコネクタは、defaultConnector() を使用して取得できる。ターゲット VM が起動し、その VM とデバッガ間の接続が確立される。VirtualMachine ミラーが返される より詳細に制御することも可能 launchingConnectors() によって返されるリストから、トランスポートの種類など、必要な特性に応じてコネクタを選択する 選択したコネクタの LaunchingConnector.launch(java.util.Map) メソッドを呼び出す。ターゲット VM が起動し、その VM とデバッガ間の接続が確立される。VirtualMachine ミラーが返される
デバッガから稼動中の VM に接続する	ターゲット VM は、-agentlib:jdwp=transport=xxx,server=y オプションを使用して起動される ターゲット VM によって、接続を待機するトランスポート固有のアドレスの生成および出力が行われる デバッガが起動する。トランスポートと「xxx」という名前を照合しながら、attachingConnectors() によって返されるリストからコネクタを選択する Connector.defaultArguments() によって取得したデフォルトのコネクタのパラメータがユーザに提供される。ユーザは、ターゲット VM によって生成されたトランスポート固有のアドレスを入力できる 選択したコネクタの AttachingConnector.attach(java.util.Map) メソッドを呼び出し、ターゲット VM に接続する。VirtualMachine ミラーが返される
ターゲット VM からすでに稼動中のデバッガに接続する	起動時に、1 つまたは複数のトランスポートに対して、listeningConnectors() によって返されるリストから 1 つまたは複数のコネクタを選択する 選択した各コネクタに対し、ListeningConnector.startListening(java.util.Map) メソッドを呼び出す。各呼び出しに対してトランスポート固有のアドレス文字列が生成され、返される。エンドユーザに、トランスポート名と対応するアドレス文字列が提供される 選択した各コネクタに対して ListeningConnector.accept(java.util.Map) を呼び出し、ターゲット VM の接続を待機する エンドユーザが -agentlib:jdwp=transport=xxx,address=yyy オプションを使用して、ターゲット VM を起動する。「xxx」は、デバッガが選択したコネクタ。「yyy」は、ListeningConnector.accept(java.util.Map) によって、そのトランスポートに対して生成されたアドレス ListeningConnector.accept(java.util.Map) を呼び出し、VirtualMachine ミラーが返される
ターゲット VM からデバッガを起動する (「Just-In-Time」デバッグと呼ばれる こともある)	ターゲット VM が -agentlib:jdwp=launch=cmdline,onuncaught=y,transport=xxx,server=y オプションを使用して起動される ターゲット VM 内にキャッチされない例外がスローされる。ターゲット VM によって、接続を待機するトランスポート固有のアドレスが生成される 次の項目で構成されるコマンド行を使用して、ターゲット VM からデバッガを起動する。各項目は、空白で区切らなければならない launch= 値 transport= 値 VM がデバッガの接続を待機する、トランスポート固有の生成されたアドレス 起動時に、トランスポートと「xxx」という名前を照合しながら、attachingConnectors() によって返されるリストからコネクタを選択する (obtained through Connector.defaultArguments()) によって取得したデフォルトのコネクタのパラメータを変更して、VM が待機するトランスポート固有のアドレスを指定する。オプションで、ほかのコネクタの引数もユーザに提供できる 選択したコネクタの AttachingConnector.attach(java.util.Map) メソッドを呼び出し、ターゲット VM に接続する。VirtualMachine ミラーが返される

Connectors は起動時に生成されます。つまり、Connectors は Bootstrap.virtualMachineManager() がはじめて呼び出されたときに生成されます。起動時に生成されたすべての Connectors のリストは、allConnectors を呼び出して VirtualMachineManager から取得できます。

Connectors は、プラットフォームにインストールされている場合、起動時に生成されます。加えて、Connectors は VirtualMachineManager により自動的に生成され、プラットフォームにインストールされた TransportService の実装にカプセル化されます。ここでは、Connectors を生成する 2 つの機構について説明します。

Connector が Connector 型の定義しているクラスローダから可視である jar ファイルにインストールされ、その jar ファイルが META-INF/services リソースディレクトリにある com.sun.jdi.connect.Connector という名前のプロバイダ構成ファイルを含み、そのプロバイダ構成ファイルに Connector 実装の完全修飾クラス名のリストが含まれる場合、Connector はプラットフォームにインストールされます。Connector は、Connector インタフェースを実装するクラスです。より適切には、クラスは特定の Connector 型、つまり AttachingConnector、ListeningConnector、または LaunchingConnector の 1 つを実装します。プロバイダ構成ファイルの形式は、行ごとに 1 つの完全修飾クラス名が示された形式です。各クラスを囲む空白文字とタブ文字ばかりでなく空白行も無視されます。コメント文字は '#' (0x23) です。各行では、最初のコメント文字以降の文字はすべて無視されます。このファイルは、UTF-8 方式で符号化する必要があります。

起動時、VirtualMachineManager はプロバイダ構成ファイルに示されている各クラスをロードおよびインスタンス化しようとします (引数なしのコンストラクタを使用)。Connector のロードおよび生成時にスローされた例外は、キャッチされ、無視されます。つまり、起動プロセスはエラーにかかわらず続行されます。

プラットフォームにインストールされた Connectors に加え、VirtualMachineManager はプラットフォームにインストールされた TransportService の実装をカプセル化する Connectors も生成します。TransportService が TransportService 型の定義クラスローダから可視である jar ファイルにインストールされ、その jar ファイルが META-INF/services リソースディレクトリにある com.sun.jdi.connect.spi.TransportService という名前のプロバイダ構成ファイルを含み、そのプロバイダ構成ファイルに TransportService の実装の 完全修飾クラス名のリストが含まれる場合、TransportService はプラットフォームにインストールされます。TransportService は、 TransportService の具象サブクラスです。各クラスは TransportService インタフェースを実装するクラスの完全修飾クラス名でなければならない点を除き、プロバイダ構成ファイルの形式は Connectors のプロバイダ構成ファイルと同じです。

プラットフォームにインストールされた TransportService ごとに、VirtualMachineManager は対応する AttachingConnector と ListeningConnector を生成します。これらの Connectors は、TransportService をさらにその次にカプセル化する Transport をカプセル化するために生成されます。AttachingConnector は、Attach 文字列を使って連結されたトラスポートサービスの名前に基づいて名前が付けられます。たとえば、トランスポートサービス name() メソッドが telepathic を返すと、AttachingConnector には telepathicAttach という名前が付けられます。同様に、ListeningConnector には、トランスポートサービスの名前に Listen 文字列がタグ付けされた名前が付けられます。AttachingConnector と ListeningConnector の両方の description() メソッドは、配下のトランスポートサービスの description() に委譲されます。AttachingConnector と ListeningConnector の両方は、2 つの Connector 引数 を持ちます。address という名前の StringArgument は、接続先アドレスまたは待機するアドレスを指定するコネクタ引数です。timeout という名前の IntegerArgument は、接続時または受け入れ時のタイムアウトを指定するコネクタ引数です。タイムアウトコネクタは、トランスポートサービスが接続タイムアウトまたは受け入れタイムアウトをサポートしているかどうかに応じて無視できます。

仮想マシンマネージャがコネクタを生成できない場合、仮想マシンマネージャの初期化は失敗します。つまり、Bootstrap.virtualMachineManager() はエラーをスローします。

導入されたバージョン:

1.3

メソッドの概要

List<Connector>	allConnectors() 既知のすべての Connector オブジェクトのリストを返します。
List<AttachingConnector>	attachingConnectors() 既知の AttachingConnector オブジェクトのリストを返します。
List<VirtualMachine>	connectedVirtualMachines() デバッガに接続されるすべてのターゲット VM のリストを作成します。
VirtualMachine	createVirtualMachine(Connection connection) 新しい仮想マシンを生成します。
VirtualMachine	createVirtualMachine(Connection connection, Process process) ターゲット VM の仮想マシンミラーを生成します。
LaunchingConnector	defaultConnector() デフォルトのコネクタを識別します。
List<LaunchingConnector>	launchingConnectors() 既知の LaunchingConnector オブジェクトのリストを返します。
List<ListeningConnector>	listeningConnectors() 既知の AttachingConnector オブジェクトのリストを返します。
int	majorInterfaceVersion() JDI インタフェースのメジャーバージョン番号を返します。
int	minorInterfaceVersion() JDI インタフェースのマイナーバージョン番号を返します。

メソッドの詳細

defaultConnector

LaunchingConnector defaultConnector()

デフォルトのコネクタを識別します。このコネクタは、特定の特性のコネクタを選択する必要がない場合に、起動コネクタとして使用します。

戻り値:

デフォルトの LaunchingConnector

launchingConnectors

List<LaunchingConnector> launchingConnectors()

既知の LaunchingConnector オブジェクトのリストを返します。返されたオブジェクトから任意のオブジェクトを選択して、新しいターゲット VM を起動することができます。ただちに、VirtualMachine ミラーが作成されます。 起動コネクタにより起動されたターゲット VM は、VMStartEvent が受け入れられるまで安定であることを保証されていません。

戻り値:

LaunchingConnector オブジェクトのリスト

attachingConnectors

List<AttachingConnector> attachingConnectors()

既知の AttachingConnector オブジェクトのリストを返します。返されたオブジェクトから任意のオブジェクトを選択して、既存のターゲット VM に接続することができます。VirtualMachine ミラーが作成されます。

戻り値:

AttachingConnector オブジェクトのリスト

listeningConnectors

List<ListeningConnector> listeningConnectors()

既知の AttachingConnector オブジェクトのリストを返します。返されたオブジェクトから任意のオブジェクトを選択して、ターゲット VM によって開始された接続を待機できます。VirtualMachine ミラーが作成されます。

戻り値:

ListeningConnector オブジェクトのリスト

allConnectors

List<Connector> allConnectors()

既知のすべての Connector オブジェクトのリストを返します。

戻り値:

Connector オブジェクトのリスト

connectedVirtualMachines

List<VirtualMachine> connectedVirtualMachines()

デバッガに接続されるすべてのターゲット VM のリストを作成します。リストには、接続を開始したすべてのターゲット VM と、このマネージャが接続を開始した接続先のすべてのターゲット VM の VirtualMachine インスタンスが含まれます。ターゲット VM は、仮想マシンの接続が解除されるとこのリストから削除されます。リストから仮想マシンが削除されると、VMDisconnectEvent はイベントキューに配置されます。

戻り値:

ターゲット VM をミラー化する VirtualMachine オブジェクトのリスト

majorInterfaceVersion

int majorInterfaceVersion()

JDI インタフェースのメジャーバージョン番号を返します。バージョン情報についての詳細は、VirtualMachine.version() のターゲット VM バージョンと情報、および VirtualMachine.description() を参照してください。

戻り値:

メジャーバージョン番号を表す整数

minorInterfaceVersion

int minorInterfaceVersion()

JDI インタフェースのマイナーバージョン番号を返します。バージョン情報についての詳細は、VirtualMachine.version() のターゲット VM バージョンと情報、および VirtualMachine.description() を参照してください。

戻り値:

マイナーバージョン番号を表す整数

createVirtualMachine

VirtualMachine createVirtualMachine(Connection connection,
                                    Process process)
                                    throws IOException

ターゲット VM の仮想マシンミラーを生成します。

Connection がすでに存在するターゲット VM マシンの仮想マシンミラーを生成します。Connection は、Connector が接続を確立し、ターゲット VM と正常にハンドシェークしたときに生成されます。次に、Connector はこのメソッドを使って、ターゲット VM の複合状態を表すために仮想マシンミラーを生成します。

process 引数は、ターゲット VM の Process オブジェクトを指定します。この引数には null を指定することもできます。ターゲット VM が LaunchingConnector により起動される場合、process 引数を指定する必要があります。そうでない場合は、生成された仮想マシンで VirtualMachine.process() を呼び出すと null が返されます。

ターゲット VM との接続が確立されたとき、Connectors が仮想マシンミラーを生成できるようにするためにこのメソッドは存在します。新しい Connector 実装を構築している開発者だけがこのメソッドを直接使用する必要があります。

パラメータ:

connection - ターゲット VM への開かれた接続

process - 起動された場合はターゲット VM の Process オブジェクト、起動されなかった場合は null

戻り値:

ターゲット VM を表す新しい仮想マシン

例外:

IOException - I/O エラーが発生した場合

IllegalStateException - 接続が開かれていない場合

導入されたバージョン:

1.5

関連項目:

Connection.isOpen(), VirtualMachine.process()

createVirtualMachine

VirtualMachine createVirtualMachine(Connection connection)
                                    throws IOException

新しい仮想マシンを生成します。

この簡易メソッドは、createVirtualMachine(Connection, Process) メソッドを呼び出し、process 引数に null を指定した場合と同様に機能します。

ターゲット VM との接続が確立されたとき、Connectors が仮想マシンミラーを生成できるようにするためにこのメソッドは存在します。新しい Connector 実装を構築している開発者だけがこのメソッドを直接使用する必要があります。

戻り値:

新しい仮想マシン

例外:

IOException - I/O エラーが発生した場合

IllegalStateException - 接続が開かれていない場合

導入されたバージョン:

1.5