compact3

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のみです。

名前	型	使用する場所	意味
class	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)