-
public interface VirtualMachineManager
ターゲット仮想マシンへの接続を管理するマネージャです。 VirtualMachineManagerを使用すると、1つのアプリケーションから複数のターゲットVMをデバッグすることができます。 ただし、この逆はサポートされていません。つまり、ターゲットVMは、複数のデバッガ・アプリケーションからデバッグすることはできません。 このインタフェースには、リモート・ターゲットVMへの接続を管理するメソッドと、使用可能なターゲットVMのVirtualMachine
ミラーを取得するメソッドが組み込まれています。接続の確立のためには、いくつかの
Connector
オブジェクトから1つを選んで使用します。 各コネクタには、デバッガをターゲットVMに接続する方法がカプセル化されています。VirtualMachineManagerでは、デバッガを仮想マシンに接続するための複数の方法がサポートされています。 次の表に、4つの例を示します。 これらの例では、Sunの実装で採用されていたコマンド行構文を使用します。 一部の
Connector
実装では、次に示す例と若干異なった操作が必要になることがあります。シナリオ 説明 デバッガからターゲット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が
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のロードおよび生成時にスローされた例外は、キャッチされ、無視されます。 つまり、起動プロセスはエラーにかかわらず続行されます。
VirtualMachineManagerは、プラットフォームにインストールされたConnectorに加え、プラットフォームにインストールされた任意の
TransportService
実装をカプセル化するConnectorも生成します。 TransportServiceは、TransportService
型の定義クラス・ローダーに表示されるjarファイルにインストールされ、jarファイルにはリソース・ディレクトリMETA-INF/services
にcom.sun.jdi.connect.spi.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つのConnectorArguments
を持ちます。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()
既知のListeningConnector
オブジェクトのリストを返します。int
majorInterfaceVersion()
JDIインタフェースのメジャー・バージョン番号を返します。int
minorInterfaceVersion()
JDIインタフェースのマイナー・バージョン番号を返します。
-
-
-
メソッドの詳細
-
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
-
-