javax.management
介面 Descriptor

所有父級介面：

Cloneable, Serializable

所有已知實作類別：

DescriptorSupport, ImmutableDescriptor

public interface Descriptor
extends Serializable, Cloneable

JMX 元素的附加元資料。Descriptor 與 MBeanInfo、MBeanAttributeInfo 等關聯。它由一個欄位集合組成。欄位由一個名稱和一個關聯值組成。

欄位名稱不區分大小寫。名稱 descriptorType、descriptortype 和 DESCRIPTORTYPE 都是等效的。但是，第一次設置欄位時所使用的大小寫將保留在 getFields() 和 getFieldNames() 方法的結果中。

並非所有的欄位名稱和值都可以預定義。任何程序都可以定義和添加新欄位。

描述符可以是可變的，也可以是不可變的。不可變的描述符一旦創建就不能更改。對於不可變的描述符，可以修改描述符內容的 Descriptor 方法將拋出異常。不可變的描述符通常是 ImmutableDescriptor 或子類別的實例。可變描述符通常是 DescriptorSupport 或子類別的實例。

某些欄位由 JMX 實作使用。這意味著這類別欄位的存在可以改變 JMX API 的行為，或者可以在 JMX API 返回的描述符中設置這類別欄位。這些欄位在下表中將以斜體 形式出現，每個欄位在 JMX 類別中都有一個相應的常數。例如，欄位 defaultValue 由常數 JMX.DEFAULT_VALUE_FIELD 表示。

在下表中描述了某些其他欄位的常規含意，但 JMX 實作不必瞭解或設置它們。

在此版本或所有未來版本中由 JMX 規範定義的欄位名稱將永遠不會包含句點 (.)。通過在名稱中包含句點，使用者可以安全地創建自己的欄位，並能確保這些名稱不會與任何將來的 JMX API 版本相衝突。建議遵循 Java 套件命名約定以避免不同來源的欄位名稱發生衝突。例如，由 example.com 創建的欄位可能有名稱 com.example.interestLevel。

注意，defaultValue、legalValues、maxValue 和 minValue 欄位中的值應該與對關聯的 MBeanAttributeInfo 或 MBeanParameterInfo 調用 getType() 方法所返回的型別一致。對於 MXBean，這意味著它們應該屬於映射的 Java 型別，該型別在 MXBean 型別映射規則中稱作 opendata(J)。

