診断プロバイダー・メソッドの実装
診断プロバイダー (DP) を作成するには、 デプロイメント Extensible Markup Language (XML) ファイル内に 必要なメソッドが含まれている MBean が必要となります。 これらのメソッドによって、MBean が 診断プロバイダーとして機能するために必要な 操作、属性、および統合機能を定義します。
getRegisteredDiagnostics
このメソッドは、この診断プロバイダーの登録情報を公開します。 これは一般に、管理コンソールの DP ユーティリティーにより、コンソールに表示される診断プロバイダーについての情報を収集するために使用されます。 このメソッドは通常、該当する XML を DiagnosticProviderHelper ヘルパー・クラスに渡すことにより獲得さ れる DiagnosticProviderInfo オブジェクトを戻します。 以下に例を示します。
public DiagnosticProviderInfo getRegisteredDiagnostics() {
InputStream regIS= Thread.currentThread().getContextClassLoader().getResourceAsStream(
"com/ibm/ws/xxx/SampleDP2DiagnosticProvider.xml");
dpInfo = DiagnosticProviderHelper.loadRegistry(regIS, sDPName) ;
if (dpInfo == null) {
sSampleDP2MBeanLogger.logp(Level.WARNING, sThisClass, "getRegisteredDiagnostics",
"RasDiag.DPInfo.NoGotz") ;
}
return dpInfo ;
}
XML はパッケージ化され、現行の classloader の classpath で使用できることに注意してください。 登録 XML には、診断プロバイダーが有効搭載量の取り込みに使用する重要な情報およびローカライズの結果が含まれています。
getDiagnosticProviderName
これは通常、次の例が示すように、とても単純な定数の戻りです。
public String getDiagnosticProviderName() {
return sDPName;
}
getDiagnosticProviderID
これは通常、MBean が基本クラス・メソッドから取り出すことのできる、非常に単純な Java™ Management Extensions (JMX) オブジェクト ID の戻りです。以下に例を示します。
public String getDiagnosticProviderId() {
return getObjectName().toString() ;
}
configDump
configDump メソッドにより、診断プロバイダーは 、開始したときに決まった所にあった構成データ (またはそれらのデータの現行値) を公開できます。 このメソッドが戻す DiagnosticEvent オブジェクトは、コア・データを含むペイロードを含んでいます。以下は、configDump メソッドの抜粋です。
public DiagnosticEvent [] configDump(String aAttributeIdSpec, boolean aRegisteredOnly) {
HashMap cdHash = new HashMap(64) ;
// 有効搭載量の取り込み
DiagnosticEvent [] diagnosticEvent = new DiagnosticEvent[1] ;
diagnosticEvent[0] = DiagnosticEventFactory.createConfigDump(getObjectName().toString(),
"ThisClassName", "configDump", cdHash) ;
return diagnosticEvent ;
}
これにより、DiagnosticEvent オブジェクトの配列が戻されます。通常、configDump および stateDump は、1 つのオブジェクトのみを戻します。 ただし、z/OS® システムではサーバーが複数のサーバントを持つことができるため、このメソッドは配列を受け入れ、サーバントからの出力の集約が配列に保管されます。
stateDump
stateDump メソッドにより、診断プロバイダーは現 在の状態のデータ、つまり診断プロバイダーの現在の操作状況についてのデータを公開することができます。 問題が発生した場合に、顧客、IBM® サポート担当者、または自動化ツールが使用可能になったデータを利用して、コンポーネントの正常性の分析と問題判別を行うことができます。使用可能なデータの量は、その時点で有効になっている、状態収集仕様 に影響を受けます。 現在の状態収集仕様に、診断プロバイダーによる追加データの集合が含まれる場合、この追加データは stateDump で公開できます。このメソッドが戻す DiagnosticEvent オブジェクトは、コア・データを含むペイロードを含んでいます。以下は、stateDump メソッドの抜粋です。
public DiagnosticEvent [] stateDump(String aAttributeIdSpec, boolean aRegisteredOnly) {
HashMap sdHash = new HashMap(64) ;
// 有効搭載量の取り込み
DiagnosticEvent [] diagnosticEvent = new DiagnosticEvent[1] ;
diagnosticEvent[0] = DiagnosticEventFactory.createStateDump(getObjectName().toString(),
"ThisClassName", "stateDump", sdHash) ;
return diagnosticEvent ;
}
これにより、DiagnosticEvent オブジェクトの配列が戻されます。通常、configDump および stateDump は、1 つのオブジェクトのみを戻します。
z/OS サーバーが複数のサーバントを持つことができるため、このメソッドは配列を受け入れ、サーバントからの出力の集約が、その配列に保管されます。
selfDiagnostic
selfDiagnostic メソッドにより、診断プ ロバイダーは、システムの主要な機能をテストするための特定の定義済みアクティビティーを実行できます。 これらのテストが、後までシステムに影響しないようにしてください。 例えば、テストでリモート・ホストへの TCP/IP 接続が作成する場合、結果を戻す前にテスト中に 接続の切断も行い、コンポーネントの状態がテストによって変更されないようにする必要があります。 テストにより戻される情報は、XML ファイルのテストのセクションに含まれる属性で決定されます。 以下は、selfDiagnostic メソッドの抜粋です。
public DiagnosticEvent [] selfDiagnostic(String aAttributeIdSpec, boolean aRegisteredOnly) {
TestInfo [] testInfo = dpInfo.selfDiagnosticInfo.testInfo ; // Retrieve the test registry information
Pattern testChecker = Pattern.compile(aAttributeIdSpec) ; // Compile test regexp parm for faster checking
ArrayList deList = new ArrayList(8) ; // Allocate expandable list of DiagnosticEvents
for (int i = 0; i < testInfo.length; i++) {
if (testChecker.matcher(testInfo[i].id).matches()) {
HashMap deHash = new HashMap(32) ;
// 有効搭載量の取り込み
deList.add(DiagnosticEventFactory.createDiagnosticEvent(getObjectName().toString(),
DiagnosticEvent.EVENT_TYPE_SELF_DIAGNOSTIC, DiagnosticEvent.LEVEL_INFO,
"ThisClassName", "selfDiagnostic", dpInfo.resourceBundleName,
"RasDiag.SDP2.createDE3", // MsgKey for localization
// Parms to incorporate in msg
new Object [] { "OneParm", "TwoParm", "RedParm", "BlueParm"}, deHash)) ;
}
}
DiagnosticEvent [] diagnosticEvent = new DiagnosticEvent[deList.size()] ;
diagnosticEvent = (DiagnosticEvent [])deList.toArray(diagnosticEvent) ;
return diagnosticEvent ;
}
これにより、DiagnosticEvent オブジェクトの配列が戻されます。この例では、パラメーターの正規表現の突き合わせを 行うテストごとに、1 つの DiagnosticEvent が作成されました。 診断プロバイダーは、テストごとに 1 つだけを作成する必要はありません。 ペイロードの生成は、configDump および stateDump の生成に 類似しています。
個々のサーバーに対する複数の z/OS サーバントの集約は、各サーバントの配列を連結したものです。
ローカライズ
メソッドが戻す DiagnosticEvents には、MessageKeys および ResourceBundles を含む有効搭載量 HashMaps が含まれます。 これらのイベントの最終利用者はたいていサーバー上には存在しないため、これを解決するための適切なクラスパス がない場合があります。この目的のために、変数をローカライズするための診断プロバイダーのコールバックが行われます。ただし次の例で示すように、helper メソッドにより、これは作成が単純なメソッドになります。
public String [] localize(String [] aKeys, Locale aLocale) {
return DiagnosticProviderHelper.localize(dpInfo.resourceBundleName, aKeys, aLocale) ;
}
dpInfo (DiagnosticProviderInfo) オブジェクトには ResourceBundle への参照が含まれ ているため、このオブジェクトが必要になることに注意してください。
ペイロード
これらのメソッドで繰り返されるテーマは、戻りオブジェクトに有効搭載量を含める機能です。 これは、メソッドにより公開される情報を含む名前 = 値 ペアのセットです。 configDump、stateDump、または selfDiagnostic テストから戻される診断イベントは、比較的複雑な Java オブジェクトです。戻される情報の大半は、DiagnosticEvent オブジェクトの DiagnosticData 部分に含まれています。 診断プロバイダーにより戻される各属性は、HashMap の項目に保管されます。単一の DiagnosticEvent オブジェクトに、カスケード HashMap が存在する場合があります (データを subGroups に分解することに意味がある場合)。HashMap 項目ごとに、子 HashMap か DiagnosticTypedValue (ラベルまたは名前のローカライズのための値、データ・タイプ、および MsgKey を含む) への参照が含まれています。戻される値は、次のものによりフィルタリングされる必要があります。
- メソッドのタイプ (すなわち、configDump、stateDump、または selfDiagnostic)
- 値をフィルタリングするために送信される AttributeIdSpec
- 現在の状態収集仕様 (これは、使用可能なデータの量に影響を与えることがあります。)。
有効搭載量の取り込み
DiagnosticProviderHelper.queryMatchingDPInfoAttributes の API 文書では、データを取り出す前にフィルタリングを行う方法を説明しています。 場合によっては、すべてのデータを有効搭載量に取り出し、事後に HashMap をフィルタリングすることが 、診断プロ バイダーにとって簡単であり、パフォーマンスの点でも効果的です。post-population フィルタリングは、メソッド DiagnosticProviderHelper.filterEventPayload を使用して行うことができます。 JavaBeans タイプを使用する方法に関する情報は、AttributeBeanInfo.populateMap メソッドの API 資料を参 照して ください。
登録 XML
登録 XML により、診断プロバイダーが必要とする情報の多くを外部化することができます。 また、テストのローカライズと利用の共通化 (つまり、自動化支援) の手段が提供されます。サンプル診断プロバイダーの XML の抜粋は、以下のとおりです。
<!DOCTYPE diagnosticProvider PUBLIC "RasDiag" "/DiagnosticProvider.dtd">
<diagnosticProvider>
<resourceBundleName> com.ibm.ws.rasdiag.resources.RasDiagSample</resourceBundleName>
<state>
<attribute>
<id>Leg-Foot</id>
<descriptionKey>SampleDiagnostic.LegFoot.descriptionKey</descriptionKey>
<registered>true</registered>
</attribute>
<attribute>
<id>Leg-Ankle</id>
<descriptionKey>SampleDiagnostic.LegAnkle.descriptionKey</descriptionKey>
<registered>true</registered>
</attribute>
</state>
<config>
<attribute>
<id>Arm-Hand-Size</id>
<descriptionKey>SampleDiagnostic.HandSize.descriptionKey</descriptionKey>
<registered>true</registered>
</attribute>
<attribute>
<id>Leg-Foot-Size</id>
<descriptionKey>SampleDiagnostic.FootSize.descriptionKey</descriptionKey>
<registered>true</registered>
</attribute>
</config>
<selfDiagnostic>
<test>
<id>Kick</id>
<descriptionKey>SampleDiagnostic.Kick.descriptionKey</descriptionKey>
<attribute>
<id>Kick-Pain</id>
<descriptionKey>SampleDiagnostic.KickPain.descriptionKey</descriptionKey>
</attribute>
<attribute>
<id>Kick-Length</id>
<descriptionKey>SampleDiagnostic.KickLength.descriptionKey</descriptionKey>
</attribute>
</test>
<test>
<id>Throw</id>
<descriptionKey>SampleDiagnostic.Throw.descriptionKey</descriptionKey>
<attribute>
<id>Throw-Pain</id>
<descriptionKey>SampleDiagnostic.ThrowPain.descriptionKey</descriptionKey>
<registered>true</registered>
</attribute>
<attribute>
<id>Throw-Length</id>
<descriptionKey>SampleDiagnostic.ThrowLength.descriptionKey</descriptionKey>
<registered>true</registered>
</attribute>
</test>
</selfDiagnostic>
</diagnosticProvider>
この情報の DiagnosticProviderInfo オブジェクトへの保管を理解するには、DiagnosticProviderInfo の API 資料を参照してください。 登録 XML の目的に関する概念的な情報については、診断プロバイダーの登録済み属性と登録済みテストを参照してください。