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, GatewayParameters
, CallbackServerParameters
, java_import
, get_field
, get_method
, launch_gateway
, and is_instance_of
. The other module members are documented to
support the extension of Py4J.
py4j.java_gateway.
JavaGateway
(gateway_client=None, auto_field=False, python_proxy_port=25334, start_callback_server=False, auto_convert=False, eager_load=False, gateway_parameters=None, callback_server_parameters=None, python_server_entry_point=None)¶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: |
|
---|
close
(keep_callback_server=False, close_callback_server_connections=False)¶JavaMethod
is called).Parameters: |
|
---|
close_callback_server
(raise_exception=False)¶CallbackServer
connections.Parameters: | raise_exception – If True, raise an exception if an error occurs while closing the callback server connections (very likely with sockets). |
---|
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.
Parameters: | java_object – The JavaObject instance to dereference (free) on the Java side. |
---|
get_callback_server
()¶help
(var, pattern=None, short_name=True, display=True)¶Displays a help page about a class or an object.
Parameters: |
|
---|
launch_gateway
(port=0, jarpath='', classpath='', javaopts=[], die_on_exit=False, redirect_stdout=None, redirect_stderr=None, daemonize_redirect=True, java_path='java', create_new_process_group=False)¶Launch a Gateway in a new Java process and create a default
JavaGateway
to connect to
it.
See launch_gateway
for more
information about this function.
Parameters: |
|
---|---|
Return type: | a |
new_array
(java_class, *dimensions)¶Creates a Java array of type java_class of dimensions
Parameters: |
|
---|---|
Return type: | A |
new_jvm_view
(name='custom jvm')¶Creates a new JVM view with its own imports. A JVM view ensures that the import made in one view does not conflict with the import of another view.
Generally, each Python module should have its own view (to replicate Java behavior).
Parameters: | name – Optional name of the jvm view. Does not need to be unique, i.e., two distinct views can have the same name (internally, they will have a distinct id). |
---|---|
Return type: | A JVMView instance (same class as the gateway.jvm instance). |
restart_callback_server
()¶Shuts down the callback server (if started) and restarts a new one.
set_gateway_client
(gateway_client)¶Sets the gateway client for this JavaGateway. This sets the appropriate gateway_property and resets the main jvm view (self.jvm).
This is for advanced usage only. And should only be set before the gateway is loaded.
shutdown
(raise_exception=False)¶GatewayClient
and theCallbackServer
.Parameters: | raise_exception – If True, raise an exception if an error occurs while shutting down (very likely with sockets). |
---|
shutdown_callback_server
(raise_exception=False)¶CallbackServer
.Parameters: | raise_exception – If True, raise an exception if an error occurs while shutting down (very likely with sockets). |
---|
start_callback_server
(callback_server_parameters=None)¶Starts the callback server.
Parameters: | callback_server_parameters – parameters to use to start the server. If not provided, it will use the gateway callback server parameters. |
---|---|
Return type: | Returns True if the server was started by this call or False if it was already started (you cannot have more than one started callback server). |
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(GatewayParameters(auto_field=True))
>>> example2 = java_gateway2.jvm.py4j.examples.ExampleWithField()
>>> example2.member
1
>>> get_method(example2,'member')()
u'Hello World'
py4j.java_gateway.
GatewayParameters
(address='127.0.0.1', port=25333, auto_field=False, auto_close=True, auto_convert=False, eager_load=False, ssl_context=None, enable_memory_management=True, read_timeout=None)¶Wrapper class that contains all parameters that can be passed to configure a JavaGateway
Parameters: |
|
---|
py4j.java_gateway.
CallbackServerParameters
(address='127.0.0.1', port=25334, daemonize=False, daemonize_connections=False, eager_load=True, ssl_context=None, accept_timeout='DEFAULT', read_timeout=None)¶Wrapper class that contains all parameters that can be passed to configure a CallbackServer
Parameters: |
|
---|
This is an internal class. Do not use it directly.
py4j.java_gateway.
GatewayClient
(address='127.0.0.1', port=25333, auto_close=True, gateway_property=None, ssl_context=None, gateway_parameters=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: |
|
---|
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, binary=False)¶JavaMember
instances.Parameters: |
|
---|---|
Return type: | the string answer received from the JVM (The answer follows the Py4J protocol). The guarded GatewayConnection is also returned if binary is True. |
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.
This is an internal class. Do not use it directly.
py4j.java_gateway.
GatewayConnection
(gateway_parameters, gateway_property=None)¶Default gateway connection (socket based) responsible for communicating with the Java Virtual Machine.
Parameters: |
|
---|
close
(reset=False)¶Closes the connection by closing the socket.
If reset is True, sends a RST packet with SO_LINGER
send_command
(command)¶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
This is an internal class. Do not use it directly.
py4j.java_gateway.
JVMView
(gateway_client, jvm_name, id=None, jvm_object=None)¶A JVMView 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.
This is an internal class. Do not use it directly.
Represents a Java object from which you can call methods or access fields.
This is an internal class. Do not use it directly.
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.
This is an internal class. Do not use it directly.
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.
_java_lang_class
¶Property that returns the java.lang.Class associated with this JavaClass. Equivalent to calling .class in Java.
This is an internal class. Do not use it directly.
py4j.java_gateway.
JavaPackage
(fqn, gateway_client, jvm_id=None)¶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.
This is an internal class. Do not use it directly.
py4j.java_gateway.
PythonProxyPool
¶A PythonProxyPool manages proxies that are passed to the Java side. A proxy is a Python class that implements a Java interface.
A proxy has an internal class named Java with a member named implements which is a list of fully qualified names (string) of the implemented interfaces.
The PythonProxyPool implements a subset of the dict interface: pool[id], del(pool[id]), pool.put(proxy), pool.clear(), id in pool, len(pool).
The PythonProxyPool is thread-safe.
clear
()¶put
(object, force_id=None)¶Adds a proxy to the pool.
Parameters: | object – The proxy to add to the pool. |
---|---|
Return type: | A unique identifier associated with the object. |
py4j.java_gateway.
CallbackServer
(pool, gateway_client, port=25334, address='127.0.0.1', callback_server_parameters=None)¶The CallbackServer is responsible for receiving call back connection requests from the JVM. Usually connections are reused on the Java side, but there is at least one connection per concurrent thread.
Parameters: |
|
---|
close
()¶Closes all active callback connections
get_listening_address
()¶Returns the address on which the callback server is listening to. May be different than address if address was an alias (e.g., localhost).
get_listening_port
()¶Returns the port on which the callback server is listening to. Different than port when port is 0.
run
()¶Starts listening and accepting connection requests.
This method is called when invoking CallbackServer.start(). A
CallbackServer instance is created and started automatically when
a JavaGateway
instance is
created.
shutdown
()¶Stops listening and accepting connection requests. All live connections are closed.
This method can safely be called by another thread.
start
()¶Starts the CallbackServer. This method should be called by the client instead of run().
This is an internal class. Do not use it directly.
This is a list of signals that Py4J can send during various lifecycle events.
They are all instances of Signal
.
py4j.java_gateway.
server_connection_stopped
¶Signal sent when a Python (Callback) Server connection is stopped.
Will supply the connection
argument, an instance of CallbackConnection.
The sender is the CallbackServer instance.
py4j.java_gateway.
server_connection_started
¶Signal sent when a Python (Callback) Server connection is started.
Will supply the connection
argument, an instance of CallbackConnection.
The sender is the CallbackServer instance.
py4j.java_gateway.
server_connection_error
¶Signal sent when a Python (Callback) Server encounters an error while waiting for a connection.
Will supply the error
argument, an instance of Exception.
The sender is the CallbackServer instance.
py4j.java_gateway.
server_started
¶Signal sent when a Python (Callback) Server is started
Will supply the server
argument, an instance of CallbackServer
The sender is the CallbackServer instance, but it is not possible for now to bind to a CallbackServer instance before it is started (limitation of the current JavaGateway and ClientServer API).
py4j.java_gateway.
server_stopped
¶Signal sent when a Python (Callback) Server is stopped
Will supply the server
argument, an instance of CallbackServer
The sender is the CallbackServer instance.
py4j.java_gateway.
pre_server_shutdown
¶Signal sent when a Python (Callback) Server is about to shut down.
Will supply the server
argument, an instance of CallbackServer
The sender is the CallbackServer instance.
py4j.java_gateway.
post_server_shutdown
¶Signal sent when a Python (Callback) Server is shutted down.
Will supply the server
argument, an instance of CallbackServer
The sender is the CallbackServer instance.
The following functions get be used to import packages or to get a particular field or method when fields and methods in a Java class have the same name:
py4j.java_gateway.
java_import
(jvm_view, import_str)¶Imports the package or class specified by import_str in the jvm view namespace.
Parameters: | jvm_view – The jvm_view in which to import a class/package. |
---|---|
Import_str: | The class (e.g., java.util.List) or the package (e.g., java.io.*) to import |
py4j.java_gateway.
launch_gateway
(port=0, jarpath='', classpath='', javaopts=[], die_on_exit=False, redirect_stdout=None, redirect_stderr=None, daemonize_redirect=True, java_path='java', create_new_process_group=False)¶Launch a Gateway in a new Java process.
The redirect parameters accept file-like objects, Queue, or deque. When
text lines are sent to the stdout or stderr of the child JVM, these lines
are redirected to the file-like object (write(line)
), the Queue
(put(line)
), or the deque (appendleft(line)
).
The text line will contain a newline character.
Only text output is accepted on stdout and stderr. If you wish to communicate with the child JVM through bytes, you need to create your own helper function.
Parameters: |
|
---|---|
Return type: | the port number of the Gateway server. |
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: |
|
---|
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: |
|
---|
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: |
|
---|
py4j.java_gateway.
is_instance_of
(gateway, java_object, java_class)¶Indicates whether a java object is an instance of the provided java_class.
Parameters: |
|
---|
py4j.java_gateway.
get_java_class
(java_class)¶Returns the java.lang.Class of a JavaClass. This is equivalent to calling .class in Java.
Parameters: | java_class – An instance of JavaClass |
---|---|
Return type: | An instance of JavaObject that corresponds to a java.lang.Class |