Installation und Konfiguration

Server

Der jadice server ist ab Sun/Oracle Java VM in Version 11 11.0.8 or newer (Deprecated but still supported for version 5.8: Sun/Oracle Java VM in Version 1.8.0 Update 3 (Java 8) or newer) lauffähig. Für die Installation muss zuerst die Distributionsdatei (i. d. R. jadice-server-5.x.y.z-dist.zip) in ein leeres Verzeichnis auf einem lokalen Laufwerk des Servers entpackt werden. Datei- oder Ordnernamen, die im weiteren Verlauf dieses Entwicklerhandbuchs genannt werden, sind relativ zu diesem Verzeichnis.

Die Installations-/Startdateien befinden sich im Verzeichnis /bin.

Um jadice server als Windows-Dienst zu installieren und zu administrieren, stehen folgende Dateien zur Verfügung:

installService.bat

        Installiert einen Windowsdienst mit Namen "levigo jadice server 5".

startService.bat

        Startet den Dienst.

stopService.bat

        Beendet den Dienst.

queryService.bat

        Ermittelt den Status des Dienstes.

systemTrayIconW.bat

        Startet ein Tray-Icon in der Taskleiste, über das der Windows-Dienst
        jadice server gestartet und gestopt werden kann. Außerdem werden
        Exceptions, die während des Betriebs von jadice server auftreten,
        als Benachrichtigungen eingeblendet.

Zur Ausführung dieser Dateien werden gegebenenfalls Administrationsrechte angefordert.

Alternativ kann der Server mit dem Skript jadice-server.bat gestartet werden. Für Linux-basierte Betriebssysteme ist das Skript jadice-server.sh zu verwenden. Beim Start wird eine Konsole geöffnet; mit der Tastenkombination [ STRG+C ] kann jadice server beendet werden.

Um jadice server als Linux/Unix-Daemon zu installieren und zu administrieren, stehen folgende Dateien zur Verfügung:

startDaemon.sh

        Startet den Daemon.

stopDaemon.sh

        Beendet den Daemon.

queryDaemon.sh

        Ermittelt den Status des Daemon.

systemTrayIcon.sh

        Startet ein Tray-Icon in der Taskleiste, über das der Daemon jadice
        server gestartet und gestopt werden kann. Außerdem werden
        Exceptions, die während des Betriebs von jadice server auftreten,
        als Benachrichtigungen eingeblendet.

Die Dateien mit der Dateinamenendung NoPriv startet das jeweilige Shell-Script nicht unter dem sudo-Befehl.

Alle serverseitig benötigten jar-Dateien befinden sich im Verzeichnis /server-lib.

Lizenzdatei

Neben der Distributionsdatei von jadice server erhalten Sie eine separate Lizenzdatei (JadiceServerLicense.properties) . Diese muss im Konfigurationsverzeichnis /server-config des jadice server abgelegt werden.

Ist diese Datei nicht vorhanden bzw. die Lizenz abgelaufen oder ungültig, wird beim Start des jadice servers sowie bei jeder Anforderung eines _JOBs eine Fehlermeldung in das Server- und das Client-Log geschrieben.

Sollte es sich um eine zeitlich beschränkte Evaluationslizenz handeln, wird nur beim Start des Servers eine Meldung gezeigt. Darüber hinaus gibt es keine Funktionseinschränkungen des jadice server.

Manueller Download für Silbentrennung

jadice server verwendet Apache FOP zur Konvertierung von XML-Dokumenten und E-Mails nach PDF. Aus lizenzrechtlichen Gründen darf das optionale Paket zur Silbentrennung dem Auslieferungspaket von jadice server nicht beiliegen. Dies ist jedoch frei unter http://offo.sourceforge.net/ verfügbar. Zur Installation muss lediglich die Datei hyphenation.jar in den Ordner server-lib kopiert werden.

Konfiguration des Messagingsystems

Es stehen drei Varianten für den Aufbau des Messagingsystems zur Verfügung.

Eingebetteter Broker (Standard)
- Betrieb eines Brokers innerhalb der JVM von jadice server
- Einsatz von Apache ActiveMQ
- Clusterfähig durch "Network of Brokers"
- Konfiguration siehe nächster Abschnitt
Separater Broker
- Einsatz eines separaten Brokers auf der Infrastruktur des jadice server
- Einsatz beliebiger kompatibler MOM
- Ggf. clusterfähig
Separate MOM-Infrastruktur
- Einsatz separater MOM-Infrastruktur
- Einsatz beliebiger kompatibler MOM
- Verfügbarkeit muss durch Infrastruktur sichergestellt werden

