py4j

## Class CallbackClient

- java.lang.Object
- - py4j.CallbackClient

- All Implemented Interfaces:
    Py4JPythonClient
  Direct Known Subclasses:
    PythonClient

      public class CallbackClient
      extends java.lang.Object
      implements Py4JPythonClient

  A CallbackClient is responsible for managing communication channels: channels are created as needed (e.g., one per concurrent thread) and are closed after a certain time.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.net.InetAddress` | `address`
    `protected java.lang.String` | `authToken`
    `protected java.util.Deque<Py4JClientConnection>` | `connections`
    `static java.lang.String` | `DEFAULT_ADDRESS`
    `static long` | `DEFAULT_MIN_CONNECTION_TIME`
    `static java.util.concurrent.TimeUnit` | `DEFAULT_MIN_CONNECTION_TIME_UNIT`
    `protected boolean` | `enableMemoryManagement`
    `protected java.util.concurrent.locks.Lock` | `lock`
    `protected long` | `minConnectionTime`
    `protected java.util.concurrent.TimeUnit` | `minConnectionTimeUnit`
    `protected int` | `port`
    `protected int` | `readTimeout`
    `protected javax.net.SocketFactory` | `socketFactory`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CallbackClient(int port)`
    `CallbackClient(int port, java.net.InetAddress address)`
    `CallbackClient(int port, java.net.InetAddress address, long minConnectionTime, java.util.concurrent.TimeUnit minConnectionTimeUnit)`
    `CallbackClient(int port, java.net.InetAddress address, long minConnectionTime, java.util.concurrent.TimeUnit minConnectionTimeUnit, javax.net.SocketFactory socketFactory)`
    `CallbackClient(int port, java.net.InetAddress address, long minConnectionTime, java.util.concurrent.TimeUnit minConnectionTimeUnit, javax.net.SocketFactory socketFactory, boolean enableMemoryManagement)`
    `CallbackClient(int port, java.net.InetAddress address, long minConnectionTime, java.util.concurrent.TimeUnit minConnectionTimeUnit, javax.net.SocketFactory socketFactory, boolean enableMemoryManagement, int readTimeout)`
    `CallbackClient(int port, java.net.InetAddress address, java.lang.String authToken)`
    `CallbackClient(int port, java.net.InetAddress address, java.lang.String authToken, long minConnectionTime, java.util.concurrent.TimeUnit minConnectionTimeUnit, javax.net.SocketFactory socketFactory, boolean enableMemoryManagement, int readTimeout)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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 `minConnectionTime` and the `socketFactory`.
    `java.net.InetAddress` | `getAddress()`
    `protected Py4JClientConnection` | `getConnection()`
    `protected Py4JClientConnection` | `getConnectionLock()`
    `int` | `getPort()`
    `java.lang.Object` | `getPythonServerEntryPoint(Gateway gateway, java.lang.Class[] interfacesToImplement)` Gets a reference to the entry point on the Python side.
    `int` | `getReadTimeout()`
    `protected void` | `giveBackConnection(Py4JClientConnection cc)`
    `boolean` | `isMemoryManagementEnabled()`
    `void` | `periodicCleanup()` Closes communication channels that have not been used for a time specified at the creation of the callback client.
    `java.lang.String` | `sendCommand(java.lang.String command)` Sends a command to the Python side.
    `java.lang.String` | `sendCommand(java.lang.String command, boolean blocking)` Sends a command to the Python side.
    `protected void` | `setupCleaner()`
    `protected boolean` | `shouldRetrySendCommand(Py4JClientConnection cc, Py4JNetworkException pne)`
    `void` | `shutdown()` Closes all active channels, stops the periodic cleanup of channels and mark the client as shutting down.

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

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

- - ### Field Detail

    - #### DEFAULT_ADDRESS

          public static final java.lang.String DEFAULT_ADDRESS

      See Also:
        Constant Field Values

    - #### port

          protected final int port

    - #### address

          protected final java.net.InetAddress address

    - #### socketFactory

          protected final javax.net.SocketFactory socketFactory

    - #### connections

          protected final java.util.Deque<Py4JClientConnection> connections

    - #### lock

          protected final java.util.concurrent.locks.Lock lock

    - #### DEFAULT_MIN_CONNECTION_TIME

          public static final long DEFAULT_MIN_CONNECTION_TIME

      See Also:
        Constant Field Values

    - #### DEFAULT_MIN_CONNECTION_TIME_UNIT

          public static final java.util.concurrent.TimeUnit DEFAULT_MIN_CONNECTION_TIME_UNIT

    - #### minConnectionTime

          protected final long minConnectionTime

    - #### minConnectionTimeUnit

          protected final java.util.concurrent.TimeUnit minConnectionTimeUnit

    - #### enableMemoryManagement

          protected final boolean enableMemoryManagement

    - #### readTimeout

          protected final int readTimeout

    - #### authToken

          protected final java.lang.String authToken

  - ### Constructor Detail

    - #### CallbackClient

          public CallbackClient(int port)

    - #### CallbackClient

          public CallbackClient(int port,
                                java.net.InetAddress address)

    - #### CallbackClient

          public CallbackClient(int port,
                                java.net.InetAddress address,
                                java.lang.String authToken)

    - #### CallbackClient

          public CallbackClient(int port,
                                java.net.InetAddress address,
                                long minConnectionTime,
                                java.util.concurrent.TimeUnit minConnectionTimeUnit)

    - #### CallbackClient

          public CallbackClient(int port,
                                java.net.InetAddress address,
                                long minConnectionTime,
                                java.util.concurrent.TimeUnit minConnectionTimeUnit,
                                javax.net.SocketFactory socketFactory)

      Parameters:
        `port` - The port used by channels to connect to the Python side.
        `address` - The addressed used by channels to connect to the Python side..
        `minConnectionTime` - The minimum connection time: channels are guaranteed to stay connected for this time after sending a command.
        `minConnectionTimeUnit` - The minimum coonnection time unit.
        `socketFactory` - The non-`null` factory to make `Socket`s.

    - #### CallbackClient

          public CallbackClient(int port,
                                java.net.InetAddress address,
                                long minConnectionTime,
                                java.util.concurrent.TimeUnit minConnectionTimeUnit,
                                javax.net.SocketFactory socketFactory,
                                boolean enableMemoryManagement)

      Parameters:
        `port` - The port used by channels to connect to the Python side.
        `address` - The addressed used by channels to connect to the Python side..
        `minConnectionTime` - The minimum connection time: channels are guaranteed to stay connected for this time after sending a command.
        `minConnectionTimeUnit` - The minimum coonnection time unit.
        `socketFactory` - The non-`null` factory to make `Socket`s.
        `enableMemoryManagement` - If False, we do not send tell the Python side when a PythonProxy is no longer used by the Java side.

    - #### CallbackClient

          public CallbackClient(int port,
                                java.net.InetAddress address,
                                long minConnectionTime,
                                java.util.concurrent.TimeUnit minConnectionTimeUnit,
                                javax.net.SocketFactory socketFactory,
                                boolean enableMemoryManagement,
                                int readTimeout)

      Parameters:
        `port` - The port used by channels to connect to the Python side.
        `address` - The addressed used by channels to connect to the Python side..
        `minConnectionTime` - The minimum connection time: channels are guaranteed to stay connected for this time after sending a command.
        `minConnectionTimeUnit` - The minimum coonnection time unit.
        `socketFactory` - The non-`null` factory to make `Socket`s.
        `enableMemoryManagement` - If False, we do not send tell the Python side when a PythonProxy is no longer used by the Java side.
        `readTimeout` - Time in milliseconds (0 = infinite). Once a Python program is connected, if a GatewayServer does not receive a request (e.g., a method call) after this time, the connection with the Python program is closed.

    - #### CallbackClient

          public CallbackClient(int port,
                                java.net.InetAddress address,
                                java.lang.String authToken,
                                long minConnectionTime,
                                java.util.concurrent.TimeUnit minConnectionTimeUnit,
                                javax.net.SocketFactory socketFactory,
                                boolean enableMemoryManagement,
                                int readTimeout)

      Parameters:
        `port` - The port used by channels to connect to the Python side.
        `address` - The addressed used by channels to connect to the Python side.
        `authToken` - Token for authenticating with the callback server.
        `minConnectionTime` - The minimum connection time: channels are guaranteed to stay connected for this time after sending a command.
        `minConnectionTimeUnit` - The minimum coonnection time unit.
        `socketFactory` - The non-`null` factory to make `Socket`s.
        `enableMemoryManagement` - If False, we do not send tell the Python side when a PythonProxy is no longer used by the Java side.
        `readTimeout` - Time in milliseconds (0 = infinite). Once a Python program is connected, if a GatewayServer does not receive a request (e.g., a method call) after this time, the connection with the Python program is closed.

  - ### Method Detail

    - #### getAddress

          public java.net.InetAddress getAddress()

      Specified by:
        `getAddress` in interface `Py4JPythonClient`

    - #### isMemoryManagementEnabled

          public boolean isMemoryManagementEnabled()

      Specified by:
        `isMemoryManagementEnabled` in interface `Py4JPythonClient`

    - #### getConnection

          protected Py4JClientConnection getConnection()
                                                throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### getConnectionLock

          protected Py4JClientConnection getConnectionLock()

    - #### getPort

          public int getPort()

      Specified by:
        `getPort` in interface `Py4JPythonClient`

    - #### getReadTimeout

          public int getReadTimeout()

      Specified by:
        `getReadTimeout` in interface `Py4JPythonClient`

    - #### copyWith

          public 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 `minConnectionTime` and the `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`
      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.

    - #### giveBackConnection

          protected void giveBackConnection(Py4JClientConnection cc)

    - #### periodicCleanup

          public void periodicCleanup()

      Closes communication channels that have not been used for a time specified at the creation of the callback client.

      Clients should not directly call this method: it is called by a periodic cleaner thread.

    - #### sendCommand

          public java.lang.String sendCommand(java.lang.String command)

      Sends a command to the Python side. This method is typically used by Python proxies to call Python methods or to request the garbage collection of a proxy.

      Specified by:
        `sendCommand` in interface `Py4JPythonClient`
      Parameters:
        `command` - The command to send.
      Returns:
        The response.

    - #### sendCommand

          public java.lang.String sendCommand(java.lang.String command,
                                              boolean blocking)

      Sends a command to the Python side. This method is typically used by Python proxies to call Python methods or to request the garbage collection of a proxy.

      Specified by:
        `sendCommand` in interface `Py4JPythonClient`
      Parameters:
        `command` - The command to send.
        `blocking` - If the CallbackClient should wait for an answer (default should be True, except for critical cases such as a finalizer sending a command).
      Returns:
        The response.

    - #### getPythonServerEntryPoint

          public java.lang.Object getPythonServerEntryPoint(Gateway gateway,
                                                            java.lang.Class[] interfacesToImplement)

      Description copied from interface: `Py4JPythonClient`

      Gets a reference to the entry point on the Python side. This is often necessary if Java is driving the communication because Java cannot call static methods, initialize Python objects or load Python modules yet.

      Specified by:
        `getPythonServerEntryPoint` in interface `Py4JPythonClient`
      Returns:

    - #### shouldRetrySendCommand

          protected boolean shouldRetrySendCommand(Py4JClientConnection cc,
                                                   Py4JNetworkException pne)

    - #### setupCleaner

          protected void setupCleaner()

    - #### shutdown

          public void shutdown()

      Closes all active channels, stops the periodic cleanup of channels and mark the client as shutting down. No more commands can be sent after this method has been called, except commands that were initiated before the shutdown method was called..

      Specified by:
        `shutdown` in interface `Py4JPythonClient`