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() メソッドにより返される型と一致するようにしてください。MXBeans の場合、これは、MXBean 型マッピングルールで opendata(J) と呼ばれる、マップされた Java 型にすることを意味します。

名前	型	使用する場所	意味
defaultValue	Object	MBeanAttributeInfo MBeanParameterInfo	属性またはパラメータのデフォルト値。javax.management.openmbean を参照してください。
deprecated	String	Any	情報モデルのこの要素は、使用が推奨されなくなったことを示します。アプリケーションにより定義された MBeans のセットは、まとめて「情報モデル」と呼ばれます。規則では、このフィールド値の文字列には、要素が最初に非推奨になったモデルのバージョン、空白、非推奨の説明がこの順序で含められます。たとえば、"1.3 Capacity 属性を使用" となります。
descriptionResource BundleBaseName	String	Any	descriptionResourceKey フィールドに指定されたキーがある ResourceBundle のベース名。たとえば、"com.example.myapp.MBeanResources" となります。この指定によりフィールドの意味が定義されますが、このフィールドが JMX API 自体により設定または使用されることはありません。
descriptionResourceKey	String	Any	この要素の説明に対するリソースキー。これを 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 または 10 進数の文字列を使用できます。これにより、DynamicMBean または immutableInfo を true として定義しない任意の MBean から、この期間内には MBeanInfo が変更されない可能性が高いのでキャッシュ可能であるというヒントが与えられます。このフィールドが見つからないか値がゼロの場合は、immutableInfo が true に設定されないかぎり、MBeanInfo をキャッシュすることは推奨されません。
interfaceClassName	String	MBeanInfo	Class.getName() により返される、Standard MBean または MXBean の Java インタフェース名。Standard MBean、または MBean Server に直接登録されるか StandardMBean クラスを使って作成された MXBean には、MBeanInfo Descriptor 内にこのフィールドがあります。
legalValues	Set<?>	MBeanAttributeInfo MBeanParameterInfo	属性またはパラメータの有効な値。javax.management.openmbean を参照してください。
maxValue	Object	MBeanAttributeInfo MBeanParameterInfo	属性またはパラメータの有効な最大値。javax.management.openmbean を参照してください。
metricType	String	MBeanAttributeInfo MBeanOperationInfo	メトリックのタイプ。文字列 "counter" と "gauge"のいずれかになります。メトリックは、MBean によりエクスポートされる計測です。通常は属性ですが、オペレーションの結果である場合もあります。「カウンタ」であるメトリックの値は、開始値にリセットしないかぎり、決して減少することがありません。カウンタメトリックスは、ほとんどの場合、負でない整数になります。たとえば、受信した要求の数がこれに該当します。「ゲージ」であるメトリックは、増加または減少可能な数値になります。たとえば、開いている接続の数、キャッシュヒット率、読み取った温度がこれに該当します。
minValue	Object	MBeanAttributeInfo MBeanParameterInfo	属性またはパラメータの有効な最小値。javax.management.openmbean を参照してください。
mxbean	String	MBeanInfo	この MBean が MXBean であるかどうかにより、文字列 "true" または "false" になります。Standard MBean、または MBean Server に直接登録されるか StandardMBean クラスを使って作成された MXBean は、MBeanInfo Descriptor 内にこのフィールドを保持します。
openType	OpenType	MBeanAttributeInfo MBeanOperationInfo MBeanParameterInfo	この要素の Open Type。MBeanAttributeInfo および MBeanParameterInfo の場合、これは属性またはパラメータの Open Type です。MBeanOperationInfo の場合、これは戻り値の Open Type です。このフィールドは、OpenMBeanAttributeInfoSupport、OpenMBeanOperationInfoSupport、および OpenMBeanParameterInfoSupport のすべてのインスタンスの Descriptor で設定されます。これは、MXBeans の属性、オペレーション、およびパラメータに対しても設定されます。 このフィールドは、MBeanNotificationInfo に対して設定できます。この場合、ユーザーデータ の Open Type を示します。
originalType	String	MBeanAttributeInfo MBeanOperationInfo MBeanParameterInfo	この MBeanAttributeInfo を生成した MXBean インタフェースメソッドに表示される、この要素の元の Java 型。たとえば、MXBean インタフェース内のメソッド public MemoryUsage getHeapMemoryUsage(); は、CompositeData 型の HeapMemoryUsage という属性を定義します。この属性の Descriptor 内の originalType フィールドの値は "java.lang.management.MemoryUsage" になります。 この文字列の書式については、MXBean 仕様の「型名」セクションを参照してください。
severity	String Integer	MBeanNotificationInfo	この通知の重要度。値 0 は重大度不明を意味します。値 1 〜 6 は、値が大きくなるに従って重要度が低下します。これは、10 進数文字列または Integer で表すことができます。
since	String	Any	この要素が導入された情報モデルのバージョン。アプリケーションにより定義された MBeans のセットは、まとめて「情報モデル」と呼ばれます。アプリケーションは、このモデルのバージョンを定義し、"since" フィールドを使って要素が最初に出現したバージョンを記録することもできます。
units	String	MBeanAttributeInfo MBeanParameterInfo MBeanOperationInfo	属性、パラメータ、またはオペレーション戻り値の測定単位 ("bytes"、"seconds" など)。

