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 包中定義的一個接口，也是這個包的核心部分，集中了其中幾乎所有的功能方法，例如類定義的轉換和操作等等。
(2) jar 文件打包
將這個 Java 類打包成一個 jar 文件，并在其中的 manifest 屬性當中加入” Premain-Class”來指定步驟 1 當中編寫的那個帶有 premain 的 Java 類。（可能還需要指定其他屬性以開啟更多功能）
(3) 運行
用如下方式運行帶有 Instrumentation 的 Java 程序：
java -javaagent:jar 文件的位置 [= 傳入 premain 的參數 ]
對 Java 類文件的操作，可以理解為對一個 byte 數組的操作（將類文件的二進制字節流讀入一個 byte 數組）。開發者可以在“ClassFileTransformer”的 transform 方法當中得到，操作并最終返回一個類的定義（一個 byte 數組）。這方面，Apache 的 BCEL 開源項目提供了強有力的支持，具體的字節碼操作并非本文的重點，所以，本文中所舉的例子，只是采用簡單的類文件替換的方式來演示 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 的這個類文件命名為 TransClass2.class.2。
接下來，我們建立一個 Transformer 類：
import java.lang.instrument.ClassFileTransformer;
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 之中。