Configuración del entorno

Tener diferentes configuraciones basadas en el entorno de la aplicación puede resultar muy beneficioso. Por ejemplo, la configuración del entorno le permite personalizar las políticas de secuencias de comandos, anular los estilos de los documentos con una hoja de estilos definida por el usuario o gestionar solicitudes web. Para facilitar esto, Aspose.HTML for Java ofrece la clase Configuration diseñada específicamente para cumplir con estos requisitos. Al utilizar el objeto Configuración, puede adaptar sin esfuerzo el comportamiento de su aplicación Java de acuerdo con sus necesidades específicas.

Zona de arena – Sandboxing

Un conjunto de sandboxing flag es un conjunto de cero o más indicadores que limitan las capacidades de recursos potencialmente no confiables. Un sandbox proporciona un entorno de ejecución seguro y controlado al aislar el código potencialmente malicioso o no confiable del sistema subyacente y los datos confidenciales.

El siguiente ejemplo de Java demuestra cómo convertir un documento HTML a formato PDF y aplicar restricciones de espacio aislado: cómo marcar Scripts como un recurso que no es de confianza. Como resultado, los Scripts se desactivarán durante la ejecución de la aplicación.

// @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($o("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($o("sandboxing.html"), configuration);

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

En el ejemplo, se crea una nueva instancia de la clase “Configuración” para configurar el entorno limitado. El método setSecurity() se llama en el objeto configuration, pasando com.aspose.html.Sandbox.Scripts como argumento. Esta bandera habilita el espacio aislado y restringe la ejecución de scripts dentro del documento HTML.

Servicio de agente de usuario – User Agent Service

Todas las funciones importantes se agrupan en servicios separados para fines de usabilidad y se ubican en el Paquete com.aspose.html.services. En el contexto de la configuración del entorno, el User Agent Service le permite especificar una hoja de estilo de usuario personalizada, un conjunto de caracteres principal para el documento, el idioma y la configuración de fuentes.

Hoja de estilo de usuario – User Style Sheet

El usuario puede especificar información de estilo personalizada para un documento en particular. Esta información se aplica al documento de acuerdo con las cascading rules y puede afectar la presentación del documento. El siguiente fragmento de código Java muestra el uso del Servicio de agente de usuario ( IUserAgentService) para aplicar una hoja de estilo de usuario personalizada a un documento HTML que luego se convierte a PDF.

Veamos los pasos necesarios para especificar una hoja de estilo personalizada en un documento HTML:

1. En el ejemplo, utilizamos el constructor Configuration() para crear una instancia de la clase Configuration.
2. Luego llamamos al método getService() en la clase de Configuración y le pasamos IUserAgentService.class como parámetro. Entonces, obtenemos una instancia del Servicio de Agente de Usuario.
3. Para configurar una hoja de estilo de usuario personalizada que se aplicará al documento HTML, utilizamos el método setUserStyleSheet() del User Agent Service, proporcionando un código CSS como argumento. En este caso, la regla CSS span { color: green; } se usa para hacer que todos los elementos <span> muestren texto en color verde.

// @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($o("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($o("user-agent-stylesheet.html"), configuration);

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

Conjunto de caracteres – Character Set

Para analizar y mostrar un documento HTML correctamente, la aplicación debe saber qué juego de caracteres (codificación) se utiliza para el documento. Si la codificación de caracteres no se especifica directamente en el encabezado del documento, Aspose.HTML usa UTF-8, que se define como el valor predeterminado para la especificación HTML5. Sin embargo, si está seguro de que su documento HTML está escrito de manera diferente a la codificación UTF-8, puede especificarlo manualmente. Consideremos los pasos necesarios para especificar un juego de caracteres (codificación) en el documento HTML:

1. Cree una instancia de la clase Configuration.
2. Utilice el método getService() para obtener una instancia del User Agent Service. El método toma IUserAgentService.class como parámetro.
3. Llame al método setCharSet() del User Agent Service y proporcione el juego de caracteres deseado (codificación). En este ejemplo, ISO-8859-1 está configurado como juego de caracteres.

// @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($o("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($o("user-agent-charset.html"), configuration);

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

Al configurar el juego de caracteres usando el método setCharSet(), la aplicación informa al motor de análisis y renderizado Aspose.HTML for Java sobre la codificación específica utilizada en el documento HTML. Esto es muy importante porque diferentes conjuntos de caracteres pueden representar caracteres de manera diferente y, sin la información de codificación correcta, es posible que el documento no se analice o muestre con precisión.

