Konfiguration

Server-Konfiguration

Der Server kann über die ServerConfiguration konfiguriert werden. Zugriff darauf erhält man über ConfigurationManager .getServerConfiguration(). Mittels setServerConfiguration(ServerConfiguration serverConfiguration) kann eine eigene ServerConfiguration gesetzt werden, sofern ein eigenes Konfigurationsframework eingebunden werden soll. In der Regel ist dies aber nicht notwendig, da die Einstellungen auch direkt auf der bestehenden ServerConfiguration geändert werden können. Standardmäßig wird eine DefaultServerConfiguration zurückgegeben.

• Über ConfigurationManager.getServerConfiguration().getNetworkConfiguration() können Details zur NetworkConfiguration eingestellt werden. Die verschiedenen Konfigurationsparameter sind unter Serverseitig nachzulesen.

• HTTP Session: Das jadice web toolkit erzeugt standardmäßig eine HTTP-Session (inkl. Cookie JSESSIONID) — der Default von alwaysCreateHttpSession in der NetworkConfiguration ist true. Die Session dient der Zuordnung des Transports (WebSocket/Longpoll) und ist Voraussetzung für den Tile-Security-Filter (s.u.). Soll keine Session erzeugt werden, kann das über ConfigurationManager.getServerConfiguration().getNetworkConfiguration().setAlwaysCreateHttpSession(false); abgeschaltet werden — dann steht die sessionbasierte Tile-Absicherung nicht zur Verfügung.

• Tile Security: Per Definition sind Tiles (gerenderte Kacheln) nicht "geschützt". Die URL einer Tile kann von einem anderen Client ausgeführt werden und der zweite Client erhält ebenfalls die Kachel angezeigt, sofern Sie nicht in Ihrer Integration einen eigenen Security-Filter einbauen. Es ist jedoch möglich, in Kombination mit der HTTP-Session (standardmäßig aktiv, s.o.) die Tile-Requests an eine HTTP-Session zu binden. Ein Tile kann dann nur von dem Client abgerufen werden, die das Tile initial erzeugt hat. Dies geschieht über ConfigurationManager.getServerConfiguration().setTileSecurityFilterEnabled(true); Bei manchen Konfigurationen kann es zudem erforderlich sein, in diesem Fall die application.yml ebenfalls anzupassen:

  server:
    servlet:
      session:
        cookie:
          same-site: none
          secure: true

  Der Tile-Security-Filter arbeitet standardmäßig fail-open: Trifft ein Tile-Request mit einer Client-ID ein, für die serverseitig keine Session-Bindung registriert ist (etwa eine unbekannte oder gefälschte Client-ID), wird er durchgelassen und die Session-Prüfung entfällt. Die Autorisierung liegt in diesem Fall allein beim DocumentDataProvider der Integration. Über ConfigurationManager.getServerConfiguration().setTileSecurityFilterFailClosed(true); (Spring-Property webtoolkit.tileSecurityFilterFailClosed, Default false) lässt sich der Filter auf fail-closed umstellen: Tile-Requests ohne registrierte Session-Bindung werden dann mit HTTP 401 abgelehnt. Fail-closed ist die sicherere Einstellung, greift aber in das Failover ein: Fällt im Mehrknoten-Betrieb ein Server aus, verbindet sich der Client per Recovery (siehe Load-Balancing) mit einem anderen Knoten. Dort ist die Session-Bindung seiner Client-ID zunächst nicht registriert, weshalb die ersten Tile-Requests im Fail-closed-Modus abgewiesen würden. Fail-open ist deshalb der Default, damit das Recovery nach einem Knotenausfall funktioniert. Fail-closed eignet sich für Einzelknoten-Installationen oder Umgebungen, in denen dieser Nachteil bewusst in Kauf genommen wird. Der Schalter wirkt nur, wenn der Tile-Security-Filter aktiviert ist. Die Client-ID (Query-Parameter c) ermitteln Filter und TileServlet mit derselben Parser-Logik, sodass ein manipulierter Query-String nicht zu abweichenden Werten und damit zu einer Umgehung des Filters führen kann.

• Remote-Logging: Über setRemoteLoggingEnabled(boolean) (Spring-Property webtoolkit.remoteLoggingEnabled, Default true) wird gesteuert, ob vom Client gesendete Log-Meldungen serverseitig ins Log geschrieben werden. Details zu Sanitisierung und Drosselung siehe Logging.

