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	任意	情報モデルのこの要素は、使用が推奨されなくなったことを示します。アプリケーションにより定義された MBeans のセットは、まとめて情報モデルと呼ばれます。規則では、このフィールド値の文字列には、要素が最初に非推奨になったモデルのバージョン、空白、非推奨の説明がこの順序で含められます。たとえば、"1.3 Replaced by the Capacity attribute" となります。
descriptionResource BundleBaseName	String	任意	descriptionResourceKey フィールドに指定されたキーがある ResourceBundle のベース名。たとえば、"com.example.myapp.MBeanResources" となります。この指定によりフィールドの意味が定義されますが、このフィールドが JMX API 自体により設定または使用されることはありません。
descriptionResourceKey	String	任意	この要素の説明に対するリソースキー。これを descriptionResourceBundleBaseName とともに使用すると、ローカライズされた説明を検出できます。この指定によりフィールドの意味が定義されますが、このフィールドが JMX API 自体により設定または使用されることはありません。
enabled	String	MBeanAttributeInfo MBeanNotificationInfo MBeanOperationInfo	この項目が使用可能であるかどうかにより、文字列 "true" または "false" になります。属性またはオペレーションが使用可能でない場合は、存在していても、現時点ではアクセスできません。ユーザーインタフェースによっては、これが淡色の項目で表示される場合があります。たとえば、属性が意味を持つのが、MBean の start() メソッドが呼び出されたあとだけで、それ以外では属性を使用できないことがあります。同様に、通知が現時点で発行できない場合は通知が使用可能でない可能性がありますが、ほかの状況下では発行できる可能性があります。
exceptions	String[]	MBeanAttributeInfo、MBeanConstructorInfo、MBeanOperationInfo	コンストラクタまたはオペレーションの呼び出し時、あるいは属性の取得時にスローされる場合がある例外のクラス名。この指定によりフィールドの意味が定義されますが、このフィールドが JMX API 自体により設定または使用されることはありません。属性の設定時にスローされる例外は、フィールド setExceptions で指定されます。
immutableInfo	String	MBeanInfo	MBean の MBeanInfo が不変であるかどうかにより、文字列 "true" または "false" になります。このフィールドが true の場合、指定した MBean の MBeanInfo は、MBean の有効期間中は変更されないことが保証されます。このため、クライアントは一度読み取って、その値をキャッシュできます。このフィールドが false または空の場合、MBeanInfo が必ず変更されるわけではありませんが、変更されないという保証はありません。"jmx.mbean.info.changed" 通知も参照してください。
infoTimeout	String Long	MBeanInfo	MBeanInfo が変更されないと予想できる妥当な時間 (ミリ秒単位)。値には、Long または 10 進数の文字列を使用できます。これにより、DynamicMBean または immutableInfo を true として定義しない任意の MBean から、この期間内には MBeanInfo が変更されない可能性が高いのでキャッシュ可能であるというヒントが与えられます。このフィールドが見つからないか値がゼロの場合は、immutableInfo が true に設定されず、かつ、MBeanNotificationInfo 配列内に "jmx.mbean.info.changed" がないかぎり、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 を参照してください。
locale	String	任意	Locale.toString() により返される、この MBeanInfo、MBeanAttributeInfo などの説明のロケール。
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 に対して設定できます。この場合、user data の Open Type を示します。
originalType	String	MBeanAttributeInfo MBeanOperationInfo MBeanParameterInfo	この MBeanAttributeInfo などを生成した MXBean インタフェースメソッドに表示される、この要素の元の Java 型。たとえば、MXBean インタフェース内のメソッド public MemoryUsage getHeapMemoryUsage(); は、CompositeData 型の HeapMemoryUsage という属性を定義します。この属性の Descriptor 内の originalType フィールドの値は "java.lang.management.MemoryUsage" になります。 この文字列の書式については、MXBean 仕様の「型名」セクションを参照してください。
setExceptions	String[]	MBeanAttributeInfo	属性の設定時にスローされる場合がある例外のクラス名。この指定によりフィールドの意味が定義されますが、このフィールドが JMX API 自体により設定または使用されることはありません。属性の取得時にスローされる例外は、フィールド exceptions で指定されます。
severity	String Integer	MBeanNotificationInfo	この通知の重要度。値 0 は重要度不明を意味します。値 1 - 6 は、値が大きくなるに従って重要度が低下します。これは、10 進数文字列または Integer で表すことができます。
since	String	任意	この要素が導入された情報モデルのバージョン。アプリケーションにより定義された MBeans のセットは、まとめて情報モデルと呼ばれます。アプリケーションは、このモデルのバージョンを定義し、"since" フィールドを使って要素が最初に出現したバージョンを記録することもできます。
units	String	MBeanAttributeInfo MBeanParameterInfo MBeanOperationInfo	属性、パラメータ、またはオペレーション戻り値の測定単位 ("bytes"、"seconds" など)。

