1. IronPDF
  2. Comenzar
  3. Usar IronPDFEngine

Curtis Chau
Curtis Chau
Actualizado:

IronPdfEngine es un servidor gRPC que realiza todas las operaciones PDF: creación, edición, lectura y representación. La biblioteca IronPDF for Java es un envoltorio de API alrededor de este servidor: cuando su código Java llama a cualquier método de IronPDF, IronPdfEngine ejecuta el trabajo. Por defecto, IronPDF for Java inicia IronPdfEngine como un subproceso local y gestiona su ciclo de vida automáticamente. Para despliegues más avanzados, como microservicios compartidos, contenedores Docker o redes aisladas, puede ejecutar IronPdfEngine como un servidor remoto independiente.

Guía rápida: configurar IronPdfEngine for Java

Cómo configurar IronPdfEngine for Java

  1. Agregue la dependencia de IronPDF a su archivo pom.xml
  2. Elija un modo local: descarga en tiempo de ejecución o dependencia empaquetada
  3. Para el modo remoto, use setIronPdfEngineHost para configurar la dirección del host
  4. Para el modo remoto, use setIronPdfEnginePort para configurar el puerto
  5. Llame a cualquier método de representación de IronPDF, IronPdfEngine se encarga del trabajo PDF

Por favor notaCada versión de IronPDF for Java requiere una versión correspondiente de IronPdfEngine. No se admite la compatibilidad entre versiones. Use Settings.getIronPdfEngineVersion() para confirmar la versión requerida.

¿Qué modo de despliegue debería usar?

IronPdfEngine admite dos enfoques de despliegue: local y remoto. Elegir entre ellos depende de la arquitectura de su aplicación.

Modo local (el defecto) es la opción correcta para aplicaciones independientes, herramientas de escritorio y despliegues de servidor único. IronPDF for Java inicia IronPdfEngine automáticamente como un subproceso: no se necesita infraestructura adicional. Dentro del modo local, hay dos opciones para obtener los binarios de IronPdfEngine: descargarlos al primer inicio o incluirlos como dependencia de Maven.

Modo remoto es adecuado para sistemas distribuidos donde una sola instancia de IronPdfEngine sirve a múltiples nodos de aplicación. También es el enfoque preferido para despliegues basados en Docker, pods de Kubernetes, redes aisladas que no pueden descargar binarios en tiempo de ejecución, y cualquier escenario donde centralizar el procesamiento de PDF reduzca los gastos generales por servicio.

Las siguientes secciones cubren ambos modos en detalle.

¿Cómo se configura IronPdfEngine localmente?

Existen dos opciones para ejecutar IronPdfEngine localmente. Ambas producen el mismo comportamiento en tiempo de ejecución: la diferencia es cuándo y cómo llega el binario del motor a la máquina objetivo.

Opción 1: Descargar IronPdfEngine en tiempo de ejecución

Por defecto, después de agregar la dependencia principal ironpdf, IronPDF detecta la plataforma host (por ejemplo, Windows x64 o Linux x64) en la primera ejecución y descarga el binario correspondiente de IronPdfEngine desde internet.

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf</artifactId>
    <version>20xx.xx.xx</version>
</dependency>
//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf</artifactId>
    <version>20xx.xx.xx</version>
</dependency>
XML

Después de la descarga inicial, el binario se almacena temporalmente en el lugar y las ejecuciones posteriores se inician sin una llamada de red.

Opción 1 — Descarga en tiempo de ejecución: Ventajas e inconvenientes
VentajaInconveniente
Tamaño más pequeño del paquete de aplicación Se requiere acceso a internet en el primer inicio
Admite múltiples plataformas objetivo desde un solo artefacto Inicio más lento en la primera ejecución mientras se descarga el binario

Opción 2: Incluir IronPdfEngine como una dependencia (Recomendado)

IronPDF Java proporciona artefactos Maven específicos para la plataforma que incluyen IronPdfEngine como un archivo .zip dentro de la dependencia. La biblioteca lo extrae y lo usa automáticamente: no es necesaria una llamada de red en tiempo de ejecución.

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>
//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>
XML

Luego agregue el artefacto de plataforma para su entorno objetivo. Instale solo el artefacto para su plataforma objetivo: cada uno es grande, e instalar todos ellos inflaría innecesariamente la construcción.

Windows x64

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-windows-x64</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>
//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-windows-x64</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>
XML

Windows x86

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-windows-x86</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>
//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-windows-x86</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>
XML

