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 函數運行前執行。簡要說來就是如下幾個步驟：

編寫 premain 函數

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

1. 其中，[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 類文件的操作，可以理解為對一個 byte 數組的操作（將類文件的二進制字節流讀入一個 byte 數組）。開發者可以在“ClassFileTransformer”的 transform 方法當中得到，操作并最終返回一個類的定義（一個 byte 數組）。這方面，Apache 的 BCEL 開源項目提供了強有力的支持，讀者可以在參考文章“Java SE 5 特性 Instrumentation 實踐”中看到一個 BCEL 和 Instrumentation 結合的例子。具體的字節碼操作并非本文的重點，所以，本文中所舉的例子，只是采用簡單的類文件替換的方式來演示 Instrumentation 的使用。

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

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

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

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

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

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

這個類實現了 ClassFileTransformer 接口。其中，getBytesFromFile 方法根據文件名讀入二進制字符流，而 ClassFileTransformer 當中規定的 transform 方法則完成了類定義的替換轉換。

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

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

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

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

則會得到輸出“2”。

當然，程序運行的 main 函數不一定要放在 premain 所在的這個 jar 文件里面，這里只是為了例子程序打包的方便而放在一起的。

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

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 類：

同樣，[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 代碼為：

含有 agentmain 的 AgentMain 類的代碼為：

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

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

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


運行時，可以首先運行上面這個啟動新線程的 main 函數，然后，在 5 秒鐘內（僅僅簡單模擬 JVM 的監控過程）運行如下命令啟動測試 Jar 文件:

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

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

回頁首

Java SE 6 新特性：本地方法的 Instrumentation

在 1.5 版本的 instumentation 里，并沒有對 Java 本地方法（Native Method）的處理方式，而且在 Java 標準的 JVMTI 之下，并沒有辦法改變 method signature， 這就使替換本地方法非常地困難。一個比較直接而簡單的想法是，在啟動時替換本地代碼所在的動態鏈接庫 —— 但是這樣，本質上是一種靜態的替換，而不是動態的 Instrumentation。而且，這樣可能需要編譯較大數量的動態鏈接庫 —— 比如，我們有三個本地函數，假設每一個都需要一個替換，而在不同的應用之下，可能需要不同的組合，那么如果我們把三個函數都編譯在同一個動態鏈接庫之中， 最多我們需要 8 個不同的動態鏈接庫來滿足需要。當然，我們也可以獨立地編譯之，那樣也需要 6 個動態鏈接庫——無論如何，這種繁瑣的方式是不可接受的。

在 Java SE 6 中，新的 Native Instrumentation 提出了一個新的 native code 的解析方式，作為原有的 native method 的解析方式的一個補充，來很好地解決了一些問題。這就是在新版本的 java.lang.instrument 包里，我們擁有了對 native 代碼的 instrument 方式 —— 設置 prefix。

假設我們有了一個 native 函數，名字叫 nativeMethod，在運行中過程中，我們需要將它指向另外一個函數（需要注意的是，在當前標準的 JVMTI 之下，除了 native 函數名，其他的 signature 需要一致）。比如我們的 Java 代碼是：

那么我們已經實現的本地代碼是:
現在我們需要在調用這個函數時，使之指向另外一個函數。那么按照 J2SE 的做法，我們可以按他的命名方式，加上一個 prefix 作為新的函數名。比如，我們以 "another_" 作為 prefix，那么我們新的函數是:

然后將之編入動態鏈接庫之中。

現在我們已經有了新的本地函數，接下來就是做 instrument 的設置。正如以上所說的，我們可以使用 premain 方式，在虛擬機啟動之時就載入 premain 完成 instrument 代理設置。也可以使用 agentmain 方式，去 attach 虛擬機來啟動代理。而設置 native 函數的也是相當簡單的:

在這里要注意兩個問題。一是不是在任何的情況下都是可以設置 native 函數的 prefix 的。首先，我們要注意到 agent 包之中的 Manifest 所設定的特性:

要注意，這一個參數都可以影響是否可以設置 native prefix，而且，在默認的設置之中，這個參數是 false 的，我們需要將之設置成 true（順便說一句，對 Manifest 之中的屬性來說都是大小寫無關的，當然，如果給一個不是“true”的值，就會被當作 false 值處理）。

當然，我們還需要確認虛擬機本身是否支持 setNativePrefix。在 Java API 里，Instrumentation 類提供了一個函數 isNativePrefix，通過這個函數我們可以知道該功能是否可以實行。

二 是我們可以為每一個 ClassTransformer 加上它自己的 nativeprefix；同時，每一個 ClassTransformer 都可以為同一個 class 做 transform，因此對于一個 Class 來說，一個 native 函數可能有不同的 prefix，因此對這個函數來說，它可能也有好幾種解析方式。

在 Java SE 6 當中，Native prefix 的解釋方式如下：對于某一個 package 內的一個 class 當中的一個 native method 來說，首先，假設我們對這個函數的 transformer 設置了 native 的 prefix“another”，它將這個函數接口解釋成:

由 Java 的函數接口

和上述 prefix"another"，去尋找本地代碼中的函數
一旦可以找到，那么調用這個函數，整個解析過程就結束了；如果沒有找到，那么虛擬機將會做進一步的解析工作。我們將利用 Java native 接口最基本的解析方式,去找本地代碼中的函數:

如果找到，則執行之。否則，因為沒有任何一個合適的解析方式，于是宣告這個過程失敗。

那么如果有多個 transformer，同時每一個都有自己的 prefix，又該如何解析呢？事實上，虛擬機是按 transformer 被加入到的 Instrumentation 之中的次序去解析的（還記得我們最基本的 addTransformer 方法嗎？）。

假 設我們有三個 transformer 要被加入進來，他們的次序和相對應的 prefix 分別為：transformer1 和“prefix1_”，transformer2 和 “prefix2_”，transformer3 和 “prefix3_”。那么，虛擬機會首先做的就是將接口解析為:

然后去找它相對應的 native 代碼。

但是如果第二個 transformer（transformer2）沒有設定 prefix，那么很簡單，我們得到的解析是：

這個方式簡單而自然。

當然，對于多個 prefix 的情況，我們還要注意一些復雜的情況。比如，假設我們有一個 native 函數接口是：

然后我們為它設置了兩個 prefix，比如 "wrapped_" 和 "wrapped2_"，那么，我們得到的是什么呢？是
嗎？答案是否定的，因為事實上，對 Java 中 native 函數的接口到 native 中的映射，有一系列的規定，因此可能有一些特殊的字符要被代入。而實際中，這個函數的正確的函數名是：

很有趣不是嗎？因此如果我們要做類似的工作，一個很好的建議是首先在 Java 中寫一個帶 prefix 的 native 接口，用 javah 工具生成一個 c 的 header-file，看看它實際解析得到的函數名是什么，這樣我們就可以避免一些不必要的麻煩。

另外一個事實是，與我們的想像不同，對于兩個或者兩個以上的 prefix，虛擬機并不做更多的解析；它不會試圖去掉某一個 prefix，再來組裝函數接口。它做且僅作兩次解析。

總 之，新的 native 的 prefix-instrumentation 的方式，改變了以前 Java 中 native 代碼無法動態改變的缺點。在當前，利用 JNI 來寫 native 代碼也是 Java 應用中非常重要的一個環節，因此它的動態化意味著整個 Java 都可以動態改變了 —— 現在我們的代碼可以利用加上 prefix 來動態改變 native 函數的指向，正如上面所說的，如果找不到，虛擬機還會去嘗試做標準的解析，這讓我們擁有了動態地替換 native 代碼的方式，我們可以將許多帶不同 prefix 的函數編譯在一個動態鏈接庫之中，而通過 instrument 包的功能，讓 native 函數和 Java 函數一樣動態改變、動態替換。

當然，現在的 native 的 instrumentation 還有一些限制條件，比如，不同的 transformer 會有自己的 native prefix，就是說，每一個 transformer 會負責他所替換的所有類而不是特定類的 prefix —— 因此這個粒度可能不夠精確。

回頁首

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 的發展的值得考量的新趨勢。

---

盡管千里冰封
依然擁有晴空

你我共同品味JAVA的濃香.