Instrumentation 新功能

weixin_34393428發表於2019-01-05

Instrumentation 簡介

利用 Java 程式碼，即 java.lang.instrument 做動態 Instrumentation 是 Java SE 5 的新特性，它把 Java 的 instrument 功能從原生程式碼中解放出來，使之可以用 Java 程式碼的方式解決問題。使用 Instrumentation，開發者可以構建一個獨立於應用程式的代理程式（Agent），用來監測和協助執行在 JVM 上的程式，甚至能夠替換和修改某些類的定義。有了這樣的功能，開發者就可以實現更為靈活的執行時虛擬機器監控和 Java 類操作了，這樣的特性實際上提供了一種虛擬機器級別支援的 AOP 實現方式，使得開發者無需對 JDK 做任何升級和改動，就可以實現某些 AOP 的功能了。

在 Java SE 6 裡面，instrumentation 包被賦予了更強大的功能：啟動後的 instrument、原生程式碼（native code）instrument，以及動態改變 classpath 等等。這些改變，意味著 Java 具有了更強的動態控制、解釋能力，它使得 Java 語言變得更加靈活多變。

在 Java SE6 裡面，最大的改變使執行時的 Instrumentation 成為可能。在 Java SE 5 中，Instrument 要求在執行前利用命令列引數或者系統引數來設定代理類，在實際的執行之中，虛擬機器在初始化之時（在絕大多數的 Java 類庫被載入之前），instrumentation 的設定已經啟動，並在虛擬機器中設定了回撥函式，檢測特定類的載入情況，並完成實際工作。但是在實際的很多的情況下，我們沒有辦法在虛擬機器啟動之時就為其設定代理，這樣實際上限制了 instrument 的應用。而 Java SE 6 的新特性改變了這種情況，通過 Java Tool API 中的 attach 方式，我們可以很方便地在執行過程中動態地設定載入代理類，以達到 instrumentation 的目的。

另外，對 native 的 Instrumentation 也是 Java SE 6 的一個嶄新的功能，這使以前無法完成的功能 —— 對 native 介面的 instrumentation 可以在 Java SE 6 中，通過一個或者一系列的 prefix 新增而得以完成。

最後，Java SE 6 裡的 Instrumentation 也增加了動態新增 class path 的功能。所有這些新的功能，都使得 instrument 包的功能更加豐富，從而使 Java 語言本身更加強大。

Instrumentation 的基本功能和用法

“java.lang.instrument”包的具體實現，依賴於 JVMTI。JVMTI（Java Virtual Machine Tool Interface）是一套由 Java 虛擬機器提供的，為 JVM 相關的工具提供的本地程式設計介面集合。JVMTI 是從 Java SE 5 開始引入，整合和取代了以前使用的 Java Virtual Machine Profiler Interface (JVMPI) 和 the Java Virtual Machine Debug Interface (JVMDI)，而在 Java SE 6 中，JVMPI 和 JVMDI 已經消失了。JVMTI 提供了一套”代理”程式機制，可以支援第三方工具程式以代理的方式連線和訪問 JVM，並利用 JVMTI 提供的豐富的程式設計介面，完成很多跟 JVM 相關的功能。事實上，java.lang.instrument 包的實現，也就是基於這種機制的：在 Instrumentation 的實現當中，存在一個 JVMTI 的代理程式，通過呼叫 JVMTI 當中 Java 類相關的函式來完成 Java 類的動態操作。除開 Instrumentation 功能外，JVMTI 還在虛擬機器記憶體管理，執行緒控制，方法和變數操作等等方面提供了大量有價值的函式。關於 JVMTI 的詳細資訊，請參考 Java SE 6 文件（請參見 參考資源）當中的介紹。

Instrumentation 的最大作用，就是類定義動態改變和操作。在 Java SE 5 及其後續版本當中，開發者可以在一個普通 Java 程式（帶有 main 函式的 Java 類）執行時，通過 – javaagent引數指定一個特定的 jar 檔案（包含 Instrumentation 代理）來啟動 Instrumentation 的代理程式。

在 Java SE 5 當中，開發者可以讓 Instrumentation 代理在 main 函式執行前執行。簡要說來就是如下幾個步驟：

  1. 編寫 premain 函式

    編寫一個 Java 類，包含如下兩個方法當中的任何一個

