Umgebung Konfiguration

Unterschiedliche Konfigurationen, die auf der Umgebung der Anwendung basieren, können sehr vorteilhaft sein. Die Umgebungskonfiguration ermöglicht es Ihnen zum Beispiel, Skriptrichtlinien anzupassen, Dokumentstile mit einem benutzerdefinierten Stylesheet zu überschreiben oder Webanfragen zu bearbeiten. Um dies zu erleichtern, bietet Aspose.HTML for Java die Klasse Configuration an, die speziell dafür entwickelt wurde, diese Anforderungen zu erfüllen. Durch die Verwendung des Configuration-Objekts können Sie das Verhalten Ihrer Java-Anwendung mühelos an Ihre spezifischen Bedürfnisse anpassen.

Sandboxing

Ein Sandboxing-Flag ist ein Satz von null oder mehr Flags, die die Fähigkeiten von potenziell nicht vertrauenswürdigen Ressourcen einschränken. Eine Sandbox bietet eine sichere und kontrollierte Ausführungsumgebung, indem sie potenziell bösartigen oder nicht vertrauenswürdigen Code vom zugrunde liegenden System und sensiblen Daten isoliert.

Das folgende Java-Beispiel zeigt, wie ein HTML-Dokument in das PDF-Format konvertiert und Sandboxing-Beschränkungen angewandt werden, d. h. wie Scripts als nicht vertrauenswürdige Ressource gekennzeichnet werden. Infolgedessen werden Scripts während der Ausführung der Anwendung deaktiviert.

// How to disable scripts for HTML to PDF conversion using Java

// Prepare HTML code and save it to a file
String code = "<span>Hello, World!!</span>\n" +
        "<script>document.write('Have a nice day!');</script>\n";

try (java.io.FileWriter fileWriter = new java.io.FileWriter("sandboxing.html")) {
    fileWriter.write(code);
}

// Create an instance of the Configuration class
Configuration configuration = new Configuration();

// Mark 'scripts' as an untrusted resource
configuration.setSecurity(com.aspose.html.Sandbox.Scripts);

// Initialize an HTML document with specified configuration
HTMLDocument document = new HTMLDocument("sandboxing.html", configuration);

// Convert HTML to PDF
Converter.convertHTML(document, new PdfSaveOptions(), "sandboxing_out.pdf");

Im Beispiel wird eine neue Instanz der Klasse Configuration erstellt, um die Sandbox zu konfigurieren. Die Methode setSecurity() wird für das Objekt Configuration aufgerufen, wobei com.aspose.html.Sandbox.Scripts als Argument übergeben wird. Dieses Flag aktiviert die Sandbox und schränkt die Ausführung von Skripten innerhalb des HTML-Dokuments ein.

Benutzeragentendienst - User Agent Service

Alle wichtigen Funktionen sind aus Gründen der Benutzerfreundlichkeit in getrennten Diensten gruppiert und im Paket com.aspose.html.services untergebracht. Im Zusammenhang mit der Umgebungskonfiguration ermöglicht der User Agent Service die Angabe eines benutzerdefinierten Stylesheets, eines primären Zeichensatzes für das Dokument sowie von Sprach- und Schrifteinstellungen.

Benutzer-Stylesheet

Der Benutzer kann benutzerdefinierte Stilinformationen für ein bestimmtes Dokument angeben. Diese Informationen gelten für das Dokument gemäß den Kaskadierungsregeln und können die Darstellung des Dokuments beeinflussen. Der folgende Java-Codeausschnitt zeigt die Verwendung des User Agent Service ( IUserAgentService) zur Anwendung eines benutzerdefinierten Stylesheets auf ein HTML-Dokument, das anschließend in PDF konvertiert wird.

Schauen wir uns nur die notwendigen Schritte an, um eine benutzerdefinierte Stilvorlage in einem HTML-Dokument anzugeben:

