Environment Configuration

Having different configurations based on the application’s environment can be highly beneficial. For example, environment configuration allows you to customize script policies, override document styles with a user-defined stylesheet, or handle web requests. To facilitate this, Aspose.HTML for Java offers the Configuration class specifically designed to fulfill these requirements. By utilizing the Configuration object, you can effortlessly tailor the behavior of your Java application according to your specific needs.

Sandboxing

A sandboxing flag set is a set of zero or more flags that limit the capabilities of potentially untrusted resources. A sandbox provides a secure and controlled execution environment by isolating potentially malicious or untrusted code from the underlying system and sensitive data.

The following Java example demonstrates how to convert an HTML document to PDF format and apply sandboxing restrictions – how to mark Scripts as an untrusted resource. As a result, Scripts will be disabled during the application execution.

// @code-snippet1
// 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");

In the example, a new instance of Configuration class is created to configure the sandbox. The setSecurity() method is called on the configuration object, passing com.aspose.html.Sandbox.Scripts as an argument. This flag enables sandboxing and restricts the execution of scripts within the HTML document.

User Agent Service

All important functional is grouped into separated services for usability purpose and located into the Package com.aspose.html.services. In the context of environment configuration, the User Agent Service allows you to specify a custom user stylesheet, a primary character set for the document, language and fonts settings.

User Style Sheet

The user is able to specify a custom style information for a particular document. This information applies to the document according to the cascading rules and may affect the presentation of the document. The following Java code snippet showcases the usage of the User Agent Service ( IUserAgentService) for applying a custom user stylesheet to an HTML document that is then converted to PDF.

Let’s just look at the necessary steps to specify a custom style sheet in an HTML document:

1. In the example, we use the Configuration() constructor to create an instance of the Configuration class.
2. Then we call the getService() method on the Configuration class and pass the IUserAgentService.class to it as a parameter. So, we get an instance of the User Agent Service.
3. To set a custom user stylesheet to be applied to the HTML document, we use the setUserStyleSheet() method of the User Agent Service, providing a CSS code as an argument. In this case, the CSS rule span { color: green; } is used to make all <span> elements display text in green color.

// @code-snippet2
// 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 the 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");

Character Set

In order to parse and display an HTML document correctly, the application must know what character set (encoding) is used for the document. If the character encoding is not directly specified in the document’s header, Aspose.HTML uses UTF-8, which is defined as the default for HTML5 specification. However, if you are sure that your HTML document is written differently from UTF-8 encoding, you can specify it manually. Let’s consider the necessary steps to specify a character set (encoding) in the HTML document:

1. Create an instance of Configuration class.
2. Use the getService() method to get an instance of the User Agent Service. The method takes the IUserAgentService.class as a parameter.
3. Call the setCharSet() method of the User Agent Service and provide the desired character set (encoding). In this example, ISO-8859-1 is set as the character set.

// @code-snippet3

// 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");

By setting the character set using the setCharSet() method, the application informs the Aspose.HTML for Java parsing and rendering engine about the specific encoding used in the HTML document. This is very important because different character sets can represent characters differently, and without the correct encoding information, the document may not be accurately parsed or displayed.

Set Path to the Font Folder

One of the key features of Aspose.HTML is its ability to work with custom fonts, allowing developers to add their own fonts to the rendering process. For a situation when you need to use the custom fonts instead of the fonts installed on OS, you can set the path to your custom folder, as it follows:

// @code-snippet4

// 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 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");

To set font folder using Aspose.HTML for Java, we use the setFontsLookupFolder() method of the FontsSettings class. This method allows you to specify the folder where custom fonts are located. By setting the font folder, Aspose.HTML will look for fonts in the specified folder when rendering the HTML document.

The figure illustrates the result of the FontsSettings and UserStyleSheet applying (b) to the source “user-agent-fontsetting.html” file (a).

Runtime Service

The Runtime Service gives you control over the lifetime of the internal processes. For instance, using IRuntimeService you can specify timeouts for JavaScripts. It is important to have such a timeout in case if a script contains an endless loop. The following code snippet demonstrates how to use the Runtime Service to limit JavaScript execution time and convert an HTML document to an image format:

1. In the example, we create an HTML document from scratch. Prepared HTML code includes an infinite loop within a <script> element. We use the FileWriter() to write the HTML code to a file.
2. Create an instance of Configuration class.
3. Call the getService() method to get an instance of the Runtime Service.
4. Use the setJavaScriptTimeout() method of the Runtime Service to specify the maximum allowed JavaScript code execution time. The example is set to 5 seconds.
5. Create an HTMLDocument object using the HTMLDocument(address, configuration) constructor. It takes the path to the previously created HTML file and the configuration object.
6. Convert HTML to PNG using convertHTML(document, options, outputPath) method.

In the example, if the timeout of 5 seconds is exceeded during JavaScript execution, Aspose.HTML for Java will interrupt JavaScript code execution and continue with the remaining HTML to PNG conversion process.

// @code-snippet5
// 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");

Network Service

INetworkService allows you to control all incoming/outcoming traffic and implement your custom message handlers. It can be used for different purposes, such as: create custom caching mechanism, trace/logging request messages, etc.

Message Handlers

Using the MessageHandler class and overriding the invoke() method, you can define custom logic that will be executed during network operations. The following example demonstrates how to use message handlers to log information about unreachable resources. In the example, the logic checks the response status code and handles the case where the file is not found:

// @code-snippet6

// Create a MessageHandler. This 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);
    }
};

First of all, you need to create a custom message handler and use it, as it follows:

// @code-snippet7

// 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 Configuration
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");

Conclusion

The Environment Configurations feature in Aspose.HTML for Java allows developers to fine-tune their applications’ behavior to meet specific requirements. Using the Configuration class and its associated services, you can effectively manage critical aspects such as security, customization, character encoding, font settings, runtime, and network operations.

• Sandbox improves security by restricting the execution of potentially harmful scripts.
• User Agent Service allows customization of styles, character sets, and fonts, offering a tailored document rendering experience.
• Runtime Service provides control over the JavaScript execution time to prevent unresponsive or malicious scripts.
• Network Service facilitates customized handling of network requests by providing robust logging, caching, and traffic control.

You can download the complete examples and data files from GitHub.