com.ironsoftware.ironpdf

Class IronPdfEngineConnection

java.lang.Object

com.ironsoftware.ironpdf.IronPdfEngineConnection

public class IronPdfEngineConnection
extends Object

IronPdfEngineConnection is a configuration class used to set up various connection modes for IronPdfEngine. It provides a fluent API to configure different connection methods such as Host/Port, Target, Subprocess, or a predefined Cloud-based service.

The supported connection modes are:

- SUBPROCESS: (Default) Launch a local IronPdfEngine as a subprocess.

- HOST_PORT: Connect to IronPdfEngine using a host and port.

- TARGET: Connect to IronPdfEngine using a target string (e.g., DNS-based resolution).

- OFFICIAL_CLOUD: (Default for IronPDF for Java Cloud) Connect to an official cloud-based IronPdfEngine. (require subscription License)

- CUSTOM: Connect to IronPdfEngine using a custom gRPC connection.

Example usage:

  IronPdfEngineConnection settings = IronPdfEngineConnection.configure()
      .withHostPort("localhost", 33350); 
 

Get IronPDF engine docker @see official-ironpdfengine-docker

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	IronPdfEngineConnection.ConnectionMode

Constructor Summary

Constructors

Constructor and Description
IronPdfEngineConnection()

Method Summary

Modifier and Type	Method and Description
static IronPdfEngineConnection	configure() Static factory method to initiate the configuration of IronPdfEngineConnection.
io.grpc.ManagedChannel	getCustomChannel() Retrieves custom channel.
String	getHost() Retrieves the host name of the gRPC server.
IronPdfEngineConnection.ConnectionMode	getMode() Retrieves the current connection mode (HOST_PORT, TARGET, SUBPROCESS, or CUSTOM).
int	getPort() Retrieves the port number of the IronPdfEngine.
String	getTarget() Retrieves the target string used for service discovery (if applicable).
String	toString() Provides a string representation of the current IronPdfEngine settings.
IronPdfEngineConnection	withCustomGrpcConnection(io.grpc.ManagedChannel customChannel)
IronPdfEngineConnection	withHostPort(String host, int port) Recommended for hosting IronPdfEngine Docker in local network.
IronPdfEngineConnection	withOfficialCloud() Configures IronPDF Java to use an official cloud-based IronPdfEngine.
IronPdfEngineConnection	withSubprocess() Default use-case.
IronPdfEngineConnection	withSubprocess(int port) Recommended if port 33350 is not available.
IronPdfEngineConnection	withTarget(String target) Recommended for hosting IronPdfEngine Docker in Cloud or remote server.

Methods inherited from class java.lang.Object

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

Constructor Detail

IronPdfEngineConnection

public IronPdfEngineConnection()

Method Detail

configure

public static IronPdfEngineConnection configure()

Static factory method to initiate the configuration of IronPdfEngineConnection. This method serves as the entry point for setting up the connection configuration. Example:

 
 IronPdfEngineConnection settings = IronPdfEngineConnection.configure()
      .withHostPort("localhost", 8080);
 
 

Returns:

IronPdfEngineConnection The instance of the settings to be configured.

withHostPort

public IronPdfEngineConnection withHostPort(String host,
                                            int port)

Recommended for hosting IronPdfEngine Docker in local network.

Set IronPdfEngine connection mode using host and port.

This mode allows connecting to an already running IronPdfEngine.

Use IronPDF engine docker. All PDF operation will happen on the connected IronPDF engine docker.

This setting required IronPdfEngine is already up and running in docker. (on the given port)

Get IronPDF engine docker @see official-ironpdfengine-docker}

Parameters:

host - The hostname or IP address of the IronPdfEngine.

port - The port number where the IronPdfEngine is running.

Throws:

IllegalArgumentException - if the host is null or empty, or if the port is out of range.

withTarget

public IronPdfEngineConnection withTarget(String target)

Recommended for hosting IronPdfEngine Docker in Cloud or remote server.

Set IronPdfEngine connection mode using a target string.

This mode is typically used for service discovery mechanisms (e.g., DNS, load balancing).

Parameters:

target - The target string (e.g., "dns:///my-service:8080").

withSubprocess

public IronPdfEngineConnection withSubprocess()

Default use-case. IronPDF Java will spawn IronPdfEngine as a local subprocess.

Launch a IronPdfEngine as a subprocess.

The subprocess will be launched with a predefined host (localhost) and port (33350).

To use another port withSubprocess(int)

withSubprocess

public IronPdfEngineConnection withSubprocess(int port)

Recommended if port 33350 is not available.

Launch a IronPdfEngine as a subprocess with a custom port.

The subprocess will be launched with a predefined host (localhost) and custom port.

Parameters:

port - The port number where the IronPdfEngine subprocess will be used.

withOfficialCloud

public IronPdfEngineConnection withOfficialCloud()

Configures IronPDF Java to use an official cloud-based IronPdfEngine.

Only works for Subscription license. For more information please contact sales@ironsoftware.com

withCustomGrpcConnection

public IronPdfEngineConnection withCustomGrpcConnection(io.grpc.ManagedChannel customChannel)

getHost

public String getHost()

Retrieves the host name of the gRPC server.

Returns:

String The hostname or IP address of the IronPdfEngine.

getPort

public int getPort()

Retrieves the port number of the IronPdfEngine.

Returns:

int The port number where the IronPdfEngine server is running.

getTarget

public String getTarget()

Retrieves the target string used for service discovery (if applicable).

Returns:

String The target string (e.g., "dns:///my-service:8080").

getMode

public IronPdfEngineConnection.ConnectionMode getMode()

Retrieves the current connection mode (HOST_PORT, TARGET, SUBPROCESS, or CUSTOM).

Returns:

ConnectionMode The connection mode being used by the settings.

getCustomChannel

public io.grpc.ManagedChannel getCustomChannel()

Retrieves custom channel.

Returns:

ManagedChannel custom channel.

toString

public String toString()

Provides a string representation of the current IronPdfEngine settings. Displays either the host/port, target, or subprocess details based on the mode.

Overrides:

toString in class Object

Returns:

String A description of the current IronPdfEngine connection settings.