1. Im Beispiel verwenden wir den Konstruktor Konfiguration(), um eine Instanz der Klasse Configuration zu erstellen.
2. Dann rufen wir die Methode getService() der Klasse Configuration auf und übergeben ihr die Klasse IUserAgentService.class als Parameter. So erhalten wir eine Instanz des User Agent Service.
3. Um ein benutzerdefiniertes Stylesheet festzulegen, das auf das HTML-Dokument angewendet werden soll, verwenden wir die Methode setUserStyleSheet() des User Agent Service und geben einen CSS-Code als Argument an. In diesem Fall wird die CSS-Regel span { color: green; } verwendet, damit alle <span>-Elemente den Text in grüner Farbe anzeigen.

// Apply a custom user stylesheet to HTML content and convert it to PDF using Java

// Prepare HTML code and save it to a file
String code = "<span>Hello, World!!!</span>";

try (java.io.FileWriter fileWriter = new java.io.FileWriter("user-agent-stylesheet.html")) {
    fileWriter.write(code);
}

// Create an instance of the Configuration class
Configuration configuration = new Configuration();

// Get the IUserAgentService
IUserAgentService userAgent = configuration.getService(IUserAgentService.class);

// Set a custom color to the <span> element
userAgent.setUserStyleSheet("span { color: green; }");

// Initialize an HTML document with specified configuration
HTMLDocument document = new HTMLDocument("user-agent-stylesheet.html", configuration);

// Convert HTML to PDF
Converter.convertHTML(document, new PdfSaveOptions(), "user-agent-stylesheet_out.pdf");

Zeichensatz - Character Set

Um ein HTML-Dokument korrekt zu parsen und anzuzeigen, muss die Anwendung wissen, welcher Zeichensatz (Kodierung) für das Dokument verwendet wird. Wenn die Zeichenkodierung nicht direkt in der Kopfzeile des Dokuments angegeben ist, verwendet Aspose.HTML UTF-8, das als Standard für die HTML5-Spezifikation definiert ist. Wenn Sie jedoch sicher sind, dass Ihr HTML-Dokument anders als in UTF-8 kodiert ist, können Sie es manuell angeben. Betrachten wir die notwendigen Schritte zur Angabe eines Zeichensatzes (Kodierung) im HTML-Dokument:

1. Erstellen Sie eine Instanz der Klasse Configuration.
2. Verwenden Sie die Methode getService(), um eine Instanz des User Agent Service zu erhalten. Die Methode nimmt die IUserAgentService.class als Parameter.
3. Rufen Sie die Methode setCharSet() des User Agent Service auf und geben Sie den gewünschten Zeichensatz (Kodierung) an. In diesem Beispiel wird ISO-8859-1 als Zeichensatz festgelegt.

// Set User Agent charset to ISO-8859-1 and convert HTML to PDF using Java

// Prepare HTML code and save it to a file
String code = "<h1>Character Set</h1>\r\n" +
        "<p>The <b>CharSet</b> property sets the primary character-set for a document.</p>\r\n";

try (java.io.FileWriter fileWriter = new java.io.FileWriter("user-agent-charset.html")) {
    fileWriter.write(code);
}

// Create an instance of the Configuration class
Configuration configuration = new Configuration();

// Get the IUserAgentService
IUserAgentService userAgent = configuration.getService(IUserAgentService.class);

// Set ISO-8859-1 encoding to parse the document
userAgent.setCharSet("ISO-8859-1");

// Initialize an HTML document with specified configuration
HTMLDocument document = new HTMLDocument("user-agent-charset.html", configuration);

// Convert HTML to PDF
Converter.convertHTML(document, new PdfSaveOptions(), "user-agent-charset_out.pdf");

Durch das Setzen des Zeichensatzes mit der Methode setCharSet() informiert die Anwendung die Aspose.HTML for Java Parsing- und Rendering-Engine über die spezifische Kodierung, die im HTML-Dokument verwendet wird. Dies ist sehr wichtig, da verschiedene Zeichensätze Zeichen unterschiedlich darstellen können, und ohne die korrekten Kodierungsinformationen kann das Dokument möglicherweise nicht genau geparst oder angezeigt werden.

Pfad zum Schriftartenordner festlegen

