Jak skonfigurować IronPdfEngine
IronPdfEngine to serwer gRPC, który wykonuje każdą operację PDF — tworzenie, edycję, czytanie i renderowanie. Biblioteka IronPDF for Java jest API wokół tego serwera: gdy twój kod Java wywołuje jakąkolwiek metodę IronPDF, IronPdfEngine wykonuje prace. Domyślnie IronPDF for Java uruchamia IronPdfEngine jako lokalny proces podrzędny i zarządza jego cyklem życia automatycznie. Dla bardziej zaawansowanych wdrożeń — dzielonych mikrousług, kontenerów Docker lub sieci izolowanych — można uruchomić IronPdfEngine jako samodzielny serwer zdalny.
Szybki start: Konfiguracja IronPdfEngine dla JavaJak skonfigurować IronPdfEngine dla Java
- Dodaj zależność IronPDF do pliku
pom.xml - Wybierz tryb lokalny: pobieranie w czasie wykonania lub zależność wbudowana
- Dla trybu zdalnego użyj
setIronPdfEngineHost, aby skonfigurować adres hosta - Dla trybu zdalnego użyj
setIronPdfEnginePort, aby skonfigurować port - Wywołaj dowolną metodę renderowania IronPDF — IronPdfEngine zajmuje się pracą PDF
Settings.getIronPdfEngineVersion(), aby potwierdzić wymaganą wersję.Który tryb wdrożenia powinieneś użyć?
IronPdfEngine wspiera dwa podejścia do wdrożenia: lokalne i zdalne. Wybór między nimi zależy od architektury twojej aplikacji.
Tryb lokalny (domyślny) jest właściwym wyborem dla aplikacji samodzielnych, narzędzi desktopowych i wdrożeń na jednym serwerze. IronPDF for Java uruchamia IronPdfEngine automatycznie jako proces podrzędny — nie jest potrzebna oddzielna infrastruktura. W trybie lokalnym istnieją dwie opcje uzyskania plików binarnych IronPdfEngine: pobranie ich przy pierwszym uruchomieniu lub wbudowanie jako zależność Maven.
Tryb zdalny pasuje do systemów rozproszonych, gdzie jedna instancja IronPdfEngine obsługuje wiele węzłów aplikacyjnych. Jest to również preferowane podejście dla wdrożeń opartych na Docker, klastrach Kubernetes, sieciach izolowanych, które nie mogą pobierać plików binarnych w czasie wykonywania, i wszelkich scenariuszy, gdzie centralizacja przetwarzania PDF zmniejsza koszty per usługe.
Poniższe sekcje szczegółowo opisują oba tryby.
Jak skonfigurować lokalny IronPdfEngine?
Istnieją dwie opcje dla uruchamiania IronPdfEngine lokalnie. Obie zapewniają takie samo zachowanie w czasie wykonywania — różnica polega na tym, kiedy i w jaki sposób plik binarny silnika dociera na maszynę docelową.
Opcja 1: Pobierz IronPdfEngine w czasie wykonania
Domyślnie, po dodaniu podstawowej zależności ironpdf IronPDF wykrywa platformę hosta (na przykład Windows x64 lub Linux x64) przy pierwszym uruchomieniu i pobiera pasujące binarium IronPdfEngine z internetu.
//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf</artifactId>
<version>20xx.xx.xx</version>
</dependency>Po początkowym pobraniu, plik binarny jest buforowany lokalnie i kolejne uruchomienia zaczynają się bez wywołania sieciowego.
| Zaleta | Ograniczenie |
|---|---|
| Najmniejszy rozmiar pakietu aplikacji | Wymagany dostęp do internetu przy pierwszym uruchomieniu |
| Wsparcie dla wielu platform docelowych z jednego artefaktu | Wolniejsze pierwsze uruchomienie podczas pobierania pliku binarnego |
Opcja 2: Dołącz IronPdfEngine jako zależność (Zalecane)
Java IronPDF dostarcza specyficzne dla platformy artefakty Maven, które pakują IronPdfEngine jako plik .zip wewnątrz zależności. Biblioteka wyodrębnia i używa go automatycznie — nie jest potrzebne połączenie sieciowe w czasie wykonania.
//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>Następnie dodaj artefakt dla swojej platformy docelowej. Zainstaluj tylko artefakt dla swojej platformy docelowej — każdy z nich jest duży, a instalowanie wszystkich niepotrzebnie powiększa budowę.
Windows x64
//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-windows-x64</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>Windows x86
//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-windows-x86</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>Linux x64
//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-linux-x64</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>macOS x64
//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-macos-x64</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>macOS ARM (Apple Silicon)
//:path=pom.xml
<dependency>
<groupId>com.ironsoftware</groupId>
<artifactId>ironpdf-engine-macos-arm64</artifactId>
<version>20xx.xx.xxxx</version>
</dependency>ironpdf i ironpdf-engine-xxx-xxx muszą się dokładnie zgadzać. Ciąg wersji odnosi się do wydania IronPDF for Java, a nie wewnętrznego numeru wersji IronPdfEngine.| Zaleta | Ograniczenie |
|---|---|
| Szybsze uruchomienie — brak kroku pobierania | Większy pakiet aplikacji |
| Nie jest wymagany dostęp do internetu po instalacji | Należy wyraźnie określić platformę docelową |
| Spójne zachowanie w środowiskach izolowanych | Zainstalowanie wielu artefaktów platformowych znacznie powiększa rozmiar budowy |
Jak połączyć się z zdalnym IronPdfEngine?
Tryb zdalny pozwala wielu instancjom aplikacji dzielić się jednym serwerem IronPdfEngine przez gRPC. Jest to powszechne w architekturach mikrousług, wdrożeniach kontenerowych i środowiskach, gdzie przetwarzanie PDF jest scentralizowane.
Jak zweryfikować wymaganą wersję IronPdfEngine?
Dopasowanie wersji jest ścisłe — IronPDF for Java 2024.2.2 wymaga dokładnie IronPdfEngine 2024.2.2. Użyj getIronPdfEngineVersion, aby potwierdzić wymaganą wersję przed wdrożeniem serwera:
// Retrieve the IronPdfEngine version required by this Java library build
String ironPdfEngineVersion = Settings.getIronPdfEngineVersion();
System.out.println("Required IronPdfEngine version: " + ironPdfEngineVersion);Wdróż lub pobierz obraz Docker lub plik binarny IronPdfEngine, który pasuje do zwróconego ciągu wersji.
Jak skonfigurować połączenie zdalne?
Załóż, że IronPdfEngine działa pod 123.456.7.8:33350. Ustaw hosta i port przed wywołaniem jakiejkolwiek metody IronPDF. Najlepszą praktyką jest umieszczenie tych wywołań podczas uruchamiania aplikacji, przed jakąkolwiek operacją PDF:
// 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);Po wykonaniu tych dwóch linii wszystkie kolejne wywołania IronPDF w twojej aplikacji będą kierowane do zdalnego serwera. Nie jest uruchamiany żaden lokalny podproces IronPdfEngine, ani nie jest potrzebna specyficzna dla platformy zależność silnika w pom.xml.
33350 jest otwarty w jakichkolwiek zaporach sieciowych lub grupach zabezpieczeń pomiędzy nimi.Jak wygląda pełna konfiguracja zdalna?
Poniższy przykład łączy się z zdalnym wystąpieniem IronPdfEngine i renderuje ciąg HTML do pliku PDF — to samo API używane w trybie lokalnym, różni się tylko konfiguracja:
//: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");
}
}Renderowany PDF jest zwracany do procesu Java za pośrednictwem gRPC i zapisywany lokalnie. Zdalny serwer obsługuje całe renderowanie oparte na Chrome, wczytywanie czcionek i rozwiązywanie zasobów.
Jakie są kolejne kroki?
Po skonfigurowaniu IronPdfEngine dostępny jest pełny zestaw funkcji IronPDF for Java — HTML do PDF, edycja PDF, scalanie, stemplowanie i więcej.
- Rozpocznij renderowanie HTML do PDF w Java — przykłady krok po kroku dla najczęstszych scenariuszy konwersji
- Poznaj samouczki IronPDF for Java — bardziej szczegółowe przewodniki obejmujące znaki wodne, nagłówki i stopki, formularze oraz podpisy cyfrowe
- Pobierz IronPDF for Java i rozpocznij darmowy okres próbny — w pełni funkcjonalna wersja próbna bez ograniczenia czasowego dla użycia w dewelopmencie
- Kup licencję do wdrożenia produkcyjnego — opcje wieczyste i subskrypcyjne z dostępem do kodu źródłowego
Często Zadawane Pytania
Czym jest IronPdfEngine i dlaczego IronPDF dla Java go wymaga?
IronPdfEngine to serwer gRPC, który wykonuje wszystkie operacje na PDF — tworzenie, edytowanie, czytanie i renderowanie. IronPDF dla Java to API otoczka wokół tego serwera, więc każde wywołanie metody Java jest przetwarzane przez IronPdfEngine. Bez niego biblioteka Java nie może wykonywać żadnych prac z PDF.
Jaka jest różnica między lokalnym a zdalnym IronPdfEngine?
Tryb lokalny uruchamia IronPdfEngine jako podproces na tej samej maszynie, co aplikacja Java — nie potrzeba dodatkowej infrastruktury. Tryb zdalny łączy się z samodzielnym serwerem IronPdfEngine przez gRPC, co jest odpowiednie dla mikrousług, wdrożeń w Dockera i wspólnych węzłów przetwarzania PDF.
Kiedy powinienem używać zdalnego IronPdfEngine zamiast lokalnego?
Używaj zdalnego IronPdfEngine, gdy potrzebujesz, aby wiele instancji aplikacji współdzieliło jeden serwer przetwarzania PDF, gdy wdrażasz w środowiskach Kubernetes lub Docker Compose, lub gdy działasz w sieciach odizolowanych, które nie mogą pobierać binariów w czasie wykonywania.
Jak skonfigurować zdalne połączenie IronPdfEngine w Java?
Wywołaj Settings.setIronPdfEngineHost() z adresem IP serwera lub nazwą hosta i Settings.setIronPdfEnginePort() z numerem portu przy uruchamianiu aplikacji, przed wywołaniem jakiejkolwiek metody IronPDF. Domyślny port IronPdfEngine to 33350.
Który artefakt Maven powinienem użyć do wbudowania IronPdfEngine jako zależności?
Dodaj artefakt specyficzny dla platformy pasujący do twojej platformy wdrożeniowej — na przykład ironpdf-engine-linux-x64 dla serwerów Linux lub ironpdf-engine-windows-x64 dla Windows. Wersja artefaktu musi dokładnie pasować do wersji zależności core ironpdf.
Jak sprawdzić, która wersja IronPdfEngine jest wymagana przez moją bibliotekę Java?
Wywołaj Settings.getIronPdfEngineVersion() w swoim kodzie Java. Zwraca ona dokładny ciąg wersji, który musi pasować do wersji binarnej IronPdfEngine lub obrazu Dockera, który wdrażasz.
Czy mogę zainstalować wiele zależności silnika dla platform w jednym projekcie?
Technicznie tak, ale każdy artefakt jest duży, a instalowanie więcej niż jednego niepotrzebnie zwiększa rozmiar kompilacji. Zainstaluj tylko artefakt pasujący do twojej platformy wdrożeniowej.
Czy potrzebuję połączenia z Internetem, aby używać IronPDF dla Java?
Tylko jeśli używasz opcji pobierania w czasie wykonywania (brak specyficznej dla platformy zależności w pom.xml). Podczas pierwszego uruchomienia IronPDF pobiera binarną wersję IronPdfEngine dla twojej platformy. Po tym pobraniu, nie jest już potrzebny dostęp do internetu. Jeśli dodasz wbudowaną zależność dla platformy lub użyjesz trybu zdalnego, nie jest potrzebny dostęp do internetu na żadnym etapie.
How do I detect and recover from a dead IronPdfEngine in Java?
Call IronPdfEngineManager.isEngineActive() to check whether the engine is connected, then IronPdfEngineManager.restartEngine() to force a clean reconnect if it is not. This watchdog pattern lets long-running services recover automatically when the engine is interrupted by a host restart, an operating system kill, or a native crash. It is an advanced feature; most applications rely on the automatic lifecycle and never call it.
Can I restart IronPdfEngine when using a custom gRPC connection?
No. In CUSTOM connection mode (a channel passed to IronPdfEngineConnection.withCustomGrpcConnection), stopEngine() and restartEngine() throw UnsupportedOperationException because the caller owns the channel and IronPDF cannot rebuild it. isEngineActive() and startEngine() still work in every connection mode.
Curtis Chau posiada tytuł licencjata z informatyki (Uniwersytet Carleton) i specjalizuje się w front-endowym rozwoju, z ekspertką w Node.js, TypeScript, JavaScript i React. Pasjonuje się tworzeniem intuicyjnych i estetycznie przyjemnych interfejsów użytkownika, Curtis cieszy się pracą z nowoczesnymi frameworkami i tworzeniem dobrze zorganizowanych, atrakcyjnych wizualnie podręczników.