Welche dieser drei Varianten zum Einsatz kommt, wird in der XML-Konfiguration bestimmt. Im Abschnitt <bean id="jms-connection-factory" …> in der Datei server-config/application/activemq-client.xml wird der zu verwendende Konnektor und in Datei server-config/application/server.xml im Abschnitt <property name="properties" …> unter jadice.server.queue-name der Name der Message-Queue und unter jadice.server.activemq-port der Port für ActiveMQ konfiguriert, wohin sich jadice server verbinden soll. Da die Klasse ActiveMQConnectionFactory sowohl QueueConnectionFactory wie auch TopicConnectionFactory implementiert, wird sie über die Aliase jms-queue-connection-factory wie auch jms-topic-connection-factory an den jeweils passenden Stellen referenziert.

Beispiele, wie Verbindungen über IBM Websphere MQ aufgebaut werden können, sind in der Datei server-config/application/example/jms.xml zu finden. Die passende Konfiguration muss anstelle der vorhandenen Abschnitte <bean id="jms-queue-connection-factory" …> bzw. <bean id="jms-topic-connection-factory" …> in die XML-Konfiguration eingebunden werden.

Konfiguration des eingebetteten Messagebrokers

jadice server stellt standardmäßig das zu verwendende Messagingsystem (d. h. den Message-Broker) in der Server-Instanz bereit. In diesem Falle wird Apache ActiveMQ als Messagingsystem verwendet. Es wird in der Datei server-config/application/embedded-activemq-broker.xml konfiguriert. Um die Übertragung zwischen Client und Server mit SSL zu verschlüsseln, findet sich unter http://activemq.apache.org/ssl-transport-reference.html und http://activemq.apache.org/how-do-i-use-ssl.html eine Anleitung, wie dies realisiert werden kann.

Der Port und der Name der verwendeten Messagequeue werden zentral in der Datei server-config/application/server.xml konfiguriert, siehe Abschnitt Konfiguration des Messagingsystems

Um diesen internen Broker nicht zu starten, muss der Abschnitt <feature>embedded-activemq-broker</feature> in der Datei server-config/application/active-features.xml auskommentiert werden.

Clustering

Folgende Konfigurationsänderung ist notwendig, um jadice server via ActiveMQ in einem Cluster zu betreiben:

In der Datei server-config/application/embedded-activemq-broker.xml die Kommentarzeichen um eins der beiden Elemente <networkConnector …> entfernen.

Der Cluster hat dabei folgenden Aufbau:

Auf jedem Knoten läuft eine Instanz von jadice server mit jeweils einem eingebetteten Broker unter Apache ActiveMQ.
Das Clustering basiert auf einem ActiveMQ Network-of-Brokers, d. h. der eingebettete Broker eines jeden Knotens nimmt gleichberechtigt an einem verteilten Broker teil.
Die Broker finden sich entweder gegenseitig über Auto-Discovery, das über Multicast realisiert wird, oder das Network-of-Brokers wird statisch definiert.

Damit das Clustering wirksam ist, müssen die Clients entsprechend konfiguriert werden. Finden sich die Broker über Auto-Discovery, so kann man für Clientverbindungen die Methode Multicast-Discovery verwenden. Dazu muss der Gruppenname des Clusters bekannt sein, den die jadice server-Instanzen bilden. Dieser wird in der Datei /server-config/application/server.xml unter jadice.server.activemq-group gesetzt und lautet standardmäßig jadice-server.cluster.

