public abstract class VirtualMachine extends Object
VirtualMachine
は、このJava仮想マシンの接続先のJava仮想マシンを表します。 接続先のJava仮想マシンは、ターゲット仮想マシンまたはターゲットVMとも呼ばれます。 アプリケーションは、通常は管理コンソールやプロファイラのようなツールであり、VirtualMachineを使用してターゲットVM内にエージェントをロードします。 たとえば、Java言語で作成されたプロファイル・ツールで、実行中のアプリケーションに接続し、そのプロファイラ・エージェントをロードして実行中のアプリケーションのプロファイルを作成することもできます。
VirtualMachineを取得するには、ターゲット仮想マシンを識別する識別子を付けてattach
メソッドを呼び出します。 識別子は実装によって異なりますが、通常、各Java仮想マシンがそれぞれ独自のオペレーティング・システム・プロセスで実行される環境ではプロセス識別子(pid)になります。 別の方法として、VirtualMachine
インスタンスは、list
メソッドによって返される仮想マシン記述子のリストから取得されるVirtualMachineDescriptor
で、attach
メソッドを呼び出すことでも取得されます。 仮想マシンへの参照を取得すると、loadAgent
、loadAgentLibrary
、およびloadAgentPath
の各メソッドを使用して、ターゲット仮想マシン内にエージェントをロードします。 loadAgent
メソッドは、Java言語で作成されJAR file
に配置されているエージェントをロードするのに使用します。 (これらのエージェントのロードおよび起動方法の詳細は、java.lang.instrument
を参照してください)。 loadAgentLibrary
およびloadAgentPath
メソッドは、ダイナミック・ライブラリに配置されるか、または静的にVMにリンクされ、JVM Tools Interfaceを利用するエージェントのロードに使用します。
エージェントのロードのほか、VirtualMachineはターゲットVM内のsystem properties
への読取りアクセスも提供します。 これは、ターゲットVM内にロードされるエージェントへのパスを構築するために、java.home
、os.name
、os.arch
などのプロパティを使用する環境で有用です。
次にVirtualMachineの使用方法の例を示します。
// attach to target VM VirtualMachine vm = VirtualMachine.attach("2177"); // start management agent Properties props = new Properties(); props.put("com.sun.management.jmxremote.port", "5000"); vm.startManagementAgent(props); // detach vm.detach();
この例では、プロセス識別子2177
で識別されるJava仮想マシンに接続します。 次に、入力した引数を使用してターゲット・プロセスでJMX管理エージェントが起動されます。 最後にクライアントがターゲットVMから切り離されます。
VirtualMachineは、複数の並行スレッドで安全に使用できます。
- 導入されたバージョン:
- 1.6
-
コンストラクタのサマリー
コンストラクタ 修飾子 コンストラクタ 説明 protected
VirtualMachine(AttachProvider provider, String id)
このクラスの新しいインスタンスを初期化します。 -
メソッドのサマリー
修飾子と型 メソッド 説明 static VirtualMachine
attach(VirtualMachineDescriptor vmd)
Java仮想マシンに接続します。static VirtualMachine
attach(String id)
Java仮想マシンに接続します。abstract void
detach()
仮想マシンから切り離します。boolean
equals(Object ob)
このVirtualMachineが別のオブジェクトと等しいかどうかを判定します。abstract Properties
getAgentProperties()
ターゲット仮想マシン内の現在のエージェント・プロパティを返します。abstract Properties
getSystemProperties()
ターゲット仮想マシン内の現在のシステム・プロパティを返します。int
hashCode()
このVirtualMachineのハッシュ・コード値を返します。String
id()
このJava仮想マシンの識別子を返します。static List<VirtualMachineDescriptor>
list()
Java仮想マシンのリストを返します。void
loadAgent(String agent)
エージェントをロードします。abstract void
loadAgent(String agent, String options)
エージェントをロードします。void
loadAgentLibrary(String agentLibrary)
エージェント・ライブラリをロードします。abstract void
loadAgentLibrary(String agentLibrary, String options)
エージェント・ライブラリをロードします。void
loadAgentPath(String agentPath)
フル・パス名を使用して、ネーティブ・エージェント・ライブラリをロードします。abstract void
loadAgentPath(String agentPath, String options)
フル・パス名を使用して、ネーティブ・エージェント・ライブラリをロードします。AttachProvider
provider()
この仮想マシンの作成元プロバイダを返します。abstract String
startLocalManagementAgent()
ターゲット仮想マシンでローカルJMX管理エージェントを起動します。abstract void
startManagementAgent(Properties agentProperties)
ターゲット仮想マシンでJMX管理エージェントを起動します。String
toString()
VirtualMachine
の文字列表記を返します。
-
コンストラクタの詳細
-
VirtualMachine
protected VirtualMachine(AttachProvider provider, String id)このクラスの新しいインスタンスを初期化します。- パラメータ:
provider
- このクラスを作成する接続プロバイダ。id
- Java仮想マシンを識別する抽象識別子。- 例外:
NullPointerException
-provider
またはid
がnull
の場合。
-
-
メソッドの詳細
-
list
public static List<VirtualMachineDescriptor> list()Java仮想マシンのリストを返します。このメソッドは、Java
VirtualMachineDescriptor
要素のリストを返します。 このリストは仮想マシン記述子リストの集合で、インストールされているすべてのattach providers
のlistVirtualMachines
メソッドを呼び出すことで取得されます。 プロバイダで認識されているJava仮想マシンがない場合は、空のリストが返されます。- 戻り値:
- 仮想マシン記述子のリスト。
-
attach
public static VirtualMachine attach(String id) throws AttachNotSupportedException, IOExceptionJava仮想マシンに接続します。このメソッドは、
AttachProvider.providers()
メソッドを呼び出すことで、接続プロバイダのリストを取得します。 次に、リストに対して繰返し処理を行い、各プロバイダのattachVirtualMachine
メソッドを順番に呼び出します。 プロバイダが正常に接続すると、繰返し処理は終了し、正常に接続されたプロバイダによって作成されたVirtualMachineがこのメソッドによって返されます。 すべてのプロバイダのattachVirtualMachine
メソッドがAttachNotSupportedException
をスローすると、このメソッドもAttachNotSupportedException
をスローします。 つまり、AttachNotSupportedException
は、このメソッドに提供された識別子が無効な場合、存在しないJava仮想マシンに対する識別子である場合、またはそれに接続できるプロバイダがない場合にスローされます。 この例外は、AttachProvider.providers()
が空のリストを返す場合にもスローされます。- パラメータ:
id
- Java仮想マシンを識別する抽象識別子。- 戻り値:
- ターゲットVMを表すVirtualMachine。
- 例外:
SecurityException
- セキュリティ・マネージャがインストールされていて、そのマネージャがAttachPermission
("attachVirtualMachine")
、または実装に必要な別のアクセス権を拒否した場合。AttachNotSupportedException
- インストールされているすべてのプロバイダのattachVirtualmachine
メソッドがAttachNotSupportedException
をスローする場合、またはプロバイダがインストールされていない場合。IOException
- 入出力エラーが発生した場合NullPointerException
-id
がnull
である場合。
-
attach
public static VirtualMachine attach(VirtualMachineDescriptor vmd) throws AttachNotSupportedException, IOExceptionJava仮想マシンに接続します。このメソッドは、最初に、指定された仮想マシン記述子の
provider()
メソッドを呼び出して、接続プロバイダを取得します。 次に、接続プロバイダのattachVirtualMachine
を呼び出して、ターゲットVMに接続します。- パラメータ:
vmd
- 仮想マシン記述子。- 戻り値:
- ターゲットVMを表すVirtualMachine。
- 例外:
SecurityException
- セキュリティ・マネージャがインストールされていて、そのマネージャがAttachPermission
("attachVirtualMachine")
、または実装に必要な別のアクセス権を拒否した場合。AttachNotSupportedException
- 接続プロバイダのattachVirtualmachine
がAttachNotSupportedException
をスローする場合。IOException
- 入出力エラーが発生した場合NullPointerException
-vmd
がnull
である場合。
-
detach
public abstract void detach() throws IOException仮想マシンから切り離します。仮想マシンから切り離したあと、その仮想マシンでさらにオペレーションを呼び出そうとすると、
IOException
がスローされます。 このメソッドが呼び出されたときに、たとえばloadAgent
のようなオペレーションが進行中の場合、その動作は実装によって異なります。 つまり、オペレーションが完了するかIOException
をスローするかは、実装固有です。仮想マシンからすでに切り離されている場合は、このメソッドを呼び出しても何の効果もありません。
- 例外:
IOException
- 入出力エラーが発生した場合
-
provider
public final AttachProvider provider()この仮想マシンの作成元プロバイダを返します。- 戻り値:
- この仮想マシンの作成元プロバイダ。
-
id
public final String id()このJava仮想マシンの識別子を返します。- 戻り値:
- このJava仮想マシンの識別子。
-
loadAgentLibrary
public abstract void loadAgentLibrary(String agentLibrary, String options) throws AgentLoadException, AgentInitializationException, IOExceptionエージェント・ライブラリをロードします。JVM TIクライアントはエージェントと呼ばれます。 これはネイティブ言語で開発されています。 JVM TIエージェントはプラットフォーム固有の方法で配置されますが、通常これはプラットフォームのダイナミック・ライブラリに相当します。 また、静的にVMにリンクされる場合もあります。 このメソッドは、指定されたエージェント・ライブラリがまだターゲットVMにロードされていない場合や静的にVMにリンクされていない場合に、それをロードします。 次に、ターゲットVMが
Agent_OnAttach
関数を呼び出すか、'L'という名前の静的にリンクされたエージェントの場合、「JVMツールのインタフェース」仕様で指定されているAgent_OnAttach_L
関数が呼び出されます。Agent_OnAttach[_L]
関数は、このメソッドを呼び出す前にエージェント・ライブラリがロードされていた場合でも呼び出されます。ロードするエージェント・ライブラリは、エージェント・ライブラリの名前で指定します。 これは、ターゲット仮想マシンで、実装によって異なる方法で解釈されます。 通常は、実装で、ライブラリ名はオペレーティング・システム固有のファイル名に拡張されます。 たとえば、UNIXシステムでは、
L
という名前はlibL.so
に拡張され、LD_LIBRARY_PATH
環境変数で指定された検索パスを使用して検索されます。 「L」という名前のエージェントが静的にVMにリンクされている場合、VMはAgent_OnAttach_L
という名前の関数をエクスポートする必要があります。エージェント・ライブラリ内の
Agent_OnAttach[_L]
関数がエラーを返すと、AgentInitializationException
がスローされます。 その後、例外でreturnValue
メソッドを呼び出すと、Agent_OnAttach[_L]
からの戻り値を取得できます。- パラメータ:
agentLibrary
- エージェント・ライブラリの名前。options
-Agent_OnAttach[_L]
関数に指定するオプション(null
にすることができる)。- 例外:
AgentLoadException
- エージェント・ライブラリが存在しない場合、エージェント・ライブラリが静的にVMにリンクされていない場合、または別の理由によりロードできない場合。AgentInitializationException
-Agent_OnAttach[_L]
関数がエラーを返す場合。IOException
- 入出力エラーが発生した場合NullPointerException
-agentLibrary
がnull
である場合。- 関連項目:
AgentInitializationException.returnValue()
-
loadAgentLibrary
public void loadAgentLibrary(String agentLibrary) throws AgentLoadException, AgentInitializationException, IOException- パラメータ:
agentLibrary
- エージェント・ライブラリの名前。- 例外:
AgentLoadException
- エージェント・ライブラリが存在しない場合、エージェント・ライブラリが静的にVMにリンクされていない場合、または別の理由によりロードできない場合。AgentInitializationException
-Agent_OnAttach[_L]
関数がエラーを返す場合。IOException
- 入出力エラーが発生した場合NullPointerException
-agentLibrary
がnull
である場合。
-
loadAgentPath
public abstract void loadAgentPath(String agentPath, String options) throws AgentLoadException, AgentInitializationException, IOExceptionフル・パス名を使用して、ネーティブ・エージェント・ライブラリをロードします。JVM TIクライアントはエージェントと呼ばれます。 これはネイティブ言語で開発されています。 JVM TIエージェントはプラットフォーム固有の方法で配置されますが、通常これはプラットフォームのダイナミック・ライブラリに相当します。 また、agentPathパラメータで指定されたネイティブ・ライブラリが静的にVMにリンクされる場合もあります。 静的にリンクされたライブラリ名へのagentPathパラメータの解析は、VMでプラットフォーム固有の方法によって実行されます。 たとえば、UNIXでは、
/a/b/libL.so
のagentPathパラメータはライブラリに「L」という名前を付けます。 詳細は、JVM TI仕様を参照してください。 このメソッドは、指定されたエージェント・ライブラリがまだターゲットVMにロードされていない場合や静的にVMにリンクされていない場合に、それをロードします。 次に、ターゲットVMがAgent_OnAttach
関数を呼び出すか、'L'という名前の静的にリンクされたエージェントの場合、「JVMツールのインタフェース」仕様で指定されているAgent_OnAttach_L
関数が呼び出されます。Agent_OnAttach[_L]
関数は、このメソッドを呼び出す前にエージェント・ライブラリがロードされていた場合でも呼び出されます。ロードするエージェント・ライブラリは、エージェント・ライブラリのロード元の絶対パスで指定します。
loadAgentLibrary
とは異なり、ライブラリ名はターゲット仮想マシンでは拡張されません。エージェント・ライブラリ内の
Agent_OnAttach[_L]
関数がエラーを返すと、AgentInitializationException
がスローされます。 その後、例外でreturnValue
メソッドを呼び出すと、Agent_OnAttach[_L]
からの戻り値を取得できます。- パラメータ:
agentPath
- エージェント・ライブラリのフル・パス。options
-Agent_OnAttach[_L]
関数に指定するオプション(null
にすることができる)。- 例外:
AgentLoadException
- エージェント・ライブラリが存在しない場合、エージェント・ライブラリが静的にVMにリンクされていない場合、または別の理由によりロードできない場合。AgentInitializationException
-Agent_OnAttach[_L]
関数がエラーを返す場合。IOException
- 入出力エラーが発生した場合NullPointerException
-agentPath
がnull
である場合。- 関連項目:
AgentInitializationException.returnValue()
-
loadAgentPath
public void loadAgentPath(String agentPath) throws AgentLoadException, AgentInitializationException, IOExceptionフル・パス名を使用して、ネーティブ・エージェント・ライブラリをロードします。この簡易メソッドは、次のものを呼び出した場合と同様に機能します。
loadAgentPath
(agentLibrary, null);- パラメータ:
agentPath
- エージェント・ライブラリへのフル・パス。- 例外:
AgentLoadException
- エージェント・ライブラリが存在しない場合、エージェント・ライブラリが静的にVMにリンクされていない場合、または別の理由によりロードできない場合。AgentInitializationException
-Agent_OnAttach[_L]
関数がエラーを返す場合。IOException
- 入出力エラーが発生した場合NullPointerException
-agentPath
がnull
である場合。
-
loadAgent
public abstract void loadAgent(String agent, String options) throws AgentLoadException, AgentInitializationException, IOExceptionエージェントをロードします。このメソッドに指定するエージェントは、ターゲット仮想マシンのファイル・システム上のJARファイルへのパス名です。 このパスは、それを解釈するターゲット仮想マシンに渡されます。 ターゲット仮想マシンは、
java.lang.instrument
仕様の指定どおりにエージェントを起動しようとします。 つまり、指定されたJARファイルはターゲット仮想マシンのシステム・クラス・パスに追加され、JARマニフェスト内のAgent-Class
属性で指定された、エージェント・クラスのagentmain
メソッドが呼び出されます。 このメソッドは、agentmain
メソッドの完了時に完了します。- パラメータ:
agent
- エージェントを含むJARファイルへのパス。options
- エージェントのagentmain
メソッドに指定するオプション。null
にすることができる。- 例外:
AgentLoadException
- エージェントが存在しない場合、またはjava.lang.instrument
仕様に指定されている方法で起動できない場合。AgentInitializationException
-agentmain
が例外をスローする場合IOException
- 入出力エラーが発生した場合NullPointerException
-agent
がnull
である場合。
-
loadAgent
public void loadAgent(String agent) throws AgentLoadException, AgentInitializationException, IOException- パラメータ:
agent
- エージェントを含むJARファイルへのパス。- 例外:
AgentLoadException
- エージェントが存在しない場合、またはjava.lang.instrument
仕様に指定されている方法で起動できない場合。AgentInitializationException
-agentmain
が例外をスローする場合IOException
- 入出力エラーが発生した場合NullPointerException
-agent
がnull
である場合。
-
getSystemProperties
public abstract Properties getSystemProperties() throws IOExceptionターゲット仮想マシン内の現在のシステム・プロパティを返します。このメソッドは、ターゲット仮想マシン内のシステム・プロパティを返します。 キーまたは値が
String
でないプロパティは省略されます。 このメソッドは、String
ではないキーまたは値を持つプロパティが含まれていない場合を除き、ターゲット仮想マシンでのSystem.getProperties
メソッドの呼び出しとほぼ同等です。このメソッドは、通常、
loadAgent
またはloadAgentLibrary
でターゲット仮想マシンにロードするエージェントを決定するために使用します。 たとえば、java.home
またはuser.dir
プロパティを使用すると、エージェント・ライブラリまたはJARファイルへのパスを作成できます。- 戻り値:
- システム・プロパティ
- 例外:
AttachOperationFailedException
- ターゲット仮想マシンがアタッチ操作を完了できない場合。 より具体的なエラー・メッセージはThrowable.getMessage()
から提供されます。IOException
- エラーとして認識されない、ターゲットVMで操作が失敗したことを示す通信エラーなどのI/Oエラーが発生した場合。- 関連項目:
System.getProperties()
,loadAgentLibrary(java.lang.String, java.lang.String)
,loadAgent(java.lang.String, java.lang.String)
-
getAgentProperties
public abstract Properties getAgentProperties() throws IOExceptionターゲット仮想マシン内の現在のエージェント・プロパティを返します。ターゲット仮想マシンでは、エージェントの代わりにプロパティのリストを保持できます。 これを行う方法、プロパティの名前、および許可される値の型は、実装固有です。 エージェント・プロパティは、通常、通信端点とその他のエージェント構成の詳細を格納するために使用します。 たとえば、デバッガ・エージェントでは、そのトランスポート・アドレスのエージェント・プロパティを作成できます。
このメソッドは、キーと値が
String
であるエージェント・プロパティを返します。 キーまたは値がString
でないプロパティは省略されます。 ターゲット仮想マシンでエージェント・プロパティを保持していない場合は、空のプロパティ・リストが返されます。- 戻り値:
- エージェント・プロパティ
- 例外:
AttachOperationFailedException
- ターゲット仮想マシンがアタッチ操作を完了できない場合。 より具体的なエラー・メッセージはThrowable.getMessage()
から提供されます。IOException
- エラーとして認識されない、ターゲットVMで操作が失敗したことを示す通信エラーなどのI/Oエラーが発生した場合。
-
startManagementAgent
public abstract void startManagementAgent(Properties agentProperties) throws IOExceptionターゲット仮想マシンでJMX管理エージェントを起動します。構成プロパティは、JMX管理エージェントを起動したときのコマンドラインの指定と同じです。 コマンドラインの場合と同じように、最低限、
com.sun.management.jmxremote.port
プロパティを指定する必要があります。詳細については、「JMXテクノロジを使用したモニタリングと管理」のオンライン・ドキュメントを参照してください。
- パラメータ:
agentProperties
- エージェントの構成プロパティを含むプロパティ・オブジェクト。- 例外:
AttachOperationFailedException
- ターゲット仮想マシンがアタッチ操作を完了できない場合。 より具体的なエラー・メッセージはThrowable.getMessage()
から提供されます。IOException
- エラーとして認識されない、ターゲットVMで操作が失敗したことを示す通信エラーなどのI/Oエラーが発生した場合。IllegalArgumentException
- agentPropertiesのキーまたは値が無効な場合。NullPointerException
- agentPropertiesがnullの場合。- 導入されたバージョン:
- 1.8
-
startLocalManagementAgent
public abstract String startLocalManagementAgent() throws IOExceptionターゲット仮想マシンでローカルJMX管理エージェントを起動します。詳細については、「JMXテクノロジを使用したモニタリングと管理」のオンライン・ドキュメントを参照してください。
- 戻り値:
- ローカル・コネクタのサービス・アドレスの文字列表現。 この値は、
JMXServiceURL(String)
コンストラクタによって解析できます。 - 例外:
AttachOperationFailedException
- ターゲット仮想マシンがアタッチ操作を完了できない場合。 より具体的なエラー・メッセージはThrowable.getMessage()
から提供されます。IOException
- エラーとして認識されない、ターゲットVMで操作が失敗したことを示す通信エラーなどのI/Oエラーが発生した場合。- 導入されたバージョン:
- 1.8
-
hashCode
public int hashCode()このVirtualMachineのハッシュ・コード値を返します。 ハッシュ・コードはVirtualMachineのコンポーネントに基づき、Object.hashCode
メソッドの汎用規約を満たします。- オーバーライド:
hashCode
、クラス:Object
- 戻り値:
- この仮想マシンのハッシュ・コード値
- 関連項目:
Object.equals(java.lang.Object)
,System.identityHashCode(java.lang.Object)
-
equals
public boolean equals(Object ob)このVirtualMachineが別のオブジェクトと等しいかどうかを判定します。指定されたオブジェクトがVirtualMachineではない場合、このメソッドは
false
を返します。 2つのVirtualMachineを等しいとみなすためには、両方とも同じプロバイダを参照し、それらのidentifiers
が等しい必要があります。このメソッドは
Object.equals
メソッドの汎用規約を満たします。- オーバーライド:
equals
、クラス:Object
- パラメータ:
ob
- このオブジェクトと比較するオブジェクト- 戻り値:
- 指定されたオブジェクトがこのVirtualMachineと等しいVirtualMachineである場合にだけ
true
。 - 関連項目:
Object.hashCode()
、HashMap
-
toString
public String toString()VirtualMachine
の文字列表記を返します。
-