public static void premain(String agentArgs, Instrumentation inst); [1]
public static void premain(String agentArgs); [2]

其中，[1] 的優先順序比 [2] 高，將會被優先執行（[1] 和 [2] 同時存在時，[2] 被忽略）。

在這個 premain 函式中，開發者可以進行對類的各種操作。

agentArgs 是 premain 函式得到的程式引數，隨同 “– javaagent”一起傳入。與 main 函式不同的是，這個引數是一個字串而不是一個字串陣列，如果程式引數有多個，程式將自行解析這個字串。

Inst 是一個 java.lang.instrument.Instrumentation 的例項，由 JVM 自動傳入。java.lang.instrument.Instrumentation 是 instrument 包中定義的一個介面，也是這個包的核心部分，集中了其中幾乎所有的功能方法，例如類定義的轉換和操作等等。

  1. jar 檔案打包

    將這個 Java 類打包成一個 jar 檔案，並在其中的 manifest 屬性當中加入” Premain-Class”來指定步驟 1 當中編寫的那個帶有 premain 的 Java 類。（可能還需要指定其他屬性以開啟更多功能）

  2. 執行

    用如下方式執行帶有 Instrumentation 的 Java 程式：

java -javaagent:jar 檔案的位置 [= 傳入 premain 的引數 ]

對 Java 類檔案的操作，可以理解為對一個 byte 陣列的操作（將類檔案的二進位制位元組流讀入一個 byte 陣列）。開發者可以在“ClassFileTransformer”的 transform 方法當中得到，操作並最終返回一個類的定義（一個 byte 陣列）。這方面，Apache 的 BCEL 開源專案提供了強有力的支援，讀者可以在參考文章“Java SE 5 特性 Instrumentation 實踐”中看到一個 BCEL 和 Instrumentation 結合的例子。具體的位元組碼操作並非本文的重點，所以，本文中所舉的例子，只是採用簡單的類檔案替換的方式來演示 Instrumentation 的使用。

下面，我們通過簡單的舉例，來說明 Instrumentation 的基本使用方法。

首先，我們有一個簡單的類，TransClass， 可以通過一個靜態方法返回一個整數 1。

public class TransClass {
  public int getNumber() {
    return 1;
  }
}

我們執行如下類，可以得到輸出 ”1“。

public class TestMainInJar {
  public static void main(String[] args) {
    System.out.println(new TransClass().getNumber());
  }
}

然後，我們將 TransClass 的 getNumber 方法改成如下 :

public int getNumber() {
  return 2;
}

再將這個返回 2 的 Java 檔案編譯成類檔案，為了區別開原有的返回 1 的類，我們將返回 2 的這個類檔案命名為 TransClass.class.2。

接下來，我們建立一個 Transformer 類：

import java.io.File; 
import java.io.FileInputStream; 
import java.io.IOException; 
import java.io.InputStream; 
import java.lang.instrument.ClassFileTransformer; 
import java.lang.instrument.IllegalClassFormatException; 
import java.security.ProtectionDomain; 
 
class Transformer implements ClassFileTransformer { 
 
   public static final String classNumberReturns2 = "TransClass.class.2"; 
 
   public static byte[] getBytesFromFile(String fileName) { 
       try { 
           // precondition 
           File file = new File(fileName); 
           InputStream is = new FileInputStream(file); 
           long length = file.length(); 
           byte[] bytes = new byte[(int) length]; 
 
           // Read in the bytes 
           int offset = 0; 
           int numRead = 0; 
           while (offset <bytes.length
                   && (numRead = is.read(bytes, offset, bytes.length - offset)) >= 0) { 
               offset += numRead; 
           } 
 
           if (offset < bytes.length) { 
               throw new IOException("Could not completely read file "
                       + file.getName()); 
           } 
           is.close(); 
           return bytes; 
       } catch (Exception e) { 
           System.out.println("error occurs in _ClassTransformer!"
                   + e.getClass().getName()); 
           return null; 
       } 
   } 
 
   public byte[] transform(ClassLoader l, String className, Class<?> c, 
           ProtectionDomain pd, byte[] b) throws IllegalClassFormatException { 
       if (!className.equals("TransClass")) { 
           return null; 
       } 
       return getBytesFromFile(classNumberReturns2); 
 
   } 
}

