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, auto_field=False)

A JavaGateway is the main interaction point between a Python VM and a JVM.

  • A JavaGateway instance is connected to a Gateway instance on the Java side.
  • The entry_point field of a JavaGateway instance is connected to the Gateway.entryPoint instance on the Java side.
  • The jvm field of JavaGateway enables user to access classes, static members (fields and methods) and call constructors.

Methods that are not defined by JavaGateway are always redirected to entry_point. For example, gateway.doThat() is equivalent to gateway.entry_point.doThat(). This is a trade-off between convenience and potential confusion.

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().
  • 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.
attach(java_object)
close()
help(var, short_name=True, display=True)

Displays a help page about a class or an object.

Parameters:
  • var – JavaObject or JavaClass for which a help page will be generated.
  • short_name – If True, only the simple name of the parameter types and return types will be displayed. If False, the fully qualified name of the types will be displayed.
  • display – If True, the help page is displayed in an interactive page similar to the help command in Python. If False, the page is returned as a string.
shutdown()
start()

3.2.1. Examples

Using the jvm property:

>>> gateway = JavaGateway()
>>> jvm = gateway.jvm
>>> l = jvm.java.util.ArrayList()
>>> l.append(10)
>>> l.append(1)
>>> jvm.java.util.Collections.sort(l)
>>> l
[1, 10]
>>> l.append(5)
>>> l.sort()
>>> l
[1, 5, 10]

Using non-default value of auto_start:

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

Using auto_field:

First we declare a class that has a field AND a method called member:

package py4j.examples;
public class ExampleWithField {
    public int member = 1;
    public String member() {
        return "Hello World";
    }
}

Then we play with the class using the two possible values of auto_field:

>>> java_gateway = JavaGateway() # auto_field = False
>>> example = java_gateway.jvm.py4j.examples.ExampleWithField()
>>> example.member()
u'Hello World'
>>> get_field(example,'member')
1
>>> java_gateway2 = JavaGateway(auto_field=True)
>>> example2 = java_gateway2.jvm.py4j.examples.ExampleWithField()
>>> example2.member
1
>>> get_method(example2,'member')()
u'Hello World'

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().

close(throw_exception=False)
Closes the communication channel by closing the socket.
delay_command(command)
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.
send_delay()
shutdown_gateway()
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

3.4. Py4JError

class py4j.java_gateway.Py4JError(value)

Exception thrown when a problem occurs with Py4J.

Parameter:value – the error message

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.

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

class py4j.java_collections.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.8. Py4J Functions

py4j.java_gateway.get_field(java_object, field_name)

Retrieves the field named field_name from the java_object.

This function is useful when auto_field=false in a gateway or Java object.

Parameters:
  • java_object – the instance containing the field
  • field_name – the name of the field to retrieve
py4j.java_gateway.get_method(java_object, method_name)

Retrieves a reference to the method of an object.

This function is useful when auto_field=true and an instance field has the same name as a method. The full signature of the method is not required: it is determined when the method is called.

Parameters:
  • java_object – the instance containing the method
  • method_name – the name of the method to retrieve
py4j.java_gateway.escape_new_line(original)

Replaces new line characters by a backslash followed by a n.

Backslashes are also escaped by another backslash.

Parameter:original – the string to escape
Return type:an escaped string
py4j.java_gateway.unescape_new_line(escaped)

Replaces escaped characters by unescaped characters.

For example, double backslashes are replaced by a single backslash.

Parameter:escaped – the escaped string
Return type:the original string
py4j.java_gateway.get_command_part(parameter)

Converts a Python object into a string representation respecting the Py4J protocol.

For example, the integer 1 is converted to u’i1’

Parameter:parameter – the object to convert
py4j.java_gateway.get_return_value(answer, comm_channel, target_id=None, name=None)

Converts an answer received from the Java gateway into a Python object.

For example, string representation of integers are converted to Python integer, string representation of objects are converted to JavaObject instances, etc.

Parameters:
  • answer – the string returned by the Java gateway
  • comm_channel – the communication channel used to communicate with the Java Gateway. Only necessary if the answer is a reference (e.g., object, list, map)
  • target_id – the name of the object from which the answer comes from (e.g., object1 in object1.hello()). Optional.
  • name – the name of the member from which the answer comes from (e.g., hello in object1.hello()). Optional.

Questions/Feedback?

blog comments powered by Disqus