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

クラスVirtualMachine

  • public abstract class VirtualMachine
extends Object
    Java仮想マシンです。

    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

    • コンストラクタの詳細

      • 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,
                                    IOException
        Java仮想マシンに接続します。

        このメソッドは、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,
                                    IOException
        Java仮想マシンに接続します。

        このメソッドは、最初に、指定された仮想マシン記述子の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
        エージェント・ライブラリをロードします。

        この簡易メソッドは、次のものを呼び出した場合と同様に機能します。

        loadAgentLibrary(agentLibrary, null);
        パラメータ:
        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である場合。

      • 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

      • 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の文字列表記を返します。
        オーバーライド:
        toString 、クラス:  Object
        戻り値:
        このオブジェクトの文字列表現