Конфигурация среды – Environment Configuration

Наличие различных конфигураций, основанных на среде приложения, может быть очень полезным. Например, конфигурация среды позволяет настраивать политики сценариев, переопределять стили документов с помощью определяемой пользователем таблицы стилей или обрабатывать веб-запросы. Чтобы облегчить это, Aspose.HTML предлагает класс Configuration, специально разработанный для выполнения этих требований. Используя объект Configuration, вы можете легко настроить поведение вашего приложения Aspose.HTML в соответствии с вашими конкретными потребностями.

Песочница – Sandbox

Набор sandboxing flag – это набор из нуля или более флагов, которые ограничивают возможности потенциально ненадежных ресурсов. Песочница обеспечивает безопасную и контролируемую среду выполнения, изолируя потенциально вредоносный или ненадежный код от базовой системы и конфиденциальных данных.

В следующем примере Java показано, как преобразовать HTML-документ в формат PDF и применить ограничения песочницы – как пометить “Scripts” как ненадежный ресурс. В результате “Scripts” будут отключены во время выполнения приложения.

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

В примере создается новый экземпляр Configuration класса для настройки песочницы. Метод setSecurity() вызывается для объекта конфигурации, ему передается com.aspose.html.Sandbox.Scripts в качестве аргумента. Этот флаг включает песочницу и ограничивает выполнение скриптов в HTML-документе.

Сервисы – Services

Весь важный функционал сгруппирован в отдельные сервисы для удобства использования и расположен в пакете com.aspose.html.services.

Служба пользовательского агента – User Agent Service

В контексте конфигурации среды User Agent Service позволяет указать пользовательскую таблицу стилей пользователя, основной набор символов для документа, настройки языка и шрифтов.

Пользовательская таблица стилей – User Style Sheet

Пользователь может указать информацию пользовательского стиля для конкретного документа. Эта информация применяется к документу в соответствии с cascading rules и может повлиять на представление документа. Следующий фрагмент кода Java демонстрирует использование службы агента пользователя ( IUserAgentService) для применения пользовательской таблицы стилей к HTML-документу, который затем преобразуется в PDF.

Давайте просто рассмотрим необходимые шаги для указания пользовательской таблицы стилей в HTML-документе:

1. В примере мы используем конструктор Configuration() для создания экземпляра класса Configuration.
2. Затем мы вызываем метод getService() класса Configuration и передаем ему IUserAgentService.class в качестве параметра. Итак, мы получаем экземпляр User Agent Service.
3. Чтобы установить пользовательскую таблицу стилей, которая будет применяться к HTML-документу, мы используем метод setUserStyleSheet() службы агента пользователя, предоставляя код CSS в качестве аргумента. В этом случае правило CSS span { color: green; } используется для того, чтобы все элементы <span> отображали текст зеленым цветом.

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

Набор символов – Character Set

Чтобы правильно анализировать и отображать документ HTML, приложение должно знать, какой набор символов (кодировка) используется для документа. Если кодировка символов не указана напрямую в заголовке документа, Aspose.HTML использует UTF-8, которая определена как кодировка по умолчанию для спецификации HTML5. Однако, если вы уверены, что кодировка вашего HTML-документа отличается от кодировки UTF-8, вы можете указать ее вручную. Рассмотрим необходимые шаги для указания набора символов (кодировки) в HTML-документе:

1. Создайте экземпляр класса Configuration.
2. Используйте метод getService() для получения экземпляра службы агента пользователя. Метод принимает IUserAgentService.class в качестве параметра.
3. Вызовите метод setCharSet() службы агента пользователя и укажите желаемый набор символов (кодировку). В этом примере в качестве набора символов задан ISO-8859-1.

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

Установив набор символов с помощью метода setCharSet(), приложение информирует механизм синтаксического анализа и рендеринга Aspose.HTML for Java о конкретной кодировке, используемой в документе HTML. Это очень важно, потому что разные наборы символов могут представлять символы по-разному, и без правильной информации о кодировке документ может быть неточно проанализирован или отображен.

