Package com.ironsoftware.ironpdf

Class 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

    • 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.