• Sitzungs-/Mandantentrennung im Dokument-Cache: Serverseitig geladene Dokumente werden in einem Cache gehalten, dessen Schlüssel bestimmt, welche Clients ein bereits geladenes Dokument "sehen". Standardmäßig ist useSessionSpecificDocumentKey deaktiviert — die Trennung hängt dann allein davon ab, was die konfigurierbare getClientIdFunction in den Cache-Schlüssel einbringt. Für Installationen, in denen mehrere Benutzer oder Mandanten denselben Server nutzen und nicht jede Dokument-URI global eindeutig und berechtigungsneutral ist, wird verbindlich empfohlen, useSessionSpecificDocumentKey auf true zu setzen (ConfigurationManager.getServerConfiguration().setUseSessionSpecificDocumentKey(true);) oder eine eigene getClientIdFunction zu konfigurieren, die den Benutzer-/Mandantenkontext einbezieht. Andernfalls können Dokumente zwischen Sitzungen sichtbar werden (Datenschutz-Relevanz, DSGVO Art. 32).

• Tile Caching: Über die Methoden setTileCachingEnabled(boolean tileCachingEnabled)/isTileCachingEnabled() wird definiert, ob die auf dem Server gerenderten Kacheln dort gecached werden sollen. In der DefaultServerConfiguration ist dieser Wert standardmäßig auf false gesetzt.

• Kompressionslevel des Tile Renderings bei Http-Requests: Über die Methoden setTileCompressionType(TileCompressionType tileCompressionType)/getTileCompressionType() wird definiert, wie der erzeugte PNG- oder WebP-Datenstrom beim TileRendering in den OutputStream für den Client geschrieben werden soll. Hierbei wird unterschieden zwischen ImageIO ("Best Compression", Default bis jadice 5.11.0.0), PNGJ in den Ausprägungen "Best Compression" und "Best Speed" und WebP in den Ausprägungen "Lossy" (Default) und "Lossless". Wenn WebP verwendet wird, prüft der Server bei einem Tile-Request, ob der Client WebP anzeigen kann. Ist das nicht der Fall, wird automatisch PNG über ImagIO (höchste Kompatibilität) zurückgeliefert. Die Werte sind über die Enum ServerConfiguration.TileCompressionType definiert.

• Eine Einstellung, die vom Integrator an der Server-Konfiguration vorbei vorgenommen werden kann, ist die ScreenResolution. Diese wird über die Methode GraphicsEnvironment.setUserDefinedScreenResolution(int resolution) direkt auf dem GraphicsEnvironment der jadice document platform vorgenommen. Der aktuell eingestellte Wert kann also serverseitig zu jeder Zeit wie beschrieben gesetzt und über GraphicsEnvironment.getScreenResolution() abgefragt werden. Hintergrund dieser Konfiguration ist, dass an einigen Stellen in der jadice document platform die Auflösung über das GraphicEnvironment und nicht über die BaseRenderSettings) abgefragt wird. Auf dem lokalen Rechner gibt dies die Auflösung des Rechners (bei Windows in der Regel 96) zurück. Auf Servern wird in der Regel aufgrund einer HeadlessException jedoch der Wert 72 verwendet. Um dieses Verhalten zu vereinheitlichen, wird der Wert im jadice web toolkit auf 96 voreingestellt (davon ausgehend, dass die meisten Clients Windows PCs mit genau dieser Auflösung sind).

• Thread Pools: jadice web toolkit verwendet im Wesentlichen zwei Thread Pools für Aufgaben wie beispielsweise das asynchrone Rendern von Tiles. Die Größe der Thread Pools richtet sich nach der Anzahl der CPUs im System. Um die Größe der Pools anzupassen, stehen über die ServerConfiguration die Methoden setGeneralPoolCoreSize()/setGeneralPoolMaxSize() und setTileRendererPoolCoreSize()/setTileRendererPoolMaxSize() bereit. Achtung: Eine falsche Konfiguration dieser Werte kann negative Auswirkungen auf das Gesamtsystem haben. Weiterführende Informationen finden Sie in dem Knowledge-Base-Artikel Thread Pools and Concurrency.

• Filter: Die Filter NoCacheFilter, CacheFilter und TileCacheFilter (siehe hier) können über die Methoden setCacheFilterEnabled(), setNoCacheFilterEnabled() und setTileCacheFilterEnabled() aktiviert bzw. deaktiviert werden.

Client-Konfiguration

Analog zum Server wird der Client über die ClientConfiguration konfiguriert. Auf die ClientConfiguration kann über ClientConfigurationManager .getClientConfiguration() zugegriffen werden. Über die Methode ClientConfigurationManager.setClientConfiguration(ClientConfiguration clientConfiguration) kann eine eigene Implementierung einer ClientConfiguration gesetzt werden. Dies ist aber in der Regel nicht notwendig, da die Einstellungen auch direkt auf der bestehenden ClientConfiguration geändert werden können. Standardmäßig wird eine DefaultClientConfiguration zurückgegeben.

