モジュール jdk.jdi
パッケージ com.sun.jdi

インタフェースVirtualMachineManager

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

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

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

デバッガを仮想マシンに接続するための4つのシナリオ"
シナリオ 説明
デバッガからターゲットVMを起動する(もっとも簡単で一般的な方法) デバッガが、defaultConnector()で取得したデフォルトのコネクタのLaunchingConnector.launch(java.util.Map)メソッドを呼び出します。 ターゲット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()によって返されたリストからコネクタを選択します。
  • Connector.defaultArguments()を使って取得したデフォルトのコネクタのパラメータを変更して、VMが待機するトランスポート固有のアドレスを指定します。 オプションで、ほかのコネクタの引数もユーザーに提供できます。
  • デバッガは選択したコネクタのAttachingConnector.attach(java.util.Map)メソッドを呼び出し、ターゲットVMに接続します。 VirtualMachineミラーが返されます。

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

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

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

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

VirtualMachineManagerは、プラットフォームにインストールされたConnectorに加え、プラットフォームにインストールされた任意のTransportService実装をカプセル化するConnectorも生成します。 TransportServiceは、TransportServiceタイプの定義クラス・ローダーに表示されるjarファイルにインストールされ、jarファイルにはリソース・ディレクトリMETA-INF/servicesにTransportServiceという名前のプロバイダ構成ファイルが含まれ、プロバイダ構成ファイル・リストTransportService実装の完全修飾されたクラス名。 TransportServiceは、TransportServiceの具象サブクラスです。 各クラスはTransportServiceインタフェースを実装するクラスの完全指定クラス名でなければならない点を除き、プロバイダ構成ファイルの形式はConnectorsのプロバイダ構成ファイルと同じです。

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

コネクタを作成できない場合、仮想マシン・マネージャの初期化は失敗し、Bootstrap.virtualMachineManager()によってエラーがスローされます。

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

  • メソッドの詳細

    • defaultConnector

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

    • launchingConnectors

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

    • attachingConnectors

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

    • listeningConnectors

      List<ListeningConnector> listeningConnectors()
      既知のListeningConnectorオブジェクトのリストを返します。 返されたオブジェクトから任意のオブジェクトを選択して、ターゲットVMによって開始された接続を待機し、このターゲットVMのVirtualMachineミラーを作成することができます。
      戻り値:
      ListeningConnectorオブジェクトのリスト。

    • allConnectors

      List<Connector> allConnectors()
      既知のすべてのConnectorオブジェクトのリストを返します。
      戻り値:
      Connectorオブジェクトのリスト。

    • connectedVirtualMachines

      List<VirtualMachine> connectedVirtualMachines()
      デバッガに接続されるすべてのターゲットVMのリストを作成します。 リストには、接続を開始したすべてのターゲットVMと、このマネージャが接続を開始した接続先のすべてのターゲットVMのVirtualMachineインスタンスが含まれます。 ターゲットVMは、VMの接続が切断されるまで、このリストから削除されません。 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 - 入出力エラーが発生した場合
      IllegalStateException - 接続が開いていない場合
      導入されたバージョン:
      1.5
      関連項目:
      Connection.isOpen(), VirtualMachine.process()

    • createVirtualMachine

      VirtualMachine createVirtualMachine​(Connection connection) throws IOException
      新しい仮想マシンを作成します。

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

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

      戻り値:
      新しい仮想マシン
      例外:
      IOException - 入出力エラーが発生した場合
      IllegalStateException - 接続が開いていない場合
      導入されたバージョン:
      1.5