Implementierung der Diagnoseprovidermethoden
Zum Erstellen eines Diagnoseproviders (DP) muss eine MBean existieren, die die erforderlichen Methoden in ihrer ausführbaren XML-Datei (Extensible Markup Language) enthält. Diese Methoden definieren die Operationen, Attribute und Aggregatoren, die erforderlich sind, damit eine MBean ein Diagnoseprovider fungieren kann.
getRegisteredDiagnostics
Diese Methode stellt die Registrierungsinformationen für diesen Diagnoseprovider bereit. Sie wird im allgemeinen vom Dienstprogramm Diagnoseprovider (DP) in der Administrationskonsole verwendet, um Informationen zu Diagnoseprovidern zusammenzutragen, die in der Konsole angezeigt werden sollen. Diese Methode gibt das Objekt DiagnosticProviderInfo zurück, das man normalerweise dann erhält, wenn die geeignete XML an die Helper-Klasse DiagnosticProviderHelper übergeben wird. Beispiel:
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 ;
}
Beachten Sie, dass die XML gepackt und im Klassenpfad des aktuellen Klassenladers verfügbar ist. Die Registrierungs-XML enthält die entscheidenden Informationen, die der Diagnoseprovider verwendet, um Daten in die Nutzinformationen aufnehmen zu können sowie für die Lokalisierung der Ergebnisse.
getDiagnosticProviderName
Dies ist, wie im folgenden Beispiel gezeigt, normalerweise eine relativ einfache Rückgabe einer Konstanten:
public String getDiagnosticProviderName() {
return sDPName;
}
getDiagnosticProviderID
Dies ist normalerweise eine relativ einfache Rückgabe einer JMX-Objekt-ID (Java™ Management Extensions), die MBeans aus der Basisklassenmethode extrahieren können. Beispiel:
public String getDiagnosticProviderId() {
return getObjectName().toString() ;
}
configDump
Mit der Methode configDump kann der Diagnoseprovider die Konfigurationsdaten zeigen, die bei seinem Start verwendet wurden (oder die aktuellen Werte dieser Daten). Die von dieser Methode zurückgegebenen DiagnosticEvent-Objekte beinhalten Nutzinformationen, in denen die Kerndaten enthalten sind. Nachfolgend ist ein Auszug aus einer configDump-Methode aufgeführt:
public DiagnosticEvent [] configDump(String aAttributeIdSpec, boolean aRegisteredOnly) {
HashMap cdHash = new HashMap(64) ;
// Daten in die Nutzinformationen aufnehmen
DiagnosticEvent [] diagnosticEvent = new DiagnosticEvent[1] ;
diagnosticEvent[0] = DiagnosticEventFactory.createConfigDump(getObjectName().toString(),
"ThisClassName", "configDump", cdHash) ;
return diagnosticEvent ;
}
Hierdurch wird ein Bereich von DiagnosticEvent-Objekten zurückgegeben. Normalerweise geben die Methoden configDump und stateDump nur ein Objekt zurück. Allerdings akzeptiert die Methode einen Bereich, weil ein Server auf z/OS-Systemen mehrere Servants haben kann, und die Zusammenfassung der Ausgaben von den Servants im Bereich gespeichert wird.
stateDump
Mit der Methode stateDump kann der Diagnoseprovider die aktuellen Statusdaten oder die Daten zu den aktuellen Ausführungsbedingungen des Diagnoseproviders zeigen. Die zurückgegebenen Daten sind Informationen, die einen Kunden, den IBM® Support oder ein automatisiertes Tool dabei unterstützen, den Zustand der Komponente zu analysieren und die, falls erforderlich, Unterstützung bei der Fehlerbehebung bieten. Die Menge der Daten, die bereitgestellt wird, wird durch die gültige Spezifikation für Statuserfassung beeinflusst. Falls die aktuelle Spezifikation für Statuserfassung das Erfassen von Zusatzdaten durch den Diagnoseprovider vorsieht, können diese Zusatzdaten im Speicherauszug des Status (stateDump) bereitgestellt werden. Die von dieser Methode zurückgegebenen DiagnosticEvent-Objekte beinhalten Nutzinformationen, in denen die Kerndaten enthalten sind. Nachfolgend ist ein Auszug aus einer stateDump-Methode aufgeführt:
public DiagnosticEvent [] stateDump(String aAttributeIdSpec, boolean aRegisteredOnly) {
HashMap sdHash = new HashMap(64) ;
// Daten in die Nutzinformationen aufnehmen
DiagnosticEvent [] diagnosticEvent = new DiagnosticEvent[1] ;
diagnosticEvent[0] = DiagnosticEventFactory.createStateDump(getObjectName().toString(),
"ThisClassName", "stateDump", sdHash) ;
return diagnosticEvent ;
}
Hierdurch wird ein Bereich von DiagnosticEvent-Objekten zurückgegeben. Normalerweise geben die Methoden configDump und stateDump nur ein Objekt zurück.
Die Methode akzeptiert einen Bereich, weil ein z/OS-Server
mehrere Servants haben kann, und die Zusammenfassung der Ausgaben von den Servants im Bereich
gespeichert wird.
selfDiagnostic
Mit der Methode selfDiagnostic kann der Diagnoseprovider bestimmte vordefinierte Aktivitäten ausführen, um Schlüsselfunktionen Ihres Systems zu testen. Diese Tests sollten keine bleibenden Auswirkungen auf das System haben. Wenn im Test beispielsweise eine TCP/IP-Verbindung zu einem fernen Host erstellt werden soll, dann sollte der Test diese Verbindung beenden, bevor er seine Ergebnisse zurückgibt, damit der Status der Komponente durch den Test nicht geändert wird. Die vom Test zurückgegebenen Informationen werden durch die Attribute bestimmt, die im Testabschnitt der XML-Datei angegeben werden. Nachfolgend ist ein Auszug aus einer selfDiagnostic-Methode aufgeführt:
public DiagnosticEvent [] selfDiagnostic(String aAttributeIdSpec, boolean aRegisteredOnly) {
TestInfo [] testInfo = dpInfo.selfDiagnosticInfo.testInfo ; // Die Test-Registry-Informationen abrufen
Pattern testChecker = Pattern.compile(aAttributeIdSpec) ; // Test-regexp-Parameter für eine schnellere Überprüfung kompilieren
ArrayList deList = new ArrayList(8) ; // Erweiterbare Liste der Diagnoseereignisse anlegen
for (int i = 0; i < testInfo.length; i++) {
if (testChecker.matcher(testInfo[i].id).matches()) {
HashMap deHash = new HashMap(32) ;
// Daten in die Nutzinformationen aufnehmen
deList.add(DiagnosticEventFactory.createDiagnosticEvent(getObjectName().toString(),
DiagnosticEvent.EVENT_TYPE_SELF_DIAGNOSTIC, DiagnosticEvent.LEVEL_INFO,
"ThisClassName", "selfDiagnostic", dpInfo.resourceBundleName,
"RasDiag.SDP2.createDE3", // MsgKey for localization
// Parameter, die in msg aufgenommen werden sollen
new Object [] { "OneParm", "TwoParm", "RedParm", "BlueParm"}, deHash)) ;
}
}
DiagnosticEvent [] diagnosticEvent = new DiagnosticEvent[deList.size()] ;
diagnosticEvent = (DiagnosticEvent [])deList.toArray(diagnosticEvent) ;
return diagnosticEvent ;
}
Hierdurch wird ein Bereich von DiagnosticEvent-Objekten zurückgegeben. In diesem Beispiel wurde bei jedem Test, der mit dem regulären Parameterausdruck übereinstimmte, ein DiagnosticEvent (Diagnoseereignis) erstellt. Der Diagnoseprovider unterliegt nicht der Einschränkung, nur eines pro Test zu erzeugen. Die Erzeugung von Nutzinformationen ist ähnlich der im configDump und stateDump.
Bei der Aggregation für mehrere
z/OS-Servants eines einzelnen Servers
werden die Bereiche aus jedem Servant miteinander verknüpft.
Lokalisierung
Die von den Methoden zurückgegebenen DiagnosticEvents (Diagnoseereignissen) enthalten HashMaps mit Nutzinformationen, die MessageKeys und ResourceBundles enthalten. Der Endkonsument dieser Ereignisse ist häufig nicht der Server und hat daher möglicherweise nicht den geeigneten Klassenpfad, um dies aufzulösen. Zu diesem Zweck erfolgt ein Rückruf des Diagnoseproviders, um die Variablen gemäß der Ländereinstellung anzupassen, d. h. zu lokalisieren. Wie im folgenden Beispiel gezeigt, kann diese Methode mithilfe einer Helper-Methode einfach geschrieben werden.
public String [] localize(String [] aKeys, Locale aLocale) {
return DiagnosticProviderHelper.localize(dpInfo.resourceBundleName, aKeys, aLocale) ;
}
Beachten Sie, dass das dpInfo-Objekt (DiagnosticProviderInfo) benötigt wird, weil dieses eine Referenz auf das ResourceBundle enthält.
Nutzinformationen
Ein wiederholtes Thema in diesen Methoden ist die Fähigkeit, Nutzinformationen in die Rückgabeobjekte aufzunehmen. Dabei handelt es sich um eine Gruppe von Name=Wert-Paaren, die die von der Methode bereitgestellten Informationen enthalten. Diagnoseereignisse, die durch den Test configDump, stateDump oder selfDiagnostic zurückgegeben werden, sind relativ komplexe Java-Objekte. Der Großteil der zurückgegebenen Informationen ist im Abschnitt DiagnosticData (Diagnosedaten) des Objekts DiagnosticEvent enthalten. Jedes vom Diagnoseprovider zurückgegebene Attribut wird in einem Eintrag in einer HashMap gespeichert. Innerhalb eines einzelnen DiagnosticEvent-Objekts können gestaffelte HashMaps enthalten sein (falls die Unterteilung der Daten in Untergruppen (subGroups) sinnvoll ist). Jeder HashMap-Eintrag enthält entweder eine Referenz auf eine untergeordnete HashMap oder einen DiagnosticTypedValue (der den Wert, den Datentyp und einen MsgKey (Nachrichtenschlüssel) für die Lokalisierung des Kennsatzes oder des Namens enthält). Die Werte, die zurückgegeben werden sollen, sollten nach den folgenden Angaben gefiltert werden:
- Art der Methode (d. h. configDump, stateDump oder selfDiagnostic)
- Die zum Filtern der Werte gesendete AttributeIdSpec
- Aktuelle Spezifikation für Statuserfassung (die die Menge der verfügbaren Daten beeinflussen kann).
Daten in die Nutzinformationen aufnehmen
Die API-Dokumentation für DiagnosticProviderHelper.queryMatchingDPInfoAttributes erläutert, wie die Filterung ausgeführt wird, bevor die Daten abgerufen werden. Manchmal ist es einfacher und besser für die Leistung, wenn ein Diagnoseprovider alle Daten in die Nutzinformationen aufnimmt und dann die HashMap nachträglich filtert. Die Filterung nach Aufnahme der Daten kann mit der Methode DiagnosticProviderHelper.filterEventPayload ausgeführt werden. Informationen zur Verwendung der JavaBeans-Typmethode finden Sie in der API-Dokumentation für die Methode AttributeBeanInfo.populateMap.
Registrierungs-XML
Die Registrierungs-XML ermöglicht es, dass ein Großteil der vom Diagnoseprovider benötigten Informationen ausgelagert wird. Sie bietet auch eine Möglichkeit, die Lokalisierung und den Einsatz der Tests zu vereinheitlichen (und dient damit der Automatisierung). Nachfolgend ist ein Auszug dieser XML aus einem Beispieldiagnoseprovider aufgeführt:
<!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>
Informationen zum Speichern dieser Informationen in einem DiagnosticProviderInfo-Objekt finden Sie in der API-Dokumentation für DiagnosticProviderInfo. Erläuterungen des Zweckes der Registrierungs-XML finden Sie im Artikel Registrierte Attribute und registrierte Tests des Diagnoseproviders.