這個類實現了 ClassFileTransformer 介面。其中，getBytesFromFile 方法根據檔名讀入二進位制字元流，而 ClassFileTransformer 當中規定的 transform 方法則完成了類定義的替換轉換。

最後，我們建立一個 Premain 類，寫入 Instrumentation 的代理方法 premain：

public class Premain { 
   public static void premain(String agentArgs， Instrumentation inst) 
           throws ClassNotFoundException， UnmodifiableClassException { 
       inst.addTransformer(new Transformer()); 
   } 
}

可以看出，addTransformer 方法並沒有指明要轉換哪個類。轉換髮生在 premain 函式執行之後，main 函式執行之前，這時每裝載一個類，transform 方法就會執行一次，看看是否需要轉換，所以，在 transform（Transformer 類中）方法中，程式用 className.equals("TransClass") 來判斷當前的類是否需要轉換。

程式碼完成後，我們將他們打包為 TestInstrument1.jar。返回 1 的那個 TransClass 的類檔案保留在 jar 包中，而返回 2 的那個 TransClass.class.2 則放到 jar 的外面。在 manifest 裡面加入如下屬性來指定 premain 所在的類：

Manifest-Version: 1.0
Premain-Class: Premain

在執行這個程式的時候，如果我們用普通方式執行這個 jar 中的 main 函式，可以得到輸出“1”。如果用下列方式執行 :

java – javaagent:TestInstrument1.jar – cp TestInstrument1.jar TestMainInJar

則會得到輸出“2”。

當然，程式執行的 main 函式不一定要放在 premain 所在的這個 jar 檔案裡面，這裡只是為了例子程式打包的方便而放在一起的。

除開用 addTransformer 的方式，Instrumentation 當中還有另外一個方法“redefineClasses”來實現 premain 當中指定的轉換。用法類似，如下：

public class Premain { 
   public static void premain(String agentArgs， Instrumentation inst) 
           throws ClassNotFoundException， UnmodifiableClassException { 
       ClassDefinition def = new ClassDefinition(TransClass.class， Transformer 
               .getBytesFromFile(Transformer.classNumberReturns2)); 
       inst.redefineClasses(new ClassDefinition[] { def }); 
       System.out.println("success"); 
   } 
}

redefineClasses 的功能比較強大，可以批量轉換很多類。

Java SE 6 的新特性：虛擬機器啟動後的動態 instrument

在 Java SE 5 當中，開發者只能在 premain 當中施展想象力，所作的 Instrumentation 也僅限與 main 函式執行前，這樣的方式存在一定的侷限性。

在 Java SE 5 的基礎上，Java SE 6 針對這種狀況做出了改進，開發者可以在 main 函式開始執行以後，再啟動自己的 Instrumentation 程式。

在 Java SE 6 的 Instrumentation 當中，有一個跟 premain“並駕齊驅”的“agentmain”方法，可以在 main 函式開始執行之後再執行。

跟 premain 函式一樣， 開發者可以編寫一個含有“agentmain”函式的 Java 類：

public static void agentmain (String agentArgs, Instrumentation inst);          [1] 
public static void agentmain (String agentArgs);            [2]

同樣，[1] 的優先順序比 [2] 高，將會被優先執行。

跟 premain 函式一樣，開發者可以在 agentmain 中進行對類的各種操作。其中的 agentArgs 和 Inst 的用法跟 premain 相同。

與“Premain-Class”類似，開發者必須在 manifest 檔案裡面設定“Agent-Class”來指定包含 agentmain 函式的類。

可是，跟 premain 不同的是，agentmain 需要在 main 函式開始執行後才啟動，這樣的時機應該如何確定呢，這樣的功能又如何實現呢？

在 Java SE 6 文件當中，開發者也許無法在 java.lang.instrument 包相關的文件部分看到明確的介紹，更加無法看到具體的應用 agnetmain 的例子。不過，在 Java SE 6 的新特性裡面，有一個不太起眼的地方，揭示了 agentmain 的用法。這就是 Java SE 6 當中提供的 Attach API。

Attach API 不是 Java 的標準 API，而是 Sun 公司提供的一套擴充套件 API，用來向目標 JVM ”附著”（Attach）代理工具程式的。有了它，開發者可以方便的監控一個 JVM，執行一個外加的代理程式。

