java.lang.instrument
介面 ClassFileTransformer

public interface ClassFileTransformer

一個提供此介面的實作以轉換類別檔案的代理。轉換在 JVM 定義類別之前發生。

注意，根據 The Java Virtual Machine Specification 的 The class File Format 一章中的定義使用術語類別檔案，它指以類別檔案格式表示的位元組序列，無論這些字元是否駐留在檔案中。

從以下版本開始：

1.5

另請參見：

Instrumentation, Instrumentation.addTransformer(java.lang.instrument.ClassFileTransformer, boolean), Instrumentation.removeTransformer(java.lang.instrument.ClassFileTransformer)

方法摘要

byte[]

transform(ClassLoader loader, String className, Class<?> classBeingRedefined, ProtectionDomain protectionDomain, byte[] classfileBuffer) 此方法的實作可以轉換提供的類別檔案，並返回一個新的替換類別檔案。

方法詳細資訊

transform

byte[] transform(ClassLoader loader,
                 String className,
                 Class<?> classBeingRedefined,
                 ProtectionDomain protectionDomain,
                 byte[] classfileBuffer)
                 throws IllegalClassFormatException

此方法的實作可以轉換提供的類別檔案，並返回一個新的替換類別檔案。

有兩種裝換器，由 Instrumentation.addTransformer(ClassFileTransformer,boolean) 的 canRetransform 參數確定：

• 可重轉換 轉換器，將 canRetransform 設為 true 可添加這種轉換器
• 不可重轉換 轉換器，將 canRetransform 設為 false 或者使用 Instrumentation.addTransformer(ClassFileTransformer) 可添加這種轉換器

在轉換器使用 addTransformer 註冊之後，每次定義新類別和重定義類別時都將調用該轉換器。每次重轉換類別時還將調用可重轉換轉換器。對新類別定義的請求通過 ClassLoader.defineClass 或其本機等價方法進行。對類別重定義的請求通過 Instrumentation.redefineClasses 或其本機等價方法進行。對類別重轉換的請求將通過 Instrumentation.retransformClasses 或其本機等價方法進行。轉換器是在驗證或應用類別檔案位元組之前的請求處理過程中調用的。 當存在多個轉換器時，轉換將由 transform 調用鏈組成。 也就是說，一個 transform 調用返回的 byte 陣列將成為下一個調用的輸入（通過 classfileBuffer 參數）。

轉換將按以下順序應用：

• 不可重轉換轉換器
• 不可重轉換本機轉換器
• 可重轉換轉換器
• 可重轉換本機轉換器

對於重轉換，不會調用不可重轉換轉換器，而是重用前一個轉換的結果。對於所有其他情況，調用此方法。在每個這種調用組中，轉換器將按照註冊的順序調用。本機轉換器由 Java 虛擬機器 Tool 介面中的 ClassFileLoadHook 事件提供。

第一個轉換器的輸入（通過 classfileBuffer 參數）如下：

• 對於新的類別定義，是傳遞給 ClassLoader.defineClass 的 byte
• 對於類別重定義，是 definitions.getDefinitionClassFile()，其中 definitions 是 Instrumentation.redefineClasses 的參數
• 對於類別重轉換，是傳遞給新類別定義的 byte，或者是最後一個重定義（如果有重定義），所有不可轉換轉換器進行的轉換都將自動重新應用並保持不變；有關細節，請參閱 Instrumentation.retransformClasses

如果實作方法確定不需要進行轉換，則應返回 null。否則，它將創建一個新的 byte[] 陣列，將輸入 classfileBuffer 連同所有需要的轉換複製到其中，並返回這個新陣列。不得修改輸入 classfileBuffer。

在重轉換和重定義中，轉換器必須支持重定義語義：如果轉換器在初始定義期間更改的類別在以後要重轉換或重定義，那麼轉換器必須確保第二個輸出類別檔案是第一個輸出類別檔案的合法重定義檔案。

如果轉換器拋出異常（未捕獲的異常），後續轉換器仍然將被調用並載入，仍然將嘗試重定義或重轉換。因此，拋出異常與返回 null 的效果相同。若要使用轉換器程式碼在產生未檢驗異常時防止不希望發生的行為，可以讓轉換器捕獲 Throwable。 如果轉換器認為 classFileBuffer 不表示一個有效格式的類別檔案，則將拋出 IllegalClassFormatException；儘管這與返回 null 的效果相同，但它便於對格式毀壞進行記錄或除錯。

參數：

loader - 定義要轉換的類別載入器；如果是引導載入器，則為 null

className - 完全限定類別內部形式的類別名稱和 The Java Virtual Machine Specification 中定義的介面名稱。例如，"java/util/List"。

classBeingRedefined - 如果是被重定義或重轉換觸發，則為重定義或重轉換的類別；如果是類別載入，則為 null

protectionDomain - 要定義或重定義的類別的保護域

classfileBuffer - 類別檔案格式的輸入位元組緩衝區（不得修改）

返回：

一個格式良好的類別檔案緩衝區（轉換的結果），如果未執行轉換,則返回 null。

拋出：

IllegalClassFormatException - 如果輸入不表示一個格式良好的類別檔案

另請參見：

Instrumentation.redefineClasses(java.lang.instrument.ClassDefinition...)