Eines der Hauptmerkmale von Aspose.HTML ist die Fähigkeit, mit benutzerdefinierten Schriftarten zu arbeiten, so dass Entwickler ihre eigenen Schriftarten zum Rendering-Prozess hinzufügen können. Für eine Situation, in der Sie die benutzerdefinierten Schriftarten anstelle der auf dem Betriebssystem installierten Schriftarten verwenden müssen, können Sie den Pfad zu Ihrem benutzerdefinierten Ordner wie folgt festlegen:

// Set font folder for HTML to PDF conversion using Java

// Prepare HTML code and save it to a file
String code = "<h1>FontsSettings property</h1>\r\n" +
        "<p>The FontsSettings property is used for configuration of fonts handling.</p>\r\n";

try (java.io.FileWriter fileWriter = new java.io.FileWriter("user-agent-fontsetting.html")) {
    fileWriter.write(code);
}

// Initialize an instance of the Configuration class
Configuration configuration = new Configuration();

// Get the IUserAgentService
IUserAgentService userAgent = configuration.getService(IUserAgentService.class);

// Set a custom font folder path
userAgent.getFontsSettings().setFontsLookupFolder("fonts");

// Initialize an HTML document with specified configuration
HTMLDocument document = new HTMLDocument("user-agent-fontsetting.html", configuration);

// Convert HTML to PDF
Converter.convertHTML(document, new PdfSaveOptions(), "user-agent-fontsetting_out.pdf");

Um den Schriftordner mit Aspose.HTML for Java festzulegen, verwenden wir die Methode setFontsLookupFolder() der Klasse FontsSettings. Mit dieser Methode können Sie den Ordner angeben, in dem sich die benutzerdefinierten Schriftarten befinden. Durch das Festlegen des Schriftordners sucht Aspose.HTML beim Rendern des HTML-Dokuments nach Schriftarten im angegebenen Ordner.

Die Abbildung zeigt das Ergebnis der Anwendung von FontsSettings und UserStyleSheet (b) auf die Quelldatei “user-agent-fontsetting.html” (a).

Laufzeitdienst - Runtime Service

Der Runtime Service gibt Ihnen die Kontrolle über die Lebensdauer der internen Prozesse. Mit IRuntimeService können Sie zum Beispiel Timeouts für JavaScripts festlegen. Eine solche Zeitüberschreitung ist wichtig für den Fall, dass ein Skript eine Endlosschleife enthält. Der folgende Codeschnipsel zeigt, wie man den Runtime Service verwendet, um die Ausführungszeit von JavaScript zu begrenzen und ein HTML-Dokument in ein Bildformat zu konvertieren:

1. In diesem Beispiel wird ein HTML-Dokument von Grund auf neu erstellt. Der vorbereitete HTML-Code enthält eine Endlosschleife innerhalb eines <script>-Elements. Wir verwenden den FileWriter(), um den HTML-Code in eine Datei zu schreiben.
2. Erstellen Sie eine Instanz der Klasse Configuration.
3. Rufen Sie die Methode getService() auf, um eine Instanz des Runtime Service zu erhalten.
4. Verwenden Sie die Methode setJavaScriptTimeout() des Runtime-Dienstes, um die maximal zulässige Ausführungszeit für JavaScript-Code anzugeben. Das Beispiel ist auf 5 Sekunden eingestellt.
5. Erstellen Sie ein HTMLDocument-Objekt mit dem Konstruktor HTMLDocument(address, configuration). Er nimmt den Pfad zu der zuvor erstellten HTML-Datei und das Konfigurationsobjekt.
6. Konvertierung von HTML in PNG mit der Methode convertHTML(document, options, outputPath).

Wenn im Beispiel die Zeitüberschreitung von 5 Sekunden während der JavaScript-Ausführung überschritten wird, unterbricht Aspose.HTML for Java die Ausführung des JavaScript-Codes und fährt mit dem restlichen HTML-zu-PNG-Konvertierungsprozess fort.

// Limit JavaScript execution time when converting HTML to image using Java

// Prepare HTML code and save it to a file
String code = "<h1>Runtime Service</h1>\r\n" +
        "<script> while(true) {} </script>\r\n" +
        "<p>The Runtime Service optimizes your system by helping it start apps and programs faster.</p>\r\n";

try (java.io.FileWriter fileWriter = new java.io.FileWriter("runtime-service.html")) {
    fileWriter.write(code);
}

