JRas-Nachrichten- und Traceereignistypen
Die grundlegenden JRas-Nachrichten- und -Ereignistypen sind nicht dieselben wie diejenigen, die von WebSphere Application Server nativ erkannt werden, so dass die JRas-Typen den Typen zugeordnet werden, die für die Laufzeitumgebung nativ sind. Mit angepassten Filtern und Nachrichtensteuerung können Sie festlegen, wie JRas-Nachrichten- und -Traceereignisse verarbeitet werden.
Ereignistypen
Das JRas-Framework, das in dieser Task und den untergeordneten Tasks beschrieben wird, wird nicht weiter unterstützt. Sie können jedoch ähnliche Ergebnisse mit der Java™-Protokollierung erzielen.
Die Basistypen für Nachrichten- und Traceereignisse, die vom eigenständigen JRas-Protokollierungstoolkit definiert werden, sind mit den "nativen" Typen, die von der Laufzeitumgebung von WebSphere Application Server erkannt werden, nicht identisch. Die JRas-Basistypen werden stattdessen den nativen Typen zugeordnet. Diese Zuordnung kann je nach Plattform oder Edition variieren. Die Zuordnung wird im folgenden Abschnitt beschrieben.
Plattformspezifische Nachrichtenereignistypen
Nativer Typ von WebSphere Application Server | JRas-RASIMessageEvent-Typ |
---|---|
Audit | TYPE_INFO, TYPE_INFORMATION |
Warning | TYPE_WARN, TYPE_WARNING |
Error | TYPE_ERR, TYPE_ERROR |
Anwendungsentwickler
können JRas verwenden, um eine MVS-WTO-Nachricht (Write To Operator)
mit dem JRas-RASIMessageEvent-Typ TYPE_INFO oder TYPE_INFORMATION abzusetzen, um einen Prüftrace für
WebSphere Application Server for z/OS
einzuleiten. Der Prüftrace von
WebSphere Application Server for z/OS
wird einem MVS-WTO-Routencode 11 (Hardcopy WTO) zugeordnet.
Plattformspezifische Traceereignistypen
- Für einen Benutzer, der eine einfache Gruppe von Stufen vorzieht, stellt die Schnittstelle "RASITraceEvent" TYPE_LEVEL1, TYPE_LEVEL2 und TYPE_LEVEL3 bereit. Die Implementierungen bieten Unterstützung für diese Gruppe von Stufen. Die Stufen sind hierarchisch aufgebaut (d. h. bei Aktivierung von Stufe 2 wird auch Stufe 1 aktiviert, und bei Aktivierung von Stufe 3 werden auch die Stufen 1 und 2 aktiviert).
- Für Benutzer, die eine komplexere Gruppe von Werten verwenden möchten, die mit OR verknüpft werden können, stellt die Schnittstelle "RASITraceEvent" TYPE_API, TYPE_CALLBACK, TYPE_ENTRY_EXIT, TYPE_ERROR_EXC, TYPE_MISC_DATA, TYPE_OBJ_CREATE, TYPE_OBJ_DELETE, TYPE_PRIVATE, TYPE_PUBLIC, TYPE_STATIC und TYPE_SVC bereit.
Diese Traceereignistypen sind den nativen Tracetypen wie folgt zugeordnet:
Nativer Typ von WebSphere Application Server | Stufentyp für JRas-RASITraceEvent |
---|---|
Event | TYPE_LEVEL1 |
EntryExit | TYPE_LEVEL2 |
Debug | TYPE_LEVEL3 |
Nativer Typ von WebSphere Application Server | Enumerated-Typen der JRas-RASITraceEventsp |
---|---|
Event | TYPE_ERROR_EXC, TYPE_SVC, TYPE_OBJ_CREATE, TYPE_OBJ_DELETE |
EntryExit | TYPE_ENTRY_EXIT, TYPE_API, TYPE_CALLBACK, TYPE_PRIVATE, TYPE_PUBLIC, TYPE_STATIC |
Debug | TYPE_MISC_DATA |
Aus Gründen der Übersichtlichkeit wird empfohlen, nur einen der Tracetypen konsistent in der Anwendung zu verwenden. Benutzern, die keine stufenbasierten Typen verwenden möchten, wird außerdem empfohlen, je einen Typ aus jeder Kategorie auszuwählen und dann in der Anwendung konsistent zu verwenden, um Missverständnisse zu vermeiden.
Nachrichten- und Traceparameter
- Primitive Datentypen
- Primitive Datentypen, wie z. B. int und long, werden nicht als Unterklassen von Object erkannt und können nicht direkt an eine dieser Methoden übergeben werden. Der Wert eines primitiven Datentyps muss in einen richtigen Object-Typ umgewandelt werden (Integer, Long), bevor er als Parameter übergeben wird.
- Object
- Die Methode "toString" wird für das Objekt aufgerufen, und die resultierende Zeichenfolge wird angezeigt. Die Methode "toString" muss für jedes Objekt, das an eine Nachrichtenprotokollierungsmethode oder Tracemethode übergeben wird, ordnungsgemäß implementiert werden. Es obliegt der Verantwortung des aufrufenden Prozesses (Caller) sicherzustellen, dass mit der Methode "toString" keine vertraulichen Daten, wie z. B. Kennwörter im Klartext, angezeigt werden und keine Endlosrekursion ausgelöst wird.
- Object[]
- Der Typ Object[] wird für den Fall bereitgestellt, dass mehrere Parameter an eine Nachrichtenprotokollierungs- oder Tracemethode übergeben werden. Die Methode "toString" wird für jedes Object im Array aufgerufen. Verschachtelte Arrays werden nicht bearbeitet (d. h. keines der Elemente im Object-Array darf ein Array sein.
- Throwable
- Der Stack-Trace des Throwable wird abgerufen und angezeigt.
- Array primitiver Datentypen
- Ein Array primitiver Datentypen, z. B.
byte[], int[],
wird als Objekt erkannt, wird aber flexibel über
den Java-Code gekoppelt. Im Allgemeinen sollte die Verwendung von Array primitiver Datentypen vermieden werden. Wenn Arrays primitiver Datentypen übergeben werden, sind die Ergebnisse unbestimmt und können in Abhängigkeit vom Typ des übergebenen Array, von der API, die für die
Übergabe des Array verwendet wird, sowie vom Produkt-Release variieren. Zur Gewährleistung der Konsistenz der Ergebnisse muss der Benutzercode den
Array primitiver Datentypen vorverarbeiten und in einen String-Typ konvertieren, bevor er ihn an die Methode übergibt. Falls
keine solche Vorverarbeitung durchgeführt wird, kann sich Folgendes ergeben:
- [B@924586a0b - Diese Nachricht wird als Byte-Array an Position X entschlüsselt. Diese Nachricht wird gewöhnlich zurückgegeben, wenn ein Array als Member eines Object[] übergeben wird, und ist das Ergebnis des Aufrufs der Methode "toString" für den Typ byte[].
- Ungültiges Traceargument: Array vom Typ long. Diese Antwort wird normalerweise zurückgegeben, wenn ein Array primitiver Datentypen an eine Methode übergeben und dabei der Typ Object[] verwendet wird.
- 01040703: Die Hexadezimaldarstellung eines Byte-Array. Dieses Problem tritt typischerweise auf, wenn ein Byte-Array an eine Methode übergeben wird, die nur ein Object akzeptiert. Dieses Verhalten kann variieren und sollte nicht als gegeben vorausgesetzt werden.
- "1" "2": Die Darstellung von int[]-Membern in Form einer Zeichenfolge (String), die dadurch entsteht, dass die einzelnen Elemente in integer konvertiert werden und anschließend toString für die Integer aufgerufen wird. Dieses Verhalten kann variieren und sollte nicht als gegeben vorausgesetzt werden.
- [Ljava.lang.Object;@9136fa0b : Ein Array von Objekten. Normalerweise wird diese Antwort zurückgegeben, wenn ein Array, der verschachtelte Arrays enthält, übergeben wird.
Nachrichtenprotokollierung steuern
- Der Nachrichtenereignistyp muss einer der Nachrichtenereignistypen sein, die in der Schnittstelle "RASIMessageEvent" definiert sind.
- Die Protokollierung dieses Nachrichtenereignistyps muss über den Status der Maske für die Nachrichtenprotokollfunktion aktiviert werden.
- Der Typ des Nachrichtenereignisses muss alle Filterbedingungen übergeben, die von der Laufzeitumgebung von WebSphere Application Server selbst aufgestellt werden.
Wenn eine Protokollfunktion (Logger) von WebSphere Application Server von der Klasse "Manager" abgerufen wird, sieht die Ausgangseinstellung der Maske vor, dass alle nativen Nachrichtenereignistypen an den Handler von WebSphere Application Server weitergeleitet werden. Sie können festlegen, welche Nachrichten protokolliert werden, indem Sie den Status der Maske für die Nachrichtenprotokollfunktion über das Programm definieren.
Einige Editionen des Produkts unterstützen benutzerdefinierte Stufen für Nachrichtenfilter für einen Serverprozess. Wenn eine solche Filterstufe definiert ist, werden nur die Nachrichten mit den angegebenen Wertigkeitsstufen in WebSphere Application Server geschrieben. Nachrichtentypen, die die Maskenprüfung der Nachrichtenprotokollfunktion erfolgreich durchlaufen, können von WebSphere Application Server gefiltert werden.
Traceerstellung steuern
Jede Produkt-Edition stellt ein Verfahren für das Aktivieren bzw. Inaktivieren des Trace bereit. Die verschiedenen Editionen können die statische Traceaktivierung (Traceeinstellungen werden angegeben, bevor der Server gestartet wird) und/oder die dynamische Traceaktivierung (Traceeinstellung für einen laufenden Serverprozess können dynamisch geändert werden) unterstützen.
- Der Traceereignistyp muss einer der Traceereignistypen sein, die in der Schnittstelle "RASITraceEvent" definiert sind.
- Die Protokollierung dieses Traceereignistyps muss durch den Status der Traceprotokollfunktionsmaske aktiviert werden.
- Der Traceereignistyp muss alle Filterbedingungen übergeben, die von der Laufzeit von WebSphere Application Server selbst aufgestellt werden.
Wenn eine Protokollfunktion von der Klasse "Manager" abgerufen wird, sieht die Ausgangseinstellung der Maske vor, dass alle Tracetypen unterdrückt werden. Ausgenommen von dieser Regel ist der Fall, in dem WebSphere Application Server zur Laufzeit die Aktivierung statischer Traces unterstützt und ein vom Standard abweichender Anfangstracestatus für diese Traceprotokollfunktion angegeben wurde. Im Gegensatz zu Nachrichtenprotokollfunktionen kann WebSphere Application Server den Status einer Traceprotokollfunktionsmaske dynamisch ändern. WebSphere Application Server ändert nur den Abschnitt der Traceprotokollfunktionsmaske, die den in der Schnittstelle "RASITraceEvent" definierten Werten entspricht. WebSphere Application Server nimmt keine Änderungen an nicht definierten Bits der Maske vor, die möglicherweise von anderen benutzerdefinierten Typen verwendet werden.
Wenn auf einigen Plattformen die Aktivierung dynamischer Traces verwendet wird, spiegelt sich die Änderung des Tracestatus in der Laufzeitumgebung des Anwendungsservers und in der Tracemaske der Traceprotokollfunktion wider. Sollte der Benutzercode die Bits in der Tracemaske gemäß den von der Schnittstelle "RASITraceEvent" definierten Werten über das Programm ändern, sind Status der Protokollfunktionsmaske und Laufzeitstatus nicht mehr synchron, und es treten unerwartete Ereignisse auf. Deshalb wird die programmgesteuerte Änderung der Maskenbits, die den in der Schnittstelle "RASITraceEvent" definierten Werten entsprechen, nicht unterstützt.