Model MBeans により、追加フィールドがいくつか定義されます。ModelMBeanInfo や関連するクラス、および『JMX 仕様』の「Model MBeans」の章を参照してください。

導入されたバージョン:

1.5

メソッドの概要

Object	clone() この記述子と等価な記述子を返します。
boolean	equals(Object obj) この記述子と指定されたオブジェクトを比較します。
String[]	getFieldNames() 記述子内のすべてのフィールド名を返します。
String[]	getFields() この記述子に含まれるすべてのフィールドを単一の文字列配列として返します。
Object	getFieldValue(String fieldName) 特定のフィールド名の値を返します。
Object[]	getFieldValues(String... fieldNames) 記述子内のすべてのフィールドの値を Object の配列として返します。
int	hashCode() この記述子のハッシュコード値を返します。
boolean	isValid() すべてのフィールドに名前が付与されていて値が有効な場合、true を返します。
void	removeField(String fieldName) 記述子からフィールドを削除します。
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()

この記述子に含まれるすべてのフィールドを単一の文字列配列として返します。

戻り値:

fieldName=fieldValue の形式のフィールドの文字列配列
フィールドの値が String でない場合、toString() メソッドが 呼び出され、戻り値が括弧で囲まれて 返される配列内のフィールドの値として使用される。フィールドの値が null の場合、返される配列内のフィールドの値は 空になる。記述子が空の場合、空の配列が 返される

関連項目:

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

getFieldNames

String[] getFieldNames()

記述子内のすべてのフィールド名を返します。

戻り値:

フィールド名の文字列配列。記述子が空の場合、空の配列が 返される

getFieldValues

Object[] getFieldValues(String... fieldNames)

記述子内のすべてのフィールドの値を Object の配列として返します。戻り値の順番は、fieldNames String 配列パラメータの場合と同じになります。

パラメータ:

fieldNames - 値が返されるフィールドの名前で構成される 文字列配列。配列が空の場合、 空の配列が返される。配列が null の場合、 パラメータが getFieldNames() により返された配列であるかのように、 すべての値が返される。配列内のフィールド名が存在しない場合 (フィールド名が null または空の文字列である場合を含む)、返される対応する配列要素に対して null が返される

戻り値:

フィールド値から成るオブジェクト配列。fieldNames のリストが 空の場合、空の配列が返される

removeField

void removeField(String fieldName)

記述子からフィールドを削除します。

パラメータ:

fieldName - 削除されるフィールドの文字列名。フィールド名が不正であるか、フィールドが見つからない場合、 例外はスローされない

例外:

RuntimeOperationsException - 指定した名前のフィールドが存在し、 記述子が不変の場合。ラップされた例外は、 UnsupportedOperationException になる

setFields

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

フィールド名配列内のすべてのフィールドを新しい値に設定し、フィールド値配列に同じインデックスを設定します。配列サイズは一致している必要があります。

フィールド値は、検証されてから設定されます。無効な値の場合は例外がスローされます。配列が空の場合、変更内容は適用されません。

パラメータ:

fieldNames - フィールド名の文字列配列。配列および配列要素は、 null にはできない

fieldValues - 対応するフィールド値から成るオブジェクト配列。配列は 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 であり、2 つの記述子のフィールド名が同一で (大文字と小文字が異なる可能性がある)、関連付けられた値が同じである場合、オジェクトは等価です。次の条件を満たす場合、2 つの 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