Attach API 很簡單，只有 2 個主要的類，都在 com.sun.tools.attach 包裡面： VirtualMachine 代表一個 Java 虛擬機器，也就是程式需要監控的目標虛擬機器，提供了 JVM 列舉，Attach 動作和 Detach 動作（Attach 動作的相反行為，從 JVM 上面解除一個代理）等等 ; VirtualMachineDescriptor 則是一個描述虛擬機器的容器類，配合 VirtualMachine 類完成各種功能。

為了簡單起見，我們舉例簡化如下：依然用類檔案替換的方式，將一個返回 1 的函式替換成返回 2 的函式，Attach API 寫在一個執行緒裡面，用睡眠等待的方式，每隔半秒時間檢查一次所有的 Java 虛擬機器，當發現有新的虛擬機器出現的時候，就呼叫 attach 函式，隨後再按照 Attach API 文件裡面所說的方式裝載 Jar 檔案。等到 5 秒鐘的時候，attach 程式自動結束。而在 main 函式裡面，程式每隔半秒鐘輸出一次返回值（顯示出返回值從 1 變成 2）。

TransClass 類和 Transformer 類的程式碼不變，參看上一節介紹。 含有 main 函式的 TestMainInJar 程式碼為：

public class TestMainInJar { 
   public static void main(String[] args) throws InterruptedException { 
       System.out.println(new TransClass().getNumber()); 
       int count = 0; 
       while (true) { 
           Thread.sleep(500); 
           count++; 
           int number = new TransClass().getNumber(); 
           System.out.println(number); 
           if (3 == number || count >= 10) { 
               break; 
           } 
       } 
   } 
}

含有 agentmain 的 AgentMain 類的程式碼為：

import java.lang.instrument.ClassDefinition; 
import java.lang.instrument.Instrumentation; 
import java.lang.instrument.UnmodifiableClassException; 
 
public class AgentMain { 
   public static void agentmain(String agentArgs, Instrumentation inst) 
           throws ClassNotFoundException, UnmodifiableClassException, 
           InterruptedException { 
       inst.addTransformer(new Transformer (), true); 
       inst.retransformClasses(TransClass.class); 
       System.out.println("Agent Main Done"); 
   } 
}

其中，retransformClasses 是 Java SE 6 裡面的新方法，它跟 redefineClasses 一樣，可以批量轉換類定義，多用於 agentmain 場合。

Jar 檔案跟 Premain 那個例子裡面的 Jar 檔案差不多，也是把 main 和 agentmain 的類，TransClass，Transformer 等類放在一起，打包為“TestInstrument1.jar”，而 Jar 檔案當中的 Manifest 檔案為 :

Manifest-Version: 1.0
Agent-Class: AgentMain

另外，為了執行 Attach API，我們可以再寫一個控制程式來模擬監控過程：（程式碼片段）

import com.sun.tools.attach.VirtualMachine; 
 import com.sun.tools.attach.VirtualMachineDescriptor; 
……
 // 一個執行 Attach API 的執行緒子類
 static class AttachThread extends Thread { 
         
 private final List<VirtualMachineDescriptor> listBefore; 
 
        private final String jar; 
 
        AttachThread(String attachJar, List<VirtualMachineDescriptor> vms) { 
            listBefore = vms;  // 記錄程式啟動時的 VM 集合
            jar = attachJar; 
        } 
 
        public void run() { 
            VirtualMachine vm = null; 
            List<VirtualMachineDescriptor> listAfter = null; 
            try { 
                int count = 0; 
                while (true) { 
                    listAfter = VirtualMachine.list(); 
                    for (VirtualMachineDescriptor vmd : listAfter) { 
                        if (!listBefore.contains(vmd)) { 
 // 如果 VM 有增加，我們就認為是被監控的 VM 啟動了
 // 這時，我們開始監控這個 VM 
                            vm = VirtualMachine.attach(vmd); 
                            break; 
                        } 
                    } 
                    Thread.sleep(500); 
                    count++; 
                    if (null != vm || count >= 10) { 
                        break; 
                    } 
                } 
                vm.loadAgent(jar); 
                vm.detach(); 
            } catch (Exception e) { 
                 ignore 
            } 
        } 
    } 
……
 public static void main(String[] args) throws InterruptedException {    
     new AttachThread("TestInstrument1.jar", VirtualMachine.list()).start(); 
 
 }

