4.2. py4j.clientserver — Py4J Single Threading Model Implementation

The py4j.clientserver module defines an implementation of Python Server and Java client that ensures that commands started from a Python or Java thread are always executed on the same Java or Python thread.

For example, if a command to Python is sent from Java UI thread and the Python code calls some Java code, the Java code will be executed in the UI thread.

Py4J users are expected to only use explicitly ClientServer and optionally, JavaParameters and PythonParameters. The other module members are documented to support the extension of Py4J.

4.2.1. ClientServer

class py4j.clientserver.ClientServer(java_parameters, python_parameters, python_server_entry_point=None)

Subclass of JavaGateway that implements a different threading model: a thread always use the same connection to the other side so callbacks are executed in the calling thread.

For example, if Python thread 1 calls Java, and Java calls Python, the callback (from Java to Python) will be executed in Python thread 1.

Parameters:
  • java_parameters – collection of parameters and flags used to configure the JavaGateway (Java client)
  • python_parameters – collection of parameters and flags used to configure the CallbackServer (Python server)
  • python_server_entry_point – can be requested by the Java side if Java is driving the communication.

4.2.1.1. Examples

Using the jvm property:

>>> clientserver = ClientServer()
>>> l = clientserver.jvm.java.util.ArrayList()
>>> l.append(10)
>>> l.append(1)
>>> jvm.java.util.Collections.sort(l)
>>> l
[1, 10]

The ClientServer class is a subclass of JavaGateway is fully compatible with all examples and code written for a JavaGateway.`

4.2.2. JavaParameters

class py4j.clientserver.JavaParameters(address=u'127.0.0.1', port=25333, auto_field=False, auto_close=True, auto_convert=False, eager_load=False, ssl_context=None)

Wrapper class that contains all parameters that can be passed to configure a ClientServer.`

Parameters:
  • address – the address to which the client will request a connection. If you’re assing a SSLContext with check_hostname=True then this address must match (one of) the hostname(s) in the certificate the gateway server presents.
  • port – the port to which the client will request a connection. Default is 25333.
  • auto_field – if False, each object accessed through this gateway won”t try to lookup fields (they will be accessible only by calling get_field). If True, fields will be automatically looked up, possibly hiding methods of the same name and making method calls less efficient.
  • auto_close – if True, the connections created by the client close the socket when they are garbage collected.
  • auto_convert – if True, try to automatically convert Python objects like sequences and maps to Java Objects. Default value is False to improve performance and because it is still possible to explicitly perform this conversion.
  • eager_load – if True, the gateway tries to connect to the JVM by calling System.currentTimeMillis. If the gateway cannot connect to the JVM, it shuts down itself and raises an exception.
  • ssl_context – if not None, SSL connections will be made using this SSLContext

4.2.3. PythonParameters

class py4j.clientserver.PythonParameters(address=u'127.0.0.1', port=25334, daemonize=False, daemonize_connections=False, eager_load=True, ssl_context=None)

Wrapper class that contains all parameters that can be passed to configure a ClientServer

Parameters:
  • address – the address to which the client will request a connection
  • port – the port to which the client will request a connection. Default is 25333.
  • daemonize – If True, will set the daemon property of the server thread to True. The callback server will exit automatically if all the other threads exit.
  • daemonize_connections – If True, callback server connections are executed in daemonized threads and will not block the exit of a program if non daemonized threads are finished.
  • eager_load – If True, the callback server is automatically started when the JavaGateway is created.
  • ssl_context – if not None, the SSLContext’s certificate will be presented to callback connections.

4.2.4. JavaClient

class py4j.clientserver.JavaClient(java_parameters, python_parameters, gateway_property=None)

Responsible for managing requests from Python to Java.

This implementation is thread-safe because it always use only one ClientServerConnection per thread.

Parameters:
  • java_parameters – collection of parameters and flags used to configure the JavaGateway (Java client)
  • python_parameters – collection of parameters and flags used to configure the CallbackServer (Python server)
  • gateway_property – used to keep gateway preferences without a cycle with the JavaGateway

4.2.5. PythonServer

class py4j.clientserver.PythonServer(java_client, java_parameters, python_parameters, gateway_property)

Responsible for managing requests from Java to Python.

Parameters:
  • java_client – the gateway client used to call Java objects.
  • java_parameters – collection of parameters and flags used to configure the JavaGateway (Java client)
  • python_parameters – collection of parameters and flags used to configure the CallbackServer (Python server)
  • gateway_property – used to keep gateway preferences.

4.2.6. ClientServerConnection

class py4j.clientserver.ClientServerConnection(java_parameters, python_parameters, gateway_property, java_client)

Default connection for a ClientServer instance (socket-based, one per thread) responsible for communicating with the Java Virtual Machine.

Parameters:
  • java_parameters – collection of parameters and flags used to configure the JavaGateway (Java client)
  • python_parameters – collection of parameters and flags used to configure the CallbackServer (Python server)
  • gateway_property – used to keep gateway preferences.
  • java_client – the gateway client used to call Java objects.
close()
connect_to_java_server()
init_socket_from_python_server(socket, stream)
run()
send_command(command)
shutdown_gateway()

Sends a shutdown command to the Java side.

This will close the ClientServer on the Java side: all active connections will be closed. This may be useful if the lifecycle of the Java program must be tied to the Python program.

start()
wait_for_commands()

Questions/Feedback?