Model MBeans により、追加フィールドがいくつか定義されます。ModelMBeanInfo、ModelMBeanAttributeInfo、ModelMBeanConstructorInfo、ModelMBeanNotificationInfo、および ModelMBeanOperationInfo と、『JMX 仕様』の「Model MBean」の章を参照してください。次の表に、これらのフィールドのサマリーを示します。この表で型が Number である場合は、Long の 10 進数表現である String を使用することもできます。

これらのフィールドを Model MBean 以外の MBean で使用することも可能です。たとえば、Model MBean の外部にある displayName、severity、visibility フィールドが対象です。ただし、これらのフィールドに対する事前定義済の動作があるのは Model MBean のみです。

名前	型	使用する場所	意味
クラス	String	ModelMBeanOperationInfo	メソッドが定義されたクラス (完全修飾)。
currencyTimeLimit	Number	ModelMBeanInfo ModelMBeanAttributeInfo ModelMBeanOperationInfo	キャッシュ値の有効期間。<0 無効、=0 常に有効、>0 秒。
default	Object	ModelMBeanAttributeInfo	属性のデフォルト値。
descriptorType	String	任意	mbean、attribute、constructor、operation、notification のいずれかの記述子型。
displayName	String	任意	この項目の人間が読める形式の名前。
export	String	ModelMBeanInfo	この MBean をほかの JMX エージェントにエクスポートまたは公開するとき使用する名前。
getMethod	String	ModelMBeanAttributeInfo	get メソッドのオペレーション記述子の名前。
lastUpdatedTimeStamp	Number	ModelMBeanAttributeInfo ModelMBeanOperationInfo	value が設定された時刻。
log	String	ModelMBeanInfo ModelMBeanNotificationInfo	t または T:すべての通知をログに記録、f または F:通知を記録しない。
logFile	String	ModelMBeanInfo ModelMBeanNotificationInfo	イベントの記録先ファイルの完全修飾ファイル名。
messageID	String	ModelMBeanNotificationInfo	メッセージテキストの一意のキー (翻訳、分析用)。
messageText	String	ModelMBeanNotificationInfo	通知テキスト。
name	String	任意	この項目の名前。
persistFile	String	ModelMBeanInfo	MBean を保持するファイルの名前。
persistLocation	String	ModelMBeanInfo	完全修飾ディレクトリ名。MBean は、必要に応じてこのディレクトリに保持される。
persistPeriod	Number	ModelMBeanInfo ModelMBeanAttributeInfo	永続サイクルの頻度 (秒単位)。persistPolicy が OnTimer または NoMoreOftenThan のとき使用。
persistPolicy	String	ModelMBeanInfo ModelMBeanAttributeInfo	OnUpdate、OnTimer、NoMoreOftenThan、OnUnregister、Always、Never のいずれか。JMX 仕様ドキュメントの「MBean Descriptor Fields」を参照。
presentationString	String	任意	データ表現を可能にするための XML 形式の文字列。
protocolMap	Descriptor	ModelMBeanAttributeInfo	JMX 仕様ドキュメントの「Protocol Map Support」を参照。属性に適したマッピングでなければならない。エントリは実行時に更新または追加可能。
role	String	ModelMBeanConstructorInfo ModelMBeanOperationInfo	constructor、operation、getter、または setter のいずれか。
setMethod	String	ModelMBeanAttributeInfo	set メソッドのオペレーション記述子の名前。
severity	Number	ModelMBeanNotificationInfo	0 - 6 の値のうち 0:未知、1:回復不能、2:クリティカル、障害、3:メジャー、重大、4:マイナー、非重要、エラー、5:警告、6:通常、クリア済み、情報
targetObject	Object	ModelMBeanOperationInfo	メソッドはこのオブジェクトに対して実行される。
targetType	String	ModelMBeanOperationInfo	targetObject のオブジェクト参照型。ObjectReference、Handle、EJBHandle、IOR、RMIReference のいずれか。
value	Object	ModelMBeanAttributeInfo ModelMBeanOperationInfo	属性またはオペレーションの現在値 (キャッシュ値)。
visibility	Number	任意	1 - 4 の値のうち 1:常に可視、4: ほとんど不可視。

導入されたバージョン:

1.5

メソッドのサマリー

メソッド

修飾子と型	メソッドと説明
Object	clone() この記述子と等価な記述子を返します。
boolean	equals(Object obj) この記述子と指定されたオブジェクトを比較します。
String[]	getFieldNames() 記述子内のすべてのフィールド名を返します。
String[]	getFields() この記述子に含まれるすべてのフィールドを単一の文字列配列として返します。
Object	getFieldValue(String fieldName) 特定のフィールド名の値を返します。その名前の値が存在しない場合は null を返します。
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 を返さなければならない。

オーバーライド:

equals、クラス: Object

パラメータ:

obj - 比較対象のオブジェクト。

戻り値:

オブジェクトが同じである場合は true、そうでない場合は false。

導入されたバージョン:

1.6

関連項目:

Object.hashCode()、HashMap

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() になる。

オーバーライド:

hashCode、クラス: Object

戻り値:

このオブジェクトのハッシュコード値。

導入されたバージョン:

1.6

関連項目:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)