モジュール java.management
パッケージ 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型にすることを意味します。

Descriptorフィールド
名前 型 使用する場所 意味
defaultValueObject MBeanAttributeInfo
MBeanParameterInfo		 属性またはパラメータのデフォルト値。 javax.management.openmbeanを参照してください。
deprecatedString任意 情報モデルのこの要素は、使用が推奨されなくなったことを示します。 アプリケーションにより定義されたMBeansのセットは、まとめて情報モデルと呼ばれます。 規則では、このフィールド値の文字列には、要素が最初に非推奨になったモデルのバージョン、空白、非推奨の説明の順序で含められます。たとえば、"1.3 Replaced by the Capacity attribute"となります。
descriptionResource
BundleBaseName		String任意 descriptionResourceKeyフィールドに指定されたキーがあるResourceBundleのベース名。たとえば、"com.example.myapp.MBeanResources"となります。 この指定によりフィールドの意味が定義されますが、このフィールドがJMX API自体により設定または使用されることはありません。
descriptionResourceKey String任意 この要素の説明に対するリソース・キー。 これをdescriptionResourceBundleBaseNameとともに使用すると、ローカライズされた説明を検出できます。 この指定によりフィールドの意味が定義されますが、このフィールドがJMX API自体により設定または使用されることはありません。
enabledString MBeanAttributeInfo
MBeanNotificationInfo
MBeanOperationInfo		 この項目が使用可能であるかどうかにより、文字列"true"または"false"になります。 属性またはオペレーションが使用可能でない場合は、存在していても、現時点ではアクセスできません。 ユーザー・インタフェースによっては、これが淡色の項目で表示される場合があります。 たとえば、属性が意味を持つのが、MBeanのstart()メソッドが呼び出されたあとだけで、それ以外では属性を使用できないことがあります。 同様に、通知が現時点で発行できない場合は通知が使用可能でない可能性がありますが、ほかの状況下では発行できる可能性があります。
exceptionsString[] MBeanAttributeInfo、MBeanConstructorInfo、MBeanOperationInfo コンストラクタまたはオペレーションの呼出し時、あるいは属性の取得時にスローされる場合がある例外のクラス名。 この指定によりフィールドの意味が定義されますが、このフィールドがJMX API自体により設定または使用されることはありません。 属性の設定時にスローされる例外は、フィールドsetExceptionsで指定されます。
immutableInfoString MBeanInfo MBeanのMBeanInfoが不変であるかどうかにより、文字列"true"または"false"になります。 このフィールドがtrueの場合、指定したMBeanのMBeanInfoは、MBeanの有効期間中は変更されないことが保証されます。 このため、クライアントは一度読み取って、その値をキャッシュできます。 このフィールドがfalseまたは空の場合、MBeanInfoが必ず変更されるわけではありませんが、変更されないという保証はありません。 "jmx.mbean.info.changed"通知も参照してください。
infoTimeoutString
Long		MBeanInfo MBeanInfoが変更されないと予想できる妥当な時間(ミリ秒単位)。 値には、Longまたは10進数の文字列を使用できます。 これにより、DynamicMBeanまたはimmutableInfoをtrueとして定義しない任意のMBeanから、この期間内にはMBeanInfoが変更されない可能性が高いのでキャッシュ可能であるというヒントが与えられます。 このフィールドが見つからないか値がゼロの場合は、immutableInfoがtrueに設定されず、かつ、MBeanNotificationInfo配列内に"jmx.mbean.info.changed"がないかぎり、MBeanInfoをキャッシュすることは推奨されません。
interfaceClassName StringMBeanInfo 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などの説明のロケール。
maxValueObject MBeanAttributeInfo
MBeanParameterInfo		 属性またはパラメータの有効な最大値。 javax.management.openmbeanを参照してください。
metricTypeString MBeanAttributeInfo
MBeanOperationInfo		 メトリックのタイプ。文字列"counter"と"gauge"のいずれかになります。 メトリックは、MBeanによりエクスポートされる計測です。通常は属性ですが、オペレーションの結果である場合もあります。 カウンタであるメトリックの値は、開始値にリセットしないかぎり、決して減少することがありません。 カウンタ・メトリックスは、ほとんどの場合、負でない整数になります。 たとえば、受信した要求の数がこれに該当します。 ゲージであるメトリックは、増加または減少可能な数値になります。 たとえば、開いている接続の数、キャッシュ・ヒット率、読み取った温度がこれに該当します。
minValueObject MBeanAttributeInfo
MBeanParameterInfo		 属性またはパラメータの有効な最小値。 javax.management.openmbeanを参照してください。
mxbeanString MBeanInfo このMBeanがMXBeanであるかどうかにより、文字列"true"または"false"になります。 Standard MBean、またはMBean Serverに直接登録されるかStandardMBeanクラスを使って作成されたMXBeanには、MBeanInfo Descriptor内にこのフィールドがあります。
openTypeOpenType MBeanAttributeInfo
MBeanOperationInfo
MBeanParameterInfo

