4.1. py4j.java_gateway — Py4J Main API

The py4j.java_gateway module defines most of the classes that are needed to use Py4J. Py4J users are expected to only use explicitly JavaGateway and optionally, GatewayClient, get_field, and get_method. The other module members are documented to support the extension of Py4J.

4.1.1. JavaGateway

class py4j.java_gateway.JavaGateway(gateway_client=None, auto_field=False, python_proxy_port=25334, start_callback_server=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:
  • gateway_client – gateway client used to connect to the JVM. If None, a gateway client based on a socket with the default parameters is created.
  • 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.
  • python_proxy_port – port used to receive callback from the JVM.
  • start_callback_server – if True, the callback server is started.
close(keep_callback_server=False)

Closes all gateway connections. A connection will be reopened if necessary (e.g., if a JavaMethod is called).

Parameters:
  • keep_callback_server – if True, the callback server is not shut down.
detach(java_object)

Makes the Java Gateway dereference this object.

The equivalent of this method is called when a JavaObject instance is garbage collected on the Python side. This method, or gc.collect() should still be invoked when memory is limited or when too many objects are created on the Java side. :param java_object: The JavaObject instance to dereference (free) on the Java side.

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.
new_array(java_class, *dimensions)

Creates a Java array of type java_class of dimensions

Parameters:
  • java_class – The JavaClass instance representing the type of the array.
  • dimensions – A list of dimensions of the array. For example [1,2] would produce an array[1][2].
restart_callback_server()

Shuts down the callback server (if started) and restarts a new one.

shutdown()

Shuts down the GatewayClient and the CallbackServer.

4.1.1.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 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'

4.1.2. GatewayClient

class py4j.java_gateway.GatewayClient(address='localhost', port=25333, auto_close=True, gateway_property=None)

Responsible for managing connections to the JavaGateway.

This implementation is thread-safe and connections are created on-demand. This means that Py4J-Python can be accessed by multiple threads and messages are sent to and processed concurrently by the Java Gateway.

When creating a custom JavaGateway, it is recommended to pass an instance of GatewayClient instead of a GatewayConnection: both have the same interface, but the client supports multiple threads and connections, which is essential when using callbacks.

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.
  • auto_close – if True, the connections created by the client close the socket when they are garbage collected.
  • gateway_property – used to keep gateway preferences without a cycle with the gateway
close()

Closes all currently opened connections.

This operation is not thread safe and is only a best effort strategy to close active connections. All connections are guaranteed to be closed only if no other thread is accessing the client and no call is pending.

send_command(command, retry=True)

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.

Parameters:
  • command – the string command to send to the JVM. The command must follow the Py4J protocol.
Retry :

if True, the GatewayClient tries to resend a message if it fails.

Return type:

the string answer received from the JVM. The answer follows the Py4J protocol.

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.

4.1.3. CommChannel

class py4j.java_gateway.GatewayConnection(address='localhost', port=25333, auto_close=True, gateway_property=None)

Default gateway connection (socket based) responsible for communicating with the Java Virtual Machine.

Parameters:
  • address – the address to which the connection will be established
  • port – the port to which the connection will be established. Default is 25333.
  • auto_close – if True, the connection closes the socket when it is garbage collected.
  • gateway_property – contains gateway preferences to avoid a cycle with gateway
close(throw_exception=False)

Closes the connection by closing the socket.

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.

Parameters:
  • 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_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 connection by connecting to the address and the port

4.1.4. Py4JError

class py4j.java_gateway.Py4JError(value)

Exception thrown when a problem occurs with Py4J.

Parameters:
  • value – the error message

4.1.5. JVM

class py4j.java_gateway.JVM(gateway_client)

A JVM allows access to the Java Virtual Machine of a JavaGateway. This can be used to reference static members (fields and methods) and to call constructors.

4.1.6. JavaObject

class py4j.java_gateway.JavaObject(target_id, gateway_client)

Represents a Java object from which you can call methods or access fields.

Parameters:
  • target_id – the identifier of the object on the JVM side. Given by the JVM.
  • gateway_client – the gateway client used to communicate with the JVM.

4.1.7. JavaMember

class py4j.java_gateway.JavaMember(name, container, target_id, gateway_client)

Represents a member (i.e., method) of a JavaObject. For now, only methods are supported. Fields are retrieved directly and are not contained in a JavaMember.

4.1.8. JavaClass

class py4j.java_gateway.JavaClass(fqn, gateway_client)

A JavaClass represents a Java Class from which static members can be retrieved. JavaClass instances are also needed to initialize an array.

Usually, JavaClass are not initialized using their constructor, but they are created while accessing the jvm property of a gateway, e.g., gateway.jvm.java.lang.String.

4.1.9. JavaPackage

class py4j.java_gateway.JavaPackage(fqn, gateway_client)

A JavaPackage represents part of a Java package from which Java classes can be accessed.

Usually, JavaPackage are not initialized using their constructor, but they are created while accessing the jvm property of a gateway, e.g., gateway.jvm.java.lang.

4.1.10. Py4J Functions

The following functions get be used to get a particular field or method when fields and methods in a Java class have the same name:

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.set_field(java_object, field_name, value)

Sets the field named field_name of java_object to value.

This function is the only way to set a field because the assignment operator in Python cannot be overloaded.

Parameters:
  • java_object – the instance containing the field
  • field_name – the name of the field to set
  • value – the value to assign to the field
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

4.1.11. Py4J Misc. Functions

The following functions can be used to extend Py4J (e.g., to create new commands):

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.

Parameters:
  • 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.

Parameters:
  • escaped – the escaped string
Return type:

the original string

py4j.java_gateway.get_command_part(parameter, python_proxy_pool=None)

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

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

Parameters:
  • parameter – the object to convert
Return type:

the string representing the command part

py4j.java_gateway.get_return_value(answer, gateway_client, 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
  • gateway_client – the gateway client 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