軟體套件 java.lang.instrument

提供允許 Java 程式語言代理檢測運行在 JVM 上的程序的服務。

請參見：
描述

介面摘要

ClassFileTransformer	一個提供此介面的實作以轉換類別檔案的代理。
Instrumentation	此類別提供檢測 Java 程式語言程式碼所需的服務。

類別摘要

ClassDefinition

此類別用作 Instrumentation.redefineClasses 方法的參數鎖定。

異常摘要

IllegalClassFormatException	當其輸入參數無效時，由 ClassFileTransformer.transform 的實作拋出該異常。
UnmodifiableClassException	在無法修改指定類別之一時，由 Instrumentation.redefineClasses 的實作拋出此異常。

軟體套件 java.lang.instrument 的描述

提供允許 Java 程式語言代理檢測運行在 JVM 上的程序的服務。檢測機制是對方法的位元組碼進行修改。

套件規範

代理被部署為 JAR 檔案。JAR 檔案清單中的屬性指定將被載入以啟動代理的代理類別。對於支持命令行介面的實作，可以在命令行指定一個選項來啟動代理。實作也支持在 VM 啟動後某一時刻啟動代理的機制。例如，實作可以提供一種機制，允許某種工具連接 到運行的應用程序，並將該工具代理的載入初啟到該應用程序中。如何初啟載入的細節與實作有關。

命令行介面

對於使用命令行介面的實作，可以將以下選項添加到命令行來啟動代理：

-javaagent:jarpath[=options]

jarpath 是代理 JAR 檔案的路徑。 options 是代理選項。 此開關可以在同一程式碼行使用多次，從而創建多個代理。 多個代理可以使用相同的 jarpath。 代理 JAR 檔案必須遵守 JAR 檔案規範。

代理 JAR 檔案的清單必須包含 Premain-Class 屬性。此屬性的值是代理類別 的名稱。代理類別必須實作公共靜態 premain 方法，該方法的原理與 main 應用程序入口點類似。在 Java 虛擬機器 (JVM) 初始化後，每個 premain 方法將按照指定代理的順序調用，然後將調用實際的應用程序 main 方法。每個 premain 方法必須按照依次進行的啟動順序返回。

premain 方法有兩種可能的簽章。JVM 首先嘗試在代理類別上調用以下方法：

public static void premain(String agentArgs, Instrumentation inst);

如果代理類別沒有實作此方法，那麼 JVM 將嘗試調用：

public static void premain(String agentArgs);

如果代理在 VM 啟動之後啟動，那麼代理類別還有一個要使用的 agentmain 方法。如果是使用命令行選項啟動代理，那麼 agentmain 方法將不會被調用。

代理類別將被系統類別載入器載入（參見 ClassLoader.getSystemClassLoader）。系統類別載入器是通常載入包含應用程序 main 方法的類別的類別載入器。 premain 方法將在與應用程序 main 方法相同的安全性和類別載入器規則下運行。不存在代理 premain 方法可以執行的建模限制。任何應用程序 main 可以執行的事情（包括創建執行緒）對於 premain 都是合法的。

每個代理通過 agentArgs 參數傳遞其代理選項。代理選項作為單個字元串傳遞，任何其他解析應由代理本身執行。

如果該代理不能被解析（例如，由於無法載入代理類別，或者代理類別沒有恰當的 premain 方法），那麼 JVM 將中止。如果 premain 方法拋出未捕獲的異常，那麼 JVM 將中止。

VM 啟動後啟動代理

實作可以提供一種機制在 VM 啟動之後某一時刻啟動代理。如何初啟的細節是特定於實作的，但通常應用程序已經啟動並且其 main 方法已經調用。如果實作支持在 VM 啟動之後啟動代理，則以下內容適用：

1. 代理 JAR 的清單必須包含屬性 Agent-Class。此屬性的值是代理類別 的名稱。

2. 代理類別必須實作公共靜態 agentmain 方法。