執行時，可以首先執行上面這個啟動新執行緒的 main 函式，然後，在 5 秒鐘內（僅僅簡單模擬 JVM 的監控過程）執行如下命令啟動測試 Jar 檔案 :

java – javaagent:TestInstrument2.jar – cp TestInstrument2.jar TestMainInJar

如果時間掌握得不太差的話，程式首先會在螢幕上打出 1，這是改動前的類的輸出，然後會打出一些 2，這個表示 agentmain 已經被 Attach API 成功附著到 JVM 上，代理程式生效了，當然，還可以看到“Agent Main Done”字樣的輸出。

以上例子僅僅只是簡單示例，簡單說明這個特性而已。真實的例子往往比較複雜，而且可能執行在分散式環境的多個 JVM 之中。

Java SE 6 新特性：BootClassPath / SystemClassPath 的動態增補

我們知道，通過設定系統引數或者通過虛擬機器啟動引數，我們可以設定一個虛擬機器執行時的 boot class 載入路徑（-Xbootclasspath）和 system class（-cp）載入路徑。當然，我們在執行之後無法替換它。然而，我們也許有時候要需要把某些 jar 載入到 bootclasspath 之中，而我們無法應用上述兩個方法；或者我們需要在虛擬機器啟動之後來載入某些 jar 進入 bootclasspath。在 Java SE 6 之中，我們可以做到這一點了。

實現這幾點很簡單，首先，我們依然需要確認虛擬機器已經支援這個功能，然後在 premain/agantmain 之中加上需要的 classpath。我們可以在我們的 Transformer 裡使用 appendToBootstrapClassLoaderSearch/appendToSystemClassLoaderSearch 來完成這個任務。

同時我們可以注意到，在 agent 的 manifest 里加入 Boot-Class-Path 其實一樣可以在動態地載入 agent 的同時加入自己的 boot class 路徑，當然，在 Java code 中它可以更加動態方便和智慧地完成 —— 我們可以很方便地加入判斷和選擇成分。

在這裡我們也需要注意幾點。首先，我們加入到 classpath 的 jar 檔案中不應當帶有任何和系統的 instrumentation 有關的系統同名類，不然，一切都陷入不可預料之中 —— 這不是一個工程師想要得到的結果，不是嗎？

其次，我們要注意到虛擬機器的 ClassLoader 的工作方式，它會記載解析結果。比如，我們曾經要求讀入某個類 someclass，但是失敗了，ClassLoader 會記得這一點。即使我們在後面動態地加入了某一個 jar，含有這個類，ClassLoader 依然會認為我們無法解析這個類，與上次出錯的相同的錯誤會被報告。

再次我們知道在 Java 語言中有一個系統引數“java.class.path”，這個 property 裡面記錄了我們當前的 classpath，但是，我們使用這兩個函式，雖然真正地改變了實際的 classpath，卻不會對這個 property 本身產生任何影響。

在公開的 JavaDoc 中我們可以發現一個很有意思的事情，Sun 的設計師們告訴我們，這個功能事實上依賴於 ClassLoader 的 appendtoClassPathForInstrumentation 方法 —— 這是一個非公開的函式，因此我們不建議直接（使用反射等方式）使用它，事實上，instrument 包裡的這兩個函式已經可以很好的解決我們的問題了。

結語

從以上的介紹我們可以得出結論，在 Java SE 6 裡面，instrumentation 包新增的功能 —— 虛擬機器啟動後的動態 instrument、原生程式碼（native code）instrumentation，以及動態新增 classpath 等等，使得 Java 具有了更強的動態控制、解釋能力，從而讓 Java 語言變得更加靈活多變。

這些能力，從某種意義上開始改變 Java 語言本身。在過去很長的一段時間內，動態 指令碼語言的大量湧現和快速發展，對整個軟體業和網路業提高生產率起到了非常重要的作用。在這種背景之下，Java 也正在慢慢地作出改變。而 Instrument 的新功能和 Script 平臺（本系列的後面一篇中將介紹到這一點）的出現，則大大強化了語言的動態化和與動態語言融合，它是 Java 的發展的值得考量的新趨勢。

轉自：https://www.ibm.com/developerworks/cn/java/j-lo-jse61/index.html

相關文章