この要素のOpen Type。 MBeanAttributeInfoおよびMBeanParameterInfoの場合、これは属性またはパラメータのOpen Typeです。 MBeanOperationInfoの場合、これは戻り値のOpen Typeです。 このフィールドは、OpenMBeanAttributeInfoSupport、OpenMBeanOperationInfoSupport、およびOpenMBeanParameterInfoSupportのすべてのインスタンスのDescriptorで設定されます。 これは、MXBeansの属性、オペレーション、およびパラメータに対しても設定されます。

このフィールドは、MBeanNotificationInfoに対して設定できます。この場合、user dataのOpen Typeを示します。
originalTypeString MBeanAttributeInfo
MBeanOperationInfo
MBeanParameterInfo

この MBeanAttributeInfoなどを生成したMXBeanインタフェース・メソッドに表示される、この要素の元のJava型。 たとえば、MXBeanインタフェース内のメソッド
public MemoryUsage getHeapMemoryUsage();
は、CompositeData型の HeapMemoryUsageという属性を定義します。 この属性のDescriptor内の originalTypeフィールドの値は"java.lang.management.MemoryUsage"になります。

この文字列の書式については、MXBean仕様の「型名」セクションを参照してください。

setExceptionsString[] MBeanAttributeInfo 属性の設定時にスローされる場合がある例外のクラス名。 この指定によりフィールドの意味が定義されますが、このフィールドがJMX API自体により設定または使用されることはありません。 属性の取得時にスローされる例外は、フィールドexceptionsで指定されます。
severityString
Integer		 MBeanNotificationInfo この通知の重要度。 値0は重要度不明を意味します。値1 - 6は、値が大きくなるに従って重要度が低下します。 これは、10進数文字列またはIntegerで表すことができます。
sinceString任意 この要素が導入された情報モデルのバージョン。 アプリケーションにより定義されたMBeansのセットは、まとめて情報モデルと呼ばれます。 アプリケーションは、このモデルのバージョンを定義し、"since"フィールドを使って要素が最初に出現したバージョンを記録することもできます。
unitsString 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のみです。

ModelMBeanフィールド
名前 型 使用する場所 意味
classStringModelMBeanOperationInfo メソッドが定義されたクラス(完全修飾)。
currencyTimeLimitNumber ModelMBeanInfo
ModelMBeanAttributeInfo
ModelMBeanOperationInfo		 キャッシュ値の有効期間。<0無効、=0常に有効、>0秒。
defaultObjectModelMBeanAttributeInfo 属性のデフォルト値。
descriptorTypeString任意 mbean、attribute、constructor、operation、notificationのいずれかの記述子型。
displayNameString任意 この項目の人間が読める形式の名前。
exportStringModelMBeanInfo このMBeanをほかのJMXエージェントにエクスポートまたは公開するとき使用する名前。
getMethodStringModelMBeanAttributeInfo getメソッドのオペレーション記述子の名前。
lastUpdatedTimeStampNumber ModelMBeanAttributeInfo
ModelMBeanOperationInfo		 valueが設定された時刻。
logStringModelMBeanInfo
ModelMBeanNotificationInfo		 tまたはT: すべての通知をログに記録、fまたはF:通知を記録しない。
logFileStringModelMBeanInfo
ModelMBeanNotificationInfo		 イベントの記録先ファイルの完全修飾ファイル名。
messageIDStringModelMBeanNotificationInfo メッセージ・テキストの一意のキー(翻訳、分析用)。
messageTextStringModelMBeanNotificationInfo 通知テキスト。
nameString任意 この項目の名前。
persistFileStringModelMBeanInfo MBeanを保持するファイルの名前。
persistLocationStringModelMBeanInfo 完全修飾ディレクトリ名。MBeanは、必要に応じてこのディレクトリに保持される。
persistPeriodNumber ModelMBeanInfo
ModelMBeanAttributeInfo		 永続サイクルの頻度(秒単位)。 persistPolicyがOnTimerまたはNoMoreOftenThanのとき使用。
persistPolicyString ModelMBeanInfo
ModelMBeanAttributeInfo		 OnUpdate、OnTimer、NoMoreOftenThan、OnUnregister、Always、Neverのいずれか。 JMX仕様ドキュメントの「MBean Descriptor Fields」を参照。
presentationStringString任意 データ表現を可能にするためのXML形式の文字列。
protocolMapDescriptorModelMBeanAttributeInfo JMX仕様ドキュメントの「Protocol Map Support」を参照。 属性に適したマッピングでなければならない。エントリは実行時に更新または追加可能。
roleString ModelMBeanConstructorInfo
ModelMBeanOperationInfo		 constructor、operation、getter、またはsetterのいずれか。
setMethodStringModelMBeanAttributeInfo setメソッドのオペレーション記述子の名前。
severityNumber ModelMBeanNotificationInfo 0 - 6の値のうち0: 未知、1:回復不能、2:クリティカル、障害、3:メジャー、重大、4:マイナー、非重要、エラー、5:警告、6:通常、クリア済み、情報
targetObjectObjectModelMBeanOperationInfo メソッドはこのオブジェクトに対して実行される。
targetTypeStringModelMBeanOperationInfo targetObjectのオブジェクト参照型。 ObjectReference、Handle、EJBHandle、IOR、RMIReferenceのいずれか。
valueObject ModelMBeanAttributeInfo
ModelMBeanOperationInfo		 属性またはオペレーションの現在値(キャッシュ値)。
visibilityNumber任意 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)