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

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

Песочница – Sandbox

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

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

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

В примере создается новый экземпляр 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> отображали текст зеленым цветом.

// 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

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

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

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

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

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

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

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

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

Служба выполнения – 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.

// 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 позволяет контролировать весь входящий/исходящий трафик и реализовывать собственные обработчики сообщений. Его можно использовать для различных целей, таких как: создание собственного механизма кэширования, трассировка/логирование сообщений запроса и т. д.

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

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

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

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

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

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