com.ironsoftware.ironpdf

Class IronPdfEngineManager

java.lang.Object

com.ironsoftware.ironpdf.IronPdfEngineManager

public final class IronPdfEngineManager
extends Object

Manages the lifecycle of the IronPdfEngine.

Normally the engine is started automatically on the first IronPDF call and stopped when your application shuts down, so most applications never need this class. It exists for long-running services that must recover after the engine is interrupted by something outside IronPDF's control; for example a remote IronPdfEngine host restart, an OS kill, or a native crash. After such an event the cached connection is stale and subsequent IronPDF calls hang or fail; restartEngine() clears that state and reconnects.

A typical watchdog loop:

 if (!IronPdfEngineManager.isEngineActive()) {
     IronPdfEngineManager.restartEngine();
 }
 PdfDocument pdf = PdfDocument.renderHtmlAsPdf("<h1>Hello World</h1>");
 

All methods are static and thread-safe.

Method Summary

Modifier and Type	Method and Description
static boolean	isEngineActive() Checks whether IronPdfEngine is currently reachable and responsive.
static void	restartEngine() Restarts IronPdfEngine by stopping it (if running) and establishing a fresh connection.
static void	startEngine() Ensures IronPdfEngine is started and connected.
static void	stopEngine() Stops IronPdfEngine and releases the connection.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

isEngineActive

public static boolean isEngineActive()

Checks whether IronPdfEngine is currently reachable and responsive.

Against a running engine this is a lightweight, fast check: a single 5s-deadline handshake against the existing connection. It will not start the engine, so calling it before the first IronPDF call (or after stopEngine()) returns false.

Note: this method shares a lock with startEngine()/ restartEngine(), so if a connect or restart is in progress on another thread, the check waits for that operation to finish first.

Returns:

true if a connection exists and the engine answers within the deadline; false if the engine was never started, has been stopped, or is unresponsive (crashed / killed / host restarted).

startEngine

public static void startEngine()

Ensures IronPdfEngine is started and connected.

Equivalent to what happens implicitly on the first IronPDF call: in SUBPROCESS mode it launches the local engine (downloading the binaries if necessary); in remote modes it connects and handshakes. If a healthy connection already exists this is a no-op.

Note: this does not recover a stale connection left behind by a crashed engine. Use restartEngine() for recovery.

stopEngine

public static void stopEngine()

Stops IronPdfEngine and releases the connection.

In SUBPROCESS mode the local engine process is terminated. In remote modes the gRPC channel is closed but the remote server is left running. The engine will be started again automatically on the next IronPDF call, or explicitly via startEngine().

Throws:

UnsupportedOperationException - in CUSTOM connection mode, where the gRPC channel is owned by the caller and cannot be rebuilt once shut down. Manage the lifecycle of your custom channel yourself.

restartEngine

public static void restartEngine()

Restarts IronPdfEngine by stopping it (if running) and establishing a fresh connection.

This is the recommended recovery action when isEngineActive() reports false on a previously working engine. It fully resets the cached connection state, which a plain IronPDF call would not do, so a dead subprocess is relaunched and a restarted remote host is re-handshaked.

Throws:

UnsupportedOperationException - in CUSTOM connection mode, where the gRPC channel is owned by the caller and cannot be rebuilt once shut down. Manage the lifecycle of your custom channel yourself.