• Clientseitige Verwendung von IconFonts: setIsIconFontUsed(boolean). Siehe hierzu Eigene Icons in Buttons

• Anzahl der parallelen Renderanfragen: Bei der Kachelübertragung muss die Anzahl der parallelen Serverrequests begrenzt werden, ansonsten könnte ein einziger Client den Server mit Anfragen überlasten. In der DefaultClientConfiguration wird die Anzahl der parallelen Tileanfragen auf 6 begrenzt. Dieser Wert kann über die Methode setMaxParallelTileRequests(int maxRequestCount) angepasst werden.

• Darstellungsqualität: Der Viewer verwendet standardmäßig das vom Browser gelieferte Device-Pixel-Ratio, um die Auflösung zu bestimmen, in der Dokumentseiten als Kacheln (Tiles) gerendert werden. Konfigurativ kann der automatisch erkannte Wert durch ein festes Verhältnis ersetzt werden, sodass alle nachfolgenden Render-Anfragen unabhängig von der tatsächlichen Display-Dichte den angegebenen Skalierungsfaktor verwenden. Dies ist in folgenden Szenarien nützlich:

  • Erzwingen einer hochauflösenden Darstellung auf Standard-Displays (z. B. für druckqualitätsnahe Vorschauen)
  • Reduzierung der Render-Auflösung auf HiDPI-Bildschirmen zur Verbesserung der Performance oder Verringerung der Bandbreite
  • Sicherstellen konsistenter Darstellung über verschiedene Client-Umgebungen hinweg (z. B. in Tests)

  Ein Wert von 1 entspricht der Standardauflösung (ein gerenderter Pixel pro CSS-Pixel), während 2 die gerenderten Abmessungen in jede Richtung verdoppelt und damit einem typischen HiDPI-/Retina-Display entspricht. Da dies bei hochauflösenden Bildschirmen zu lange Wartezeiten führen kann (da die Kacheln je nach Display dann 2 - 3 mal so groß gerendert werden müssen, wie sie angezeigt werden), kann über die ClientConfiguration eine fester Wert angegeben werden. Somit kann ein Kompromiss aus Renderzeit und Kachelschärfe erreicht werden. Per Default ist das fixedDevicePixelRatio auf 0. Somit wird das Device-Pixel-Ratio automatisch erkannt. Der Wert kann über setFixedDevicePixelRatio(double fixedDevicePixelRatio) gesetzt werden.

• Soll der minimale bzw. maximale Zoomfaktor begrenzt werden, so geht dies über die Methoden setMinZoomFactor(float minZoom) bzw. setMaxZoomFactor(float maxZoom). Zum Abfragen der Werte werden die Methoden getMinZoomFactor() bzw. getMaxZoomFactor() bereitgestellt. Standardmäßig werden keine Zoombegrenzungen gesetzt.

• Fokusverhalten des Browsers beim Annotations-Texteditor: Über setFocusTextEditor(boolean) kann das Fokusverhalten des Browsers in Bezug auf den Text Editor von textbasierten Annotationen gesteuert werden. Bei true wird das scrollverhalten des Browsers beim Fokussieren auf die eigenen Scrollbalken übernommen. Bei false wird das Scrollverhalten des Browsers ignoriert und zurückgesetzt.

Client-Konfiguration über den Server (NG-Stack)

Im TypeScript-/NG-Stack bezieht der Client seine Konfiguration beim Start zusätzlich vom Server: Der Endpoint GET /client-configuration liefert die über Spring-Properties konfigurierten Werte aus webtoolkit.clientConfiguration.* (z. B. maxUploadFileSize) an den Browser. Eigene, integrationsspezifische Schlüssel können über die Map webtoolkit.clientConfiguration.internalCustomProperties mitgegeben und im Frontend ausgewertet werden:

webtoolkit:
  clientConfiguration:
    maxUploadFileSize: 50000000
    internalCustomProperties:
      annotationProfileId: "MyProfile"
      myCustomFlag: "true"

Vollständige Property-Referenz

Eine verlässliche, vollständige Liste aller webtoolkit.*-Spring-Properties inklusive Beschreibung und Default-Werten liefert die Datei spring-configuration-metadata.json im webtoolkit-server-Artefakt — gängige IDEs werten sie automatisch aus und bieten in application.yml/application.properties Autovervollständigung samt Dokumentation an.