PythonClient (py4j-java 0.10.9.4 API)
Date: 2022-03-16

py4j

## Class PythonClient

- java.lang.Object
- - py4j.CallbackClient
  - - py4j.PythonClient

- All Implemented Interfaces:
    GatewayServerListener, Py4JPythonClient, Py4JPythonClientPerThread

      public class PythonClient
      extends CallbackClient
      implements Py4JPythonClientPerThread, GatewayServerListener

  Subclass of CallbackClient that implements the new threading model, ensuring that each thread uses its own connection.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.util.List<java.lang.Class<? extends Command>>` | `customCommands`
    `protected Gateway` | `gateway`
    `protected Py4JJavaServer` | `javaServer`
    `protected java.util.logging.Logger` | `logger`
    `protected int` | `readTimeout`
    `protected java.lang.ThreadLocal<java.lang.ref.WeakReference<ClientServerConnection>>` | `threadConnection`

    - ### Fields inherited from class py4j.CallbackClient

      `address, authToken, connections, DEFAULT_ADDRESS, DEFAULT_MIN_CONNECTION_TIME, DEFAULT_MIN_CONNECTION_TIME_UNIT, enableMemoryManagement, lock, minConnectionTime, minConnectionTimeUnit, port, socketFactory`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PythonClient(Gateway gateway, java.util.List<java.lang.Class<? extends Command>> customCommands, int pythonPort, java.net.InetAddress pythonAddress, long minConnectionTime, java.util.concurrent.TimeUnit minConnectionTimeUnit, javax.net.SocketFactory socketFactory, Py4JJavaServer javaServer)`
    `PythonClient(Gateway gateway, java.util.List<java.lang.Class<? extends Command>> customCommands, int pythonPort, java.net.InetAddress pythonAddress, long minConnectionTime, java.util.concurrent.TimeUnit minConnectionTimeUnit, javax.net.SocketFactory socketFactory, Py4JJavaServer javaServer, boolean enableMemoryManagement, int readTimeout)`
    `PythonClient(Gateway gateway, java.util.List<java.lang.Class<? extends Command>> customCommands, int pythonPort, java.net.InetAddress pythonAddress, long minConnectionTime, java.util.concurrent.TimeUnit minConnectionTimeUnit, javax.net.SocketFactory socketFactory, Py4JJavaServer javaServer, boolean enableMemoryManagement, int readTimeout, java.lang.String authToken)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `connectionError(java.lang.Exception e)`
    `void` | `connectionStarted(Py4JServerConnection gatewayConnection)`
    `void` | `connectionStopped(Py4JServerConnection gatewayConnection)`
    `Py4JPythonClient` | `copyWith(java.net.InetAddress pythonAddress, int pythonPort)` Creates a callback client which connects to the given address and port, but retains all the other settings (like the `CallbackClient.minConnectionTime` and the `CallbackClient.socketFactory`.
    `protected Py4JClientConnection` | `getConnection()`
    `Gateway` | `getGateway()`
    `Py4JJavaServer` | `getJavaServer()`
    `ClientServerConnection` | `getPerThreadConnection()`
    `int` | `getReadTimeout()`
    `protected void` | `giveBackConnection(Py4JClientConnection cc)`
    `void` | `serverError(java.lang.Exception e)` This method may be called concurrently with serverPostShutdown().
    `void` | `serverPostShutdown()` This method may be called concurrently with serverStopped() and serverError().
    `void` | `serverPreShutdown()`
    `void` | `serverStarted()`
    `void` | `serverStopped()` This method may be called concurrently with serverPostShutdown().
    `void` | `setGateway(Gateway gateway)`
    `void` | `setJavaServer(Py4JJavaServer javaServer)`
    `void` | `setPerThreadConnection(ClientServerConnection clientServerConnection)`
    `protected void` | `setupCleaner()`
    `protected boolean` | `shouldRetrySendCommand(Py4JClientConnection cc, Py4JNetworkException pne)`
    `protected java.net.Socket` | `startClientSocket()`

    - ### Methods inherited from class py4j.CallbackClient

      `getAddress, getConnectionLock, getPort, getPythonServerEntryPoint, isMemoryManagementEnabled, periodicCleanup, sendCommand, sendCommand, shutdown`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface py4j.Py4JPythonClient

      `getAddress, getPort, getPythonServerEntryPoint, isMemoryManagementEnabled, sendCommand, sendCommand, shutdown`

- - ### Field Detail

    - #### gateway

          protected Gateway gateway

    - #### customCommands

          protected java.util.List<java.lang.Class<? extends Command>> customCommands

    - #### logger

          protected final java.util.logging.Logger logger

    - #### javaServer

          protected Py4JJavaServer javaServer

    - #### threadConnection

          protected java.lang.ThreadLocal<java.lang.ref.WeakReference<ClientServerConnection>> threadConnection

    - #### readTimeout

          protected final int readTimeout

  - ### Constructor Detail

    - #### PythonClient

          public PythonClient(Gateway gateway,
                              java.util.List<java.lang.Class<? extends Command>> customCommands,
                              int pythonPort,
                              java.net.InetAddress pythonAddress,
                              long minConnectionTime,
                              java.util.concurrent.TimeUnit minConnectionTimeUnit,
                              javax.net.SocketFactory socketFactory,
                              Py4JJavaServer javaServer)

      Parameters:
        `gateway` - The gateway used to pool Java instances created on the Python side.
        `customCommands` - Optional list of custom commands that can be invoked by the Python side.
        `pythonPort` - Port the PythonClient should connect to.
        `pythonAddress` - Address (IP) the PythonClient should connect to.
        `minConnectionTime` - Minimum time to wait before closing unused connections. Not used with PythonClient.
        `minConnectionTimeUnit` - Time unit of minConnectionTime
        `socketFactory` - SocketFactory used to create a socket.
        `javaServer` - The JavaServer used to receive commands from the Python side.

    - #### PythonClient

          public PythonClient(Gateway gateway,
                              java.util.List<java.lang.Class<? extends Command>> customCommands,
                              int pythonPort,
                              java.net.InetAddress pythonAddress,
                              long minConnectionTime,
                              java.util.concurrent.TimeUnit minConnectionTimeUnit,
                              javax.net.SocketFactory socketFactory,
                              Py4JJavaServer javaServer,
                              boolean enableMemoryManagement,
                              int readTimeout)

      Parameters:
        `gateway` - The gateway used to pool Java instances created on the Python side.
        `customCommands` - Optional list of custom commands that can be invoked by the Python side.
        `pythonPort` - Port the PythonClient should connect to.
        `pythonAddress` - Address (IP) the PythonClient should connect to.
        `minConnectionTime` - Minimum time to wait before closing unused connections. Not used with PythonClient.
        `minConnectionTimeUnit` - Time unit of minConnectionTime
        `socketFactory` - SocketFactory used to create a socket.
        `javaServer` - The JavaServer used to receive commands from the Python side.
        `enableMemoryManagement` - If false, the Java side does not tell the Python side when a Python proxy is garbage collected.
        `readTimeout` - Time in milliseconds (0 = infinite). Once connected to the Python side, if the Java side does not receive a response after this time, the connection with the Python program is closed. If readTimeout = 0, a default readTimeout of 1000 is used for operations that must absolutely be non-blocking.

    - #### PythonClient

          public PythonClient(Gateway gateway,
                              java.util.List<java.lang.Class<? extends Command>> customCommands,
                              int pythonPort,
                              java.net.InetAddress pythonAddress,
                              long minConnectionTime,
                              java.util.concurrent.TimeUnit minConnectionTimeUnit,
                              javax.net.SocketFactory socketFactory,
                              Py4JJavaServer javaServer,
                              boolean enableMemoryManagement,
                              int readTimeout,
                              java.lang.String authToken)

      Parameters:
        `gateway` - The gateway used to pool Java instances created on the Python side.
        `customCommands` - Optional list of custom commands that can be invoked by the Python side.
        `pythonPort` - Port the PythonClient should connect to.
        `pythonAddress` - Address (IP) the PythonClient should connect to.
        `minConnectionTime` - Minimum time to wait before closing unused connections. Not used with PythonClient.
        `minConnectionTimeUnit` - Time unit of minConnectionTime
        `socketFactory` - SocketFactory used to create a socket.
        `javaServer` - The JavaServer used to receive commands from the Python side.
        `enableMemoryManagement` - If false, the Java side does not tell the Python side when a Python proxy is garbage collected.
        `readTimeout` - Time in milliseconds (0 = infinite). Once connected to the Python side, if the Java side does not receive a response after this time, the connection with the Python program is closed. If readTimeout = 0, a default readTimeout of 1000 is used for operations that must absolutely be non-blocking.
        `authToken` - Token for authenticating with the callback server.

  - ### Method Detail

    - #### getPerThreadConnection

          public ClientServerConnection getPerThreadConnection()

      Specified by:
        `getPerThreadConnection` in interface `Py4JPythonClientPerThread`

    - #### setPerThreadConnection

          public void setPerThreadConnection(ClientServerConnection clientServerConnection)

      Specified by:
        `setPerThreadConnection` in interface `Py4JPythonClientPerThread`

    - #### getGateway

          public Gateway getGateway()

      Specified by:
        `getGateway` in interface `Py4JPythonClientPerThread`

    - #### setGateway

          public void setGateway(Gateway gateway)

      Specified by:
        `setGateway` in interface `Py4JPythonClientPerThread`

    - #### getJavaServer

          public Py4JJavaServer getJavaServer()

      Specified by:
        `getJavaServer` in interface `Py4JPythonClientPerThread`

    - #### setJavaServer

          public void setJavaServer(Py4JJavaServer javaServer)

      Specified by:
        `setJavaServer` in interface `Py4JPythonClientPerThread`

    - #### getReadTimeout

          public int getReadTimeout()

      Specified by:
        `getReadTimeout` in interface `Py4JPythonClient`
      Overrides:
        `getReadTimeout` in class `CallbackClient`

    - #### setupCleaner

          protected void setupCleaner()

      Overrides:
        `setupCleaner` in class `CallbackClient`

    - #### startClientSocket

          protected java.net.Socket startClientSocket()
                                               throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### getConnection

          protected Py4JClientConnection getConnection()
                                                throws java.io.IOException

      Overrides:
        `getConnection` in class `CallbackClient`
      Throws:
        `java.io.IOException`

    - #### shouldRetrySendCommand

          protected boolean shouldRetrySendCommand(Py4JClientConnection cc,
                                                   Py4JNetworkException pne)

      Overrides:
        `shouldRetrySendCommand` in class `CallbackClient`

    - #### giveBackConnection

          protected void giveBackConnection(Py4JClientConnection cc)

      Overrides:
        `giveBackConnection` in class `CallbackClient`

    - #### copyWith

          public Py4JPythonClient copyWith(java.net.InetAddress pythonAddress,
                                           int pythonPort)

      Description copied from class: `CallbackClient`

      Creates a callback client which connects to the given address and port, but retains all the other settings (like the `CallbackClient.minConnectionTime` and the `CallbackClient.socketFactory`. This method is useful if for some reason your CallbackServer changes its address or you come to know of the address after Gateway has already instantiated.

      Specified by:
        `copyWith` in interface `Py4JPythonClient`
      Overrides:
        `copyWith` in class `CallbackClient`
      Parameters:
        `pythonAddress` - The address used by a PythonProxyHandler to connect to a Python gateway.
        `pythonPort` - The port used by a PythonProxyHandler to connect to a Python gateway. Essentially the port used for Python callbacks.

    - #### connectionError

          public void connectionError(java.lang.Exception e)

      Specified by:
        `connectionError` in interface `GatewayServerListener`

    - #### connectionStarted

          public void connectionStarted(Py4JServerConnection gatewayConnection)

      Specified by:
        `connectionStarted` in interface `GatewayServerListener`

    - #### connectionStopped

          public void connectionStopped(Py4JServerConnection gatewayConnection)

      Specified by:
        `connectionStopped` in interface `GatewayServerListener`

    - #### serverError

          public void serverError(java.lang.Exception e)

      Description copied from interface: `GatewayServerListener`

      This method may be called concurrently with serverPostShutdown().

      Typically a one thread calls shutdown() and then, the thread running the GatewayServer breaks from the connection accept loop.

      Specified by:
        `serverError` in interface `GatewayServerListener`

    - #### serverPostShutdown

          public void serverPostShutdown()

      Description copied from interface: `GatewayServerListener`

      This method may be called concurrently with serverStopped() and serverError().

      Typically a one thread calls shutdown() and then, the thread running the GatewayServer breaks from the connection accept loop.

      Specified by:
        `serverPostShutdown` in interface `GatewayServerListener`

    - #### serverPreShutdown

          public void serverPreShutdown()

      Specified by:
        `serverPreShutdown` in interface `GatewayServerListener`

    - #### serverStarted

          public void serverStarted()

      Specified by:
        `serverStarted` in interface `GatewayServerListener`

    - #### serverStopped

          public void serverStopped()

      Description copied from interface: `GatewayServerListener`

      This method may be called concurrently with serverPostShutdown().

      Typically a one thread calls shutdown() and then, the thread running the GatewayServer breaks from the connection accept loop.

      Specified by:
        `serverStopped` in interface `GatewayServerListener`