名稱	型別	使用範圍	含義
defaultValue	Object	MBeanAttributeInfo MBeanParameterInfo	屬性或參數的預設值。請參閱 javax.management.openmbean。
deprecated	String	所有	建議不再使用此資訊模型元素的指示。應用程序定義的一組 MBean 總稱為資訊模型。此欄位值的慣例是包含一個字元串，該字元串中首先是元素第一次被廢棄時的模型版本，後跟空格，然後是對廢棄的解釋，例如 "1.3 Replaced by the Capacity attribute"。
descriptionResource BundleBaseName	String	所有	ResourceBundle 的基本名稱，可以在該 ResourceBundle 中找到在 descriptionResourceKey 欄位中給定的鍵，例如 "com.example.myapp.MBeanResources"。此欄位的含義由此規範定義，但 JMX API 本身不會設置或使用該欄位。
descriptionResourceKey	String	所有	描述此元素的資源鍵。它可以與 descriptionResourceBundleBaseName 一起使用來尋找描述的本地化版本。此欄位的含義由此規範定義，但 JMX API 本身不會設置或使用該欄位。
enabled	String	MBeanAttributeInfo MBeanNotificationInfo MBeanOperationInfo	根據此項啟用與否，決定字元串為 "true" 或 "false"。不啟用屬性或操作時，它仍存在，但當前無法存取。使用者介面可能將其表示為灰色項。例如，只有調用了 MBean 的 start() 方法後屬性才可能有意義，否則它將被禁用。同樣，如果當前無法發出通知但其他情況下可以發出時，則它可能被禁用。
immutableInfo	String	MBeanInfo	根據此 MBean 的 MBeanInfo 是否為不可變，決定字元串為 "true" 或 "false"。此欄位為 true 時，可以保證給定 MBean 的 MBeanInfo 不會隨 MBean 的生存期而更改。因此，客戶端可以對其進行一次讀取並快取記憶體讀取值。此欄位為 false 或不存在時，則無法提供這樣的保證，雖然這並不意味著 MBeanInfo 一定發生變化。
infoTimeout	String Long	MBeanInfo	MBeanInfo 理應不會更改的時間，以毫秒為單位。該值可以是 Long，也可以是十進制字元串。這從 DynamicMBean 或任何沒有將 immutableInfo 定義為 true 的 MBean 中得出一個提示，MBeanInfo 不可能在此期間發生變化，因此可以快取記憶體。此欄位丟失或具有 0 值時，不建議快取記憶體 MBeanInfo，除非它將 immutableInfo 設置為 true。
interfaceClassName	String	MBeanInfo	Standard MBean 或 MXBean 的 Java 介面名稱，由 Class.getName() 返回。直接在 MBean Server 中註冊或使用 StandardMBean 類別創建的 Standard MBean 或 MXBean 將在其 MBeanInfo Descriptor 中包含此欄位。
legalValues	Set<?>	MBeanAttributeInfo MBeanParameterInfo	屬性或參數的合法值。請參閱 javax.management.openmbean。
maxValue	Object	MBeanAttributeInfo MBeanParameterInfo	屬性或參數的最大合法值。請參閱 javax.management.openmbean。
metricType	String	MBeanAttributeInfo MBeanOperationInfo	規格的型別，字元串 "counter" 或 "gauge" 之一。規格是由 MBean 導出的尺度，通常是一個屬性，但有時是操作的結果。作為 counter 的規格有一個永遠不會減少的值，除了將其重置為初始值之外。計數器規格幾乎總是為非負整數。例如接收到的請求數。作為 gauge 的規格有一個可以增加或減少的數字值。例如打開的連接數、快取記憶體命中率、讀取的溫度。
minValue	Object	MBeanAttributeInfo MBeanParameterInfo	屬性或參數的最小合法值。請參閱 javax.management.openmbean。
mxbean	String	MBeanInfo	根據此 MBean 是否為 MXBean，決定字元串為 &quot;true&quot; 或 &quot;false&quot;。直接在 MBean Server 中註冊或使用 StandardMBean 類別創建的 Standard MBean 或 MXBean 將在其 MBeanInfo Descriptor 中包含此欄位。
openType	OpenType	MBeanAttributeInfo MBeanOperationInfo MBeanParameterInfo	此元素的開放型別。在 MBeanAttributeInfo 和 MBeanParameterInfo 的情況下，它是屬性或參數的開放型別。在 MBeanOperationInfo 的情況下，它是返回值的開放型別。此欄位在 OpenMBeanAttributeInfoSupport、OpenMBeanOperationInfoSupport 和 OpenMBeanParameterInfoSupport 的所有實例的 Descriptor 中設置。它還可以為 MXBean 的屬性、操作和參數進行設置。 此欄位可以為 MBeanNotificationInfo 進行設置，在此情況下，它指示使用者資料將具有的開放型別。
originalType	String	MBeanAttributeInfo MBeanOperationInfo MBeanParameterInfo	此元素的原始 Java 型別，在產生此 MBeanAttributeInfo（等）的 MXBean 介面方法中顯示。例如，MXBean 介面中的方法 public MemoryUsage getHeapMemoryUsage(); 定義稱為 HeapMemoryUsage 的型別為 CompositeData 的屬性。此屬性的 Descriptor 中的 originalType 欄位將包含值 &quot;java.lang.management.MemoryUsage&quot;。 此字元串的格式將在 MXBean 規範的型別名稱一節中描述。
severity	String Integer	MBeanNotificationInfo	此通知的嚴重性。它可以為 0，表示嚴重性未知；也可以為 1 到 6 之間的值，表示遞減的嚴重性級別。它可以表示為十進制字元串或 Integer。
since	String	所有	引入此元素的資訊模型的版本。應用程序定義的一組 MBean 總稱為資訊模型。應用程序也可以定義此模型的版本，並且使用 &quot;since&quot; 欄位來記錄元素第一次出現的版本。
units	String	MBeanAttributeInfo MBeanParameterInfo MBeanOperationInfo	測量屬性、參數或操作返回值的單位，如 &quot;bytes&quot; 或 &quot;seconds&quot;。

