Kapitel 4. Integration der jadice document platform

Die Implementation des Logging-Delegates für Log4J(2) entspricht folgender Namenskonvention:

logging-log4j-version.jar beziehungsweise logging-log4j2-version.jar

In der Auslieferung finden Sie die entsprechenden Log4J(2)-Delegates, jeweils passend zu den im Einsatz befindlichen jadice Modulen, unter folgender Verzeichnisstruktur:

lib/logging

Fügen Sie bitte den zu Ihrer jadice Version passenden Log4J(2)-Delegate sowie auch Log4J(2) selbst in den Klassenpfad der Anwendung ein. Ist eine log4J-Konfiguration bereits auf dem Klassenpfad verfügbar, wird keine weitere Konfiguration benötigt.

Log4J(2) wie auch detaillierte Informationen zur Konfiguration finden Sie auf der Log4J Homepage. Die zugehörigen Manuals finden Sie unter Log4J Manual und Log4J2 Manual.

Die Namenskonvention des Logging-Delegates von SLF4J entspricht folgendem Schema:

logging-slf4j-version.jar

Wie auch für Log4J finden Sie das entsprechende SLF4J-Delegate, jeweils passend zu den im Einsatz befindlichen jadice Modulen, unter folgender Verzeichnisstruktur:

lib/logging

Fügen Sie das zu Ihrer jadice Version passende SLF4J Delegate in den Klassenpfad der Anwendung ein. Zusätzlich wird das slf4j-api-version.jar und eine Logging-Implementierung benötigt. Detaillierte Informationen über SLF4J und unterstützte Typen der Logging Delegates und Implementierungen finden Sie auf der SLF4J Homepage beziehungsweise im SLF4J Manual.

Ein Großteil aller Klassen der jadice document platform generiert Logging-Ausgaben. Wird eine dieser Klassen aktiviert – also durch den ClassLoader geladen – fordert sie beim jadice Logging-Framework einen Logger an. Mit der ersten Anfrage an das Framework wird dieses initialisiert und durchsucht den Klassenpfad nach dem gewünschten Ziel-Logging-System. Sollte diese Suche fehlschlagen, wird die folgende Nachricht auf der Kommandozeile ausgegeben:

Unable to initialize logging.

Eine weitere Nachricht auf der Kommandozeile stellt daraufhin nähere Angaben über den Grund des Fehlschlags zur Verfügung. Es existieren zwei Arten von Gründen:

Häufig – vor allem während der Implementationsphase – ist es gewünscht, für eine Gesamtapplikation nur die wichtigsten Log-Meldungen auszugeben, für einzelne Komponenten jedoch detaillierte Informationen zu erhalten. Die gebräuchlichen Logging-Frameworks unterstützen dieses Konzept indem eine Hierarchie von Loggern gebildet wird. Die Detailtiefe der erzeugten Log-Meldungen kann für Teile dieser Hierarchie festgelegt werden.

Die in jadice verwendeten Logger bilden ihre Hierarchie nach einer festen Konvention, die sich an den Klassennamen in denen der Logger verwendet wird orientiert. Bis auf wenige Ausnahmen trägt jeder Logger den voll qualifizierten Namen der Klasse, in der er benutzt wird. Dies ermöglicht eine sehr leichte Einschränkung der Logger-Konfiguration auf einzelne Klassen oder, über die Verwendung des Package-Namens, auf Teilkomponenten der jadice document platform.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration PUBLIC "-//Apache//DTD Log4j 1.2//EN"
    "http://logging.apache.org/log4j/docs/api/org/apache/log4j/xml/log4j.dtd">

<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">

  <!-- ... general configuration ... -->

  <!-- for all jadice classes, log only error messages -->
  <logger name="com.levigo" additivity="true">
        <level value="error"/>
  </logger>

  <!-- for all other Loggers, log info messages -->
  <root>
    <level value="info" />
    <!-- ... specify logging destination via log4j appender ... -->
  </root>

</log4j:configuration>

Grundsätzlich sollte man sich darüber im Klaren sein, dass eine hohe Anzahl von Logausgaben die Ausführungsgeschwindigkeit der Applikation negativ beeinträchtigen kann. Würde beispielsweise in der Log4J-Konfiguration das Logging für sämtliche Klassen der jadice document platform auf debug gesetzt, hätte dies eine erhebliche Geschwindigkeitsbeeinträchtigung sowie gegebenenfalls die Erstellung großer Log-Dateien zur Folge. Für den Produktionseinsatz sollten Konfigurationen dieser Art daher vermieden werden. Auch zur Entwicklungszeit empfiehlt es sich, die Ausgabe detaillierter Log-Meldungen auf die jeweils relevanten Komponenten zu beschränken.

