3. Py4J Python API — Py4J

3. Py4J Python API

3.1. Overview

Using Py4J is usually as simple as creating a JavaGateway object:

java_gateway = JavaGateway()
# you are now connected to the JVM
# and you can call any method defined on the Java side.

You can still customize and extend Py4J in many ways (e.g., you can choose the port to which you want to connect), so here are the classes you are the most likely to interact with:

3.2. JavaGateway

class py4j.java_gateway.JavaGateway(comm_channel=None, auto_start=True)

A JavaGateway is the Python entry point to the JVM. A JavaGateway instance must be connected to a Gateway instance on the Java side.

Parameters:
  • comm_channel – communication channel used to connect to the JVM. If None, a communication channel based on a socket with the default parameters is created.
  • auto_start – if True, the JavaGateway connects to the JVM as soon as it is created. Otherwise, you need to explicitly call gateway.comm_channel.start().

3.2.1. Examples

javaGateway = JavaGateway(auto_start=False)
javaGateway.comm_channel.start()
# ... do some work here
javaGateway.comm_channel.stop()

3.3. CommChannel

class py4j.java_gateway.CommChannel(address='localhost', port=25333, auto_close=True)

Default communication channel (socket based) responsible for communicating with the Java Virtual Machine.

Parameters:
  • address – the address to which the comm channel will connect
  • port – the port to which the comm channel will connect. Default is 25333.
  • auto_close – if True, the communication channel closes the socket when it is garbage collected (i.e., when CommChannel.__del__() is called).
__del__()

Closes the socket if auto_delete is True and the socket is opened.

This is an acceptable practice if you know that your Python VM implements garbage collection and closing sockets immediately is not a concern. Otherwise, it is always better (because it is predictable) to explicitly close the socket by calling CommChannel.close().

send_command(command)

Sends a command to the JVM. This method is not intended to be called directly by Py4J users: it is usually called by JavaMember instances.

Parameter:command – the string command to send to the JVM. The command must follow the Py4J protocol.
Return type:the string answer received from the JVM. The answer follows the Py4J protocol.
shutdown()
Sends a shutdown command to the gateway. This will close the gateway server: 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()
Starts the communication channel by connecting to the address and the port
stop()
Stops the communication channel by closing the socket.

3.3.1. Examples

TBD

3.4. Py4JError

class py4j.java_gateway.Py4JError(value)

Exception thrown when a problem occurs with Py4J.

Parameter:value – the error message

3.4.1. Examples

TBD

3.5. JavaObject

class py4j.java_gateway.JavaObject(target_id, comm_channel)

Represents a Java object from which you can call methods.

Parameters:
  • target_id – the identifier of the object on the JVM side. Given by the JVM.
  • comm_channel – the communication channel used to communicate with the JVM.
get_object_id()

3.5.1. Examples

TBD

3.6. JavaMember

class py4j.java_gateway.JavaMember(name, target_id, comm_channel)
Represents a member (field, method) of a Java Object. For now, only methods are supported.

3.6.1. Examples

TBD

3.7. JavaList

class py4j.java_gateway.JavaList(target_id, comm_channel)

Maps a Python list to a Java list.

All operations possible on a Python list are implemented. For example, slicing (e.g., list[1:3]) will create a copy of the list on the JVM. Slicing is thus not equivalent to subList(), because a modification to a slice such as the addition of a new element will not affect the original list.

append(value)
count(value)
extend(other_list)
index(value)
insert(key, value)
pop(key=None)
reverse()
sort()

3.7.1. Examples

TBD

Questions/Feedback?