某些附加欄位由 Model MBean 定義。請參閱 ModelMBeanInfo 和相關的類別，以及 JMX 規範中的 "Model MBean" 一章。

從以下版本開始：

1.5

方法摘要

Object	clone() 返回一個與此描述符相等的描述符。
boolean	equals(Object obj) 將此描述符與給定物件比較。
String[]	getFieldNames() 返回描述符中的所有欄位名。
String[]	getFields() 以 string 陣列的形式返回此 descriptor 中所包含的所有欄位。
Object	getFieldValue(String fieldName) 返回指定欄位名的值，如果該名稱不存在任何值，則返回 null。
Object[]	getFieldValues(String... fieldNames) 以 Object 陣列的形式返回該 descriptor 中的所有欄位值。
int	hashCode() 返回此描述符的雜湊碼值。
boolean	isValid() 如果所有欄位在給定其名稱的情況下都有合法值，則返回 true。
void	removeField(String fieldName) 從該 descriptor 中刪除欄位。
void	setField(String fieldName, Object fieldValue) 設置特定欄位名的值。
void	setFields(String[] fieldNames, Object[] fieldValues) 將欄位名稱陣列中的所有欄位設置為與欄位值陣列中的索引相同的新值。

方法詳細資訊

getFieldValue

Object getFieldValue(String fieldName)
                     throws RuntimeOperationsException

返回指定欄位名的值，如果該名稱不存在任何值，則返回 null。

參數：

fieldName - 欄位名稱。

返回：

相應的值，如果欄位不存在，則返回 null。

拋出：

RuntimeOperationsException - 如果欄位名稱不合法。

setField

void setField(String fieldName,
              Object fieldValue)
              throws RuntimeOperationsException

設置特定欄位名的值。這將修改現有的欄位或添加一個新欄位。

設置前將驗證該欄位值。如果該值無效，則將拋出一個異常。有效性的含義依賴於描述符實作。

參數：

fieldName - 要設置的欄位的名稱。不能為 null 或空。

fieldValue - 針對該欄位名稱所設置的欄位值。如果 null 是欄位的有效值，則可以為 null。

拋出：

RuntimeOperationsException - 如果欄位名或欄位值不合法（包裹的異常為 IllegalArgumentException）；或者描述符不可變（包裹的異常為 UnsupportedOperationException）。

getFields

String[] getFields()

以 string 陣列的形式返回此 descriptor 中所包含的所有欄位。

返回：

各欄位的 String 陣列，格式為 fieldName=fieldValue。
如果欄位值不是一個 String，則對該值調用 toString() 方法並將返回值（用圓括號括起來）用作所返回陣列中欄位的值。如果欄位的值為 null，則返回陣列中的欄位值將為空。如果描述符為空，則將得到一個空陣列。

另請參見：

setFields(java.lang.String[], java.lang.Object[])

getFieldNames

String[] getFieldNames()

返回描述符中的所有欄位名。

返回：

欄位名稱的 String 陣列。如果描述符為空，則將得到一個空陣列。

getFieldValues

Object[] getFieldValues(String... fieldNames)

以 Object 陣列的形式返回該 descriptor 中的所有欄位值。返回值的順序與 fieldNames String 陣列參數的順序相同。

參數：

fieldNames - 欄位名稱的 String 陣列，應該返回這些欄位的值。如果該陣列為空，則將返回一個空陣列。如果陣列為 null，則將返回所有值，如同參數是 getFieldNames() 返回的陣列一樣。如果陣列中某個欄位名不存在（包括欄位名為 null 或空字元串的情況），則對於要返回的比對陣列元素，將返回 null。

返回：

