1. IronPDF
  2. Comece agora
  3. Use o IronPDFEngine

Curtis Chau
Curtis Chau
Atualizado:

IronPdfEngine é um servidor gRPC que executa todas as operações de PDF — criar, editar, ler e renderizar. A biblioteca IronPDF for Java é um wrapper de API em torno deste servidor: quando seu código Java chama qualquer método IronPDF, o IronPdfEngine executa o trabalho. Por padrão, IronPDF for Java inicia o IronPdfEngine como um subprocesso local e gerencia seu ciclo de vida automaticamente. Para implantações mais avançadas — microsserviços compartilhados, contêineres Docker ou redes isoladas — você pode executar o IronPdfEngine como um servidor remoto independente.

Início rápido: Configurar IronPdfEngine for Java

Como Configurar o IronPdfEngine for Java

  1. Adicione a dependência IronPDF ao seu arquivo pom.xml
  2. Escolha um modo local: download em tempo de execução ou dependência empacotada
  3. Para modo remoto, use setIronPdfEngineHost para configurar o endereço do host
  4. Para modo remoto, use setIronPdfEnginePort para configurar a porta
  5. Chame qualquer método de renderização IronPDF — o IronPdfEngine lida com o trabalho de PDF

ObserveCada versão do IronPDF for Java requer uma versão correspondente do IronPdfEngine. Compatibilidade entre versões cruzadas não é suportada. Use Settings.getIronPdfEngineVersion() para confirmar a versão necessária.

Qual Modo de Implantação Você Deve Usar?

IronPdfEngine suporta duas abordagens de implantação: local e remoto. Escolher entre elas depende da arquitetura de sua aplicação.

Modo local (o padrão) é a escolha certa para aplicativos autônomos, ferramentas de desktop e implantações em servidor único. IronPDF for Java inicia o IronPdfEngine automaticamente como um subprocesso — nenhuma infraestrutura separada é necessária. Dentro do modo local, há duas opções para obter os binários do IronPdfEngine: baixá-los na primeira execução ou empacotá-los como uma dependência Maven.

Modo remoto se adapta a sistemas distribuídos onde uma única instância do IronPdfEngine atende múltiplos nós da aplicação. É também a abordagem preferida para implantações baseadas em Docker, pods do Kubernetes, redes isoladas que não podem baixar binários em tempo de execução e qualquer cenário onde centralizar o processamento de PDFs reduz o overhead por serviço.

As seções abaixo cobrem ambos os modos em detalhes.

Como Configurar o IronPdfEngine Localmente?

Existem duas opções para executar o IronPdfEngine localmente. Ambos produzem o mesmo comportamento em tempo de execução — a diferença é quando e como o binário do engine chega à máquina de destino.

Opção 1: Baixar IronPdfEngine em Tempo de Execução

Por padrão, após adicionar a dependência principal ironpdf, o IronPDF detecta a plataforma host (por exemplo, Windows x64 ou Linux x64) na primeira execução e baixa o binário IronPdfEngine correspondente da 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

Após o download inicial, o binário é armazenado em cache localmente e as execuções subsequentes começam sem uma chamada de rede.

Opção 1 — Download em Tempo de Execução: Compromissos
VantagemLimitação
Menor tamanho de pacote de aplicativo Acesso à internet necessário na primeira execução
Suporta múltiplas plataformas de destino a partir de um artefato Início mais lento na primeira execução enquanto o binário baixa

Opção 2: Empacotar IronPdfEngine como uma Dependência (Recomendado)

O IronPDF Java fornece artefatos Maven específicos da plataforma que agrupam o IronPdfEngine como um arquivo .zip dentro da dependência. A biblioteca o extrai e usa automaticamente — nenhuma chamada de rede é necessária em tempo de execução.

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

Em seguida, adicione o artefato da plataforma para seu ambiente de destino. Instale apenas o artefato para sua plataforma de destino — cada um é grande e instalar todos desnecessariamente aumentará o build.

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

ObserveAs versões de dependência ironpdf e ironpdf-engine-xxx-xxx devem corresponder exatamente. A string de versão refere-se ao lançamento do IronPDF for Java, não ao número de versão interno do IronPdfEngine.

Opção 2 — Dependência Empacotada: Compromissos
VantagemLimitação
Início mais rápido — sem etapa de download Maior pacote de aplicativo
Nenhum acesso à internet necessário após a instalação É necessário especificar a plataforma de destino explicitamente
Comportamento consistente em ambientes isolados Instalar múltiplos artefatos de plataforma aumenta significativamente o tamanho do build

Como Conectar-se a um IronPdfEngine Remoto?

O modo remoto permite que múltiplas instâncias de aplicação compartilhem um único servidor IronPdfEngine via gRPC. Isso é comum em arquiteturas de microsserviços, implantações em contêineres e ambientes onde o processamento de PDF é centralizado.

Como Verificar a Versão Necessária do IronPdfEngine?