3. 系統類別載入器（ClassLoader.getSystemClassLoader）必須支持將代理 JAR 檔案添加到系統類別路徑的機制。

代理 JAR 將被添加到系統類別路徑。系統類別路徑是通常載入包含應用程序 main 方法的類別的類別路徑。代理類別將被載入，JVM 嘗試調用 agentmain 方法。JVM 首先嘗試對代理類別調用以下方法：

public static void agentmain(String agentArgs, Instrumentation inst);

如果代理類別沒有實作此方法，那麼 JVM 將嘗試調用：

public static void agentmain(String agentArgs);

如果代理是使用命令行選項啟動的，那麼代理類別還有一個要使用的 agentmain 方法。如果是在 VM 啟動之後啟動代理，那麼 agentmain 方法將不會被調用。

代理通過 agentArgs 參數傳遞其代理選項。代理選項作為單個字元串傳遞，任何其它解析應該由代理本身執行。

agentmain 方法應該執行任何啟動代理所需的初始化。啟動完成時該方法應返回。如果代理無法啟動（例如，由於無法載入代理類別，或者代理類別沒有建構 agentmain 方法），那麼 JVM 將中止。如果 agentmain 方法拋出未捕獲的異常，那麼它將被忽略。

清單屬性

以下清單屬性是針對代理 JAR 檔案定義的：

Premain-Class

如果 JVM 啟動時指定了代理，那麼此屬性指定代理類別，即包含 premain 方法的類別。如果 JVM 啟動時指定了代理，那麼此屬性是必需的。如果該屬性不存在，那麼 JVM 將中止。註：此屬性是類別名，不是檔案名或路徑。

Agent-Class

如果實作支持 VM 啟動之後某一時刻啟動代理的機制，那麼此屬性指定代理類別。 即包含 agentmain 方法的類別。 此屬性是必需的，如果不存在，代理將無法啟動。 註：這是類別名，而不是檔案名或路徑。

Boot-Class-Path

由引導類別載入器搜尋的路徑列表。路徑表示目錄或資源庫（在許多平臺上通常作為 JAR 或 zip 資源庫被參考）。尋找類別的特定於平臺的機制失敗後，引導類別載入器會搜尋這些路徑。按列出的順序搜尋路徑。列表中的路徑由一個或多個空格分開。路徑使用分層 URI 的路徑元件語法。如果該路徑以斜槓字元（“/”）開頭，則為絕對路徑，否則為相對路徑。相對路徑根據代理 JAR 檔案的絕對路徑解析。忽略格式不正確的路徑和不存在的路徑。如果代理是在 VM 啟動之後某一時刻啟動的，則忽略不表示 JAR 檔案的路徑。此屬性是可選的。

Can-Redefine-Classes

布林值（true 或 false，與大小寫無關）。是否能重定義此代理所需的類別。true 以外的值均被視為 false。此屬性是可選的，預設值為 false。

Can-Retransform-Classes

布林值（true 或 false，與大小寫無關）。是否能重轉換此代理所需的類別。true 以外的值均被視為 false。此屬性是可選的，預設值為 false。

Can-Set-Native-Method-Prefix

布林值（true 或 false，與大小寫無關）。是否能設置此代理所需的本機方法前綴。true 以外的值均被視為 false。此屬性是可選的，預設值為 false。

代理 JAR 檔案在清單中可以同時出現 Premain-Class 和 Agent-Class 屬性。如果代理是使用 -javaagent 選項在命令行上啟動的，那麼 Premain-Class 屬性指定代理類別的名稱，Agent-Class 屬性將被忽略。類似地，如果代理是在 VM 啟動後某一時刻啟動的，那麼 Agent-Class 屬性指定代理類別的名稱（Premain-Class 屬性的值將被忽略）。

相關文檔

有關工具文檔的資訊，請參閱：

• JDK Tools and Utilities

從以下版本開始：

JDK1.5