Linux x64

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-linux-x64</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>
//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-linux-x64</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>
XML

macOS x64

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-macos-x64</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>
//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-macos-x64</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>
XML

macOS ARM (Apple Silicon)

//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-macos-arm64</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>
//:path=pom.xml
<dependency>
    <groupId>com.ironsoftware</groupId>
    <artifactId>ironpdf-engine-macos-arm64</artifactId>
    <version>20xx.xx.xxxx</version>
</dependency>
XML

Por favor notaLas versiones de las dependencias ironpdf y ironpdf-engine-xxx-xxx deben coincidir exactamente. La cadena de versión se refiere al lanzamiento de IronPDF for Java, no al número de versión interna de IronPdfEngine.

Opción 2 — Dependencia empaquetada: Ventajas e inconvenientes
VentajaInconveniente
Inicio más rápido: sin paso de descarga Paquete de aplicación más grande
No se requiere acceso a internet después de la instalación Debe especificar explícitamente la plataforma objetivo
Comportamiento consistente en entornos aislados Instalar múltiples artefactos de plataforma infla significativamente el tamaño de la construcción

¿Cómo se conecta a un IronPdfEngine remoto?

El modo remoto permite que múltiples instancias de aplicación compartan un solo servidor IronPdfEngine a través de gRPC. Esto es común en arquitecturas de microservicios, despliegues en contenedores y entornos donde el procesamiento de PDF está centralizado.

¿Cómo se verifica la versión requerida de IronPdfEngine?

La coincidencia de versiones es estricta: IronPDF for Java 2024.2.2 requiere exactamente IronPdfEngine 2024.2.2. Use getIronPdfEngineVersion para confirmar la versión requerida antes de implementar el servidor:

//:path=Main.java
// Retrieve the IronPdfEngine version required by this Java library build
String ironPdfEngineVersion = Settings.getIronPdfEngineVersion();
System.out.println("Required IronPdfEngine version: " + ironPdfEngineVersion);
//:path=Main.java
// Retrieve the IronPdfEngine version required by this Java library build
String ironPdfEngineVersion = Settings.getIronPdfEngineVersion();
System.out.println("Required IronPdfEngine version: " + ironPdfEngineVersion);
JAVA

Despliegue o extraiga la imagen Docker de IronPdfEngine o el binario que coincida con la cadena de versión devuelta.

¿Cómo se configura la conexión remota?

Suponga que IronPdfEngine está ejecutándose en 123.456.7.8:33350. Configure el host y el puerto antes de llamar a cualquier método de IronPDF. La mejor práctica es colocar estas llamadas al inicio de la aplicación, antes de cualquier operación PDF:

//:path=Main.java
// Configure IronPDF for Java to connect to a remote IronPdfEngine instance
com.ironsoftware.ironpdf.Settings.setIronPdfEngineHost("123.456.7.8");
com.ironsoftware.ironpdf.Settings.setIronPdfEnginePort(33350);
//:path=Main.java
// Configure IronPDF for Java to connect to a remote IronPdfEngine instance
com.ironsoftware.ironpdf.Settings.setIronPdfEngineHost("123.456.7.8");
com.ironsoftware.ironpdf.Settings.setIronPdfEnginePort(33350);
JAVA

Después de que estas dos líneas se ejecuten, todas las llamadas subsiguientes a IronPDF en su aplicación se dirigirán al servidor remoto. No se inicia ningún subproceso local de IronPdfEngine, y no se necesita ninguna dependencia de motor específica de plataforma en su pom.xml.

ConsejosAsegúrese de que la dirección host de IronPdfEngine sea accesible desde su servidor de aplicaciones y que el puerto 33350 esté abierto en cualquier firewall o grupo de seguridad entre ambos.

¿Cómo se ve una configuración remota completa?

El siguiente ejemplo se conecta a una instancia remota de IronPdfEngine y representa una cadena HTML en un archivo PDF: la misma API utilizada en modo local, con solo la configuración diferiendo:

//:path=Main.java
import com.ironsoftware.ironpdf.*;

public class Main {
    public static void main(String[] args) throws Exception {
        // Point the library to the remote IronPdfEngine server
        Settings.setIronPdfEngineHost("123.456.7.8");
        Settings.setIronPdfEnginePort(33350);

        // Render HTML to PDF — IronPdfEngine on the remote host performs the work
        PdfDocument pdf = PdfDocument.renderHtmlAsPdf("<h1>Hello from remote IronPdfEngine</h1>");
        pdf.saveAs("output.pdf");
    }
}
//:path=Main.java
import com.ironsoftware.ironpdf.*;