Die URL, mit der sich ein Client in diesem Fall mit dem Cluster verbinden kann, lautet (vgl. Codebeispiel im Abschnitt „Erstellen eines Server-Jobs“): discovery:(multicast://default)?group=jadice-server.cluster&initialReconnectDelay=100

Wurde ein statisches Network-of-Brokers definiert, muss die Verbindungs-URL ebenfalls statisch definiert werden: failover:(<URL_Server_A>,<URL_Server_B>), zum Beispiel: failover:(tcp://serverA:61616,tcp://serverB:61616).

Konfiguration Wrapper

Der Server wird über einen betriebssystemabhängigen Wrapper gestartet. Hier werden Java VM und Klassenpfad-Parameter definiert.

Die Wrapper-Konfigurationsdatei wrapper.conf befindet sich im Verzeichnis /wrapper.

Pfad zur Java VM:

# Java Application
wrapper.java.command=java

Definition weiterer Klassenpfadeinträge:

# Java Classpath (include wrapper.jar)  Add class path # elements as needed starting from 1
wrapper.java.classpath.1=../bin/server-console.jar
wrapper.java.classpath.2=../msoffice-lib
# Beispiel eines weiteren Klassenpfadeintrags:
wrapper.java.classpath.N=...

Die Nummerierung muss fortlaufend sein und darf sich nicht mit bereits vorhandenen Einträgen überschneiden.

Werden für die Java Virtual Machine (JVM) zusätzliche Parameter benötigt, z. B. Setzen des temporären Verzeichnisses für die VM, können diese auf folgende Weise gesetzt werden:

# Beispiel zusätzlicher JVM Parameter
wrapper.java.additional.1=-server
wrapper.java.additional.2=-Djava.io.tmpdir=C:\tmp
wrapper.java.additional.N=<weitere Parameter>

Wird der jadice server im Multi-VM-Modus gestartet, werden diese Parameter nur für die zentrale Instanz wirksam (vgl. Abschnitt Konfiguration Multi-VM-Modus)

Definition JVM-Speichereinstellungen, wrapper.java.initmemory entspricht Parameter -Xms, wrapper.java.maxmemory entspricht Parameter -Xmx:

# Initial Java Heap Size (in MB)
#wrapper.java.initmemory=3

# Maximum Java Heap Size (in MB)
wrapper.java.maxmemory=512

Außerdem ist es möglich, den Klassenpfad und somit die geladenen Java-Bibliotheken zu ändern, um beispielsweise jadice server um eigene Worker-Implementierungen zu erweitern. Dies geschieht in den Dateien /server-config/jadice-server.options und /server-config/jadice-server-local.options. Folgende Einträge sind hier möglich:

`-cp` `<jar-Bibliothek>`	Fügt eine einzelne `jar`-Bibliothek zum Klassenpfad von jadice server hinzu.
`--classpath` `<jar-Bibliothek>`
`-ld` `<Verzeichnis>`	Alle `jar`-Bibliotheken, die im angegebenen Verzeichnis vorhanden sind, werden in alphabetischer Reihenfolge zum Klassenpfad von jadice server hinzugefügt.
`--library-dir` `<Verzeichnis>`

Dabei ist zu beachten, dass zwischen der Option und dem Parameter ein Zeilenumbruch erfolgen muss. Der effektive Klassenpfad wird in folgender Weise gebildet:

Einträge unter -cp / --classpath aus jadice-server.options
Einträge unter -cp / --classpath aus jadice-server-local.options
Einträge unter -ld / --library-dir aus jadice-server.options
Einträge unter -ld / --library-dir aus jadice-server-local.options

Des Weiteren sind folgende Optionen möglich:

`-xo` `<Konfigurationsdatei>`	Bindet eine weitere Konfigurationsdatei ein. Diese muss hier gezeigter Syntax entsprechen.
`--extra-options` `<Konfigurationsdatei>`
`-dCL`	Beim Start wird eine Auflistung des effektiven Klassenpfads und der Classloader-Hierarchie angezeigt.
`--debug-classpath`
`-dX`	Eventuelle Exceptions und Stacktraces, die während des Startens geworfen werden, werden ausgegeben.
`--debug-using-exceptions`

Kompatibilität mit Drittkomponenten

In unserer Knowledge Base finden Sie eine Übersicht über die Kompatibilität von jadice server 5 mit Drittkomponenten. Dieser Knowledge Base Eintrag bezieht sich immer auf die aktuellste jadice server 5 Version

Konfiguration LibreOffice

Es muss auf das Verzeichnis <LibreOffice-Verzeichnis>/program verwiesen werden, damit der Server auf die Programmdatei von LibreOffice zugreifen kann. Die Konfiguration steht in der Datei /server-config/jadice-server-local.options, z. B.

# LibreOffice Verzeichnis
-cp
C:\Program Files\Libre Office 5\program\

Unter MS Windows Vista, Windows 7 und Server 2008 dürfen nicht die symbolischen Dateipfade verwendet werden; anstelle von z. B. C:\Programme (x86)\ muss C:\Program Files (x86)\ angegeben werden.

Außerdem ist es notwendig, die Dateien <LibreOffice-Verzeichnis>/program/classes/java_uno.jar, juh.jar, jurt.jar, ridl.jar, unoloader.jar und unoil.jar im Klassenpfad einzubinden. Zusätzlich müssen die JVM und LibreOffice binärkompatibel sein (x86 / x64).

Sind die Pfade nicht richtig konfiguriert, wird bei einer Konvertierung ein Fehler ausgegeben.

Auf Nicht-Windows-Betriebssystemen (Linux, Unix u. ä.) muss außerdem das Paket Xvfb (X window virtual framebuffer) installiert sein, damit ein fensterloser und somit automatisierter Betrieb von LibreOffice erfolgen kann.

Konfiguration MS Office

Die Ansteuerung von MS Office wird via DCOM-Schnittstelle vorgenommen. Nach dem Sicherheitsupdate KB3155544 werden Berechtigungen für den DCOM Zugriff benötigt. Eine detaillierte Beschreibung der Einstellung dieser Berechtigungen finden Sie unter Jadice Server MS-Office Konvertierung nach Sicherheitsupdate .

Im "Trust Center" (deutsch: "Vertrauensstellungscenter") von MS Office muss eingestellt werden, wie mit Makros umgegangen werden soll. Da im Serverbetrieb keine Benutzerabfrage möglich ist, ist die Optionen "Alle Makros ohne Benachrichtigung deaktivieren" (siehe Abbildung 5.1, „Zulässige Einstellung für Makros in MS Office“). Ebenso ist mit den ActiveX-Einstellungen zu verfahren.

Abbildung 5.1, „Zulässige Einstellung für Makros in MS Office“

Ist jadice server wie in Server beschrieben als Windows-Dienst installiert, darf dieser nicht unter dem lokalen Systemkonto angemeldet sein, sondern unter einem technischen Benutzerkonto (siehe Abbildung 5.2. Installation von jadice server unter einem technischen Benutzerkonto). Andernfalls kann es bei der Konvertierung über MS Office zu diversen, nicht nachvollziehbaren Fehlern kommen.

Abbildung 5.2. Installation von jadice server unter einem technischen Benutzerkonto

Konfiguration MS Outlook

Um die Sicherheitsbestimmung zu umgehen, die es verbieten, dass jadice server auf MS Outlook zugreift, muss das Programm Advanced Security for Outlook installiert und konfiguriert werden.

Konfiguration:

Loggen Sie sich mit unter dem Benutzer, unter dem jadice server läuft, auf dem Server-Rechner ein.
Starten Sie eine Konvertierung, die den MSOutlookNode auslöst.
Bestätigen Sie den Dialog von Advanced Security for Outlook mit Allow Access und Always perform ...

Außerdem müssen unter MS Outlook 2007 die Option "Bei Programmbeendigung Ordner 'Gelöschte Objekte' leeren" aktiviert. Sie finden diese Einstellung unter → Optionen → Weitere. Außerdem muss die Option "Warnung anzeigen, bevor Elemente endgültig gelöscht werden" deaktiviert sein. Diese Einstellung befindet sich unter unter Extras → Optionen → Weitere → Erweiterte Optionen.

Ab MS Outlook 2019 ist es nicht mehr möglich Outlook mit einem Profil ohne E-Mail-Konto zu starten, da die Option ohne ein Konto fortzufahren nicht mehr verfügbar ist. Stattdessen können Sie Outlook einmalig via "Outlook.exe /PIM <profile name>" starten (https://support.office.com/de-de/article/verwenden-von-outlook-ohne-e-mail-konto-477a1fc3-4423-4156-bef4-67489edfdbef), um ein leeres Profil anzulegen.

Außerdem muss ab MS Outlook 2019 beim DCOM-Eintrag "Outlook Message Attachment" ebenfalls der technischer User hinterlegt werden. Eine detaillierte Beschreibung für das Setzen von DCOM-Einstellungen finden Sie unter Jadice Server MS-Office Konvertierung nach Sicherheitsupdate .

Konfiguration MS Project 2010

Um MS Project-Dateien konvertieren zu können, die mit vorhergehenden Versionen erstellt wurden, muss "das Laden von Dateien mit Vorversions- oder nicht standardmäßigen Dateiformaten" zugelassen im Sicherheitscenter (engl. Trust Center) von MS Project 2010 eingestellt werden:

Abbildung 5.3. Einstellung für Legacyformate in MS Project 2010

Konfiguration logging

Zur Verwaltung von Log-Einträgen wird auf das Framework log4j 2 zurückgegriffen. Dieses wird in der Datei /server-config/log4j2.xml konfiguriert. Standardmäßig werden Log-Meldungen auf die Konsole ausgeschrieben sowie im Verzeichnis /log/ gespeichert.

Die Dateien, die in diesem Verzeichnis gespeichert werden, werden in der Standardkonfiguration täglich rotiert. Dies geschieht mit Hilfe des Log-Appenders RollingRandomAccessFileAppender. Da dieser nicht die Option bietet, dass nur die Log-Dateien der letzten n Tage aufbewahrt werden, sollten Sie sicherstellen, dass für das Speichern der Log-Dateien ausreichend Speicherplatz zur Verfügung steht oder die ältesten Dateien automatisch und regelmäßig ausgelagert oder gelöscht werden. Der RollingRandomAccessFileAppender bietet dazu die Option nur eine maximale Anzahl an Dateien aufzubewahren.

Das Layout der Lognachrichten ist standardmäßig Date Priority [Category] Message\n für die Konsolenausgabe und Date Priority [NDC; Category; Thread] Message\n für die Logdatei. Weitere Möglichkeiten für das Layout sind in der Konfigurationsdatei als Kommentare aufgeführt und müssen lediglich aktiviert werden.

Um die Performance der Anwendung durch das Logging möglichst wenig einzuschränken, werden standardmäßig alle Logger global auf asynchron gestellt. Dies kann deaktiviert werden, indem die entsprechende System-Property in der Datei /wrapper/wrapper.conf im Abschnitt Java Additional Parameters entfernt wird.

Falls Sie ein anderes Logging-Framework einsetzen möchten, können Sie einfach die log4j Bibliotheken in /server-libs/ durch ihre eigenen ersetzen.

Konfiguration Ghostscript

Um den GhostscriptNode verwenden zu können, müssen zunächst folgende Voraussetzungen geschaffen werden:

Installation von GPL Ghostscript, Version 8.64 oder neuer
Anpassung der Datei /server-config/ghostscript/ghostscript.xml. Unter <bean id="ghostscript" …> muss ein Element eingefügt werden, das folgenden Inhalt hat: <property name="executableName" value="<Ort der Ghostscript-Anwendungsdatei>" />

Für die Orte, unter denen Ghostscript unter Windows bzw. Linux standardmäßig installiert wird, sind bereits Vorlagen vorhanden. Hierzu muss nur der passende XML-Kommentar entfernt werden.

Konfiguration ImageMagick

Um den ImageMagickConvertNode verwenden zu können, müssen zunächst folgende Voraussetzungen geschaffen werden:

Installation von ImageMagick, Version 7.0.11 oder neuer
Unter Linux ist keine weitere Anpassung notwendig
Unter Windows muss eine Anpassung der Datei /server-config/imagemagick/imagemagick.xml erfolgen. Unter <bean id="imagemagick" …> muss ein Element eingefügt werden, das folgenden Inhalt hat: <property name="imageMagickSearchPath" value="<Ort der ImageMagick-Anwendungsdatei>"/>

Konfiguration Multi-VM-Modus

Durch die Einbindung von externen Bibliotheken ist es möglich, dass diese in einem Fehlerfall die Java Virtual Machine und somit auch den kompletten jadice server zum Absturz bringen.

Um in diesem Fall mit der Bearbeitung von weiteren Jobs fortzufahren, gibt es die Möglichkeit, den jadice server auf einem Rechner in mehreren Instanzen zu starten. Hierbei übernimmt eine zentrale Instanz des jadice servers die Überwachung aller anderen, die die eigentliche Arbeit durchführen. Sollte eine dieser Arbeiter-Instanzen nicht mehr reagieren oder abgestürzt sein, beendet die zentrale Instanz den zugehörigen Prozess und startet automatisch eine neue Instanz des jadice servers.

Um jadice server in diesem Modus zu starten, muss in der Datei /server-config/application/active-features.xml das Kommentarzeichen um <feature>mvm</feature>{.XML} entfernt werden.

In der Datei /server-config/application/multi-vm-manager.xml können die Arbeiterinstanzen im Abschnitt <bean id="mvm-manager" …> konfiguriert werden. Um die Anzahl der zu startenden Arbeiter-Instanzen anzupassen, gibt es folgende Möglichkeiten:

Feste Anzahl an Arbeiterinstanzen: <property name="fixedVMCount" value="<n>" />
n Arbeiterinstanzen je Prozessorkern: <property name="perProcessorVMCount" value="<n> />"

Des Weiteren können unter <property name="instanceJVMOptions" …> der zu startenden JVM Startparameter wie z. B. die verfügbare Speichergröße mitgegeben werden.

Um in den Log-Meldungen die jeweilige Instanz anzugeben, sollten in der Datei /server-config/log4j2.xml die Layouts für den Multi-VM-Modus aktiviert werden.

Konfiguration SOAP-Schnittstelle

Um die SOAP-Schnittstelle, über die Anfragen im XML-Format an den jadice server gestellt werden können, zu aktivieren, muss in der Datei server-config/application/active-features.xml die Kommentarmarkierung um das Element <feature>soap</feature> entfernt werden.

In der Datei server-config/application/soap.xml wird im Element <jaxws:endpoint …> ein Endpunkt (als Instanz von javax.xml.ws.Endpoint) des Webservices propagiert. Das vorgegebene Attribut address="http://${jadice.server.hostname}:9000/jadiceServer" stellt den Endpunkt unter dem Namen des Rechners auf Port 9000 bereit.

Zur Verwendung der SOAP-Schnittstelle siehe SOAP-Schnittstelle.

Konfiguration REST-Schnittstelle

Um die REST-Schnittstelle, über die Anfragen im XML- oder im JSON-Format an den jadice server gestellt werden können, zu aktivieren, muss in der Datei server-config/application/active-features.xml die Kommentarmarkierung um das Element <feature>rest</feature> entfernt werden.

In der Datei server-config/application/rest.xml wird im Element <jaxrs:server …> der JAX-RS-Endpunkt der REST-Schnittstelle propagiert. Das vorgegebene Attribut address="http://${jadice.server.hostname}:9001/jadiceServer" stellt den Endpunkt unter dem Namen des Rechners auf Port 9001 bereit.

Zur Verwendung der REST-Schnittstelle siehe REST-Schnittstelle.

Konfiguration Security-Schnittstelle

Über die Security-Schnittstelle kann verhindert werden, dass Clients ohne Authentifikation auf jadice server und ohne Beschränkungen auf dessen vollen Funktionsumfang zugreifen. Um diese Schnittstelle zu aktivieren, muss zunächst in der Datei server-config/application/active-features.xml die Kommentarmarkierung um die Abschnitte mit <feature>security</feature> entfernt werden.

Die Datei server-config/application/security.xml enthält eine beispielhafte Konfiguration, die zunächst auf die gewünschte Sicherheitsstufe angepasst werden muss. Dies und wie die Sicherheits-Schnittstelle anschließend verwendet werden kann, ist in Sicherheits-Schnittstelle beschrieben.

Client

Für den clientseitigen Einsatz müssen die jar-Dateien aus dem Verzeichnis /client-lib in den Klassenpfad der Anwendungs-/ Entwicklungsumgebung eingebunden werden.

Die Verwendung der Client-Bibliotheken ist zusammen mit Codebeispielen in Anwendung / Funktionalität beschrieben.

Client Logging

Die Codebasis von jadice server macht an vielen Stellen Gebrauch von Logging um auf Probleme hinzuweisen und Nachvollziehbarkeit zu ermöglichen. Zur Nutzung von Logging existieren mehrere allgemein erhältliche Frameworks, die verschiedene Ansätze verfolgen und über unterschiedlichen Leistungsumfang verfügen.

Da jadice server-Client-API zur Einbindung in eine Gesamtapplikation konzipiert ist, legt sie sich nicht auf die Verwendung eines bestimmten Logging-Frameworks fest. Es existiert stattdessen die jadice Logging Framework Fassade, die das Logging-System der integrierenden Applikation mitverwenden kann.

Die jadice Logging Framework Fassade

Das jadice Logging-Framework erlaubt ein direktes und einfaches Einbinden der bekanntesten und verbreitetsten Logging-Systeme und -Frameworks, wie JDK Logging, Log4J, SLF4J und via SLF4J Logback, JCL, x4Juli und viele andere mehr. Sofern Sie bereits eines der erwähnten Frameworks einsetzen, ist zur Ausgabe von Logmeldungen in eines dieser Logging-Systeme oft nur eine Modifikation des Klassenpfads notwendig.

Falls kein bestimmtes Logging-Delegate, sprich ein bestimmtes Logging-Framework, durch den Klassenpfad vorgegeben oder verfügbar ist, wird der in Java enthaltene JDK-Logger als Fallback verwendet. Da der JDK-Logger immer zur Verfügung steht, ist es unerheblich, wann das gewünschte Ziel-Loggingsystem im Klassenpfad zur Verfügung gestellt wird. Auch ist es möglich, während der Entwicklungsphase ein anderes Loggingsystem zu verwenden als im Produktivsystem. Durch Verwendung der Logging-Fassade ist selbst ein späterer Wechsel des Logging Systems ohne weiteren Programmieraufwand möglich.

Die folgenden Abschnitte gehen zunächst auf die Verwendung der Logging-Fassade mit unterschiedlichen Ziel-Logging-Frameworks ein.

Verwendung existierender Logging-Systeme

Die Auslieferung des jadice server stellt neben dem Standard JDK-Logger zwei weitere Implementationen von Logging-Delegates zur Verfügung. Soll Log4J verwendet werden, fügen Sie die entsprechende Log4J-Implementation dem Klassenpfad der Anwendung hinzu. Zur Verwendung eines anderen Logging-Frameworks nehmen Sie statt dessen die entsprechende SLF4J-Implementation im Klassenpfad auf.

Eine detaillierte Beschreibung, wo die gewünschte Implementation des Logging-Delegates in der Auslieferung zu finden ist, ob und welche weiteren Schritte notwendig sind, entnehmen Sie bitte den folgenden Abschnitten.

Die in der Auslieferung enthaltenen Logging-Delegates benötigen keine weitere spezifische Konfiguration. Eine Anpassung des Verhaltens des Ziel-Logging-Systems, zum Beispiel des Log-Levels oder ähnlichem, wird grundsätzlich über die Konfigurationsmöglichkeiten des jeweiligen Ziel-Logging-Systems gesteuert.

Log4J

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

logging-log4j-version.jar

In der Auslieferung finden Sie das entsprechende Log4J-Delegate, jeweils passend zu den im Einsatz befindlichen jadice server-Client-API-Modulen, im Verzeichnis client-lib/logging.

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

Log4J wie auch detaillierte Informationen über die Log4J Konfiguration finden Sie auf der Log4J Homepage und im Log4J Manual.

SLF4J

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 server-Client-API-Modulen, im Verzeichnis client-lib/logging.

Fügen Sie bitte den zu Ihrer jadice server-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.

Mögliche Fehlermeldungen

Ein Großteil aller Klassen der jadice server-Client-API 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:

No logging delegation implementation on classpath

Tritt diese Fehlermeldung auf, so wurde keine der beiden in den vorigen Abschnitten beschriebenen Logging-Delegates für Log4J oder SLF4J im Klassenpfad gefunden. Es muss daher die .jar-Datei für das gewünschte Ziel-Logging-System korrekt dem Java-Klassenpfad hinzugefügt werden wie in den vorhergehenden Abschnitten beschrieben.

Initialization failure due to exception

Diese Fehlermeldung deutet auf ein Problem des zugrundeliegenden Ziel-Logging-Systems hin und kann daher vielfältige Ursachen haben. Im Allgemeinen sollte die Dokumentation des entsprechenden Systems konsultiert werden.

Die folgenden Beispiele geben Anhaltspunkte für einzelne Fehlersituationen.

Beispiel 5.2. Fehlende SLF4J-Bibliothek

Unable to initialize logging.
    Initialization failure due to exception:
    java.lang.NoClassDefFoundError: org/apache/log4j/LogManager
            at com.levigo.util.log.impl.Log4JLogFactory.<clinit>(Log4JLogFactory.java:23)
            at com.levigo.util.log.impl.LoggingBinder.getLoggerFactory(LoggingBinder.java:17)
            at com.levigo.util.log.LoggerFactory.<clinit>(LoggerFactory.java:24)
            ... (some more omitted entries)
    No logging binder available. Using JDK logging instead.

In diesem Fall ist es wahrscheinlich, dass die Log4J-Bibliothek nicht im Klassenpfad vorhanden ist. Zur Lösung des Problems muss die entsprechende .jar-Datei in den Klassenpfad der Applikation aufgenommen werden und sichergestellt werden, dass auf die Datei zugegriffen werden kann.

Beispiel 5.2. Fehlende SLF4J-Bibliothek

Die folgende Fehlerausgabe zeigt das gleiche Problem, dieses Mal jedoch durch das Fehlen der notwendigen SLF4J-Bibliothek hervorgerufen. Zur Lösung des Problems muss die entsprechende .jar-Datei in den Klassenpfad der Applikation aufgenommen werden und sichergestellt werden, dass auf die Datei zugegriffen werden kann.

Unable to initialize logging.
    Initialization failure due to exception:
    java.lang.NoClassDefFoundError: org/slf4j/LoggerFactory
            at com.levigo.util.log.impl.Slf4JLogFactory.<clinit>(Slf4JLogFactory.java:17)
            at com.levigo.util.log.impl.LoggingBinder.getLoggerFactory(LoggingBinder.java:17)
            at com.levigo.util.log.LoggerFactory.<clinit>(LoggerFactory.java:24)
            ... (some more omitted entries)
    No logging binder available. Using JDK logging instead.

Beispiel 5.3. Fehlender Delegate für SLF4J

Da es sich bei SLF4J selbst ebenfalls um eine Logging-Fassade handelt, kann der folgende Fehler auftreten.

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
    SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
    Unable to initialize logging.
    Initialization failure due to exception:
    java.lang.NoClassDefFoundError: org/slf4j/impl/StaticLoggerBinder
            at org.slf4j.LoggerFactory.<clinit>(LoggerFactory.java:60)
            at com.levigo.util.log.impl.Slf4JLogFactory.<clinit>(Slf4JLogFactory.java:17)
            at com.levigo.util.log.impl.LoggingBinder.getLoggerFactory(LoggingBinder.java:17)
            at com.levigo.util.log.LoggerFactory.<clinit>(LoggerFactory.java:24)
            at com.levigo.jadice.gui.AbstractJadicePanel.<clinit>(AbstractJadicePanel.java:42)
            ... (some more omitted entries)
    No logging binder available. Using JDK logging instead.

Nähere Hinweise zur Behebung der Fehlersituation finden sich in der Dokumentation zu SLF4J.

Installation in der Entwicklungsumgebung Eclipse

Server

Ein neues Java-Projekt anlegen.
Folgende jar-Dateien zum Klassenpfad hinzufügen:
- Alle jar-Dateien aus dem Verzeichnis /server-lib
- Datei activemq-all-5.x.x.jar aus dem Verzeichnis /apache-activemq
- Alle Dateien spring-###-3.x.y.jar aus dem Verzeichnis /apache-activemq-5.x.x/lib/optional.
Alle Konfigurationsdateien aus dem Verzeichnis /server-conf in das Source-Verzeichnis (src) kopieren.

Zum Schluss die Klasse JadiceServerControl aus der jar-Datei server-core-5.x.y.z.jar starten.
Der Server ist nun betriebsbereit.

Client

Ein neues Java-Projekt anlegen.
Alle jar-Dateien aus dem Verzeichnis /client-lib zum Klassenpfad hinzufügen.

jadice server - documentation

5.9.0.0

Server

Lizenzdatei

Manueller Download für Silbentrennung

Konfiguration des Messagingsystems

Konfiguration des eingebetteten Messagebrokers

Clustering

Konfiguration Wrapper

Kompatibilität mit Drittkomponenten

Konfiguration LibreOffice

Konfiguration MS Office

Konfiguration MS Outlook

Konfiguration MS Project 2010

Konfiguration logging

Konfiguration Ghostscript

Konfiguration ImageMagick

Konfiguration Multi-VM-Modus

Konfiguration SOAP-Schnittstelle

Konfiguration REST-Schnittstelle

Konfiguration Security-Schnittstelle

Client

Client Logging

Die jadice Logging Framework Fassade

Verwendung existierender Logging-Systeme

Log4J

SLF4J

Mögliche Fehlermeldungen

Installation in der Entwicklungsumgebung Eclipse

Server

Client