Establecer ruta a la carpeta de fuentes

Una de las características clave de Aspose.HTML es su capacidad para trabajar con fuentes personalizadas, lo que permite a los desarrolladores agregar sus propias fuentes al proceso de renderizado. Para una situación en la que necesite utilizar fuentes personalizadas en lugar de las fuentes instaladas en el sistema operativo, puede configurar la ruta a su carpeta personalizada, de la siguiente manera:

// @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($o("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($o("user-agent-fontsetting.html"), configuration);

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

Para configurar la carpeta de fuentes usando Aspose.HTML for Java, usamos el método setFontsLookupFolder() de la clase FontsSettings. Este método le permite especificar la carpeta donde se encuentran las fuentes personalizadas. Al configurar la carpeta de fuentes, Aspose.HTML buscará fuentes en la carpeta especificada al representar el documento HTML.

La figura ilustra el resultado de FontsSettings y UserStyleSheet aplicando (b) al archivo fuente “user-agent-fontsetting.html” (a).

Servicio de tiempo de ejecución – Runtime Service

El servicio Runtime le brinda control sobre la vida útil de los procesos internos. Por ejemplo, utilizando IRuntimeService puede especificar tiempos de espera para JavaScripts. Es importante tener dicho tiempo de espera en caso de que un script contenga un bucle sin fin. El siguiente fragmento de código demuestra cómo utilizar Runtime Service para limitar el tiempo de ejecución de JavaScript y convertir un documento HTML a un formato de imagen:

1. En el ejemplo, creamos un documento HTML desde cero. El código HTML preparado incluye un bucle infinito dentro de un elemento <script>. Usamos FileWriter() para escribir el código HTML en un archivo.
2. Cree una instancia de la clase Configuration.
3. Llame al método getService() para obtener una instancia del servicio de ejecución.
4. Utilice el método setJavaScriptTimeout() del Runtime Service para especificar el tiempo de ejecución máximo permitido del código JavaScript. El ejemplo está establecido en 5 segundos.
5. Cree un objeto HTMLDocument utilizando el constructor HTMLDocument(address, configuration). Toma la ruta al archivo HTML creado previamente y al objeto de configuración.
6. Convierta HTML a PNG usando el método convertHTML(document, options, outputPath).

En el ejemplo, si se excede el tiempo de espera de 5 segundos durante la ejecución de JavaScript, Aspose.HTML for Java interrumpirá la ejecución del código JavaScript y continuará con el proceso de conversión de HTML a PNG restante.

// @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($o("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($o("runtime-service.html"), configuration);

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

Servicio de red – Network Service

INetworkService le permite controlar todo el tráfico entrante/saliente e implementar sus controladores de mensajes personalizados. Se puede utilizar para diferentes propósitos, tales como: crear un mecanismo de almacenamiento en caché personalizado, mensajes de solicitud de seguimiento/registro, etc.

Controladores de mensajes

Usando la clase MessageHandler y anulando el método invoke(), puede definir la lógica personalizada que se ejecutará durante las operaciones de red. El siguiente ejemplo demuestra cómo utilizar controladores de mensajes para registrar información sobre recursos inalcanzables. En el ejemplo, la lógica verifica el código de estado de respuesta y maneja el caso en el que no se encuentra el archivo:

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

En primer lugar, debe crear un controlador de mensajes personalizado y utilizarlo, como se muestra a continuación:

// @code-snippet7

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

try (java.io.FileWriter fileWriter = new java.io.FileWriter($o("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($o("document.html"), configuration);

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

Conclusión

La característica Configuraciones de entorno en Aspose.HTML for Java permite a los desarrolladores ajustar el comportamiento de sus aplicaciones para cumplir con requisitos específicos. Al utilizar la clase Configuración y sus servicios asociados, puede administrar de manera efectiva aspectos críticos como seguridad, personalización, codificación de caracteres, configuración de fuentes, tiempo de ejecución y operaciones de red.

• Sandbox mejora la seguridad al restringir la ejecución de scripts potencialmente dañinos.
• User Agent Service permite la personalización de estilos, conjuntos de caracteres y fuentes, ofreciendo una experiencia de representación de documentos personalizada.
• Runtime Service proporciona control sobre el tiempo de ejecución de JavaScript para evitar scripts maliciosos o que no responden.
• Network Service facilita el manejo personalizado de solicitudes de red al proporcionar registro, almacenamiento en caché y control de tráfico sólidos.

Puede descargar los ejemplos completos y los archivos de datos desde GitHub.