欄位值的 Object 陣列。如果 fieldNames 列表為空，則將得到一個空陣列。

removeField

void removeField(String fieldName)

從該 descriptor 中刪除欄位。

參數：

fieldName - 要移除的欄位的 String 名稱。如果欄位名不合法或找不到欄位，則不拋出任何異常。

拋出：

RuntimeOperationsException - 如果存在給定名稱的欄位且描述符不可變。包裹的異常將是一個 UnsupportedOperationException。

setFields

void setFields(String[] fieldNames,
               Object[] fieldValues)
               throws RuntimeOperationsException

將欄位名稱陣列中的所有欄位設置為與欄位值陣列中的索引相同的新值。陣列大小必須是比對的。

設置前將驗證該欄位值。如果該值無效，則將拋出一個異常。如果陣列為空，則所有更改都將無效。

參數：

fieldNames - 欄位名稱的 String 陣列。陣列和陣列元素不能為 null。

fieldValues - 對應欄位值的 Object 陣列。陣列不能為 null。陣列的元素可以為 null。

拋出：

RuntimeOperationsException - 如果由於某種原因更改失敗。如果 fieldNames 或 fieldValues 為 null，或者陣列的長度不同，或者其中一個陣列存在非法值，則包裹的異常為 IllegalArgumentException。如果描述符不可變，且調用將更改其內容，則包裹的異常為 UnsupportedOperationException。

另請參見：

getFields()

clone

Object clone()
             throws RuntimeOperationsException

返回一個與此描述符相等的描述符。對返回的描述符進行的更改不影響此描述符，反之亦然。如果此描述符不可變，則將通過返回其本身來完成此條件。

返回：

一個與此描述符相等的描述符。

拋出：

RuntimeOperationsException - 如果欄位名或欄位值為非法值。如果描述符建構由於任何原因而失敗，都將拋出此異常。

isValid

boolean isValid()
                throws RuntimeOperationsException

如果所有欄位在給定其名稱的情況下都有合法值，則返回 true。

返回：

如果值是合法的，則返回 true。

拋出：

RuntimeOperationsException - 如果有效性檢查由於任何原因而失敗，都將拋出此異常。如果描述符無效，則該方法返回 false，但如果確定有效性的嘗試失敗，則將拋出此異常。

equals

boolean equals(Object obj)

將此描述符與給定物件比較。如果給定對象也是一個 Descriptor，並且如果兩個 Descriptor 具有相同的欄位名（可能有不同的情況）且有相同的關聯值，則物件相等。如果具備下列條件，則兩個 Descriptor 中欄位的各個值都相等：

• 如果一個值為 null，則其他值也必須為 null。
• 如果一個值是基本型別陣列，則其他值必須是同一型別的基本型別陣列，且具有相同的元素。
• 如果一個值是物件陣列，則其他值也必須是物件陣列，並且 Arrays.deepEquals(Object[],Object[]) 必須返回 true。
• 其他情況下，Object.equals(Object) 必須返回 true。

覆寫：

類別 Object 中的 equals

參數：

obj - 要與之比較的物件。

返回：

如果物件相等，則返回 true；否則，返回 false。

從以下版本開始：

1.6

另請參見：

Object.hashCode(), Hashtable

hashCode

int hashCode()

返回此描述符的雜湊碼值。該雜湊碼是描述符中每個欄位的雜湊碼的總和。具有名稱 n 和值 v 的欄位的雜湊碼是 n.toLowerCase().hashCode() ^ h。此處 h 是 v 的雜湊碼，計算方式如下：

• 如果 v 為 null，則 h 為 0。
• 如果 v 是基本型別陣列，則使用 java.util.Arrays.hashCode 的適當重載形式計算 h。
• 如果 v 是物件陣列，則使用 Arrays.deepHashCode(Object[]) 計算 h。
• 否則，h 為 v.hashCode()。

覆寫：

類別 Object 中的 hashCode

返回：

此物件的雜湊碼值。

從以下版本開始：

1.6

另請參見：

Object.equals(java.lang.Object), Hashtable