Environment Configuration – Java

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 offers the Configuration class specifically designed to fulfill these requirements. By utilizing the Configuration object, you can effortlessly tailor the behavior of your Aspose.HTML 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.

// 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(Resources.output("sandboxing.html"))) {
    fileWriter.write(code);
}

// Create an instance of the Configuration class
com.aspose.html.Configuration configuration = new com.aspose.html.Configuration();
try {
    // Mark 'scripts' as an untrusted resource
    configuration.setSecurity(com.aspose.html.Sandbox.Scripts);

    // Initialize an HTML document with specified configuration
    com.aspose.html.HTMLDocument document = new com.aspose.html.HTMLDocument(Resources.output("sandboxing.html"), configuration);
    try {
        // Convert HTML to PDF
        com.aspose.html.converters.Converter.convertHTML(
                document,
                new com.aspose.html.saving.PdfSaveOptions(),
                Resources.output("sandboxing_out.pdf")
        );
    } finally {
        if (document != null) {
            document.dispose();
        }
    }
} finally {
    if (configuration != null) {
        configuration.dispose();
    }
}

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.

Services

All important functional is grouped into separated services for usability purpose and located into the Package com.aspose.html.services.

User Agent Service

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.

// 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
com.aspose.html.Configuration configuration = new com.aspose.html.Configuration();
try {
    // Get the IUserAgentService
    com.aspose.html.services.IUserAgentService userAgent = configuration.getService(com.aspose.html.services.IUserAgentService.class);

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

    // Initialize an HTML document with specified configuration
    com.aspose.html.HTMLDocument document = new com.aspose.html.HTMLDocument(Resources.output("user-agent-stylesheet.html"), configuration);
    try {
        // Convert HTML to PDF
        com.aspose.html.converters.Converter.convertHTML(
                document,
                new com.aspose.html.saving.PdfSaveOptions(),
                Resources.output("user-agent-stylesheet_out.pdf")
        );
    } finally {
        if (document != null) {
            document.dispose();
        }
    }
} finally {
    if (configuration != null) {
        configuration.dispose();
    }
}

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.

// 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(Resources.output("user-agent-charset.html"))) {
    fileWriter.write(code);
}

// Create an instance of the Configuration class
com.aspose.html.Configuration configuration = new com.aspose.html.Configuration();
try {
    // Get the IUserAgentService
    com.aspose.html.services.IUserAgentService userAgent = configuration.getService(com.aspose.html.services.IUserAgentService.class);

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

    // Initialize an HTML document with specified configuration
    com.aspose.html.HTMLDocument document = new com.aspose.html.HTMLDocument(Resources.output("user-agent-charset.html"), configuration);
    try {
        // Convert HTML to PDF
        com.aspose.html.converters.Converter.convertHTML(
                document,
                new com.aspose.html.saving.PdfSaveOptions(),
                Resources.output("user-agent-charset_out.pdf")
        );
    } finally {
        if (document != null) {
            document.dispose();
        }
    }
} finally {
    if (configuration != null) {
        configuration.dispose();
    }
}

By setting the character set using the setCharSet() method, the application informs the Aspose.HTML for .NET 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:

// 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(Resources.output("user-agent-fontsetting.html"))) {
    fileWriter.write(code);
}

// Initialize an instance of the Configuration class
com.aspose.html.Configuration configuration = new com.aspose.html.Configuration();
try {
    // Get the IUserAgentService
    com.aspose.html.services.IUserAgentService userAgent = configuration.getService(com.aspose.html.services.IUserAgentService.class);

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

    // Initialize an HTML document with specified configuration
    com.aspose.html.HTMLDocument document = new com.aspose.html.HTMLDocument(Resources.output("user-agent-fontsetting.html"), configuration);
    try {
        // Convert HTML to PDF
        com.aspose.html.converters.Converter.convertHTML(
                document,
                new com.aspose.html.saving.PdfSaveOptions(),
                Resources.output("user-agent-fontsetting_out.pdf")
        );
    } finally {
        if (document != null) {
            document.dispose();
        }
    }
} finally {
    if (configuration != null) {
        configuration.dispose();
    }
}

To set font folder using Aspose.HTML for Java library, we use the getFontsSettings() method to access the FontsSettings object. The setFontsLookupFolder() method is called on the FontsSettings object, specifying the folder path where the fonts are located.

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 will interrupt JavaScript code execution and continue with the remaining HTML to PNG conversion process.

// 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(Resources.output("runtime-service.html"))) {
    fileWriter.write(code);
}

// Create an instance of the Configuration class
com.aspose.html.Configuration configuration = new com.aspose.html.Configuration();
try {
    // Limit JS execution time to 5 seconds
    com.aspose.html.services.IRuntimeService runtimeService = configuration.getService(com.aspose.html.services.IRuntimeService.class);
    runtimeService.setJavaScriptTimeout(TimeSpan.fromSeconds(5));

    // Initialize an HTML document with specified configuration
    com.aspose.html.HTMLDocument document = new com.aspose.html.HTMLDocument(Resources.output("runtime-service.html"), configuration);
    try {
        // Convert HTML to PNG
        com.aspose.html.converters.Converter.convertHTML(
                document,
                new ImageSaveOptions(),
                Resources.output("runtime-service_out.png")
        );
    } finally {
        if (document != null) {
            document.dispose();
        }
    }
} finally {
    if (configuration != null) {
        configuration.dispose();
    }
}

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:

// 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() != HttpStatusCode.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:

// 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
com.aspose.html.Configuration configuration = new com.aspose.html.Configuration();
try {
    // Add ErrorMessageHandler to the chain of existing message handlers
    com.aspose.html.services.INetworkService network = configuration.getService(com.aspose.html.services.INetworkService.class);
    network.getMessageHandlers().addItem(handler);

    // 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
    com.aspose.html.HTMLDocument document = new com.aspose.html.HTMLDocument("document.html", configuration);
    try {
        // Convert HTML to PNG
        com.aspose.html.converters.Converter.convertHTML(
                document,
                new com.aspose.html.saving.ImageSaveOptions(),
                "output.png"
        );
    } finally {
        if (document != null) {
            document.dispose();
        }
    }
} finally {
    if (configuration != null) {
        configuration.dispose();
    }
}

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