O pareamento de versões é rigoroso — IronPDF for Java 2024.2.2 requer IronPdfEngine 2024.2.2 exatamente. Use getIronPdfEngineVersion para confirmar a versão necessária antes de implantar o 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

Implante ou puxe a imagem Docker ou binário do IronPdfEngine que corresponde à string de versão retornada.

Como Configurar a Conexão Remota?

Suponha que o IronPdfEngine esteja em execução em 123.456.7.8:33350. Defina o host e a porta antes de chamar qualquer método IronPDF. A melhor prática é colocar essas chamadas no inicio do aplicativo, antes de qualquer operação de 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

Após estas duas linhas serem executadas, todas as chamadas IronPDF subsequentes em sua aplicação são roteadas para o servidor remoto. Nenhum subprocesso local do IronPdfEngine é iniciado e nenhuma dependência de mecanismo específica da plataforma é necessária em seu pom.xml.

Certifique-se de que o endereço do host IronPdfEngine esteja acessível a partir do seu servidor de aplicativos e que a porta esteja aberta em quaisquer firewalls ou grupos de segurança entre os dois.

Como É Uma Configuração Remota Completa?

O exemplo a seguir conecta-se a uma instância remota do IronPdfEngine e renderiza uma string HTML para um arquivo PDF — a mesma API usada no modo local, com apenas a configuração diferindo:

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

O PDF renderizado é retornado ao processo Java via gRPC e salvo localmente. O servidor remoto lida com toda a renderização baseada em Chrome, carregamento de fontes e resolução de recursos.

Quais são os próximos passos?

Com o IronPdfEngine configurado, todo o conjunto de funcionalidades do IronPDF for Java está disponível — HTML para PDF, edição de PDF, mesclagem, carimbos e mais.

Perguntas frequentes

O que é o IronPdfEngine e por que o IronPDF for Java precisa dele?

O IronPdfEngine é um servidor gRPC que executa todas as operações PDF — criação, edição, leitura e renderização. O IronPDF for Java é um wrapper de API em torno deste servidor, portanto, cada chamada de método Java é processada pelo IronPdfEngine. Sem ele, a biblioteca Java não pode realizar nenhum trabalho com PDFs.

Qual a diferença entre o IronPdfEngine local e remoto?

O modo local inicia o IronPdfEngine como um subprocesso na mesma máquina que sua aplicação Java — sem necessidade de infraestrutura extra. O modo remoto conecta-se a um servidor IronPdfEngine autônomo via gRPC, que é adequado para microserviços, implantações Docker e nós de processamento de PDF compartilhado.

Quando devo usar o IronPdfEngine remoto em vez de local?

Use o IronPdfEngine remoto quando precisar que múltiplas instâncias de aplicação compartilhem um único servidor de processamento PDF, ao implantar em ambientes Kubernetes ou Docker Compose, ou ao executar em redes isoladas que não podem baixar binários em tempo de execução.

Como configuro uma conexão remota com o IronPdfEngine em Java?

Chame Settings.setIronPdfEngineHost() com o IP ou hostname do servidor e Settings.setIronPdfEnginePort() com o número da porta na inicialização do aplicativo, antes de invocar qualquer método do IronPDF. A porta padrão do IronPdfEngine é 33350.

Qual artifact do Maven devo usar para incorporar o IronPdfEngine como dependência?

Adicione o artifact específico de plataforma que corresponda ao seu alvo de implantação — por exemplo, ironpdf-engine-linux-x64 para servidores Linux ou ironpdf-engine-windows-x64 para Windows. A versão do artifact deve corresponder exatamente à versão da dependência principal ironpdf.

Como verifico qual versão do IronPdfEngine minha biblioteca Java requer?

Chame Settings.getIronPdfEngineVersion() no seu código Java. Ele retorna a string exata da versão que deve corresponder ao binário do IronPdfEngine ou imagem Docker que você implanta.

Posso instalar múltiplas dependências de engine de plataforma em um projeto?

Tecnicamente sim, mas cada artifact é grande e instalar mais de um infla desnecessariamente seu build. Instale apenas o artifact que corresponde à sua plataforma de implantação alvo.

Preciso de uma conexão com a internet para usar o IronPDF for Java?

Apenas se você usar a opção de download de tempo de execução (nenhuma dependência específica de plataforma no pom.xml). Na primeira execução, o IronPDF baixa o binário IronPdfEngine para sua plataforma. Após esse download, nenhum acesso à internet é necessário. Se você adicionar a dependência de plataforma incorporada ou usar o modo remoto, nenhum acesso à internet é necessário em nenhum ponto.

Curtis Chau
Curtis Chau
  Converse agora mesmo com a equipe de engenharia.
Redator Técnico

Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais ...

Leia mais
Pronto para começar?
Versão: 2026.5 just released
Still Scrolling Icon

Ainda está rolando a tela?

Quer provas rápidas?
executar um exemplo Veja seu HTML se transformar em um PDF.