public class Main {
    public static void main(String[] args) throws Exception {
        // Point the library to the remote IronPdfEngine server
        Settings.setIronPdfEngineHost("123.456.7.8");
        Settings.setIronPdfEnginePort(33350);

        // Render HTML to PDF — IronPdfEngine on the remote host performs the work
        PdfDocument pdf = PdfDocument.renderHtmlAsPdf("<h1>Hello from remote IronPdfEngine</h1>");
        pdf.saveAs("output.pdf");
    }
}
JAVA

El PDF representado se devuelve al proceso Java a través de gRPC y se guarda localmente. El servidor remoto se encarga de toda la representación basada en Chrome, la carga de fuentes y la resolución de recursos.

¿Cuáles son los próximos pasos?

Con IronPdfEngine configurado, el conjunto completo de funciones de IronPDF for Java está disponible: HTML a PDF, edición de PDF, fusión, estampado y más.

Preguntas Frecuentes

¿Qué es IronPdfEngine y por qué lo requiere IronPDF for Java?

IronPdfEngine es un servidor gRPC que ejecuta todas las operaciones de PDF — crear, editar, leer y representar. IronPDF for Java es un envoltorio de API alrededor de este servidor, por lo que cada llamada de método Java es procesada por IronPdfEngine. Sin él, la biblioteca Java no puede realizar ningún trabajo con PDFs.

¿Cuál es la diferencia entre IronPdfEngine local y remoto?

El modo local inicia IronPdfEngine como un subproceso en la misma máquina que su aplicación Java — no se necesita infraestructura adicional. El modo remoto se conecta a un servidor IronPdfEngine independiente a través de gRPC, lo cual es adecuado para microservicios, implementaciones de Docker y nodos de procesamiento PDF compartidos.

¿Cuándo debo usar IronPdfEngine remoto en lugar de local?

Use IronPdfEngine remoto cuando necesite compartir un servidor de procesamiento PDF entre múltiples instancias de aplicación, cuando despliegue en entornos de Kubernetes o Docker Compose, o cuando ejecute en redes aisladas que no pueden descargar binarios en tiempo de ejecución.

¿Cómo configuro una conexión remota a IronPdfEngine en Java?

Llame a Settings.setIronPdfEngineHost() con la IP o el nombre del host del servidor y Settings.setIronPdfEnginePort() con el número de puerto al inicio de la aplicación, antes de invocar cualquier método de IronPDF. El puerto predeterminado de IronPdfEngine es 33350.

¿Qué artefacto de Maven debo usar para empaquetar IronPdfEngine como una dependencia?

Agregue el artefacto específico para la plataforma que coincida con su objetivo de despliegue — por ejemplo, ironpdf-engine-linux-x64 para servidores Linux o ironpdf-engine-windows-x64 para Windows. La versión del artefacto debe coincidir exactamente con la versión de la dependencia principal de ironpdf.

¿Cómo verifico qué versión de IronPdfEngine requiere mi biblioteca de Java?

Llame a Settings.getIronPdfEngineVersion() en su código Java. Devuelve la cadena de versión exacta que debe coincidir con el binario o imagen Docker de IronPdfEngine que despliegue.

¿Puedo instalar múltiples dependencias del motor de plataforma en un solo proyecto?

Técnicamente sí, pero cada artefacto es grande y instalar más de uno infla innecesariamente su compilación. Instale solo el artefacto que coincida con su plataforma de despliegue objetivo.

¿Necesito una conexión a Internet para usar IronPDF for Java?

Solo si utiliza la opción de descarga en tiempo de ejecución (sin dependencia específica de la plataforma en pom.xml). En la primera ejecución, IronPDF descarga el binario de IronPdfEngine para su plataforma. Después de esa descarga, no se requiere acceso a Internet. Si agrega la dependencia de plataforma empaquetada o usa el modo remoto, no se necesita acceso a Internet en ningún momento.

Curtis Chau
Curtis Chau
  Chatea con el equipo de ingeniería ahora
Escritor Técnico

Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien ...

Leer más
¿Listo para empezar?
Versión: 2026.5 just released
Still Scrolling Icon

¿Aún desplazándote?

¿Quieres una prueba rápida?
ejecutar una muestra Mira cómo tu HTML se convierte en PDF.