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

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

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

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

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

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