Установить путь к папке со шрифтами

Одной из ключевых особенностей Aspose.HTML является его способность работать с пользовательскими шрифтами, что позволяет разработчикам добавлять свои собственные шрифты в процесс рендеринга. Для ситуации, когда вам нужно использовать пользовательские шрифты вместо шрифтов, установленных в ОС, вы можете указать путь к своей пользовательской папке следующим образом:

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

Чтобы установить папку шрифта с помощью библиотеки Aspose.HTML for Java, мы используем класс FontsSettings для доступа к объекту FontsSettings. Метод setFontsLookupFolder() вызывается для объекта FontsSettings, указывая путь к папке, в которой находятся шрифты.

На рисунке показан результат применения FontsSettings и UserStyleSheet (b) к исходному файлу user-agent-fontsetting.html (a).

Служба выполнения – Runtime Service

Служба выполнения позволяет контролировать время жизни внутренних процессов. Например, с помощью IRuntimeService вы можете указать время ожидания для JavaScript. Важно иметь такой таймаут на случай, если скрипт содержит бесконечный цикл. В следующем фрагменте кода показано, как использовать службу времени выполнения для ограничения времени выполнения JavaScript и преобразования HTML-документа в формат изображения:

1. В примере мы создаем HTML-документ с нуля. Подготовленный HTML-код содержит бесконечный цикл внутри элемента <script>. Мы используем FileWriter() для записи кода HTML в файл.
2. Создайте экземпляр класса Configuration.
3. Вызовите метод getService(), чтобы получить экземпляр службы выполнения.
4. Используйте метод setJavaScriptTimeout() службы выполнения, чтобы указать максимально допустимое время выполнения кода JavaScript. Пример установлен на 5 секунд.
5. Создайте объект HTMLDocument с помощью конструктора HTMLDocument(address, configuration). Он принимает путь к ранее созданному файлу HTML и объекту конфигурации.
6. Преобразуйте HTML в PNG, используя метод convertHTML(document, options, outputPath).

В примере, если тайм-аут в 5 секунд превышен во время выполнения JavaScript, Aspose.HTML прервет выполнение кода JavaScript и продолжит оставшийся процесс преобразования HTML в PNG.

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

Сетевая служба – Network Service

INetworkService позволяет контролировать весь входящий/исходящий трафик и реализовывать собственные обработчики сообщений. Его можно использовать для различных целей, таких как: создание собственного механизма кэширования, трассировка/логирование сообщений запроса и т. д.

Обработчики сообщений

Используя MessageHandler класс и переопределяя метод invoke(), вы можете определить пользовательскую логику, которая будет выполняться во время сетевых операций. В следующем примере показано, как использовать обработчики сообщений для регистрации сведений о недоступных ресурсах. В примере логика проверяет код состояния ответа и обрабатывает случай, когда файл не найден:

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

Прежде всего, вам нужно создать собственный обработчик сообщений и использовать его следующим образом:

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

Заключение

Функция Конфигурация среды – Environment Configurations в Aspose.HTML for Java позволяет разработчикам точно настраивать поведение своих приложений в соответствии с определенными требованиями. Используя класс Configuration и связанные с ним службы, вы можете эффективно управлять критически важными аспектами, такими как безопасность, настройка, кодировка символов, параметры шрифтов, время выполнения и сетевые операции.

• Sandbox повышает безопасность, ограничивая выполнение потенциально вредоносных скриптов.
• User Agent Service позволяет настраивать стили, наборы символов и шрифты, предлагая индивидуальный опыт рендеринга документов.
• Runtime Service обеспечивает контроль над временем выполнения JavaScript для предотвращения неотвечающих или вредоносных скриптов.
• Network Service облегчает настраиваемую обработку сетевых запросов, обеспечивая надежное ведение журнала, кэширование и управление трафиком.

Вы можете скачать полные примеры и файлы данных по адресу GitHub.