Die Formatierung der einzelnen Log-Ausgaben hat ebenfalls einen Einfluss auf die zur Generierung notwendige Rechenzeit. Die meisten Ziel-Logging-Systeme bieten Möglichkeiten, das Aussehen von Log-Messages zu bestimmen. Dabei wird auch festgelegt, welche Zusatzinformationen – wie beispielsweise der Klassenname oder ein Zeitstempel – enthalten sein sollen. Unter Log4J können Einstellungen dieser Art über ein sogenanntes PatternLayout vorgenommen werden. Insbesondere komplexere Formatierungen sollten nur eingestellt werden, wo es wirklich notwendig ist.

Wie es auch in den Ziel-Logging-Systemen allgemein üblich ist, verwendet das jadice Logging Framework verschiedene Kategorien um die Wichtigkeit und Tragweite einer Log-Message einzuordnen. Die Kategorien werden Log Levels genannt und durch die Façade auf geeignete Levels des Ziel-Logging-Systems abgebildet. Es existieren mehrere Log Levels, die den von Log4J angebotenen entsprechen.

Die folgende Aufstellung zeigt, in welchen Fällen die einzelnen Levels innerhalb der jadice document platform verwendet werden.

Der Log-Level DEBUG dient dazu, einzelne Detailabläufe nachzuvollziehen. Nachrichten, die unter diesem Level produziert werden, sind hauptsächlich zur Analyse von Fehlersituationen notwendig. Wird die jadice document platform auf diesen Level konfiguriert, so wird das durch die Anzeige eines entsprechenden Wasserzeichens auf der Viewer-Komponente verdeutlicht. Der Nutzer wird durch diese Meldung darauf hingewiesen, dass die Applikation umfangreiche Log-Meldungen ausgibt und daher nicht die reguläre Performance zu erwarten ist.

Für Produktivsysteme wird empfohlen, den Log-Level auf WARN zu setzen. So werden in Fehlerfällen die wichtigsten Informationen ausgegeben ohne dass im günstigen Fall die Performance beeinträchtigt wird.

Ereignisse, die ein gewissen Schweregrad darstellen oder die in integrierenden Anwendungen möglicherweise spezifische Reaktionen auslösen sollen, werden in jadice als Qualified Log-Events kategorisiert. Die jadice document platform propagiert diese Ereignisse an QualifiedLogListener Instanzen.

QualifiedLogEvents können in den Schweregraden WARN, ERROR und FATAL auftreten. Um QualifiedLogEvents zu erhalten, müssen Realisierungen von QualifiedLogListener an dem zentralen jadice Logging Mechanismus registriert werden. Dieser wird durch die Klasse LoggingConfiguration repräsentiert. Eine Instanz der LoggingConfiguration kann mithilfe der statischen Methode LoggingConfiguration.getGlobal() bezogen werden.

Die Registrierung eines Listeners kann für zwei unterschiedliche Gültigkeitsbereiche erfolgen: Es können entweder alle qualifizierten Log-Messages der genannten Levels angefordert werden oder nur solche, die auf dem zum Registrierungs-Zeitpunkt verwendeten Thread produziert werden.

Wird ein QualifiedLogListener benachrichtigt, so erfolgt dies in Form eines QualifiedLogEvents. Neben der tatsächlichen Nachricht, die auch variable Textfragmente enthalten kann, besitzt jedes QualifiedLogEvent eine eindeutige ID, die angibt um welchen Typ von Event es sich handelt. Tritt beispielsweise ein Fehler im Lesevorgang eines Formats auf, so könnte die ID allgemein darüber informieren, dass ein Lesefehler in einem Format auftrat, während die Log-Message zusätzlich den Namen des Formats angeben könnte. Diese Trennung erlaubt es, auf gleichartige Events in einer definierten Weise zu reagieren.

Die ID eines QualifiedLogEvents setzt sich zusammen aus zwei Teilen: Component ID und Event ID. Erstere bezeichnet den Teilbereich der jadice document platform, dem die Meldung entstammt. Letztere bezeichnet den Typ des Events. Die gesamte ID wird als String repräsentiert in welchem die beiden Teile durch einen Bindestrich (-) voneinander getrennt sind; weitere Bindestriche sind nicht enthalten. Die Trennung der ID in zwei Bestandteile hat den Vorteil, dass auf eine ganze Gruppe von Nachrichten in gleicher Weise reagiert werden kann. Die jadice document platform gruppiert beispielsweise solche Events, die im Zusammenhang mit dem Rendering auftreten, unter einer gemeinsamen Component ID. Über entsprechende Filterung und Anzeigelogik könnte somit bewirkt werden, dass sämtliche Warnungen oder Fehler, die im Zusammenhang mit dem Rendering auftreten, dem Nutzer in einer Message Box angezeigt werden.

Als Hilfestellung geben sämtliche Log-Messages, die an Instanzen von QualifiedLogListener verteilt werden, ihre vollständige ID auch auf der Konsole aus. Diese kann notiert und in einem QualifiedLogListener verwendet werden.