// Create an instance of the Configuration class
Configuration configuration = new Configuration();

// Limit JS execution time to 5 seconds
IRuntimeService runtimeService = configuration.getService(IRuntimeService.class);
runtimeService.setJavaScriptTimeout(TimeSpan.fromSeconds(5));

// Initialize an HTML document with specified configuration
HTMLDocument document = new HTMLDocument("runtime-service.html", configuration);

// Convert HTML to PNG
Converter.convertHTML(document, new ImageSaveOptions(), "runtime-service_out.png");

Netzdienst - Network Service

INetworkService ermöglicht es Ihnen, den gesamten eingehenden/ausgehenden Datenverkehr zu kontrollieren und Ihre benutzerdefinierten Nachrichten-Handler zu implementieren. Er kann für verschiedene Zwecke verwendet werden, wie z. B.: Erstellung eines benutzerdefinierten Caching-Mechanismus, Verfolgung/Protokollierung von Anforderungsnachrichten usw.

Nachrichten-Handler

Mit der Klasse MessageHandler und der Überschreibung der Methode invoke() können Sie eine benutzerdefinierte Logik definieren, die bei Netzwerkoperationen ausgeführt wird. Das folgende Beispiel demonstriert die Verwendung von MessageHandlern zur Protokollierung von Informationen über nicht erreichbare Ressourcen. In diesem Beispiel prüft die Logik den Antwortstatuscode und behandelt den Fall, dass die Datei nicht gefunden wird:

// Log failed HTTP requests with a custom MessageHandler

// Message handler logs all failed requests to the console
MessageHandler handler = new MessageHandler() {
    @Override
    public void invoke(INetworkOperationContext context) {
        if (context.getResponse().getStatusCode() != HttpURLConnection.HTTP_OK) {
            System.out.println(String.format("File '%s' Not Found", context.getRequest().getRequestUri().toString()));
        }

        // Invoke the next message handler in the chain
        next(context);
    }
};

Zunächst müssen Sie einen benutzerdefinierten Message-Handler erstellen und ihn wie folgt verwenden:

// Handle missing image requests with a custom MessageHandler in Aspose.HTML for Java

// Prepare HTML code with missing image file
String code = "<img src='missing.jpg'>";

try (java.io.FileWriter fileWriter = new java.io.FileWriter("document.html")) {
    fileWriter.write(code);
}

// Create an instance of the Configuration class
Configuration configuration = new Configuration();

// Add ErrorMessageHandler to the chain of existing message handlers
INetworkService network = configuration.getService(INetworkService.class);
LogMessageHandler logHandler = new LogMessageHandler();
network.getMessageHandlers().addItem(logHandler);

// Initialize an HTML document with specified configuration
// During the document loading, the application will try to load the image and we will see the result of this operation in the console
HTMLDocument document = new HTMLDocument("document.html", configuration);

// Convert HTML to PNG
Converter.convertHTML(document, new ImageSaveOptions(), "output.png");

Schlussfolgerung

Die Funktion Umgebungskonfigurationen in Aspose.HTML for Java ermöglicht Entwicklern die Feinabstimmung des Verhaltens ihrer Anwendungen, um spezifische Anforderungen zu erfüllen. Mit der Klasse “Konfiguration” und den damit verbundenen Diensten können Sie kritische Aspekte wie Sicherheit, Anpassung, Zeichenkodierung, Schrifteinstellungen, Laufzeit und Netzwerkoperationen effektiv verwalten.

• Sandbox verbessert die Sicherheit, indem es die Ausführung potenziell schädlicher Skripte einschränkt.
• der User Agent Service ermöglicht die Anpassung von Stilen, Zeichensätzen und Schriftarten und bietet so ein maßgeschneidertes Dokument-Rendering-Erlebnis.
• der Runtime Service bietet Kontrolle über die JavaScript-Ausführungszeit, um nicht reagierende oder bösartige Skripte zu verhindern.
• der Network Service erleichtert die benutzerdefinierte Bearbeitung von Netzwerkanfragen durch robuste Protokollierung, Caching und Datenverkehrskontrolle.

Sie können die vollständigen Beispiele und Datendateien unter GitHub herunterladen.