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
メソッドは、ダイナミックライブラリに配置され JVM Tools Interface を利用するエージェントのロードに使用します。
エージェントのロードのほか、VirtualMachine はターゲット VM 内の system properties
への読み取りアクセスも提供します。これは、ターゲット VM 内にロードされるエージェントへのパスを構築するために、java.home
、os.name
、os.arch
などのプロパティーを使用する環境で有用です。
次に VirtualMachine の使用方法の例を示します。
// attach to target VM VirtualMachine vm = VirtualMachine.attach("2177"); // get system properties in target VM Properties props = vm.getSystemProperties(); // construct path to management agent String home = props.getProperty("java.home"); String agent = home + File.separator + "lib" + File.separator + "management-agent.jar"; // load agent into target VM vm.loadAgent(agent, "com.sun.management.jmxremote.port=5000"); // detach vm.detach();
この例では、プロセス識別子 2177
で識別される Java 仮想マシンに接続します。次に、ターゲット VM からのシステムプロパティーを使用して、ターゲット VM 内にロードする管理エージェントへのパスを構築します。ロード後、クライアントがターゲット VM から切り離されます。
VirtualMachine は、複数の並行スレッドで安全に使用できます。
修飾子 | コンストラクタと説明 |
---|---|
protected |
VirtualMachine(AttachProvider provider, String id)
このクラスの新しいインスタンスを初期化します。
|
修飾子と型 | メソッドと説明 |
---|---|
static VirtualMachine |
attach(String id)
Java 仮想マシンに接続します。
|
static VirtualMachine |
attach(VirtualMachineDescriptor vmd)
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()
この仮想マシンの作成元プロバイダを返します。
|
String |
toString()
VirtualMachine の文字列表記を返します。 |
protected VirtualMachine(AttachProvider provider, String id)
provider
- このクラスを作成する接続プロバイダ。id
- Java 仮想マシンを識別する抽象識別子。NullPointerException
- provider
または id
が null
の場合。public static List<VirtualMachineDescriptor> list()
このメソッドは、Java VirtualMachineDescriptor
要素のリストを返します。このリストは仮想マシン記述子リストの集合で、インストールされているすべての attach providers
の listVirtualMachines
メソッドを呼び出すことで取得されます。プロバイダで認識されている Java 仮想マシンがない場合は、空のリストが返されます。
public static VirtualMachine attach(String id) throws AttachNotSupportedException, IOException
このメソッドは、AttachProvider.providers()
メソッドを呼び出すことで、接続プロバイダのリストを取得します。次に、リストに対して繰り返し処理を行い、各プロバイダの attachVirtualMachine
メソッドを順番に呼び出します。プロバイダが正常に接続すると、繰り返し処理は終了し、正常に接続されたプロバイダによって作成された VirtualMachine がこのメソッドによって返されます。すべてのプロバイダの attachVirtualMachine
メソッドが AttachNotSupportedException
をスローすると、このメソッドも AttachNotSupportedException
をスローします。つまり、AttachNotSupportedException
は、このメソッドに提供された識別子が無効な場合、存在しない Java 仮想マシンに対する識別子である場合、またはそれに接続できるプロバイダがない場合にスローされます。この例外は、AttachProvider.providers()
が空のリストを返す場合にもスローされます。
id
- Java 仮想マシンを識別する抽象識別子。SecurityException
- セキュリティーマネージャーがインストールされていて、そのマネージャーが AttachPermission
("attachVirtualMachine")、または実装に必要な別のアクセス権を拒否した場合。AttachNotSupportedException
- インストールされているすべてのプロバイダの attachVirtualmachine
メソッドが AttachNotSupportedException
をスローする場合、またはプロバイダがインストールされていない場合。IOException
- 入出力エラーが発生した場合NullPointerException
- id
が null
である場合。public static VirtualMachine attach(VirtualMachineDescriptor vmd) throws AttachNotSupportedException, IOException
このメソッドは、最初に、指定された仮想マシン記述子の provider()
メソッドを呼び出して、接続プロバイダを取得します。次に、接続プロバイダの attachVirtualMachine
を呼び出して、ターゲット VM に接続します。
vmd
- 仮想マシン記述子。SecurityException
- セキュリティーマネージャーがインストールされていて、そのマネージャーが AttachPermission
("attachVirtualMachine")、または実装に必要な別のアクセス権を拒否した場合。AttachNotSupportedException
- 接続プロバイダの attachVirtualmachine
が AttachNotSupportedException
をスローする場合。IOException
- 入出力エラーが発生した場合NullPointerException
- vmd
が null
である場合。public abstract void detach() throws IOException
仮想マシンから切り離したあと、その仮想マシンでさらにオペレーションを呼び出そうとすると、IOException
がスローされます。このメソッドが呼び出されたときに、たとえば loadAgent
のようなオペレーションが進行中の場合、その動作は実装によって異なります。つまり、オペレーションが完了するか IOException をスローするかは、実装固有です。
仮想マシンからすでに切り離されている場合は、このメソッドを呼び出しても何の効果もありません。
IOException
- 入出力エラーが発生した場合public final AttachProvider provider()
public final String id()
public abstract void loadAgentLibrary(String agentLibrary, String options) throws AgentLoadException, AgentInitializationException, IOException
JVM TI クライアントはエージェントと呼ばれます。これはネイティブ言語で開発されています。JVM TI エージェントはプラットフォーム固有の方法で配置されますが、通常これはプラットフォームのダイナミックライブラリに相当します。このメソッドは、指定されたエージェントライブラリがまだターゲット VM にロードされていない場合は、それをロードします。次に、JVM Tools Interface 仕様の指定どおりに、ターゲット VM で Agent_OnAttach
関数を呼び出します。Agent_OnAttach
関数は、このメソッドを呼び出す前にエージェントライブラリがロードされていた場合でも呼び出されます。
ロードするエージェントライブラリは、エージェントライブラリの名前で指定します。これは、ターゲット仮想マシンで、実装によって異なる方法で解釈されます。通常は、実装で、ライブラリ名はオペレーティングシステム固有のファイル名に拡張されます。たとえば、UNIX システムでは、foo という名前は libfoo.so に拡張され、LD_LIBRARY_PATH 環境変数で指定された検索パスを使って検索されます。
エージェントライブラリ内の Agent_OnAttach
関数がエラーを返すと、AgentInitializationException
がスローされます。その後、例外で returnValue
メソッドを呼び出すと、Agent_OnAttach
からの戻り値を取得できます。
agentLibrary
- エージェントライブラリの名前。options
- Agent_OnAttach
関数に指定するオプション (null
にすることができる)。AgentLoadException
- エージェントライブラリが存在しない場合、または別の理由によりロードできない場合。AgentInitializationException
- Agent_OnAttach
関数がエラーを返す場合IOException
- 入出力エラーが発生した場合NullPointerException
- agentLibrary
が null
である場合。AgentInitializationException.returnValue()
public void loadAgentLibrary(String agentLibrary) throws AgentLoadException, AgentInitializationException, IOException
この簡易メソッドは、次のものを呼び出した場合と同様に機能します。
loadAgentLibrary
(agentLibrary, null);
agentLibrary
- エージェントライブラリの名前。AgentLoadException
- エージェントライブラリが存在しない場合、または別の理由によりロードできない場合。AgentInitializationException
- Agent_OnAttach
関数がエラーを返す場合IOException
- 入出力エラーが発生した場合NullPointerException
- agentLibrary
が null
である場合。public abstract void loadAgentPath(String agentPath, String options) throws AgentLoadException, AgentInitializationException, IOException
JVM TI クライアントはエージェントと呼ばれます。これはネイティブ言語で開発されています。JVM TI エージェントはプラットフォーム固有の方法で配置されますが、通常これはプラットフォームのダイナミックライブラリに相当します。このメソッドは、指定されたエージェントライブラリがまだターゲット VM にロードされていない場合は、それをロードします。次に、JVM Tools Interface 仕様の指定どおりに、ターゲット VM で Agent_OnAttach
関数を呼び出します。Agent_OnAttach
関数は、このメソッドを呼び出す前にエージェントライブラリがロードされていた場合でも呼び出されます。
ロードするエージェントライブラリは、エージェントライブラリのロード元の絶対パスで指定します。loadAgentLibrary
とは異なり、ライブラリ名はターゲット仮想マシンでは拡張されません。
エージェントライブラリ内の Agent_OnAttach
関数がエラーを返すと、AgentInitializationException
がスローされます。その後、例外で returnValue
メソッドを呼び出すと、Agent_OnAttach
からの戻り値を取得できます。
agentPath
- エージェントライブラリのフルパス。options
- Agent_OnAttach
関数に指定するオプション (null
にすることができる)。AgentLoadException
- エージェントライブラリが存在しない場合、または別の理由によりロードできない場合。AgentInitializationException
- Agent_OnAttach
関数がエラーを返す場合IOException
- 入出力エラーが発生した場合NullPointerException
- agentPath
が null
である場合。AgentInitializationException.returnValue()
public void loadAgentPath(String agentPath) throws AgentLoadException, AgentInitializationException, IOException
この簡易メソッドは、次のものを呼び出した場合と同様に機能します。
loadAgentPath
(agentLibrary, null);
agentPath
- エージェントライブラリへのフルパス。AgentLoadException
- エージェントライブラリが存在しない場合、または別の理由によりロードできない場合。AgentInitializationException
- Agent_OnAttach
関数がエラーを返す場合IOException
- 入出力エラーが発生した場合NullPointerException
- agentPath
が null
である場合。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
である場合。public void loadAgent(String agent) throws AgentLoadException, AgentInitializationException, IOException
この簡易メソッドは、次のものを呼び出した場合と同様に機能します。
loadAgent
(agent, null);
agent
- エージェントを含む JAR ファイルへのパス。AgentLoadException
- エージェントが存在しない場合、または java.lang.instrument
仕様に指定されている方法で起動できない場合。AgentInitializationException
- agentmain
が例外をスローする場合IOException
- 入出力エラーが発生した場合NullPointerException
- agent
が null
である場合。public abstract Properties getSystemProperties() throws IOException
このメソッドは、ターゲット仮想マシン内のシステムプロパティーを返します。キーまたは値が String でないプロパティーは省略されます。このメソッドは、String ではないキーまたは値を持つプロパティーが含まれていない場合を除き、ターゲット仮想マシンでの System.getProperties
メソッドの呼び出しとほぼ同等です。
このメソッドは、通常、loadAgent
または loadAgentLibrary
でターゲット仮想マシンにロードするエージェントを決定するために使用します。たとえば、java.home
または user.dir
プロパティーを使用すると、エージェントライブラリまたは JAR ファイルへのパスを作成できます。
IOException
- 入出力エラーが発生した場合System.getProperties()
, loadAgentLibrary(java.lang.String, java.lang.String)
, loadAgent(java.lang.String, java.lang.String)
public abstract Properties getAgentProperties() throws IOException
ターゲット仮想マシンでは、エージェントの代わりにプロパティーのリストを保持できます。これを行う方法、プロパティーの名前、および許可される値の型は、実装固有です。エージェントプロパティーは、通常、通信端点とその他のエージェント構成の詳細を格納するために使用します。たとえば、デバッガエージェントでは、そのトランスポートアドレスのエージェントプロパティーを作成できます。
このメソッドは、キーと値が String であるエージェントプロパティーを返します。キーまたは値が String でないプロパティーは省略されます。ターゲット仮想マシンでエージェントプロパティーを保持していない場合は、空のプロパティーリストが返されます。
IOException
- 入出力エラーが発生した場合public int hashCode()
Object.hashCode
メソッドの汎用規約を満たします。hashCode
、クラス: Object
Object.equals(java.lang.Object)
, System.identityHashCode(java.lang.Object)
public boolean equals(Object ob)
指定されたオブジェクトが VirtualMachine ではない場合、このメソッドは false を返します。2 つの VirtualMachine を等しいとみなすためには、両方とも同じプロバイダを参照し、それらの identifiers
が等しい必要があります。
このメソッドは Object.equals
メソッドの汎用規約を満たします。
equals
、クラス: Object
ob
- このオブジェクトと比較するオブジェクトObject.hashCode()
, HashMap
Copyright © 2005, 2013, Oracle and/or its affiliates. All rights reserved.